@lensmcp/bridge 1.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/README.md

@@ -0,0 +1,55 @@
+# @lensmcp/bridge
+
+The build-agnostic **browser-event bridge** for LensMCP.
+
+A tiny WebSocket server that the injected [`@lensmcp/client-runtime`](../client-runtime)
+connects to, forwarding every observed browser event (errors, console, fetch,
+route changes, and pre-formed React/Valtio publishes) onto the LensMCP event
+bus — either in-process or, more usually, cross-process over the same
+`LENSMCP_EVENT_FILE` / `LENSMCP_UDS` / `LENSMCP_IPC_SOCKET` transport the
+MCP server tails.
+
+This logic used to live **inside** `@lensmcp/vite-plugin`, which is why
+LensMCP only worked for Vite apps. It was lifted out here so the exact same
+bridge can run:
+
+- **embedded** in the Vite dev server (the plugin calls `createBridgeServer`
+  on an ephemeral port), or
+- **standalone** as a sidecar on a fixed port for **webpack**, **Next.js**,
+  or **no-build** hosts — where the browser runtime finds the endpoint by a
+  known URL (`ws://127.0.0.1:5747` by default) instead of one a bundler baked
+  in.
+
+## Standalone
+
+```bash
+LENSMCP_EVENT_FILE=.lensmcp/events.jsonl node bridge.js
+# or
+lensmcp bridge
+```
+
+| Env | Default | Meaning |
+| --- | --- | --- |
+| `LENSMCP_WS_HOST` | `127.0.0.1` | bind host |
+| `LENSMCP_WS_PORT` | `5747` | bind port (`0` = ephemeral) |
+| `LENSMCP_SESSION_ID` | — | session id stamped on each event |
+| `LENSMCP_EVENT_FILE` | — | JSONL sink the MCP server ingests |
+
+Point the browser at it with `@lensmcp/client-runtime/auto` (zero build):
+
+```ts
+import '@lensmcp/client-runtime/auto';
+```
+
+## Embedding
+
+```ts
+import { createBridgeServer } from '@lensmcp/bridge';
+
+const bridge = await createBridgeServer({ port: 0, bus });
+console.log(bridge.port);
+await bridge.close();
+```
+
+The bridge is **strictly passive**: it never mutates app state, never
+changes scheduling, and never throws into the host.

package/index.d.ts

@@ -0,0 +1,6 @@
+export { createBridgeServer, makePublisher, handleClientEnvelope, findFreePort, type BridgeServer, type BridgeServerOptions, type BridgeDeps, } from './lib/server.js';
+export { envelopeToEvent } from './lib/event-mappers.js';
+export { resolveEnvSink, resetEnvSinkCache, udsEnvSink } from './lib/env-sink.js';
+export { DEFAULT_WS_HOST, DEFAULT_WS_PORT, ENV_WS_HOST, ENV_WS_PORT, ENV_SESSION_ID, } from './lib/constants.js';
+export type { ClientEnvelope, EnvSink } from './lib/types.js';
+//# sourceMappingURL=index.d.ts.map

package/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,kBAAkB,EAClB,aAAa,EACb,oBAAoB,EACpB,YAAY,EACZ,KAAK,YAAY,EACjB,KAAK,mBAAmB,EACxB,KAAK,UAAU,GAChB,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AACzD,OAAO,EAAE,cAAc,EAAE,iBAAiB,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAClF,OAAO,EACL,eAAe,EACf,eAAe,EACf,WAAW,EACX,WAAW,EACX,cAAc,GACf,MAAM,oBAAoB,CAAC;AAC5B,YAAY,EAAE,cAAc,EAAE,OAAO,EAAE,MAAM,gBAAgB,CAAC"}

package/index.js

@@ -0,0 +1,4 @@
+export { createBridgeServer, makePublisher, handleClientEnvelope, findFreePort, } from './lib/server.js';
+export { envelopeToEvent } from './lib/event-mappers.js';
+export { resolveEnvSink, resetEnvSinkCache, udsEnvSink } from './lib/env-sink.js';
+export { DEFAULT_WS_HOST, DEFAULT_WS_PORT, ENV_WS_HOST, ENV_WS_PORT, ENV_SESSION_ID, } from './lib/constants.js';

