@watchforge/browser 0.1.0 → 0.1.3

package/README.md

@@ -1,142 +1,62 @@
-# WatchForge JavaScript SDK
+# WatchForge JavaScript SDK (`@watchforge/browser`)
 
-Official JavaScript SDK for WatchForge error tracking and monitoring.
+Browser and Node SDK for WatchForge. **One call to `register()`** turns on automatic error reporting—no manual `try/catch` required for typical crashes.
 
-## Installation
+## What this package does *not* require
 
-### Option 1: Copy SDK files directly
+- **No Material UI (MUI)** and no other UI library. If `npm install` fails with errors about `@mui/material` or `@mui/lab`, that conflict comes from **your app’s existing dependencies**, not from WatchForge. Fix or align MUI versions in your project, or install with:
 
-Copy the `src/` folder into your project and import:
+  ```bash
+  npm install @watchforge/browser --legacy-peer-deps
+  ```
 
-```javascript
-import { register, captureException, captureMessage } from './path/to/sdk/index.js';
-```
+- **React is optional.** It is only needed if you use the React `ErrorBoundary` export from `@watchforge/browser/react`. Plain JavaScript, Vue, Angular, etc. can use the main entry without installing React.
 
-### Option 2: Install via npm (when published)
+## Installation
 
 ```bash
 npm install @watchforge/browser
 ```
 
-## Quick Start
-
-```javascript
-import { register, captureException, captureMessage, flush } from '@watchforge/browser';
-
-// Initialize the SDK
-register({
-  endpoint: "https://PUBLIC_KEY@localhost:8001/PROJECT_ID",
-  app_env: "development",
-  debug: true  // Set to false in production
-});
-
-// Capture an exception
-try {
-  // your code
-} catch (error) {
-  captureException(error);
-}
-
-// Capture a message
-captureMessage("Something happened", "info");
-
-// Manually flush events (optional - auto-flushes after 5s or 10 events)
-flush();
-```
-
-## API Reference
+## Quick start (all most apps need)
 
-### `register(options)`
+Call **`register()` once** as early as possible (e.g. app entry / main bundle), with your **DSN** from the WatchForge project settings.
 
-Initialize the WatchForge SDK.
-
-**Parameters:**
-- `endpoint` (string, required): Your WatchForge endpoint URL
-- `app_env` (string, optional): Application environment (default: "production")
-- `debug` (boolean, optional): Enable debug logging (default: false)
-
-**Example:**
 ```javascript
+import { register } from '@watchforge/browser';
+
 register({
-  endpoint: "https://abc123@watchforge.io/project-uuid",
-  app_env: "production",
-  debug: false
+  dsn: 'https://PUBLIC_KEY@your-host/PROJECT_ID',
+  app_env: 'production',  // e.g. development | staging | production
+  debug: false,           // true while integrating locally
 });
 ```
 
-### `captureException(error)`
-
-Capture an exception/error.
-
-**Parameters:**
-- `error` (Error): The error object to capture
-
-**Example:**
-```javascript
-try {
-  riskyOperation();
-} catch (error) {
-  captureException(error);
-}
-```
-
-### `captureMessage(message, level)`
-
-Capture a custom message.
-
-**Parameters:**
-- `message` (string): The message to capture
-- `level` (string, optional): Message level - "info", "warning", or "error" (default: "info")
-
-**Example:**
-```javascript
-captureMessage("User logged in", "info");
-captureMessage("Rate limit approaching", "warning");
-captureMessage("Critical system failure", "error");
-```
-
-### `flush()`
-
-Manually flush all buffered events to the backend immediately.
+That’s enough for **automatic** reporting in the browser and Node:
 
-**Example:**
-```javascript
-captureMessage("Important event");
-flush();  // Send immediately
-```
+| Where | What gets reported automatically |
+|--------|----------------------------------|
+| **Browser** | Uncaught errors (`window.onerror`), unhandled promise rejections, plus breadcrumbs (console, clicks, navigation) to give context around failures |
+| **Node** | `uncaughtException` and `unhandledRejection` |
 
-## Automatic Error Capture
+You do **not** need to call `captureException` in normal flows—those global handlers already send errors to WatchForge.
 
