rxjs-leak-finder 0.1.0

package/HOW_IT_WORKS.md

@@ -0,0 +1,214 @@
+# How `rxjs-leak-finder` works
+
+Plain words first. The technical bits are at the bottom.
+
+---
+
+## The problem
+
+In an Angular app, you write code like this:
+
+```ts
+ngOnInit() {
+  interval(1000).subscribe(n => this.tick = n);
+}
+```
+
+When the user navigates away from this page, Angular destroys the component. But the `interval` doesn't know that. It keeps running. The callback keeps a reference to `this`. Garbage collection can't free the component. **That's a memory leak.**
+
+These leaks are usually invisible. The app feels a little slower over time, then suddenly very slow, then crashes. By then you have no idea which page introduced it.
+
+What we want: a list of subscriptions that *should* have been cleaned up but weren't, with enough information to fix them — the **component**, the **file:line** of the subscribe, and a hint about **why** it leaked.
+
+---
+
+## The trick: every Subscription gets a name tag
+
+When you call `someObservable.subscribe(...)`, RxJS returns a `Subscription` object. Normally it's anonymous: you can't tell where it came from once it exists.
+
+The detector replaces RxJS's `subscribe` method with a wrapper. Every time anyone subscribes:
+
+1. Call the original `subscribe`. Get the Subscription back.
+2. Capture a stack trace — `new Error().stack` is JavaScript's way of asking "who's calling me right now?".
+3. Attach a hidden property `__sw_meta` to the Subscription, holding: id, timestamp, current route, the stack trace, what kind of Observable it was.
+4. Also patch the Subscription's `unsubscribe` so we know when it was cleaned up.
+
+Now every Subscription carries its own name tag. You can ask any one of them: "Where did you come from? Were you ever cleaned up?"
+
+```
+┌──────────────────────────────────────────────────┐
+│ user code                                        │
+│   interval(1000).subscribe(...)                  │
+│                       │                          │
+│                       ▼                          │
+│   ╭─────────── patchedSubscribe ─────────────╮   │
+│   │ 1. call real subscribe                   │   │
+│   │ 2. snapshot the stack                    │   │
+│   │ 3. attach __sw_meta to the Subscription  │   │
+│   │ 4. ensure unsubscribe is patched too     │   │
+│   ╰──────────────────────────────────────────╯   │
+└──────────────────────────────────────────────────┘
+```
+
+The patch lives in `src/runtime/patch.ts`. About 50 lines.
+
+---
+
+## Recording a session
+
+Patching every `subscribe()` is cheap, but storing every tag forever would be a lot. So the detector only *remembers* tags during a recording session. A session has three states:
+
+| State | What happens |
+|---|---|
+| idle | Patch is installed. Tags are attached to Subscriptions. None are stored. |
+| recording | Every new tag is added to the recorder's map. Route changes are recorded. |
+| stopped | The session is sent to the dashboard (a JSON POST), then the map is cleared. |
+
+You start a session by clicking **● Rec** in the floating widget. Stop with **■ Stop**. The widget is in `src/runtime/widget.ts` — three small DOM nodes pinned to `position: fixed; top-right`. Clicking through this calls into the controller (`src/runtime/enable.ts`).
+
+The recorder lives in `src/runtime/recorder.ts`. It's a plain object with a few methods:
+
+- `start()` — clear, mark recording.
+- `onSubscribe(sub, obs, stack)` — store a tag.
+- `onUnsubscribe(sub)` — mark the tag as closed.
+- `stop()` — return the report and clear.
+
+No RxJS, no Angular, no DOM. Just data.
+
+---
+
+## Tracking which route you're on
+
+A subscribe on `/products` is a leak only if you've left `/products`. So we need to know what route was active when each tag was captured, and what route changes happened during the session.
+
+The Router's events are framework-specific. To stay framework-agnostic, we patch the **History API** instead: `pushState`, `replaceState`, and the `popstate` event. Every Angular Router (and Vue, and SvelteKit, and plain `<a>` links) eventually goes through these. Whenever any of them fires, we record `{ from, to }`.
+
+This lives in `src/runtime/route-tracker.ts`.
+
+---
+
+## Getting the report to the dashboard
+
+When you click **■ Stop**:
+
+1. The recorder returns a `RecordingReport`: meta + navigations + array of subscription tags.
+2. `sendReport()` (`src/runtime/transport.ts`) tries `POST /report` to `http://localhost:7654`.
+3. **If the dashboard is offline** the report is stashed in `localStorage`. Next time the app boots, `flushQueue()` retries.
+
+This means you can record without the dashboard running, then start it later and not lose the session.
+
+---
+
+## The dashboard server
+
+`npx rxjs-leak-finder dashboard` starts a tiny Node HTTP server (`src/cli/dashboard-server.ts`). It has five endpoints:
+
+| Endpoint | Purpose |
+|---|---|
+| `POST /report` | Save a recording report as `.rld/<timestamp>-<id>.json`. |
+| `GET /sessions` | List all `.rld/*.json` files. |
+| `GET /sessions/:id` | Read one report. |
+| `GET /source-maps?url=…` | Server-side fetch of source-map files (CORS bypass for the SPA). |
+| `POST /open` | Spawn the user's editor at `<file>:<line>:<col>`. |
+| `GET /*` | Serve the built dashboard SPA (Lit + Vite). |
+
+Reports are plain JSON files. You can commit them, share them, version them. The server doesn't run any analysis — that happens entirely in the dashboard SPA.
+
+---
+
+## Resolving stacks to file:line
+
+The stack trace captured at subscribe time looks like:
+
+```
+at patchedSubscribe (http://localhost:4200/vite/deps/rxjs-leak-finder.js:120:23)
+at SimpleLeakPage.ngOnInit (http://localhost:4200/src/app/pages/simple-leak.page.ts:24:8)
+at callHookInternal (http://localhost:4200/vite/deps/@angular_core.js:4140:14)
+…
+```
+
+To turn `http://localhost:4200/src/app/pages/simple-leak.page.ts:24:8` into the actual source file:line, the dashboard:
+
+1. Fetches the JS file from the server.
+2. Reads the `//# sourceMappingURL=…` comment at the bottom.
+3. Fetches the source map.
+4. Asks Mozilla's `source-map` library: "what original position maps to line 24, column 8?"
+
+This work happens in the dashboard SPA (`src/dashboard/app.ts`) because source maps are big and we want the server stateless. The WASM file for `source-map` (~48 kB) is shipped with the dashboard build.
+
+---
+
+## Classifying leaks
+
+A "leak" is a subscription that:
+
+- Was created during the recording window.
+- Was on a route the user has since *left* (per the navigation log).
+- Has at least one non-framework frame in its stack.
+- Was never unsubscribed.
+
+That's the binary classification. Beyond that, the dashboard adds a **kind** so you know *why* it likely leaked. Heuristics from `packages/analyzer-core/src/leak-classifier.ts`:
+
+| Kind | How we recognize it |
+|---|---|
+| `nested-subscribe` | Two or more `patchedSubscribe` frames in the same stack. |
+| `async-init` | TS's `__async` / `ZoneAwarePromise` helper between the subscribe and a `ngOnInit` frame. |
+| `ng-init` | The top non-framework frame is `*.ngOnInit`. |
+| `global-event` | `fromEvent` / `addEventListener` in the stack. |
+| `timer` | `interval` / `timer` in the stack, or the observable kind is plain `Observable`. |
+| `subject` | The observable's `constructor.name` includes `Subject`. |
+
+Heuristics are best-effort and conservative. When in doubt, kind = `unknown`.
+
+The same module exposes `extractComponentName(frames)` (scans frames for a class name matching `*Component` / `*Directive` / `*Page` / `*Dialog`) and `stripDetectorFrames(frames)` (drops the detector's own `patchedSubscribe` from the displayed stack).
+
+---
+
+## Why no Chrome extension?
+
+A Chrome extension would need DevTools access, content-script injection, message passing, a separate manifest, store reviews. For something this scoped — a dev-mode tool you run yourself — a floating widget + local HTTP server is dramatically simpler. No installs beyond `npm install`. Works in any browser, including headless Chrome.
+
+The trade-off: no heap-snapshot integration. That's the one capability a DevTools extension would unlock (walking retainer chains to *prove* what's holding the subscription). The analyzer-core package has that code (`analyze.ts`, `heap-parser.ts`, `retainer-walker.ts`), but the dashboard doesn't currently invoke it — recording-only is good enough for ~95% of leaks. If you want retainer info, save a `.heapsnapshot` and feed it into `analyzer-core` programmatically.
+
+---
+
+## Package layout
+
+```
+rxjs-leak-finder (published)
+├─ src/runtime/      ← code that ships into your Angular bundle
+│  ├─ enable.ts        the public entry point
+│  ├─ patch.ts         monkey-patches Observable.prototype.subscribe
+│  ├─ recorder.ts      session state machine
+│  ├─ route-tracker.ts patches History API
+│  ├─ widget.ts        floating UI in your app
+│  └─ transport.ts     fetch with offline localStorage queue
+├─ src/cli/          ← node-only, runs the dashboard server
+│  ├─ index.ts         arg parsing + lifecycle
+│  └─ dashboard-server.ts
+└─ src/dashboard/    ← the SPA (Lit + Vite, bundled at build)
+   └─ app.ts
+
+@rld/analyzer-core (workspace dep, bundled into the dashboard)
+├─ types.ts             shared types
+├─ leak-classifier.ts   leakKind + componentName heuristics
+├─ source-map-resolver.ts
+├─ classifier.ts        verdict (leak / long-lived / framework-noise)
+├─ heap-parser.ts       (optional) V8 heap snapshot parser
+└─ retainer-walker.ts   (optional) walks retainer chains from a heap snapshot
+
+@rld/panel-ui (workspace dep, bundled into the dashboard)
+└─ Lit components: leak-list, leak-row, leak-detail, leak-summary, stack-frame
+```
+
+`@rld/analyzer-core` and `@rld/panel-ui` are devDependencies — Vite inlines them at build time, so users only install `rxjs-leak-finder`.
+
+---
+
+## Things that surprised me
+
+- **`new Error().stack` is the cheapest reliable stack trace.** No async stacks needed; the JS engine produces it eagerly.
+- **History API patching is more universal than Router hooks.** Every framework eventually calls `pushState`. Routers are an abstraction over the same thing.
+- **Vite renames RxJS internals at dev time.** `BehaviorSubject` becomes `BehaviorSubject2`, so we can't use `instanceof Subject` reliably. We use `constructor.name` instead.
+- **The first frame of every captured stack is always `patchedSubscribe`.** We strip it before display.
+- **`takeUntilDestroyed()` after an `await` silently no-ops.** This is the bug that makes `async ngOnInit` so dangerous; the `async-init` kind catches it.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Florin Ciocirlan
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,190 @@
+# rxjs-leak-finder
+
+> Find leaked RxJS subscriptions in your Angular dev-mode app.
+> One line in `main.ts`, a floating widget, a local dashboard. No Chrome extension.
+
+[![npm](https://img.shields.io/npm/v/rxjs-leak-finder.svg)](https://www.npmjs.com/package/rxjs-leak-finder)
+[![license](https://img.shields.io/npm/l/rxjs-leak-finder.svg)](./LICENSE)
+
+---
+
+## What it does
+
+You add one line to `main.ts`. The detector patches `Observable.prototype.subscribe` and starts watching. You navigate around your app and click **Stop** in the floating widget. The detector POSTs the report to a local dashboard, which highlights subscriptions that were created on a route you left without ever being unsubscribed. Each leak shows the **component**, the **file:line** where it was subscribed, and a category (`nested-subscribe`, `async-init`, `ng-init`, `global-event`, `timer`, `subject`).
+
+It works on any Angular dev-mode app — standalone or NgModule, signals or RxJS, ChangeDetectionStrategy.OnPush or default.
+
+See [HOW_IT_WORKS.md](./HOW_IT_WORKS.md) for the design and the bits that make this possible.
+
+---
+
+## Install
+
+```sh
+npm install --save-dev rxjs-leak-finder
+# or
+pnpm add -D rxjs-leak-finder
+# or
+yarn add -D rxjs-leak-finder
+```
+
+---
+
+## Wire it up
+
+Add one block to your Angular `main.ts`. Use `isDevMode()` so it never reaches production:
+
+```ts
+import { isDevMode } from '@angular/core';
+import { bootstrapApplication } from '@angular/platform-browser';
+import { Observable } from 'rxjs';
+import { enableRxjsLeakDetector } from 'rxjs-leak-finder';
+import { AppComponent } from './app/app.component';
+import { appConfig } from './app/app.config';
+
+if (isDevMode()) {
+  enableRxjsLeakDetector(Observable);
+}
+
+bootstrapApplication(AppComponent, appConfig);
+```
+
+That's it. Reload — there's a floating widget in the top-right of your app.
+
+> Pass **your** `Observable` (the one your app imports from `rxjs`). Different bundles can produce different `Observable` classes; passing yours guarantees the right prototype gets patched.
+
+---
+
+## Use it
+
+In one terminal, run your Angular app (`ng serve` / `npm start`).
+
+In another terminal, start the dashboard:
+
+```sh
+npx rxjs-leak-finder dashboard
+# → http://localhost:7654
+```
+
+The dashboard auto-opens in your browser. To record a session:
+
+1. In your app: click **● Rec** on the floating widget.
+2. Navigate to the route you want to test.
+3. Navigate **away** to another route (the route change is the "boundary").
+4. Click **■ Stop**.
+5. Reload the dashboard — the session appears in the list. Click it to see the leaks.
+
+A leak is any subscription that was created on the route you left, never unsubscribed, and has at least one frame in your own code (framework subscriptions are filtered out).
+
+---
+
+## What the dashboard shows
+
+- **KPI cards**: total leaks, subscriptions scanned, framework subscriptions ignored, long-lived service subscriptions.
+- **Breakdowns**: by leak kind, by route, by component.
+- **Search**: filter rows by component, file, route, observable kind, leak kind.
+- **Filter chips**: click a kind or a route to narrow down.
+- **Each row**: component name + observable kind on top, `file:line:col` (clickable, opens in your editor) underneath, plus colored badges for route and leak kind.
+- **Expanded row**: full resolved stack trace; click any frame to jump to it in your editor.
+
+### Leak kinds
+
+| Kind | What triggers it |
+|---|---|
+| `nested-subscribe` | A `subscribe()` was called inside another `subscribe()`. Use `switchMap` / `mergeMap` instead. |
+| `async-init` | `subscribe()` ran after an `await` in an `async ngOnInit` — outside the injection context, so `takeUntilDestroyed()` silently no-ops. |
+| `ng-init` | Plain `subscribe()` in `ngOnInit` with no teardown. |
+| `global-event` | `fromEvent(window, …)` or `addEventListener` — survives navigation because the source outlives the component. |
+| `timer` | `interval` / `timer` subscription with no teardown. |
+| `subject` | Subscribed to a module-level or service-level `Subject` / `BehaviorSubject` without teardown. |
+
+---
+
+## Open in editor
+
+Clicking `file:line:col` POSTs to the dashboard server, which shells out to your editor. Default is VS Code (`code -g file:line:col`). To pick another editor:
+
+```sh
+RLD_EDITOR=idea     npx rxjs-leak-finder dashboard   # IntelliJ
+RLD_EDITOR=webstorm npx rxjs-leak-finder dashboard   # WebStorm
+RLD_EDITOR=cursor   npx rxjs-leak-finder dashboard   # Cursor
+RLD_EDITOR=subl     npx rxjs-leak-finder dashboard   # Sublime
+```
+
+Recognized: `code`, `cursor`, `codium`, `idea`, `webstorm`, `pycharm`, `phpstorm`, `goland`, `rubymine`, `clion`, `datagrip`, `fleet`, `subl`, `sublime`, `atom`, `vim`, `nvim`, `emacs`. The right CLI flag is picked per editor. If the launcher isn't on PATH, the server falls back to the OS opener (no jump-to-line).
+
+To make it permanent: `echo 'export RLD_EDITOR=idea' >> ~/.zshrc`.
+
+---
+
+## Config
+
+```ts
+enableRxjsLeakDetector(Observable, {
+  /** Don't mount the floating widget. You can still start/stop via the controller. */
+  disableWidget: false,
+  /** Where the dashboard listens. */
+  dashboardUrl: 'http://localhost:7654',
+  /** Disable everything (overrides the others). */
+  enabled: true,
+});
+```
+
+The call returns a `LeakDetectorController`:
+
+```ts
+const controller = enableRxjsLeakDetector(Observable);
+controller?.start();
+// …navigate…
+await controller?.stop();    // POSTs the report
+controller?.teardown();      // remove the patch + widget (rarely needed)
+```
+
+---
+
+## CLI
+
+```sh
+rxjs-leak-finder dashboard [options]
+
+  --port=<n>     Port (default 7654)
+  --cwd=<path>   Where to write .rld/ session files (default cwd)
+  --no-open      Don't auto-open the browser
+  --help, -h     Show this help
+```
+
+Sessions are stored as `.rld/*.json` in the working directory. Add `.rld/` to `.gitignore`.
+
+---
+
+## FAQ
+
+**Will it break my production build?**
+No — wrap the call in `if (isDevMode())`. The detector still ships in your bundle as a devDependency. The runtime is small (~5 kB gzipped) and inert until `enableRxjsLeakDetector` is called.
+
+**Does it work with NgRx, RxJS interop, signals?**
+Yes. It patches the `Observable` prototype, so any subscription created from any observable in your app is tracked. Signals don't create RxJS subscriptions, so they're invisible to the detector — that's correct, since signals can't leak the way subscriptions can.
+
+**Does it work in production?**
+Don't run it in production. The detector captures stack traces on every `subscribe()`, which has measurable overhead.
+
+**False positives?**
+The biggest source of noise is long-lived service subscriptions (singletons that *should* live for the app's lifetime). The detector lists those separately as `long-lived`, not as leaks. If you see a real subscription marked as a leak that you believe is correct, open an issue with the session JSON from `.rld/`.
+
+**No leak shows up?**
+Three common causes:
+1. You didn't click **● Rec** before triggering the leak.
+2. You didn't navigate away (the detector only flags subscriptions on routes you've *left*).
+3. The subscription is in a framework path (`node_modules/`, polyfills, zone.js); those are intentionally filtered.
+
+---
+
+## Architecture in one sentence
+
+The detector monkey-patches `Observable.prototype.subscribe` to tag every Subscription with a stack trace, the recorder tracks route changes via the History API, the dashboard server stores reports as JSON, and the dashboard SPA classifies each leak using stack-trace heuristics. For the full story, see [HOW_IT_WORKS.md](./HOW_IT_WORKS.md).
+
+---
+
+## License
+
+MIT © Florin Ciocirlan

package/dist/cli/dashboard-server.d.ts

@@ -0,0 +1,11 @@
+export type ServerHandle = {
+    url: string;
+    port: number;
+    close: () => Promise<void>;
+};
+export type StartServerOptions = {
+    port: number;
+    cwd: string;
+    staticDir: string | undefined;
+};
+export declare function startServer(opts: StartServerOptions): Promise<ServerHandle>;

package/dist/cli/dashboard-server.js

@@ -0,0 +1,241 @@
+import { createServer } from 'node:http';
+import { mkdirSync, writeFileSync, readdirSync, readFileSync, existsSync, statSync } from 'node:fs';
+import { join, resolve, extname, isAbsolute } from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { spawn } from 'node:child_process';
+import { platform } from 'node:os';
+const MIME = {
+    '.html': 'text/html; charset=utf-8',
+    '.js': 'application/javascript; charset=utf-8',
+    '.css': 'text/css; charset=utf-8',
+    '.json': 'application/json; charset=utf-8',
+    '.svg': 'image/svg+xml',
+};
+export async function startServer(opts) {
+    const rldDir = join(opts.cwd, '.rld');
+    if (!existsSync(rldDir))
+        mkdirSync(rldDir, { recursive: true });
+    const server = createServer((req, res) => handleRequest(req, res, opts, rldDir));
+    await new Promise((resolveStart) => server.listen(opts.port, () => resolveStart()));
+    const addr = server.address();
+    const port = typeof addr === 'object' && addr ? addr.port : opts.port;
+    return {
+        url: `http://localhost:${port}`,
+        port,
+        close: () => new Promise(r => server.close(() => r())),
+    };
+}
+function setCors(res) {
+    res.setHeader('access-control-allow-origin', '*');
+    res.setHeader('access-control-allow-methods', 'GET,POST,OPTIONS');
+    res.setHeader('access-control-allow-headers', 'content-type');
+}
+async function handleRequest(req, res, opts, rldDir) {
+    setCors(res);
+    if (req.method === 'OPTIONS') {
+        res.writeHead(204).end();
+        return;
+    }
+    const url = new URL(req.url ?? '/', 'http://localhost');
+    const pathname = url.pathname;
+    if (req.method === 'POST' && pathname === '/report') {
+        return handleReport(req, res, rldDir);
+    }
+    if (req.method === 'POST' && pathname === '/open') {
+        return handleOpen(req, res, opts.cwd);
+    }
+    if (req.method === 'GET' && pathname === '/sessions') {
+        return handleSessionsList(res, rldDir);
+    }
+    if (req.method === 'GET' && pathname.startsWith('/sessions/')) {
+        return handleSessionGet(res, rldDir, pathname.slice('/sessions/'.length));
+    }
+    if (req.method === 'GET' && pathname === '/source-maps') {
+        const mapUrl = url.searchParams.get('url');
+        const raw = url.searchParams.get('raw') === '1';
+        return handleSourceMapProxy(res, mapUrl, raw);
+    }
+    if (req.method === 'GET' && opts.staticDir) {
+        return handleStatic(res, opts.staticDir, pathname);
+    }
+    res.writeHead(404).end('Not found');
+}
+async function handleOpen(req, res, cwd) {
+    const body = await readBody(req);
+    let payload;
+    try {
+        payload = JSON.parse(body);
+    }
+    catch {
+        res.writeHead(400).end('Invalid JSON');
+        return;
+    }
+    const resolved = resolveSourcePath(payload.file ?? '', cwd);
+    if (!resolved) {
+        res.writeHead(404, { 'content-type': 'application/json' });
+        res.end(JSON.stringify({ ok: false, error: `Could not resolve ${payload.file}` }));
+        return;
+    }
+    const line = Math.max(1, Number(payload.line) || 1);
+    const column = Math.max(1, Number(payload.column) || 1);
+    const opened = await openInEditor(resolved, line, column);
+    res.writeHead(opened.ok ? 200 : 500, { 'content-type': 'application/json' });
+    res.end(JSON.stringify(opened));
+}
+function resolveSourcePath(rawFile, cwd) {
+    if (!rawFile)
+        return null;
+    // Strip common bundler prefixes that show up in source-mapped paths.
+    let f = rawFile
+        .replace(/^webpack:\/\/\/?/, '')
+        .replace(/^vite:\/?/, '')
+        .replace(/^\.\//, '');
+    // Some bundles prefix with the project name: `./projectName/src/...`
+    if (isAbsolute(f) && existsSync(f))
+        return f;
+    const candidates = [
+        resolve(cwd, f),
+        resolve(cwd, 'src', f),
+        resolve(cwd, f.replace(/^[^/]+\//, '')), // strip first path segment
+    ];
+    for (const c of candidates) {
+        if (existsSync(c))
+            return c;
+    }
+    return null;
+}
+function buildEditorCommand(absPath, line, column) {
+    const editor = (process.env.RLD_EDITOR || 'code').trim();
+    // Last path segment in case RLD_EDITOR points to a full path like /usr/local/bin/idea
+    const bin = editor.split('/').pop().toLowerCase();
+    // JetBrains IDEs: `idea --line <n> --column <n> <file>` (or `webstorm`, `pycharm`, etc.)
+    if (/^(idea|webstorm|pycharm|rubymine|phpstorm|goland|rustrover|clion|appcode|datagrip|fleet)$/.test(bin)) {
+        return { cmd: editor, args: ['--line', String(line), '--column', String(column), absPath] };
+    }
+    // Sublime Text / Atom: `subl file:line:col`
+    if (/^(subl|sublime|atom)$/.test(bin)) {
+        return { cmd: editor, args: [`${absPath}:${line}:${column}`] };
+    }
+    // Vim / Neovim / Emacs (terminal — works if user has a terminal available):
+    if (/^(vim|nvim)$/.test(bin)) {
+        return { cmd: editor, args: [`+${line}`, absPath] };
+    }
+    if (/^emacs$/.test(bin)) {
+        return { cmd: editor, args: [`+${line}:${column}`, absPath] };
+    }
+    // Default: VS Code / Cursor / Codium — all accept `code -g file:line:col`.
+    return { cmd: editor, args: ['-g', `${absPath}:${line}:${column}`] };
+}
+function openInEditor(absPath, line, column) {
+    return new Promise((resolveP) => {
+        const { cmd, args } = buildEditorCommand(absPath, line, column);
+        const fallback = () => {
+            const os = platform();
+            const openerCmd = os === 'darwin' ? 'open' : os === 'win32' ? 'explorer' : 'xdg-open';
+            const child = spawn(openerCmd, [absPath], { stdio: 'ignore', detached: true });
+            child.on('error', (err) => resolveP({ ok: false, error: err.message }));
+            child.on('spawn', () => { child.unref(); resolveP({ ok: true, cmd: openerCmd }); });
+        };
+        const child = spawn(cmd, args, { stdio: 'ignore', detached: true });
+        child.on('error', () => fallback());
+        child.on('spawn', () => { child.unref(); resolveP({ ok: true, cmd: `${cmd} ${args.join(' ')}` }); });
+    });
+}
+async function handleReport(req, res, rldDir) {
+    const body = await readBody(req);
+    let report;
+    try {
+        report = JSON.parse(body);
+    }
+    catch {
+        res.writeHead(400).end('Invalid JSON');
+        return;
+    }
+    const recordingId = report?.meta?.recordingId ?? randomUUID();
+    const fileName = `${new Date().toISOString().replace(/[:.]/g, '-')}-${recordingId}.json`;
+    writeFileSync(join(rldDir, fileName), JSON.stringify(report, null, 2));
+    res.writeHead(200, { 'content-type': 'application/json' });
+    res.end(JSON.stringify({ ok: true, fileName }));
+}
+function handleSessionsList(res, rldDir) {
+    const files = readdirSync(rldDir).filter(f => f.endsWith('.json'));
+    const list = files.map(f => {
+        const parsed = JSON.parse(readFileSync(join(rldDir, f), 'utf8'));
+        return {
+            id: f.replace(/\.json$/, ''),
+            fileName: f,
+            recordingId: parsed?.meta?.recordingId ?? null,
+            createdAt: parsed?.meta?.startedAtMs ?? null,
+            subscriptionCount: parsed?.subscriptions?.length ?? 0,
+        };
+    });
+    res.writeHead(200, { 'content-type': 'application/json' });
+    res.end(JSON.stringify(list));
+}
+function handleSessionGet(res, rldDir, id) {
+    const safe = id.replace(/[^a-zA-Z0-9._-]/g, '');
+    const file = join(rldDir, `${safe}.json`);
+    if (!existsSync(file)) {
+        res.writeHead(404).end('Not found');
+        return;
+    }
+    res.writeHead(200, { 'content-type': 'application/json' });
+    res.end(readFileSync(file));
+}
+async function handleSourceMapProxy(res, mapUrl, raw = false) {
+    if (!mapUrl) {
+        res.writeHead(400).end('Missing url param');
+        return;
+    }
+    try {
+        const upstream = await fetch(mapUrl);
+        if (!upstream.ok) {
+            console.log(`[source-maps] ${mapUrl} → ${upstream.status}`);
+            res.writeHead(upstream.status).end();
+            return;
+        }
+        const text = await upstream.text();
+        if (raw) {
+            res.writeHead(200, { 'content-type': 'text/plain' });
+            res.end(text);
+            return;
+        }
+        res.writeHead(200, { 'content-type': 'application/json' });
+        res.end(text);
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        console.log(`[source-maps] ${mapUrl} → fetch threw: ${msg}`);
+        res.writeHead(502).end(msg);
+    }
+}
+function handleStatic(res, staticDir, pathname) {
+    const filePath = resolve(staticDir, pathname === '/' ? 'index.html' : pathname.slice(1));
+    if (!filePath.startsWith(resolve(staticDir))) {
+        res.writeHead(403).end();
+        return;
+    }
+    if (!existsSync(filePath) || !statSync(filePath).isFile()) {
+        // SPA fallback to index.html
+        const index = resolve(staticDir, 'index.html');
+        if (existsSync(index)) {
+            res.writeHead(200, { 'content-type': MIME['.html'] });
+            res.end(readFileSync(index));
+            return;
+        }
+        res.writeHead(404).end();
+        return;
+    }
+    const ext = extname(filePath).toLowerCase();
+    res.writeHead(200, { 'content-type': MIME[ext] ?? 'application/octet-stream' });
+    res.end(readFileSync(filePath));
+}
+function readBody(req) {
+    return new Promise((resolve, reject) => {
+        let data = '';
+        req.on('data', chunk => { data += chunk; });
+        req.on('end', () => resolve(data));
+        req.on('error', reject);
+    });
+}
+//# sourceMappingURL=dashboard-server.js.map