package/lib/constants.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Shared transport constants for the LensMCP browser-event bridge.
+ *
+ * The bridge is the single WebSocket endpoint that the injected
+ * `@lensmcp/client-runtime` posts envelopes to. For the Vite plugin this
+ * endpoint is born inside the dev server on an ephemeral port; for every
+ * other host (webpack, Next.js, no-build) it runs as a standalone sidecar
+ * on a FIXED, env-overridable port — so the browser runtime can find it
+ * without a build step baking the URL in.
+ *
+ * `DEFAULT_WS_PORT` must agree between the standalone bridge runner
+ * (`@lensmcp/bridge`) and the no-build client entry
+ * (`@lensmcp/client-runtime/auto`), which lives in a separate
+ * browser-targeted package and re-declares the same literal.
+ */
+export declare const DEFAULT_WS_HOST = "127.0.0.1";
+/** Default fixed port for the standalone bridge sidecar. Override via `LENSMCP_WS_PORT`. */
+export declare const DEFAULT_WS_PORT = 5747;
+/** Env var: bind host for the standalone bridge. */
+export declare const ENV_WS_HOST = "LENSMCP_WS_HOST";
+/** Env var: bind port for the standalone bridge (`0` selects an ephemeral port). */
+export declare const ENV_WS_PORT = "LENSMCP_WS_PORT";
+/** Env var: session id stamped onto every event the bridge publishes. */
+export declare const ENV_SESSION_ID = "LENSMCP_SESSION_ID";
+//# sourceMappingURL=constants.d.ts.map

package/lib/constants.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../../src/lib/constants.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,eAAe,cAAc,CAAC;AAE3C,4FAA4F;AAC5F,eAAO,MAAM,eAAe,OAAO,CAAC;AAEpC,oDAAoD;AACpD,eAAO,MAAM,WAAW,oBAAoB,CAAC;AAC7C,oFAAoF;AACpF,eAAO,MAAM,WAAW,oBAAoB,CAAC;AAC7C,yEAAyE;AACzE,eAAO,MAAM,cAAc,uBAAuB,CAAC"}

package/lib/constants.js

@@ -0,0 +1,24 @@
+/**
+ * Shared transport constants for the LensMCP browser-event bridge.
+ *
+ * The bridge is the single WebSocket endpoint that the injected
+ * `@lensmcp/client-runtime` posts envelopes to. For the Vite plugin this
+ * endpoint is born inside the dev server on an ephemeral port; for every
+ * other host (webpack, Next.js, no-build) it runs as a standalone sidecar
+ * on a FIXED, env-overridable port — so the browser runtime can find it
+ * without a build step baking the URL in.
+ *
+ * `DEFAULT_WS_PORT` must agree between the standalone bridge runner
+ * (`@lensmcp/bridge`) and the no-build client entry
+ * (`@lensmcp/client-runtime/auto`), which lives in a separate
+ * browser-targeted package and re-declares the same literal.
+ */
+export const DEFAULT_WS_HOST = '127.0.0.1';
+/** Default fixed port for the standalone bridge sidecar. Override via `LENSMCP_WS_PORT`. */
+export const DEFAULT_WS_PORT = 5747;
+/** Env var: bind host for the standalone bridge. */
+export const ENV_WS_HOST = 'LENSMCP_WS_HOST';
+/** Env var: bind port for the standalone bridge (`0` selects an ephemeral port). */
+export const ENV_WS_PORT = 'LENSMCP_WS_PORT';
+/** Env var: session id stamped onto every event the bridge publishes. */
+export const ENV_SESSION_ID = 'LENSMCP_SESSION_ID';

package/lib/env-sink.d.ts

@@ -0,0 +1,7 @@
+import type { EnvSink } from './types.js';
+export declare function resolveEnvSink(): EnvSink | null;
+/** Test/embedding hook: drop the memoised sink so the next resolve re-reads env. */
+export declare function resetEnvSinkCache(): void;
+/** Reconnecting NDJSON client over a Unix domain socket (see session/uds.ts). */
+export declare function udsEnvSink(path: string): EnvSink;
+//# sourceMappingURL=env-sink.d.ts.map