-The SDK automatically captures:
-- **Unhandled errors** via `window.onerror`
-- **Unhandled promise rejections** via `window.onunhandledrejection`
+## How events reach WatchForge
 
-No additional setup required!
+After `register()`, the SDK buffers events and sends them to your ingestion endpoint derived from the DSN. Failures are grouped and shown in the WatchForge UI like other SDKs.
 
-## Event Buffering
+## Optional: copy files instead of npm
 
-Events are automatically buffered and sent:
-- When 10 events accumulate, OR
-- After 5 seconds of inactivity
+You can copy the `src/` folder into your repo and import from your path (same `register` API).
 
-Use `flush()` to send immediately.
+## Advanced (optional APIs)
 
-## Backward Compatibility
+For manual reporting (handled errors, custom messages, immediate flush), see **`CONFIGURATION_GUIDE.md`** in this repository. The main package also exports `captureException`, `captureMessage`, and `flush` if you need them—**they are not required** for automatic error capture.
 
-The old `init()` function is still available but deprecated:
-
-```javascript
-// Old (deprecated)
-init({ dsn: "...", environment: "production" });
-
-// New (recommended)
-register({ endpoint: "...", app_env: "production" });
-```
+### Deprecated
 
-## Browser Support
+`init()` is deprecated; use `register()` with a `dsn` field.
 
-- Chrome/Edge (latest)
-- Firefox (latest)
-- Safari (latest)
+## Browser support
 
-Requires ES6 modules support.
+Modern browsers with ES modules. For **React** error boundaries, import from `@watchforge/browser/react`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@watchforge/browser",
-  "version": "0.1.0",
+  "version": "0.1.3",
   "main": "./src/index.js",
   "description": "WatchForge JavaScript SDK for Node.js, Express.js, and React",
   "license": "MIT",
@@ -32,6 +32,11 @@
   "peerDependencies": {
     "react": ">=16.8.0"
   },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    }
+  },
   "browser": {
     "http": false,
     "https": false,

package/src/client.js

@@ -1,4 +1,14 @@
 import { sendEvent, parseDsn } from "./transport.js";
+import {
+  buildStacktraceFromError,
+  enrichStacktraceAsync,
+} from "./stacktrace.js";
+import {
+  getSdkMetadata,
+  getPageContext,
+  getPerformanceContext,
+  getNodeServerContext,
+} from "./contexts.js";
 
 let DSN = null;
 let APP_ENV = "production";
@@ -14,7 +24,7 @@ const isNode =
 const MAX_BREADCRUMBS = 100;
 let breadcrumbs = [];
 
-function addBreadcrumb(breadcrumb) {
+export function addBreadcrumb(breadcrumb) {
   const entry = {
     level: "info",
     category: "log",
@@ -145,7 +155,7 @@ function setupBrowserInstrumentation() {
       message: String(msg),
       data: { url, line, col },
     });
-    captureException(error || msg);
+    void captureException(error || msg);
   };
 
   window.onunhandledrejection = function (event) {
@@ -156,7 +166,7 @@ function setupBrowserInstrumentation() {
       message: String(event.reason),
       data: {},
     });
-    captureException(event.reason);
+    void captureException(event.reason);
   };
 
   // Console breadcrumbs
@@ -340,73 +350,29 @@ function setupBrowserInstrumentation() {
   }
 }
 
