hrpc-inspector 0.1.0 → 0.1.2

package/dist/detect.d.ts

@@ -0,0 +1,10 @@
+export type Runtime = 'pear' | 'bare' | 'react-native' | 'electron' | 'node' | 'browser' | 'unknown';
+export interface RuntimeInfo {
+    runtime: Runtime;
+    /** Bare is available (Pear, plain Bare, or an RN bare-kit worklet) → hyperswarm can run in-process. */
+    isBareRuntime: boolean;
+    /** A browser/RN JS context where we must export over a bridge, not a socket. */
+    isBridgeOnly: boolean;
+}
+/** Pure and injectable (pass a fake global in tests). Order matters: most specific first. */
+export declare function detectRuntime(env?: any): RuntimeInfo;

package/dist/index.d.ts

@@ -0,0 +1,16 @@
+export { observe, DEFAULT_TOPIC } from './observe.js';
+export type { ObserveOptions, ObserveHandle } from './observe.js';
+export { detectRuntime } from './detect.js';
+export type { Runtime, RuntimeInfo } from './detect.js';
+export { wrapClient } from './wrap-client.js';
+export type { Report, WrapClientOptions } from './wrap-client.js';
+export { createWebSocketReporter } from './reporters.js';
+export type { Reporter, WebSocketReporterOptions } from './reporters.js';
+export { instrumentDataChannel, instrumentPeerConnection, } from 'hrpc-inspector-probe/adapters/webrtc';
+export { instrumentWebSocket } from 'hrpc-inspector-probe/adapters/websocket';
+export { instrumentHyperswarmStream } from 'hrpc-inspector-probe/adapters/hyperswarm';
+export { CollectorSink } from 'hrpc-inspector-probe/core/sink';
+export { BatchFlusher } from 'hrpc-inspector-probe/flush';
+export { createHyperswarmExporter } from 'hrpc-inspector-probe/exporters/hyperswarm';
+export { StreamFramer, encodeFrame } from 'hrpc-inspector-probe/transport/framing';
+export type { EventSink, L2Event, L2EventType } from 'hrpc-inspector-probe/sink';

package/dist/index.js

@@ -117,10 +117,21 @@ function monitorStream(report, endpoint, corrId, stream, t0, preview, tag) {
     report({ type: "request.end", method: endpoint, corrId, status, count: n, dur: Date.now() - t0, t: Date.now(), ...tag, ...extra || {} });
   };
   try {
-    stream.on("data", (item) => report({ type: "stream.data", method: endpoint, corrId, seq: ++n, item: preview(item), t: Date.now(), ...tag }));
-    stream.on("error", (err) => settle("error", { error: String(err) }));
-    stream.on("end", () => settle("closed"));
-    stream.on("close", () => settle("closed"));
+    const original = stream.emit;
+    if (typeof original !== "function") return;
+    stream.emit = function patched(name, ...args) {
+      try {
+        if (name === "data") {
+          report({ type: "stream.data", method: endpoint, corrId, seq: ++n, item: preview(args[0]), t: Date.now(), ...tag });
+        } else if (name === "error") {
+          settle("error", { error: String(args[0]) });
+        } else if (name === "end" || name === "close") {
+          settle("closed");
+        }
+      } catch {
+      }
+      return original.apply(this, [name, ...args]);
+    };
   } catch (e) {
     report({ type: "request.end", method: endpoint, corrId, status: "error", error: "monitor-failed: " + String(e), dur: 0, t: Date.now(), ...tag });
   }
@@ -247,7 +258,8 @@ async function autoSwarm(topic, onConnection) {
   const Hyperswarm = (await import("hyperswarm")).default;
   const crypto = (await import("hypercore-crypto")).default;
   const swarm = new Hyperswarm();
-  const topicKey = crypto.hash(Buffer.from(topic));
+  const enc = new TextEncoder();
+  const topicKey = crypto.hash(enc.encode(topic));
   swarm.on("connection", (conn) => onConnection(conn));
   await swarm.join(topicKey, { client: true, server: false }).flushed();
 }