package/lib/env-sink.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"env-sink.d.ts","sourceRoot":"","sources":["../../src/lib/env-sink.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AAa1C,wBAAgB,cAAc,IAAI,OAAO,GAAG,IAAI,CAsC/C;AAED,oFAAoF;AACpF,wBAAgB,iBAAiB,IAAI,IAAI,CAExC;AAED,iFAAiF;AACjF,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAgDhD"}

package/lib/env-sink.js

@@ -0,0 +1,112 @@
+import { connect } from 'node:net';
+import { createSocket } from 'node:dgram';
+import { appendFileSync } from 'node:fs';
+/**
+ * Resolve a cross-process event sink from env, mirroring
+ * `@lensmcp/nest-instrumentation`'s `defaultEventSink` so every producer
+ * (Nest app, Vite plugin, standalone bridge) speaks the same transport:
+ *   1. `LENSMCP_EVENT_FILE` — append one JSON line per event.
+ *   2. `LENSMCP_UDS` — Unix domain socket, framed NDJSON, reconnecting.
+ *   3. `LENSMCP_IPC_SOCKET` (`host:port`) — one UDP datagram per event.
+ * Cached after first resolution; returns `null` when none is set.
+ */
+let cachedEnvSink;
+export function resolveEnvSink() {
+    if (cachedEnvSink !== undefined)
+        return cachedEnvSink;
+    const filePath = process.env['LENSMCP_EVENT_FILE'];
+    if (filePath) {
+        cachedEnvSink = (event) => {
+            try {
+                appendFileSync(filePath, JSON.stringify(event) + '\n');
+            }
+            catch {
+                /* swallow */
+            }
+        };
+        return cachedEnvSink;
+    }
+    const udsPath = process.env['LENSMCP_UDS'];
+    if (udsPath) {
+        cachedEnvSink = udsEnvSink(udsPath);
+        return cachedEnvSink;
+    }
+    const socketPath = process.env['LENSMCP_IPC_SOCKET'];
+    if (socketPath) {
+        const [host, portStr] = socketPath.split(':');
+        const port = Number(portStr);
+        if (host && Number.isFinite(port)) {
+            const sock = createSocket('udp4');
+            sock.unref();
+            cachedEnvSink = (event) => {
+                try {
+                    const buf = Buffer.from(JSON.stringify(event));
+                    sock.send(buf, port, host, () => undefined);
+                }
+                catch {
+                    /* swallow */
+                }
+            };
+            return cachedEnvSink;
+        }
+    }
+    cachedEnvSink = null;
+    return null;
+}
+/** Test/embedding hook: drop the memoised sink so the next resolve re-reads env. */
+export function resetEnvSinkCache() {
+    cachedEnvSink = undefined;
+}
+/** Reconnecting NDJSON client over a Unix domain socket (see session/uds.ts). */
+export function udsEnvSink(path) {
+    const queue = [];
+    let sock = null;
+    let connecting = false;
+    const flush = () => {
+        if (!sock || !sock.writable)
+            return;
+        while (queue.length > 0)
+            sock.write(queue.shift());
+    };
+    const open = () => {
+        if (connecting || sock)
+            return;
+        connecting = true;
+        const s = connect(path);
+        s.on('connect', () => {
+            connecting = false;
+            sock = s;
+            flush();
+        });
+        s.on('drain', flush);
+        s.on('error', () => {
+            connecting = false;
+            sock = null;
+        });
+        s.on('close', () => {
+            sock = null;
+        });
+        s.unref();
+    };
+    open();
+    return (event) => {
+        queue.push(JSON.stringify(event) + '\n');
+        while (queue.length > 10000)
+            queue.shift();
+        if (sock && sock.writable) {
+            flush();
+            return;
+        }
+        // Dead socket (server restart) — drop it so open() reconnects.
+        if (sock) {
+            try {
+                sock.destroy();
+            }
+            catch {
+                /* ignore */
+            }
+            sock = null;
+        }
+        open();
+    };
+}

package/lib/event-mappers.d.ts

@@ -0,0 +1,10 @@
+import type { BaseEvent } from '@lensmcp/protocol-types';
+import type { ClientEnvelope } from './types.js';
+/**
+ * Translate a single client-runtime envelope into the normalised
+ * `BaseEvent` consumed by the LensMCP event bus. The bridge publishes
+ * these; reducers in `@lensmcp/<app>` materialise them into
+ * `runtime://browser/*` resources.
+ */
+export declare function envelopeToEvent(env: ClientEnvelope, sessionId?: string): BaseEvent;
+//# sourceMappingURL=event-mappers.d.ts.map