-// Parse a JavaScript Error.stack string into structured frames compatible with backend
-function buildStacktraceFromError(error) {
-  if (!error || !error.stack || typeof error.stack !== "string") {
-    return null;
-  }
-
-  const stackLines = error.stack.split("\n");
-  const frames = [];
-
-  for (let i = 1; i < stackLines.length; i++) {
-    const line = stackLines[i].trim();
-    // Examples:
-    //   at funcName (http://localhost:5173/src/App.tsx:10:15)
-    //   at http://localhost:5173/assets/index-abc123.js:1:1234
-    const match =
-      line.match(/^at\s+(.*?)\s+\((.*?):(\d+):(\d+)\)$/) ||
-      line.match(/^at\s+(.*?):(\d+):(\d+)$/);
-
-    if (!match) continue;
-
-    let functionName;
-    let file;
-    let lineNo;
-    let colNo;
-
-    if (match.length === 5) {
-      functionName = match[1] || "<anonymous>";
-      file = match[2];
-      lineNo = parseInt(match[3], 10);
-      colNo = parseInt(match[4], 10);
-    } else {
-      functionName = "<anonymous>";
-      file = match[1];
-      lineNo = parseInt(match[2], 10);
-      colNo = parseInt(match[3], 10);
-    }
-
-    const filename = file.split("/").pop() || file;
-
-    frames.push({
-      filename,
-      abs_path: file,
-      lineno: lineNo,
-      colno: colNo,
-      function: functionName,
-      module: null,
-      context_line: null,
-      pre_context: [],
-      post_context: [],
-      vars: {},
-      in_app: true,
-    });
-  }
-
-  if (!frames.length) {
-    return null;
-  }
+import { initTracing } from "./tracing.js";
 
-  // Backend expects oldest frame first, newest last; JS stacks are newest first,
-  // so we reverse to be consistent with Python-style traces.
-  frames.reverse();
+async function buildEventContexts(context = {}) {
+  const runtime = getRuntimeContext();
+  const browser = getBrowserContext();
+  const os = getOsContext();
+  const device = getDeviceContext();
+  const page = getPageContext();
+  const performanceCtx = getPerformanceContext();
+  const server = await getNodeServerContext();
 
-  return { frames };
+  return {
+    ...(context.contexts || {}),
+    ...(runtime ? { runtime } : {}),
+    ...(browser ? { browser } : {}),
+    ...(os ? { os } : {}),
+    ...(device ? { device } : {}),
+    ...(page ? { page } : {}),
+    ...(performanceCtx ? { performance: performanceCtx } : {}),
+    ...(server ? { server } : {}),
+  };
 }
 
-import { initTracing } from "./tracing.js";
-
 export function register({
   dsn,
   app_env = "production",
@@ -448,11 +414,11 @@ export function register({
   // Node.js: Set up process error handlers
   if (isNode) {
     process.on("uncaughtException", (error) => {
-      captureException(error);
+      void captureException(error);
     });
-    
+
     process.on("unhandledRejection", (reason) => {
-      captureException(reason);
+      void captureException(reason);
     });
   }
 }
@@ -463,10 +429,13 @@ export function init(options) {
   return register(options);
 }
 
-export function captureException(error, context = {}) {
+export async function captureException(error, context = {}) {
   if (!DSN) return;
 
-  const stacktrace = buildStacktraceFromError(error);
+  let stacktrace = buildStacktraceFromError(error);
+  if (stacktrace) {
+    stacktrace = await enrichStacktraceAsync(stacktrace);
+  }
 
   const event = {
     event_id: generateEventId(),
@@ -476,14 +445,13 @@ export function captureException(error, context = {}) {
     stacktrace: stacktrace || error?.stack,
     timestamp: new Date().toISOString(),
     platform: isBrowser ? "javascript" : "node",
+    sdk: getSdkMetadata(),
   };
-  
-  // Add release if set
+
   if (RELEASE) {
     event.release = RELEASE;
   }
-  
-  // Add context
+
   if (context.user) {
     event.user = context.user;
   }
@@ -496,11 +464,11 @@ export function captureException(error, context = {}) {
   if (context.extra) {
     event.extra = context.extra;
   }
-  // In browser, auto-populate basic request + URL tags if not provided
+
   if (isBrowser) {
-    const url = typeof window !== "undefined" ? window.location.href : undefined;
-    const referrer =
-      typeof document !== "undefined" ? document.referrer || undefined : undefined;
+    const page = getPageContext();
+    const url = page?.url;
+    const referrer = page?.referrer;
     if (!event.request && url) {
       event.request = {
         url,
@@ -512,38 +480,27 @@ export function captureException(error, context = {}) {
     }
     event.tags = {
       ...(event.tags || {}),
-      url: url || (event.tags && event.tags.url),
-      referrer: referrer || (event.tags && event.tags.referrer),
+      url: url || event.tags?.url,
+      referrer: referrer || event.tags?.referrer,
+      page_title: page?.title || event.tags?.page_title,
     };
   }
-  // Attach runtime + environment contexts (Sentry-like)
-  const runtime = getRuntimeContext();
-  const browser = getBrowserContext();
-  const os = getOsContext();
-  const device = getDeviceContext();
 
-  event.contexts = {
-    ...(context.contexts || {}),
-    ...(runtime ? { runtime } : {}),
-    ...(browser ? { browser } : {}),
-    ...(os ? { os } : {}),
-    ...(device ? { device } : {}),
-  };
+  event.contexts = await buildEventContexts(context);
 
-  // Attach breadcrumbs (copied snapshot so later mutations don't affect this event)
   const bcs = getBreadcrumbsSnapshot();
   if (bcs.length > 0) {
     event.breadcrumbs = bcs;
   }
-  
+
   if (DEBUG) {
     console.log("WatchForge SDK - Capturing exception:", event);
   }
-  
+
   sendEvent(DSN, event);
 }
 
-export function captureMessage(message, level = "info", context = {}) {
+export async function captureMessage(message, level = "info", context = {}) {
   if (!DSN) return;
 
   const event = {
@@ -553,14 +510,13 @@ export function captureMessage(message, level = "info", context = {}) {
     message,
     timestamp: new Date().toISOString(),
     platform: isBrowser ? "javascript" : "node",
+    sdk: getSdkMetadata(),
   };
-  
-  // Add release if set
+
   if (RELEASE) {
     event.release = RELEASE;
   }
-  
-  // Add context
+
   if (context.user) {
     event.user = context.user;
   }
@@ -573,10 +529,11 @@ export function captureMessage(message, level = "info", context = {}) {
   if (context.extra) {
     event.extra = context.extra;
   }
+
   if (isBrowser) {
-    const url = typeof window !== "undefined" ? window.location.href : undefined;
-    const referrer =
-      typeof document !== "undefined" ? document.referrer || undefined : undefined;
+    const page = getPageContext();
+    const url = page?.url;
+    const referrer = page?.referrer;
     if (!event.request && url) {
       event.request = {
         url,
@@ -588,33 +545,23 @@ export function captureMessage(message, level = "info", context = {}) {
     }
     event.tags = {
       ...(event.tags || {}),
-      url: url || (event.tags && event.tags.url),
-      referrer: referrer || (event.tags && event.tags.referrer),
+      url: url || event.tags?.url,
+      referrer: referrer || event.tags?.referrer,
+      page_title: page?.title || event.tags?.page_title,
     };
   }
-  // Attach runtime + environment contexts
-  const runtime = getRuntimeContext();
-  const browser = getBrowserContext();
-  const os = getOsContext();
-  const device = getDeviceContext();
 
-  event.contexts = {
-    ...(context.contexts || {}),
-    ...(runtime ? { runtime } : {}),
-    ...(browser ? { browser } : {}),
-    ...(os ? { os } : {}),
-    ...(device ? { device } : {}),
-  };
+  event.contexts = await buildEventContexts(context);
 
   const bcs = getBreadcrumbsSnapshot();
   if (bcs.length > 0) {
     event.breadcrumbs = bcs;
   }
-  
+
   if (DEBUG) {
     console.log("WatchForge SDK - Capturing message:", event);
   }
-  
+
   sendEvent(DSN, event);
 }
 

package/src/contexts.js

@@ -0,0 +1,110 @@
+/**
+ * Event context builders (browser, Node, performance).
+ */
+
+const isBrowser = typeof window !== "undefined";
+const isNode =
+  typeof process !== "undefined" && process.versions && process.versions.node;
+
+export const SDK_NAME = "@watchforge/browser";
+export const SDK_VERSION = "0.1.1";
+
+export function getSdkMetadata() {
+  return {
+    name: SDK_NAME,
+    version: SDK_VERSION,
+  };
+}
+
+export function getPageContext() {
+  if (!isBrowser) return null;
+
+  const loc = window.location;
+  return {
+    url: loc.href,
+    path: loc.pathname,
+    search: loc.search,
+    hash: loc.hash,
+    referrer: typeof document !== "undefined" ? document.referrer || null : null,
+    title: typeof document !== "undefined" ? document.title || null : null,
+  };
+}
+
+export function getPerformanceContext() {
+  if (!isBrowser || typeof performance === "undefined") return null;
+
+  const ctx = {};
+
+  try {
+    const nav = performance.getEntriesByType("navigation")[0];
+    if (nav) {
+      ctx.navigation = {
+        type: nav.type,
+        dom_content_loaded_ms: Math.round(nav.domContentLoadedEventEnd),
+        load_event_ms: Math.round(nav.loadEventEnd),
+        dom_interactive_ms: Math.round(nav.domInteractive),
+        response_end_ms: Math.round(nav.responseEnd),
+        transfer_size: nav.transferSize ?? null,
+      };
+    }
+  } catch {
+    // ignore
+  }
+
+  try {
+    const resources = performance
+      .getEntriesByType("resource")
+      .slice(-20)
+      .map((r) => ({
+        name: r.name?.slice(0, 200),
+        initiator_type: r.initiatorType,
+        duration_ms: Math.round(r.duration),
+        transfer_size: r.transferSize ?? null,
+      }));
+    if (resources.length) {
+      ctx.resources = resources;
+    }
+  } catch {
+    // ignore
+  }
+
+  return Object.keys(ctx).length ? ctx : null;
+}
+
+let nodeOsPromise = null;
+
+async function getNodeOs() {
+  if (!isNode) return null;
+  if (!nodeOsPromise) {
+    nodeOsPromise = import("os").catch(() => null);
+  }
+  return nodeOsPromise;
+}
+
+export async function getNodeServerContext() {
+  if (!isNode) return null;
+
+  const os = await getNodeOs();
+  if (!os) return null;
+
+  const mem = process.memoryUsage();
+
+  return {
+    name: os.hostname(),
+    os: {
+      name: os.platform(),
+      version: os.release(),
+      arch: os.arch(),
+    },
+    runtime: {
+      name: "node",
+      version: process.version,
+    },
+    process: {
+      pid: process.pid,
+      uptime_seconds: Math.round(process.uptime()),
+      memory_rss_mb: Math.round(mem.rss / 1024 / 1024),
+      memory_heap_used_mb: Math.round(mem.heapUsed / 1024 / 1024),
+    },
+  };
+}

package/src/express.js

@@ -13,6 +13,16 @@
 
 import { captureException } from "./client.js";
 
+/**
+ * Optional first middleware — records request start time for duration_ms on errors.
+ */
+export function expressRequestMiddleware() {
+  return function (req, _res, next) {
+    req._watchforgeStart = Date.now();
+    next();
+  };
+}
+
 export function expressMiddleware() {
   return function (err, req, res, next) {
     // Extract IP address
@@ -45,17 +55,30 @@ export function expressMiddleware() {
       ip: ip,
     };
 
-    // Capture exception with rich API-level context
-    captureException(err, {
+    const durationMs =
+      typeof req._watchforgeStart === "number"
+        ? Date.now() - req._watchforgeStart
+        : null;
+
+    void captureException(err, {
       user,
       request,
       tags: {
         framework: "express",
         route: req.route?.path || req.path,
         status_code: res && res.statusCode,
+        ...(durationMs != null ? { duration_ms: durationMs } : {}),
       },
       extra: {
         params: req.params || {},
+        ...(durationMs != null ? { duration_ms: durationMs } : {}),
+      },
+      contexts: {
+        express: {
+          route: req.route?.path || req.path,
+          base_url: req.baseUrl || null,
+          duration_ms: durationMs,
+        },
       },
     });
 

package/src/index.js

@@ -1,5 +1,10 @@
 // Export main functions
-export { register, captureException, captureMessage } from "./client.js";
+export {
+  register,
+  captureException,
+  captureMessage,
+  addBreadcrumb,
+} from "./client.js";
 
 // Export deprecated init for backward compatibility
 export { init } from "./client.js";
@@ -8,5 +13,5 @@ export { init } from "./client.js";
 export { startTransaction, getCurrentTransaction, finishTransaction, Transaction, Span } from "./tracing.js";
 
 // Export framework integrations
-export { expressMiddleware } from "./express.js";
+export { expressMiddleware, expressRequestMiddleware } from "./express.js";
 export { ErrorBoundary } from "./react.js";

package/src/react.js

@@ -26,12 +26,18 @@ export class ErrorBoundary extends React.Component {
   }
 
   componentDidCatch(error, errorInfo) {
-    captureException(error, {
+    void captureException(error, {
       extra: {
         componentStack: errorInfo.componentStack,
       },
       tags: {
-        framework: 'react',
+        framework: "react",
+      },
+      contexts: {
+        react: {
+          framework: "react",
+          component_stack: errorInfo.componentStack || null,
+        },
       },
     });
   }

package/src/stacktrace.js

@@ -0,0 +1,231 @@
+/**
+ * Stack trace parsing and source context enrichment (Python SDK parity).
+ */
+
+const CONTEXT_LINES = 5;
+const MAX_SOURCE_FILE_BYTES = 512 * 1024;
+
+const isBrowser = typeof window !== "undefined";
+const isNode =
+  typeof process !== "undefined" && process.versions && process.versions.node;
+
+const LIBRARY_PATH_PATTERNS = [
+  "/node_modules/",
+  "node_modules\\",
+  "/webpack/",
+  "webpack-internal://",
+];
+
+function isLibraryPath(filePath) {
+  if (!filePath) return false;
+  return LIBRARY_PATH_PATTERNS.some((p) => filePath.includes(p));
+}
+
+function parseStackLine(line) {
+  const trimmed = line.trim();
+  if (!trimmed.startsWith("at ")) return null;
+
+  const withFn = trimmed.match(/^at\s+(.*?)\s+\((.*?):(\d+):(\d+)\)$/);
+  if (withFn) {
+    return {
+      function: withFn[1] || "<anonymous>",
+      file: withFn[2],
+      lineno: parseInt(withFn[3], 10),
+      colno: parseInt(withFn[4], 10),
+    };
+  }
+
+  const withoutFn = trimmed.match(/^at\s+(.*?):(\d+):(\d+)$/);
+  if (withoutFn) {
+    return {
+      function: "<anonymous>",
+      file: withoutFn[1],
+      lineno: parseInt(withoutFn[2], 10),
+      colno: parseInt(withoutFn[3], 10),
+    };
+  }
+
+  const evalMatch = trimmed.match(/^at\s+(.*?)\s+\((.*?)\)$/);
+  if (evalMatch) {
+    const inner = parseStackLine(`at ${evalMatch[2]}`);
+    if (inner) {
+      return { ...inner, function: evalMatch[1] || inner.function };
+    }
+  }
+
+  return null;
+}
+
+export function buildStacktraceFromError(error) {
+  if (!error || !error.stack || typeof error.stack !== "string") {
+    return null;
+  }
+
+  const stackLines = error.stack.split("\n");
+  const frames = [];
+
+  for (let i = 1; i < stackLines.length; i++) {
+    const parsed = parseStackLine(stackLines[i]);
+    if (!parsed) continue;
+
+    const { function: functionName, file, lineno, colno } = parsed;
+    const filename = file.split("/").pop()?.split("?")[0] || file;
+    const inApp = !isLibraryPath(file);
+
+    frames.push({
+      filename,
+      abs_path: file,
+      lineno,
+      colno,
+      function: functionName,
+      module: null,
+      context_line: null,
+      pre_context: [],
+      post_context: [],
+      vars: {},
+      in_app: inApp,
+    });
+  }
+
+  if (!frames.length) return null;
+
+  frames.reverse();
+  return { frames };
+}
+
+function applySourceContext(frame, sourceLines, lineno) {
+  if (!sourceLines?.length || !lineno || lineno < 1) return;
+
+  const idx = lineno - 1;
+  if (idx >= sourceLines.length) return;
+
+  frame.context_line = sourceLines[idx].replace(/\r$/, "");
+  const preStart = Math.max(0, idx - CONTEXT_LINES);
+  frame.pre_context = sourceLines
+    .slice(preStart, idx)
+    .map((l) => l.replace(/\r$/, ""));
+  const postEnd = Math.min(sourceLines.length, idx + CONTEXT_LINES + 1);
+  frame.post_context = sourceLines
+    .slice(idx + 1, postEnd)
+    .map((l) => l.replace(/\r$/, ""));
+}
+
+let nodeModulesPromise = null;
+
+function getNodeModules() {
+  if (!isNode) return Promise.resolve(null);
+  if (!nodeModulesPromise) {
+    nodeModulesPromise = (async () => {
+      try {
+        const { createRequire } = await import("module");
+        const { fileURLToPath } = await import("url");
+        const req = createRequire(fileURLToPath(import.meta.url));
+        return {
+          fs: req("fs"),
+          path: req("path"),
+          fileURLToPath,
+        };
+      } catch {
+        return null;
+      }
+    })();
+  }
+  return nodeModulesPromise;
+}
+
+async function readNodeSourceLines(absPath) {
+  if (!isNode || !absPath) return null;
+
+  try {
+    if (absPath.startsWith("http://") || absPath.startsWith("https://")) {
+      return null;
+    }
+
+    const mods = await getNodeModules();
+    if (!mods) return null;
+
+    const { fs, path, fileURLToPath } = mods;
+    let filePath = absPath;
+
+    if (filePath.startsWith("file://")) {
+      filePath = fileURLToPath(filePath);
+    }
+
+    if (!path.isAbsolute(filePath)) {
+      filePath = path.resolve(process.cwd(), filePath);
+    }
+
+    if (!fs.existsSync(filePath)) return null;
+
+    const stat = fs.statSync(filePath);
+    if (stat.size > MAX_SOURCE_FILE_BYTES) return null;
+
+    const content = fs.readFileSync(filePath, "utf8");
+    return content.split("\n");
+  } catch {
+    return null;
+  }
+}
+
+async function enrichFrameWithNodeSource(frame) {
+  if (!frame.in_app || !frame.lineno) return;
+  const lines = await readNodeSourceLines(frame.abs_path);
+  if (lines) applySourceContext(frame, lines, frame.lineno);
+}
+
+async function fetchBrowserSourceLines(absPath) {
+  if (!isBrowser || !absPath) return null;
+
+  try {
+    let url = absPath;
+    if (url.startsWith("webpack-internal://")) {
+      url = url.replace("webpack-internal:///", "/").replace("webpack-internal://", "/");
+    }
+
+    if (!url.startsWith("http://") && !url.startsWith("https://")) {
+      if (url.startsWith("/")) {
+        url = `${window.location.origin}${url}`;
+      } else {
+        return null;
+      }
+    }
+
+    const target = new URL(url, window.location.href);
+    if (target.origin !== window.location.origin) return null;
+
+    const response = await fetch(target.href, { credentials: "same-origin" });
+    if (!response.ok) return null;
+
+    const contentType = response.headers.get("content-type") || "";
+    if (!contentType.includes("javascript") && !contentType.includes("text")) {
+      return null;
+    }
+
+    const text = await response.text();
+    if (text.length > MAX_SOURCE_FILE_BYTES) return null;
+    return text.split("\n");
+  } catch {
+    return null;
+  }
+}
+
+async function enrichFrameWithBrowserSource(frame) {
+  if (!frame.in_app || !frame.lineno) return;
+  const lines = await fetchBrowserSourceLines(frame.abs_path);
+  if (lines) applySourceContext(frame, lines, frame.lineno);
+}
+
+export async function enrichStacktraceAsync(stacktrace) {
+  if (!stacktrace?.frames?.length) return stacktrace;
+
+  const inAppFrames = stacktrace.frames.filter((f) => f.in_app);
+  const targets = inAppFrames.slice(-5);
+
+  if (isNode) {
+    await Promise.all(targets.map((frame) => enrichFrameWithNodeSource(frame)));
+  } else if (isBrowser) {
+    await Promise.all(targets.map((frame) => enrichFrameWithBrowserSource(frame)));
+  }
+
+  return stacktrace;
+}