@@ -256,6 +268,8 @@ function observe(opts = {}) {
   const source = resolveSource(opts.source, info.runtime);
   const redactOn = opts.redact ?? (opts.websocket ? false : true);
   const redactor = opts.redactor ?? (redactOn ? new Redactor({ bodyAllowlist: opts.bodyAllowlist }) : null);
+  const redactMethods = new Set(opts.redactMethods ?? []);
+  const methodRedactor = !redactor && redactMethods.size > 0 ? new Redactor() : null;
   const wireSource = redactor ? redactSource(source, redactor) : source;
   const invokeEnabled = opts.allowInvoke === true && !!opts.websocket;
   const replayLogMax = opts.replayLogMax ?? 2e3;
@@ -295,7 +309,9 @@ function observe(opts = {}) {
   const flusher = new BatchFlusher({
     intervalMs: opts.intervalMs ?? 200,
     onFlush: (batch) => {
-      const out = redactor ? redactor.redactBatch(batch) : batch;
+      const out = redactor ? redactor.redactBatch(batch) : methodRedactor ? batch.map(
+        (e) => redactMethods.has(String(e.method)) ? methodRedactor.redact(e) : e
+      ) : batch;
       exporter.export(out.map((e) => ({ ...e, src: wireSource.id })));
     }
   });

package/dist/observe.d.ts

@@ -0,0 +1,128 @@
+import { BatchFlusher } from 'hrpc-inspector-probe/flush';
+import type { WritableStreamLike, HyperswarmExporter } from 'hrpc-inspector-probe/exporters/hyperswarm';
+import { Redactor } from 'hrpc-inspector-probe/redactor';
+import type { EventSink, L2Event } from 'hrpc-inspector-probe/sink';
+import type { Runtime } from './detect.js';
+import type { Report, WrapClientOptions } from './wrap-client.js';
+export declare const DEFAULT_TOPIC = "p2p-observability-hub:v0";
+export interface SourceInfo {
+    /** Stable id used to group/select this source in the GUI. */
+    id: string;
+    /** Human label shown in the selector. */
+    label: string;
+    /** Detected runtime (react-native | pear | bare | electron | node | browser). */
+    runtime: string;
+    /** Physical device id (client-supplied; e.g. an app's own options.deviceId). Lets the GUI select by device. */
+    deviceId?: string;
+    /** App / install instance id — distinguishes MULTIPLE apps sharing one package. */
+    appId?: string;
+    [extra: string]: unknown;
+}
+export interface ObserveOptions {
+    /** Flush cadence; must be in the collector's verified 100-250ms window. Default 200. */
+    intervalMs?: number;
+    /** Explicit hub connection (a NoiseSecretStream / socket). Skips auto-swarm. */
+    stream?: WritableStreamLike;
+    /** Fully custom exporter (e.g. Rozenite bridge, OTLP). Skips everything else. */
+    exporter?: HyperswarmExporter;
+    /** Hub topic string; must match the hub's. Default DEFAULT_TOPIC. */
+    topic?: string;
+    /** Set false to disable Bare/Pear auto-dial (then attach() a stream yourself). */
+    autoSwarm?: boolean;
+    /**
+     * Send events to a local GUI over WebSocket instead of the Hyperswarm hub — the reliable
+     * dev-viewer path for EVERY runtime (RN / Pear / desktop / browser),
+     * e.g. 'ws://127.0.0.1:9420/ws'. When set, redaction defaults OFF (local viewing);
+     * pass redact:true to force it. Takes precedence over stream/auto-swarm.
+     */
+    websocket?: string;
+    /**
+     * Redact every event on the way OUT (peer ids hashed, URLs host-only, bodies off)
+     * — ON by default, because the export path (hub / .p2plog) leaves the device.
+     * Set false ONLY for a purely-local view that never leaves the machine (F3/F4/F9).
+     */
+    redact?: boolean;
+    /**
+     * Per-`method` FORCED redaction, for when global `redact` is off (the local viewer default).
+     * A listed method still appears in the GUI — you see it fired, when, how long it took, whether
+     * it errored, and the SHAPE of its payload (`{phrase: 'string'}`) — but its values are replaced
+     * by a content summary. Use it for methods that carry secrets you never want rendered, e.g.
+     * a recovery phrase. This is a denylist: a newly added secret-bearing method must be listed.
+     * Ignored when `redact` is on, because everything is redacted already.
+     */
+    redactMethods?: Iterable<string>;
+    /** Supply a shared Redactor (e.g. to reuse its local peer reverse-map). Default: a fresh one. */
+    redactor?: Redactor;
+    /** Per-`method` opt-in allowlist for full payload bodies (default: none — bodies summarised). */
+    bodyAllowlist?: Iterable<string>;
+    /**
+     * Identity of THIS device/app, for the GUI's device & app selectors. A string label, or an
+     * object `{ id?, label?, deviceId?, appId?, app?, device?, variant? }`.
+     *   • deviceId — physical device (client-supplied; e.g. the app's own options.deviceId) → select by device
+     *   • appId    — app/install instance → distinguishes MULTIPLE apps sharing one package
+     * Omit → auto: browser reuses localStorage for a stable id (clears on delete-data); other
+     * runtimes get a session id (pass deviceId/appId for stability). Only the client knows its
+     * app name / device / variant, so it supplies those.
+     */
+    source?: string | Record<string, unknown>;
+    /**
+     * Allow the GUI to REPLAY a logged call back into this client (re-run a call the app already
+     * made). Boundary: the GUI references a call by corrId and the METHOD is resolved from this
+     * client's own call log — it never crosses the wire, so a replay cannot be redirected to a
+     * method the app never called. The ARGS may be supplied by the GUI (edit-and-replay) and are
+     * NOT validated here beyond "must be a JSON array"; use `canReplay` to check them.
+     *
+     * Fails CLOSED: must be set to `true` EXPLICITLY. There is no dev-detection default — omit it
+     * and replay is off, so a shipped build never installs the inbound handler. Only meaningful
+     * together with `websocket`.
+     */
+    allowInvoke?: boolean;
+    /**
+     * Optional gate consulted before a replay runs — return false to block (e.g. to refuse
+     * re-running a mutating method like a send). Default: allow. Receives the logged method and the
+     * args that will actually be used — which may be UNVALIDATED, GUI-supplied args. This is the
+     * only argument check in the system, so an app whose methods mutate state should implement it.
+     */
+    canReplay?: (method: string, args: unknown[]) => boolean;
+    /** Max logged calls retained for replay (corrId→method+args). Default 500. */
+    replayLogMax?: number;
+}
+export interface ObserveHandle {
+    /** Wire your L1 adapters into this: `instrumentDataChannel(dc, peerId, obs.sink)`. */
+    sink: EventSink;
+    flusher: BatchFlusher<L2Event>;
+    runtime: Runtime;
+    mode: 'websocket' | 'stream' | 'custom' | 'buffering';
+    /** The redactor applied on export (null if redact:false). Use `.resolvePeer()` for a local names view. */
+    redactor: Redactor | null;
+    /** This device/app's resolved identity — stamped on every event as `src` and announced to the GUI. */
+    source: SourceInfo;
+    /** Report one event directly to the sink (this is what wrapClient uses). */
+    report: Report;
+    /** Wrap an RPC/service client so its calls + subscription streams are observed. */
+    wrapClient<T extends Record<string, any>>(client: T, opts?: WrapClientOptions): T;
+    /**
+     * Snapshot of request/response calls currently in flight — started (request.start) but not yet
+     * settled (request.end). Each `{ method, corrId, t }`. Subscription streams are not included (see
+     * observe.ts). Wire this to a thread-occupancy probe's `getInflight` so a stall names the call
+     * that was running (e.g. hrpc-inspector-threads).
+     */
+    inflight(): Array<{
+        method: string;
+        corrId: string;
+        t: number;
+    }>;
+    /**
+     * Bridge a hypertrace tracer into the SAME event stream: pass hypertrace's `setTraceFunction`
+     * and every `trace()` from instrumented classes (e.g. a WebRTC/call layer) becomes a
+     * `type:'trace'` event on a distinct "trace" plane in the GUI. Install this BEFORE the traced
+     * objects are constructed (hypertrace only traces objects created after the function is set).
+     * Dependency-free: the app supplies `setTraceFunction`, so the package never imports hypertrace.
+     * Returns a disposer that stops forwarding.
+     */
+    bridgeTraces(setTraceFunction: (fn: (trace: any) => void) => void): () => void;
+    /** Attach a hub connection later (auto-swarm calls this on 'connection'). */
+    attach(stream: WritableStreamLike): void;
+    stop(): void;
+}
+export declare function observe(opts?: ObserveOptions): ObserveHandle;

package/dist/observe.js

@@ -117,10 +117,21 @@ function monitorStream(report, endpoint, corrId, stream, t0, preview, tag) {
     report({ type: "request.end", method: endpoint, corrId, status, count: n, dur: Date.now() - t0, t: Date.now(), ...tag, ...extra || {} });
   };
   try {
-    stream.on("data", (item) => report({ type: "stream.data", method: endpoint, corrId, seq: ++n, item: preview(item), t: Date.now(), ...tag }));
-    stream.on("error", (err) => settle("error", { error: String(err) }));
-    stream.on("end", () => settle("closed"));
-    stream.on("close", () => settle("closed"));
+    const original = stream.emit;
+    if (typeof original !== "function") return;
+    stream.emit = function patched(name, ...args) {
+      try {
+        if (name === "data") {
+          report({ type: "stream.data", method: endpoint, corrId, seq: ++n, item: preview(args[0]), t: Date.now(), ...tag });
+        } else if (name === "error") {
+          settle("error", { error: String(args[0]) });
+        } else if (name === "end" || name === "close") {
+          settle("closed");
+        }
+      } catch {
+      }
+      return original.apply(this, [name, ...args]);
+    };
   } catch (e) {
     report({ type: "request.end", method: endpoint, corrId, status: "error", error: "monitor-failed: " + String(e), dur: 0, t: Date.now(), ...tag });
   }
@@ -247,7 +258,8 @@ async function autoSwarm(topic, onConnection) {
   const Hyperswarm = (await import("hyperswarm")).default;
   const crypto = (await import("hypercore-crypto")).default;
   const swarm = new Hyperswarm();
-  const topicKey = crypto.hash(Buffer.from(topic));
+  const enc = new TextEncoder();
+  const topicKey = crypto.hash(enc.encode(topic));
   swarm.on("connection", (conn) => onConnection(conn));
   await swarm.join(topicKey, { client: true, server: false }).flushed();
 }
@@ -256,6 +268,8 @@ function observe(opts = {}) {
   const source = resolveSource(opts.source, info.runtime);
   const redactOn = opts.redact ?? (opts.websocket ? false : true);
   const redactor = opts.redactor ?? (redactOn ? new Redactor({ bodyAllowlist: opts.bodyAllowlist }) : null);
+  const redactMethods = new Set(opts.redactMethods ?? []);
+  const methodRedactor = !redactor && redactMethods.size > 0 ? new Redactor() : null;
   const wireSource = redactor ? redactSource(source, redactor) : source;
   const invokeEnabled = opts.allowInvoke === true && !!opts.websocket;
   const replayLogMax = opts.replayLogMax ?? 2e3;
@@ -295,7 +309,9 @@ function observe(opts = {}) {
   const flusher = new BatchFlusher({
     intervalMs: opts.intervalMs ?? 200,
     onFlush: (batch) => {
-      const out = redactor ? redactor.redactBatch(batch) : batch;
+      const out = redactor ? redactor.redactBatch(batch) : methodRedactor ? batch.map(
+        (e) => redactMethods.has(String(e.method)) ? methodRedactor.redact(e) : e
+      ) : batch;
       exporter.export(out.map((e) => ({ ...e, src: wireSource.id })));
     }
   });

package/dist/reporters.d.ts

@@ -0,0 +1,25 @@
+export interface Reporter {
+    export(batch: unknown[]): void;
+    close(): void;
+}
+export interface WebSocketReporterOptions {
+    /** WebSocket implementation. Default globalThis.WebSocket (RN/browser/Bare/Node ≥22 have it). */
+    WebSocketImpl?: any;
+    /** Max events buffered while disconnected (oldest dropped past this). Default 1000. */
+    maxQueue?: number;
+    /** Reconnect delay ms. Default 3000. */
+    reconnectMs?: number;
+    /** Source identity sent once per connection as `{ __source }` so the GUI can build a device selector. */
+    announce?: unknown;
+    /**
+     * Inbound frame handler. When set, the reporter becomes BIDIRECTIONAL — it installs
+     * `ws.onmessage` and forwards parsed frames here. observe() passes this ONLY in dev (for the
+     * replay/invoke path); leaving it undefined keeps the reporter strictly send-only, as before.
+     */
+    onMessage?: (msg: any) => void;
+}
+/**
+ * Send each event as one JSON WebSocket message to `url` (e.g. ws://127.0.0.1:9420/ws).
+ * Auto-connects, queues while down, flushes on open, reconnects on close. Never throws.
+ */
+export declare function createWebSocketReporter(url: string, opts?: WebSocketReporterOptions): Reporter;

package/dist/wrap-client.d.ts

@@ -0,0 +1,27 @@
+export type Report = (event: Record<string, unknown>) => void;
+export interface WrapClientOptions {
+    /** Summarise args/response/stream items before reporting. Default: bounded JSON. */
+    preview?: (v: unknown) => unknown;
+    /** Monitor subscription streams' data/end/error. Default true. */
+    monitorStreams?: boolean;
+    /**
+     * Called with the RAW (un-previewed) args at each call site, keyed by the minted corrId.
+     * observe() uses this to keep a bounded call-log so a GUI can REPLAY a logged call by corrId.
+     * The METHOD comes from this log, never from the wire, so a replay cannot be redirected to a
+     * method the app never called. ARGS, however, may be supplied by the GUI (edit-and-replay) and
+     * are not validated by this library — the app's `canReplay(method, args)` hook is the only
+     * argument check. Wired only when `allowInvoke: true` is passed explicitly.
+     */
+    onCall?: (corrId: string, method: string, args: unknown[]) => void;
+}
+export declare function setInvokeContext(ctx: {
+    invokeId: string;
+    replayOf: string;
+    method: string;
+} | null): void;
+/**
+ * Wrap a client object of namespaced methods (`client.namespace.method(...)`) so every call
+ * reports endpoint + request + response/stream. Mutates and returns the same client; method
+ * return values and `this` binding are preserved (a wrapped call behaves identically).
+ */
+export declare function wrapClient<T extends Record<string, any>>(client: T, report: Report, opts?: WrapClientOptions): T;

package/package.json

@@ -1,24 +1,24 @@
 {
   "name": "hrpc-inspector",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "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 in a local GUI, or merge multi-peer timelines over a Hyperswarm hub.",
   "type": "module",
   "main": "./dist/index.js",
-  "types": "./src/index.ts",
+  "types": "./dist/index.d.ts",
   "bin": {
     "hrpc-inspector": "bin/hrpc-inspector.mjs"
   },
   "exports": {
     ".": {
-      "types": "./src/index.ts",
+      "types": "./dist/index.d.ts",
       "default": "./dist/index.js"
     },
     "./detect": {
-      "types": "./src/detect.ts",
+      "types": "./dist/detect.d.ts",
       "default": "./dist/detect.js"
     },
     "./observe": {
-      "types": "./src/observe.ts",
+      "types": "./dist/observe.d.ts",
       "default": "./dist/observe.js"
     }
   },
@@ -30,18 +30,20 @@
     "LICENSE",
     "NOTICE",
     "README.md",
-    "USAGE.md"
+    "USAGE.md",
+    "scripts"
   ],
   "scripts": {
-    "build": "rm -rf dist && esbuild src/index.ts src/detect.ts src/observe.ts --bundle --format=esm --platform=neutral --external:hrpc-inspector-probe --external:hrpc-inspector-protocol --external:hyperswarm --external:hypercore-crypto --outdir=dist",
+    "build": "rm -rf dist && esbuild src/index.ts src/detect.ts src/observe.ts --bundle --format=esm --platform=neutral --external:hrpc-inspector-probe --external:hrpc-inspector-protocol --external:hyperswarm --external:hypercore-crypto --outdir=dist && npm run build:types",
     "prepare": "npm run build",
-    "test": "bash test/run-all.sh"
+    "test": "bash test/run-all.sh",
+    "build:types": "tsc -p tsconfig.build.json && node scripts/rewrite-dts-specifiers.mjs dist"
   },
   "repository": "git+https://github.com/holepunchto/hrpc-inspector.git",
   "license": "Apache-2.0",
   "sideEffects": false,
   "dependencies": {
-    "hrpc-inspector-probe": "^0.1.0"
+    "hrpc-inspector-probe": "^0.1.1"
   },
   "peerDependencies": {
     "hypercore-crypto": "^3.0.0",
@@ -60,6 +62,8 @@
     }
   },
   "devDependencies": {
-    "esbuild": "^0.28.2"
+    "esbuild": "^0.28.2",
+    "streamx": "^2.28.1",
+    "typescript": "^7.0.2"
   }
 }

package/scripts/rewrite-dts-specifiers.mjs

@@ -0,0 +1,32 @@
+// tsc emits declarations that keep the source's explicit `.ts` specifiers, and a consumer
+// type-checking those hits TS5097 unless they enable allowImportingTsExtensions — which no
+// consumer should. rewriteRelativeImportExtensions only rewrites emitted JS, not .d.ts, so
+// rewrite relative `./x.ts` -> `./x.js` here. Resolution then finds ./x.d.ts beside it.
+import { readdirSync, readFileSync, writeFileSync, statSync } from 'node:fs'
+import { join } from 'node:path'
+
+function walk(dir) {
+  return readdirSync(dir).flatMap((entry) => {
+    const full = join(dir, entry)
+    return statSync(full).isDirectory() ? walk(full) : [full]
+  })
+}
+
+const dir = process.argv[2] ?? 'dist'
+const SPECIFIER = /(from\s+|import\s*\(\s*)(['"])(\.\.?\/[^'"]+)\.ts\2/g
+
+const declarations = walk(dir).filter((f) => f.endsWith('.d.ts'))
+
+let changed = 0
+for (const path of declarations) {
+  const before = readFileSync(path, 'utf8')
+  const after = before.replace(SPECIFIER, (_m, kw, q, spec) => `${kw}${q}${spec}.js${q}`)
+  if (after !== before) { writeFileSync(path, after); changed++ }
+}
+
+const leftover = declarations.filter((f) => SPECIFIER.test(readFileSync(f, 'utf8')))
+if (leftover.length) {
+  console.error(`rewrite-dts-specifiers: .ts specifiers survive in ${leftover.join(', ')}`)
+  process.exit(1)
+}
+console.log(`rewrite-dts-specifiers: ${changed} file(s) rewritten in ${dir}`)

package/src/externals.d.ts

@@ -0,0 +1,16 @@
+// hyperswarm / hypercore-crypto are optional peers pulled in by a guarded dynamic import in the
+// Bare/Pear auto-dial path, and marked --external in the build. Neither ships types, so declare
+// the shape this package actually uses rather than depending on the packages being installed.
+declare module 'hyperswarm' {
+  interface SwarmDiscovery { flushed(): Promise<void> }
+  export default class Hyperswarm {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any -- the stream shape is the consumer's to name
+    on(event: 'connection', listener: (conn: any) => void): this
+    join(topic: Uint8Array, opts?: { client?: boolean; server?: boolean }): SwarmDiscovery
+  }
+}
+
+declare module 'hypercore-crypto' {
+  const crypto: { hash(data: Uint8Array): Uint8Array }
+  export default crypto
+}

package/src/observe.ts

@@ -128,6 +128,15 @@ export interface ObserveOptions {
    * Set false ONLY for a purely-local view that never leaves the machine (F3/F4/F9).
    */
   redact?: boolean;
+  /**
+   * Per-`method` FORCED redaction, for when global `redact` is off (the local viewer default).
+   * A listed method still appears in the GUI — you see it fired, when, how long it took, whether
+   * it errored, and the SHAPE of its payload (`{phrase: 'string'}`) — but its values are replaced
+   * by a content summary. Use it for methods that carry secrets you never want rendered, e.g.
+   * a recovery phrase. This is a denylist: a newly added secret-bearing method must be listed.
+   * Ignored when `redact` is on, because everything is redacted already.
+   */
+  redactMethods?: Iterable<string>;
   /** Supply a shared Redactor (e.g. to reuse its local peer reverse-map). Default: a fresh one. */
   redactor?: Redactor;
   /** Per-`method` opt-in allowlist for full payload bodies (default: none — bodies summarised). */
@@ -232,7 +241,9 @@ async function autoSwarm(topic: string, onConnection: (stream: WritableStreamLik
   const Hyperswarm = (await import('hyperswarm')).default;
   const crypto = (await import('hypercore-crypto')).default;
   const swarm = new Hyperswarm();
-  const topicKey = crypto.hash(Buffer.from(topic));
+  // Buffer is a Bare/Node global and absent in browsers; this path only runs under Bare.
+  const enc = new TextEncoder();
+  const topicKey = crypto.hash(enc.encode(topic));
   swarm.on('connection', (conn: WritableStreamLike) => onConnection(conn));
   await swarm.join(topicKey, { client: true, server: false }).flushed();
 }
@@ -247,6 +258,10 @@ export function observe(opts: ObserveOptions = {}): ObserveHandle {
   const redactOn = opts.redact ?? (opts.websocket ? false : true);
   const redactor: Redactor | null =
     opts.redactor ?? (redactOn ? new Redactor({ bodyAllowlist: opts.bodyAllowlist }) : null);
+  // Only meaningful while global redaction is off; when it is on these methods are covered anyway.
+  const redactMethods = new Set(opts.redactMethods ?? []);
+  const methodRedactor: Redactor | null =
+    !redactor && redactMethods.size > 0 ? new Redactor() : null;
   // Identity ON THE WIRE — hashed ids / no human labels when redaction is on. `handle.source`
   // keeps the original for the app's own use.
   const wireSource = redactor ? redactSource(source, redactor) : source;
@@ -304,7 +319,15 @@ export function observe(opts: ObserveOptions = {}): ObserveHandle {
   const flusher = new BatchFlusher<L2Event>({
     intervalMs: opts.intervalMs ?? 200,
     onFlush: (batch) => {
-      const out = redactor ? redactor.redactBatch(batch) : batch;
+      const out = redactor
+        ? redactor.redactBatch(batch)
+        : methodRedactor
+          ? batch.map((e) =>
+              redactMethods.has(String((e as Record<string, unknown>).method))
+                ? (methodRedactor.redact(e as Record<string, unknown>) as L2Event)
+                : e,
+            )
+          : batch;
       // Stamp the (wire) source id so the GUI can group/select by device.
       exporter.export(out.map((e) => ({ ...(e as object), src: wireSource.id })));
     },

package/src/wrap-client.ts

@@ -57,10 +57,16 @@ function defaultPreview(v: unknown): unknown {
   }
 }
 
-// Attach PASSIVE listeners to a subscription stream. Non-destructive when the app also uses
-// `.on('data')` (every listener receives each item). If a consumer instead uses `.read()` /
-// async-iteration, adding a data listener flips it to flowing mode — opt out with
-// monitorStreams:false for those.
+// Observe a subscription stream WITHOUT changing its behaviour.
+//
+// This wraps `emit` instead of calling `.on('data', ...)`. Registering a data listener is not
+// passive: it puts the stream into flowing mode immediately, so anything emitted before the app
+// attaches its own listener is delivered to us and LOST to the app. That is a debug-only data
+// loss — the app silently misses items, with no error — and it is real: keet's RPC subscriptions
+// return their stream synchronously, while the consumer attaches a tick later.
+//
+// Wrapping `emit` cannot cause that: we only see events the stream was already delivering. If
+// nothing consumes the stream, nothing is emitted and we report nothing, which is the truth.
 function monitorStream(report: Report, endpoint: string, corrId: string, stream: any, t0: number, preview: (v: unknown) => unknown, tag: Record<string, unknown>): void {
   report({ type: 'stream.open', method: endpoint, corrId, t: Date.now(), ...tag });
   let n = 0;
@@ -71,10 +77,24 @@ function monitorStream(report: Report, endpoint: string, corrId: string, stream:
     report({ type: 'request.end', method: endpoint, corrId, status, count: n, dur: Date.now() - t0, t: Date.now(), ...tag, ...(extra || {}) });
   };
   try {
-    stream.on('data', (item: unknown) => report({ type: 'stream.data', method: endpoint, corrId, seq: ++n, item: preview(item), t: Date.now(), ...tag }));
-    stream.on('error', (err: unknown) => settle('error', { error: String(err) }));
-    stream.on('end', () => settle('closed'));
-    stream.on('close', () => settle('closed'));
+    const original = stream.emit;
+    if (typeof original !== 'function') return;
+    stream.emit = function patched(this: unknown, name: string, ...args: unknown[]): unknown {
+      // Observation must never affect delivery: record, then hand off unchanged. A throw in the
+      // reporting path would surface as a stream error in the app, so it is swallowed.
+      try {
+        if (name === 'data') {
+          report({ type: 'stream.data', method: endpoint, corrId, seq: ++n, item: preview(args[0]), t: Date.now(), ...tag });
+        } else if (name === 'error') {
+          settle('error', { error: String(args[0]) });
+        } else if (name === 'end' || name === 'close') {
+          settle('closed');
+        }
+      } catch {
+        /* never break the stream */
+      }
+      return original.apply(this, [name, ...args] as never);
+    };
   } catch (e) {
     report({ type: 'request.end', method: endpoint, corrId, status: 'error', error: 'monitor-failed: ' + String(e), dur: 0, t: Date.now(), ...tag });
   }