package/lib/event-mappers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"event-mappers.d.ts","sourceRoot":"","sources":["../../src/lib/event-mappers.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yBAAyB,CAAC;AAEzD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAIjD;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,cAAc,EAAE,SAAS,SAAyB,GAAG,SAAS,CAuIlG"}

package/lib/event-mappers.js

@@ -0,0 +1,169 @@
+import { fingerprint, ulid } from '@lensmcp/core';
+const SESSION_ID_PLACEHOLDER = 'pending';
+/**
+ * Translate a single client-runtime envelope into the normalised
+ * `BaseEvent` consumed by the LensMCP event bus. The bridge publishes
+ * these; reducers in `@lensmcp/<app>` materialise them into
+ * `runtime://browser/*` resources.
+ */
+export function envelopeToEvent(env, sessionId = SESSION_ID_PLACEHOLDER) {
+    // Per-tab identity stamped by the client runtime — keys browser://tabs.
+    const tab = env.tabId ? { tabId: env.tabId } : {};
+    switch (env.kind) {
+        case 'error':
+            return {
+                id: ulid(),
+                sessionId,
+                timestamp: env.at,
+                source: 'client-runtime',
+                category: 'runtime',
+                severity: 'error',
+                context: { sessionId, ...tab },
+                fingerprint: fingerprint({
+                    kind: 'runtime',
+                    identity: `error:${normaliseStackTopFrame(env.stack)}`,
+                    file: env.source,
+                    detail: env.message,
+                }),
+                title: env.message,
+                message: env.stack ?? env.message,
+                location: env.source
+                    ? { file: env.source, line: env.lineno, column: env.colno }
+                    : undefined,
+                raw: env,
+            };
+        case 'unhandledrejection':
+            return {
+                id: ulid(),
+                sessionId,
+                timestamp: env.at,
+                source: 'client-runtime',
+                category: 'runtime',
+                severity: 'error',
+                context: { sessionId, ...tab },
+                fingerprint: fingerprint({
+                    kind: 'runtime',
+                    identity: `unhandledrejection:${env.reason.slice(0, 80)}`,
+                }),
+                title: 'Unhandled promise rejection',
+                message: env.reason,
+                raw: env,
+            };
+        case 'console': {
+            const severity = env.level === 'error' ? 'error' : env.level === 'warn' ? 'warning' : 'info';
+            const text = env.args.map(stringify).join(' ');
+            return {
+                id: ulid(),
+                sessionId,
+                timestamp: env.at,
+                source: 'client-runtime',
+                category: 'runtime',
+                severity,
+                context: { sessionId, ...tab },
+                fingerprint: fingerprint({
+                    kind: 'runtime',
+                    identity: `console:${env.level}:${text.slice(0, 80)}`,
+                }),
+                title: `console.${env.level}`,
+                message: text,
+                raw: env,
+            };
+        }
+        case 'fetch': {
+            const failed = env.error !== undefined || (env.status !== undefined && env.status >= 400);
+            return {
+                id: ulid(),
+                sessionId,
+                timestamp: env.at,
+                source: 'client-runtime',
+                category: 'network',
+                severity: failed ? 'error' : 'info',
+                context: { sessionId, ...tab },
+                fingerprint: fingerprint({
+                    kind: 'network',
+                    identity: `${env.method}:${normaliseUrl(env.url)}:${env.status ?? 'err'}`,
+                }),
+                title: `${env.method} ${env.url}${env.status !== undefined ? ` → ${env.status}` : ''}`,
+                message: env.error,
+                relatedUrls: [env.url],
+                raw: env,
+            };
+        }
+        case 'route':
+            return {
+                id: ulid(),
+                sessionId,
+                timestamp: env.at,
+                source: 'client-runtime',
+                category: 'runtime',
+                severity: 'info',
+                context: { sessionId, url: env.url, ...tab },
+                fingerprint: fingerprint({ kind: 'runtime', identity: `route:${env.url}` }),
+                title: `Route → ${env.url}`,
+                raw: env,
+            };
+        case 'ready':
+            return {
+                id: ulid(),
+                sessionId,
+                timestamp: env.at,
+                source: 'client-runtime',
+                category: 'runtime',
+                severity: 'info',
+                context: { sessionId, url: env.url, ...tab },
+                fingerprint: fingerprint({ kind: 'runtime', identity: 'client-ready' }),
+                title: 'Client runtime ready',
+                message: env.userAgent,
+                raw: env,
+            };
+        case 'publish':
+            // Pre-formed publish envelope from in-page instrumentation. Trust
+            // its source/category (the producer is our own injected code); the
+            // reducers gate on those, and the context carries the flow id so
+            // React renders correlate with the originating user action.
+            return {
+                id: ulid(),
+                sessionId,
+                timestamp: env.at,
+                source: env.source,
+                category: env.category,
+                severity: (env.severity ?? 'info'),
+                context: { sessionId, ...tab, ...(env.context ?? {}) },
+                fingerprint: env.fingerprint ?? fingerprint({ kind: 'publish', identity: env.title }),
+                title: env.title,
+                message: env.message,
+                raw: env.raw,
+            };
+    }
+}
+// --- helpers ---
+function normaliseStackTopFrame(stack) {
+    if (!stack)
+        return 'unknown';
+    const lines = stack.split('\n').slice(0, 2);
+    for (const line of lines) {
+        const m = line.match(/at\s+(\S+)/);
+        if (m && m[1])
+            return m[1];
+    }
+    return 'unknown';
+}
+function normaliseUrl(url) {
+    try {
+        const u = new URL(url, 'http://x');
+        return `${u.pathname}`;
+    }
+    catch {
+        return url;
+    }
+}
+function stringify(v) {
+    if (typeof v === 'string')
+        return v;
+    try {
+        return JSON.stringify(v);
+    }
+    catch {
+        return String(v);
+    }
+}

package/lib/server.d.ts

@@ -0,0 +1,56 @@
+import type { BaseEvent } from '@lensmcp/protocol-types';
+import type { EventBus } from '@lensmcp/core';
+import type { EnvSink } from './types.js';
+/**
+ * Where bridge events go. Both are optional:
+ *   • `bus`  — publish in-process (tests, or a host that embeds the bridge
+ *     inside the same process as its reducers).
+ *   • `sink` — forward cross-process over the env transport
+ *     (`LENSMCP_EVENT_FILE` / `LENSMCP_UDS` / `LENSMCP_IPC_SOCKET`).
+ * When neither is given, the sink is resolved lazily from env — the
+ * standalone sidecar case, where the MCP server tails the same file.
+ */
+export interface BridgeDeps {
+    bus?: EventBus;
+    sink?: EnvSink;
+    /** Session id stamped onto each event. */
+    sessionId?: string;
+}
+export interface BridgeServerOptions extends BridgeDeps {
+    /** Bind host. Default `127.0.0.1`. */
+    host?: string;
+    /** Bind port. `0` selects an ephemeral port; default {@link DEFAULT_WS_PORT}. */
+    port?: number;
+}
+export interface BridgeServer {
+    /** The actual bound port (resolved even when `port: 0` was requested). */
+    readonly port: number;
+    readonly host: string;
+    /** Stop accepting connections and release the port. */
+    close(): Promise<void>;
+}
+/**
+ * Build a `publish` function honouring the bus → sink → env-sink → console
+ * precedence. Mirrors the logic the Vite plugin used to inline, lifted here
+ * so the standalone sidecar and the plugin share one path.
+ */
+export declare function makePublisher(deps: BridgeDeps): (event: BaseEvent) => void;
+/**
+ * Parse one raw WebSocket message from the injected client runtime and
+ * forward the resulting event via `publish`. Exported so it can be
+ * exercised over a real WebSocket without booting any bundler.
+ */
+export declare function handleClientEnvelope(raw: string, publish: (event: BaseEvent) => void, sessionId?: string): void;
+/**
+ * Stand up the browser-event bridge: a WebSocket server the injected
+ * `@lensmcp/client-runtime` connects to, forwarding every envelope onto
+ * the event bus (in-process or cross-process). Build-agnostic — the Vite
+ * plugin uses it on an ephemeral port; the standalone sidecar uses it on a
+ * fixed port for webpack / Next.js / no-build hosts.
+ *
+ * Resolves once the server is listening, with the actual bound `port`.
+ */
+export declare function createBridgeServer(options?: BridgeServerOptions): Promise<BridgeServer>;
+/** Allocate an ephemeral free port (used when `port: 0` is requested). */
+export declare function findFreePort(): Promise<number>;
+//# sourceMappingURL=server.d.ts.map

package/lib/server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../../src/lib/server.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yBAAyB,CAAC;AACzD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAI9C,OAAO,KAAK,EAAkB,OAAO,EAAE,MAAM,YAAY,CAAC;AAE1D;;;;;;;;GAQG;AACH,MAAM,WAAW,UAAU;IACzB,GAAG,CAAC,EAAE,QAAQ,CAAC;IACf,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,0CAA0C;IAC1C,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,mBAAoB,SAAQ,UAAU;IACrD,sCAAsC;IACtC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,iFAAiF;IACjF,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,YAAY;IAC3B,0EAA0E;IAC1E,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,uDAAuD;IACvD,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,UAAU,GAAG,CAAC,KAAK,EAAE,SAAS,KAAK,IAAI,CAsB1E;AAED;;;;GAIG;AACH,wBAAgB,oBAAoB,CAClC,GAAG,EAAE,MAAM,EACX,OAAO,EAAE,CAAC,KAAK,EAAE,SAAS,KAAK,IAAI,EACnC,SAAS,CAAC,EAAE,MAAM,GACjB,IAAI,CASN;AAED;;;;;;;;GAQG;AACH,wBAAsB,kBAAkB,CAAC,OAAO,GAAE,mBAAwB,GAAG,OAAO,CAAC,YAAY,CAAC,CAmCjG;AAED,0EAA0E;AAC1E,wBAAgB,YAAY,IAAI,OAAO,CAAC,MAAM,CAAC,CAgB9C"}

package/lib/server.js

@@ -0,0 +1,109 @@
+import { createServer as createNetServer } from 'node:net';
+import { WebSocketServer } from 'ws';
+import { DEFAULT_WS_HOST, DEFAULT_WS_PORT } from './constants.js';
+import { resolveEnvSink } from './env-sink.js';
+import { envelopeToEvent } from './event-mappers.js';
+/**
+ * Build a `publish` function honouring the bus → sink → env-sink → console
+ * precedence. Mirrors the logic the Vite plugin used to inline, lifted here
+ * so the standalone sidecar and the plugin share one path.
+ */
+export function makePublisher(deps) {
+    let resolvedSink;
+    return (event) => {
+        if (deps.bus) {
+            deps.bus.publish(event);
+            return;
+        }
+        if (deps.sink) {
+            deps.sink(event);
+            return;
+        }
+        // Resolve the env sink once, lazily — matches the Nest sink contract.
+        if (resolvedSink === undefined)
+            resolvedSink = resolveEnvSink();
+        if (resolvedSink) {
+            resolvedSink(event);
+            return;
+        }
+        // Standalone fallback so the bridge is debuggable without any transport.
+        if (event.severity === 'error' || event.severity === 'fatal') {
+            console.debug(`[lensmcp-bridge] ${event.severity}: ${event.title}`);
+        }
+    };
+}
+/**
+ * Parse one raw WebSocket message from the injected client runtime and
+ * forward the resulting event via `publish`. Exported so it can be
+ * exercised over a real WebSocket without booting any bundler.
+ */
+export function handleClientEnvelope(raw, publish, sessionId) {
+    let env;
+    try {
+        env = JSON.parse(raw);
+    }
+    catch {
+        return; // ignore malformed
+    }
+    if (!env || typeof env !== 'object' || !('kind' in env))
+        return;
+    publish(envelopeToEvent(env, sessionId));
+}
+/**
+ * Stand up the browser-event bridge: a WebSocket server the injected
+ * `@lensmcp/client-runtime` connects to, forwarding every envelope onto
+ * the event bus (in-process or cross-process). Build-agnostic — the Vite
+ * plugin uses it on an ephemeral port; the standalone sidecar uses it on a
+ * fixed port for webpack / Next.js / no-build hosts.
+ *
+ * Resolves once the server is listening, with the actual bound `port`.
+ */
+export async function createBridgeServer(options = {}) {
+    const host = options.host ?? DEFAULT_WS_HOST;
+    const requestedPort = options.port ?? DEFAULT_WS_PORT;
+    const port = requestedPort === 0 ? await findFreePort() : requestedPort;
+    const publish = makePublisher(options);
+    const wss = new WebSocketServer({ host, port });
+    wss.on('connection', (socket) => {
+        socket.on('message', (raw) => {
+            handleClientEnvelope(raw.toString(), publish, options.sessionId);
+        });
+    });
+    await new Promise((resolve, reject) => {
+        const onError = (err) => {
+            wss.off('listening', onListening);
+            reject(err);
+        };
+        const onListening = () => {
+            wss.off('error', onError);
+            resolve();
+        };
+        wss.once('error', onError);
+        wss.once('listening', onListening);
+    });
+    return {
+        port,
+        host,
+        close: () => new Promise((resolve) => {
+            wss.close(() => resolve());
+        }),
+    };
+}
+/** Allocate an ephemeral free port (used when `port: 0` is requested). */
+export function findFreePort() {
+    return new Promise((resolve, reject) => {
+        const s = createNetServer();
+        s.unref();
+        s.on('error', reject);
+        s.listen(0, () => {
+            const addr = s.address();
+            if (!addr) {
+                s.close();
+                reject(new Error('Could not allocate free port'));
+                return;
+            }
+            const freePort = addr.port;
+            s.close(() => resolve(freePort));
+        });
+    });
+}

package/lib/types.d.ts

@@ -0,0 +1,64 @@
+/**
+ * The wire format spoken between the injected `@lensmcp/client-runtime`
+ * and the bridge's WebSocket. Kept intentionally narrow — the client
+ * runtime *only* emits these envelopes, never anything else.
+ *
+ * This type was originally owned by `@lensmcp/vite-plugin`; it moved here
+ * when the bridge was decoupled from Vite so every host (webpack, Next.js,
+ * no-build) shares one definition. The Vite plugin re-exports it for
+ * backwards compatibility.
+ */
+export type ClientEnvelope = ({
+    kind: 'error';
+    at: number;
+    message: string;
+    stack?: string;
+    source?: string;
+    lineno?: number;
+    colno?: number;
+} | {
+    kind: 'unhandledrejection';
+    at: number;
+    reason: string;
+} | {
+    kind: 'console';
+    at: number;
+    level: 'log' | 'info' | 'warn' | 'error' | 'debug';
+    args: unknown[];
+} | {
+    kind: 'fetch';
+    at: number;
+    method: string;
+    url: string;
+    status?: number;
+    durationMs?: number;
+    ok?: boolean;
+    error?: string;
+} | {
+    kind: 'route';
+    at: number;
+    url: string;
+    from?: string;
+} | {
+    kind: 'ready';
+    at: number;
+    userAgent: string;
+    url: string;
+} | {
+    kind: 'publish';
+    at: number;
+    source: string;
+    category: string;
+    severity?: string;
+    title: string;
+    message?: string;
+    fingerprint?: string;
+    context?: Record<string, unknown>;
+    raw?: unknown;
+}) & {
+    /** Per-tab identity stamped by the client runtime (sessionStorage is per-tab) — keys `browser://tabs`. */
+    tabId?: string;
+};
+/** A cross-process event sink: takes one normalised event and forwards it onward. */
+export type EnvSink = (event: import('@lensmcp/protocol-types').BaseEvent) => void;
+//# sourceMappingURL=types.d.ts.map

package/lib/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/lib/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,MAAM,MAAM,cAAc,GAAG,CACzB;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,EAAE,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,GAChH;IAAE,IAAI,EAAE,oBAAoB,CAAC;IAAC,EAAE,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GAC1D;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,EAAE,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,KAAK,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,OAAO,CAAC;IAAC,IAAI,EAAE,OAAO,EAAE,CAAA;CAAE,GACpG;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,EAAE,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAAC,EAAE,CAAC,EAAE,OAAO,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,GAC9H;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,EAAE,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,GACzD;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,EAAE,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,GAK7D;IACE,IAAI,EAAE,SAAS,CAAC;IAChB,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAClC,GAAG,CAAC,EAAE,OAAO,CAAC;CACf,CACJ,GAAG;IACF,0GAA0G;IAC1G,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB,CAAC;AAEF,qFAAqF;AACrF,MAAM,MAAM,OAAO,GAAG,CAAC,KAAK,EAAE,OAAO,yBAAyB,EAAE,SAAS,KAAK,IAAI,CAAC"}

package/lib/types.js

@@ -0,0 +1 @@
+export {};

package/main.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=main.d.ts.map

package/main.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"main.d.ts","sourceRoot":"","sources":["../src/main.ts"],"names":[],"mappings":""}

package/main.js

@@ -0,0 +1,47 @@
+/**
+ * Standalone bridge sidecar — the build-agnostic entry.
+ *
+ * Run directly (`node bridge.js`) or via `lensmcp bridge`. Stands up the
+ * WebSocket the injected `@lensmcp/client-runtime` connects to, on a FIXED
+ * port (so a no-build / webpack / Next.js host can point at a known URL),
+ * and forwards every browser envelope onto the cross-process event sink
+ * the MCP server tails.
+ *
+ * Env:
+ *   LENSMCP_WS_HOST     bind host (default 127.0.0.1)
+ *   LENSMCP_WS_PORT     bind port (default 5747; `0` = ephemeral)
+ *   LENSMCP_SESSION_ID  session id stamped onto every event (optional)
+ *   LENSMCP_EVENT_FILE  JSONL sink the MCP server ingests (or LENSMCP_UDS /
+ *                       LENSMCP_IPC_SOCKET) — resolved by the env sink.
+ */
+import { DEFAULT_WS_HOST, DEFAULT_WS_PORT, ENV_SESSION_ID, ENV_WS_HOST, ENV_WS_PORT } from './lib/constants.js';
+import { createBridgeServer } from './lib/server.js';
+async function main() {
+    const host = process.env[ENV_WS_HOST] ?? DEFAULT_WS_HOST;
+    const portRaw = process.env[ENV_WS_PORT];
+    const port = portRaw !== undefined && portRaw !== '' ? Number(portRaw) : DEFAULT_WS_PORT;
+    if (!Number.isFinite(port) || port < 0) {
+        console.error(`[lensmcp-bridge] invalid ${ENV_WS_PORT}=${portRaw}`);
+        process.exit(2);
+    }
+    const sessionId = process.env[ENV_SESSION_ID];
+    let server;
+    try {
+        server = await createBridgeServer({ host, port, sessionId });
+    }
+    catch (err) {
+        console.error(`[lensmcp-bridge] failed to listen on ws://${host}:${port} — ${err.message}`);
+        process.exit(1);
+    }
+    console.log(`[lensmcp-bridge] listening on ws://${server.host}:${server.port}`);
+    let closing = false;
+    const shutdown = () => {
+        if (closing)
+            return;
+        closing = true;
+        void server.close().then(() => process.exit(0));
+    };
+    process.on('SIGINT', shutdown);
+    process.on('SIGTERM', shutdown);
+}
+void main();

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@lensmcp/bridge",
+  "version": "1.1.0",
+  "type": "module",
+  "main": "./index.js",
+  "module": "./index.js",
+  "types": "./index.d.ts",
+  "exports": {
+    "./package.json": "./package.json",
+    ".": {
+      "types": "./index.d.ts",
+      "import": "./index.js",
+      "default": "./index.js"
+    },
+    "./server": {
+      "types": "./lib/server.d.ts",
+      "import": "./lib/server.js",
+      "default": "./lib/server.js"
+    }
+  },
+  "dependencies": {
+    "@lensmcp/core": "1.1.0",
+    "@lensmcp/protocol-types": "1.1.0",
+    "tslib": "^2.3.0",
+    "ws": "^8.21.0"
+  },
+  "license": "Apache-2.0",
+  "homepage": "https://github.com/kiwiapps-ltd/lensmcp#readme",
+  "bugs": {
+    "url": "https://github.com/kiwiapps-ltd/lensmcp/issues"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "description": "LensMCP browser-event bridge — a build-agnostic WebSocket server that forwards @lensmcp/client-runtime envelopes onto the LensMCP event bus. Used by the Vite plugin and as a standalone sidecar for webpack / Next.js / no-build hosts.",
+  "keywords": [
+    "lensmcp",
+    "mcp",
+    "observability",
+    "ai-agents",
+    "claude",
+    "websocket",
+    "bridge"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kiwiapps-ltd/lensmcp.git",
+    "directory": "libs/bridge"
+  }
+}