@watchforge/browser 0.1.4 → 0.1.6

package/CONFIGURATION_GUIDE.md

@@ -2,10 +2,51 @@
 
 ## Overview
 
-The WatchForge JavaScript SDK automatically captures errors and events in:
+The WatchForge JavaScript SDK is one npm package with typed framework entry points for:
+
+- **Browser JavaScript** applications
+- **Next.js** App Router applications
+- **React** frontend applications
 - **Node.js** applications
 - **Express.js** web servers
-- **React** frontend applications
+
+This package intentionally stays unified instead of splitting into separate `watchforge-next-sdk`, `watchforge-node-sdk`, `watchforge-react-sdk`, and `watchforge-express-sdk` packages. The shared package keeps DSN handling, event transport, breadcrumbs, stack traces, source context, and session replay consistent across JavaScript runtimes.
+
+## Supported Imports
+
+```ts
+// Browser JavaScript, React client, and shared APIs
+import { register, captureException, captureMessage } from "@watchforge/browser";
+
+// Next.js App Router client provider
+import { WatchForgeProvider } from "@watchforge/browser/next";
+
+// Next.js server route handlers
+import { withWatchForgeRouteHandler } from "@watchforge/browser/next/server";
+
+// React error boundary
+import { ErrorBoundary } from "@watchforge/browser/react";
+
+// Express middleware
+import {
+  expressRequestMiddleware,
+  expressMiddleware,
+} from "@watchforge/browser/express";
+
+// Explicit Node.js import
+import { register as registerNode } from "@watchforge/browser/node";
+```
+
+## Support Matrix
+
+| Runtime / Framework | Entry point | Recommended setup |
+| --- | --- | --- |
+| Browser JavaScript | `@watchforge/browser` | Call `register()` once in the main browser bundle |
+| React | `@watchforge/browser` + `@watchforge/browser/react` | Call `register()` once and wrap the app with `ErrorBoundary` |
+| Next.js App Router client | `@watchforge/browser/next` | Use the wizard or render `WatchForgeProvider` from a client component |
+| Next.js App Router server | `@watchforge/browser/next/server` | Wrap route handlers with `withWatchForgeRouteHandler()` |
+| Node.js | `@watchforge/browser/node` | Call `register()` once during process startup |
+| Express.js | `@watchforge/browser/express` | Add request middleware before routes and error middleware after routes |
 
 ## Installation
 
@@ -64,8 +105,9 @@ npm install ../watchforge-javascript-sdk
 ```
 
 After installation, use it the same way:
-```javascript
-import { register, ErrorBoundary } from '@watchforge/browser';
+```ts
+import { register } from "@watchforge/browser";
+import { ErrorBoundary } from "@watchforge/browser/react";
 ```
 
 ### Next.js Wizard Setup
@@ -89,7 +131,7 @@ The wizard:
 
 1. Installs `@watchforge/browser`
 2. Creates `watchforge.config.ts`
-3. Creates `app/watchforge-init.tsx` (or `src/app/watchforge-init.tsx`)
+3. Creates `app/watchforge-init.tsx` (or `src/app/.../watchforge-init.tsx`)
 4. Patches `app/layout.tsx` to render `<WatchForgeInit />`
 
 If you only want file generation and no package install:
@@ -188,11 +230,92 @@ See the React setup section below for complete examples.
 
 ## Quick Start
 
+### Browser JavaScript
+
+```ts
+import { register } from "@watchforge/browser";
+
+register({
+  dsn: "https://PUBLIC_KEY@watchforge.io/PROJECT_ID",
+  app_env: "production",
+});
+```
+
+This captures uncaught browser errors, unhandled promise rejections, breadcrumbs, page context, browser/device/OS details, and performance context.
+
+### Next.js App Router
+
+Create `watchforge.config.ts` in your project root:
+
+```ts
+export const watchforgeConfig = {
+  dsn: "https://PUBLIC_KEY@watchforge.io/PROJECT_ID",
+  app_env: "production",
+  replaysOnErrorSampleRate: 1,
+  maskAllInputs: true,
+};
+```
+
+Create a client init component beside your frontend layout, for example `src/app/watchforge-init.tsx` or `src/app/(frontend)/watchforge-init.tsx`:
+
+```tsx
+"use client";
+
+import { WatchForgeProvider } from "@watchforge/browser/next";
+import { watchforgeConfig } from "../watchforge.config";
+
+export default function WatchForgeInit() {
+  return <WatchForgeProvider options={watchforgeConfig} />;
+}
+```
+
+Render it once in the matching `layout.tsx`:
+
+```tsx
+import WatchForgeInit from "./watchforge-init";
+
+export default function RootLayout({ children }: { children: React.ReactNode }) {
+  return (
+    <html lang="en">
+      <body>
+        <WatchForgeInit />
+        {children}
+      </body>
+    </html>
+  );
+}
+```
+
+For route-group projects like `src/app/(frontend)/layout.tsx`, put `watchforge-init.tsx` in that same route group and adjust the config import path if needed.
+
+For Next.js route handlers, use the server entry point:
+
+```ts
+// app/api/example/route.ts
+import {
+  register,
+  withWatchForgeRouteHandler,
+} from "@watchforge/browser/next/server";
+
+register({
+  dsn: "https://PUBLIC_KEY@watchforge.io/PROJECT_ID",
+  app_env: "production",
+});
+
+export const GET = withWatchForgeRouteHandler(async () => {
+  throw new Error("Next.js API route test error");
+});
+```
+
 ### 1. Node.js Application
 
-```javascript
+```ts
 // app.js
-const { register, captureException, captureMessage } = require('@watchforge/browser');
+import {
+  register,
+  captureException,
+  captureMessage,
+} from "@watchforge/browser/node";
 
 // Initialize SDK
 // API URL is automatically derived from DSN host
@@ -214,10 +337,14 @@ captureMessage("User logged in", "info");
 
 ### 2. Express.js Application
 
-```javascript
+```ts
 // server.js
-const express = require('express');
-const { register, expressMiddleware } = require('@watchforge/browser');
+import express from "express";
+import { register } from "@watchforge/browser/node";
+import {
+  expressRequestMiddleware,
+  expressMiddleware,
+} from "@watchforge/browser/express";
 
 const app = express();
 
@@ -755,6 +882,7 @@ register({
 
 app.use(express.json());
 app.use(expressRequestMiddleware());
+app.use(expressRequestMiddleware());
 
 // routes here
 

package/README.md

@@ -1,6 +1,18 @@
 # WatchForge JavaScript SDK (`@watchforge/browser`)
 
-Browser and Node SDK for WatchForge. **One call to `register()`** turns on automatic error reporting—no manual `try/catch` required for typical crashes.
+Browser, Next.js, React, Node.js, and Express SDK for WatchForge. **One call to `register()`** turns on automatic error reporting for typical crashes, and framework entry points add richer context where needed.
+
+## Runtime Support
+
+| Runtime / Framework | Import | What it captures |
+| --- | --- | --- |
+| Browser JavaScript | `@watchforge/browser` | Uncaught errors, unhandled promise rejections, breadcrumbs, browser/device/page/performance context |
+| React | `@watchforge/browser` + `@watchforge/browser/react` | Browser errors plus React `ErrorBoundary` component stack context |
+| Next.js App Router | `@watchforge/browser/next` | Client-side Next.js errors through a client provider; wizard patches the app layout |
+| Node.js | `@watchforge/browser` or `@watchforge/browser/node` | `uncaughtException`, `unhandledRejection`, Node runtime/server context |
+| Express.js | `@watchforge/browser/express` | Express request errors, request URL/method/headers/body/query, user/IP, route, duration |
+
+The package is intentionally shipped as **one npm package** with typed subpath exports instead of separate SDK packages. This keeps DSN setup, replay, stack traces, breadcrumbs, and event transport consistent across JavaScript runtimes.
 
 ## What this package does *not* require
 
@@ -37,6 +49,131 @@ npx @watchforge/browser -i nextjs \
 
 The wizard installs `@watchforge/browser`, writes `watchforge.config.ts`, creates a client init component, and patches `app/layout.tsx` or `pages/_app.tsx`.
 
+## Framework Imports
+
+WatchForge ships as one JavaScript SDK package with typed framework entry points:
+
+```ts
+// Browser / React client / Node global handlers
+import { register } from "@watchforge/browser";
+
+// Next.js App Router client provider
+import { WatchForgeProvider } from "@watchforge/browser/next";
+
+// Next.js App Router server route helper
+import { withWatchForgeRouteHandler } from "@watchforge/browser/next/server";
+
+// React error boundary
+import { ErrorBoundary } from "@watchforge/browser/react";
+
+// Express middleware
+import {
+  expressRequestMiddleware,
+  expressMiddleware,
+} from "@watchforge/browser/express";
+
+// Optional explicit Node import
+import { captureException } from "@watchforge/browser/node";
+```
+
+## Next.js Manual Setup
+
+Use the wizard when possible. For manual setup in App Router projects, create a client init component for browser-side errors:
+
+```tsx
+"use client";
+
+import { WatchForgeProvider } from "@watchforge/browser/next";
+import { watchforgeConfig } from "../watchforge.config";
+
+export default function WatchForgeInit() {
+  return <WatchForgeProvider options={watchforgeConfig} />;
+}
+```
+
+Then render it once in your frontend `layout.tsx`:
+
+```tsx
+import WatchForgeInit from "./watchforge-init";
+
+export default function RootLayout({ children }: { children: React.ReactNode }) {
+  return (
+    <html lang="en">
+      <body>
+        <WatchForgeInit />
+        {children}
+      </body>
+    </html>
+  );
+}
+```
+
+For route groups, place the init component beside the frontend layout, for example `src/app/(frontend)/watchforge-init.tsx`, and import `watchforge.config.ts` using the correct relative path.
+
+For server route handlers, initialize once in server code and wrap handlers:
+
+```ts
+import {
+  register,
+  withWatchForgeRouteHandler,
+} from "@watchforge/browser/next/server";
+
+register({
+  dsn: "https://PUBLIC_KEY@your-host/PROJECT_ID",
+  app_env: "production",
+});
+
+export const GET = withWatchForgeRouteHandler(async () => {
+  throw new Error("Next.js route handler test error");
+});
+```
+
+## Express Setup
+
+```ts
+import express from "express";
+import { register } from "@watchforge/browser/node";
+import {
+  expressRequestMiddleware,
+  expressMiddleware,
+} from "@watchforge/browser/express";
+
+register({
+  dsn: "https://PUBLIC_KEY@your-host/PROJECT_ID",
+  app_env: "production",
+});
+
+const app = express();
+app.use(express.json());
+app.use(expressRequestMiddleware());
+
+app.get("/error", () => {
+  throw new Error("Express test error");
+});
+
+app.use(expressMiddleware());
+```
+
+## React Setup
+
+```tsx
+import { register } from "@watchforge/browser";
+import { ErrorBoundary } from "@watchforge/browser/react";
+
+register({
+  dsn: "https://PUBLIC_KEY@your-host/PROJECT_ID",
+  app_env: "production",
+});
+
+export function AppRoot() {
+  return (
+    <ErrorBoundary fallback={<div>Something went wrong.</div>}>
+      <App />
+    </ErrorBoundary>
+  );
+}
+```
+
 ## Quick start (all most apps need)
 
 Call **`register()` once** as early as possible (e.g. app entry / main bundle), with your **DSN** from the WatchForge project settings.

package/bin/watchforge.js

@@ -84,6 +84,15 @@ function fileExists(filePath) {
   return fs.existsSync(filePath) && fs.statSync(filePath).isFile();
 }
 
+function commandExists(command) {
+  try {
+    execSync(`command -v ${command}`, { stdio: "ignore" });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
 function findNextLayout(cwd) {
   const candidates = [
     path.join(cwd, "src", "app", "layout.tsx"),
@@ -91,6 +100,24 @@ function findNextLayout(cwd) {
     path.join(cwd, "app", "layout.tsx"),
     path.join(cwd, "app", "layout.jsx"),
   ];
+
+  for (const appRoot of [path.join(cwd, "src", "app"), path.join(cwd, "app")]) {
+    if (!fs.existsSync(appRoot) || !fs.statSync(appRoot).isDirectory()) continue;
+    const entries = fs.readdirSync(appRoot, { withFileTypes: true }).sort((a, b) => {
+      const score = (name) => {
+        if (name.includes("frontend") || name.includes("site")) return -1;
+        if (name.includes("payload") || name.includes("admin")) return 1;
+        return 0;
+      };
+      return score(a.name) - score(b.name) || a.name.localeCompare(b.name);
+    });
+    for (const entry of entries) {
+      if (!entry.isDirectory()) continue;
+      candidates.push(path.join(appRoot, entry.name, "layout.tsx"));
+      candidates.push(path.join(appRoot, entry.name, "layout.jsx"));
+    }
+  }
+
   return candidates.find(fileExists) || null;
 }
 
@@ -138,11 +165,11 @@ function installPackage(cwd, skipInstall) {
   const hasYarn = fileExists(path.join(cwd, "yarn.lock"));
   const hasBun = fileExists(path.join(cwd, "bun.lockb"));
 
-  const command = hasPnpm
+  const command = hasPnpm && commandExists("pnpm")
     ? "pnpm add @watchforge/browser"
-    : hasYarn
+    : hasYarn && commandExists("yarn")
       ? "yarn add @watchforge/browser"
-      : hasBun
+      : hasBun && commandExists("bun")
         ? "bun add @watchforge/browser"
         : "npm install @watchforge/browser";
 
@@ -152,22 +179,21 @@ function installPackage(cwd, skipInstall) {
 
 function patchAppRouter(cwd, layoutPath) {
   const appDir = path.dirname(layoutPath);
-  const isSrcApp = appDir.endsWith(path.join("src", "app"));
-  const configImport = isSrcApp ? "../../watchforge.config" : "../watchforge.config";
+  const configPath = path.join(cwd, "watchforge.config.ts");
+  let configImport = path.relative(appDir, configPath).replace(/\\/g, "/");
+  configImport = configImport.replace(/\.ts$/, "");
+  if (!configImport.startsWith(".")) {
+    configImport = `./${configImport}`;
+  }
   const initPath = path.join(appDir, "watchforge-init.tsx");
 
   const initContent = `"use client";
 
-import { useEffect } from "react";
-import { register } from "@watchforge/browser";
+import { WatchForgeProvider } from "@watchforge/browser/next";
 import { watchforgeConfig } from "${configImport}";
 
 export default function WatchForgeInit() {
-  useEffect(() => {
-    register(watchforgeConfig);
-  }, []);
-
-  return null;
+  return <WatchForgeProvider options={watchforgeConfig} />;
 }
 `;
 

package/package.json

@@ -1,8 +1,9 @@
 {
   "name": "@watchforge/browser",
-  "version": "0.1.4",
+  "version": "0.1.6",
   "main": "./src/index.js",
-  "description": "WatchForge JavaScript SDK for Node.js, Express.js, and React",
+  "types": "./src/index.d.ts",
+  "description": "WatchForge JavaScript SDK for browser JavaScript, Next.js, React, Node.js, and Express.js",
   "license": "MIT",
   "keywords": [
     "watchforge",
@@ -15,12 +16,31 @@
   ],
   "exports": {
     ".": {
+      "types": "./src/index.d.ts",
       "browser": "./src/index.js",
       "node": "./src/index.js",
       "default": "./src/index.js"
     },
-    "./express": "./src/express.js",
-    "./react": "./src/react.js"
+    "./node": {
+      "types": "./src/index.d.ts",
+      "default": "./src/index.js"
+    },
+    "./next": {
+      "types": "./src/next.d.ts",
+      "default": "./src/next.js"
+    },
+    "./next/server": {
+      "types": "./src/next-server.d.ts",
+      "default": "./src/next-server.js"
+    },
+    "./express": {
+      "types": "./src/express.d.ts",
+      "default": "./src/express.js"
+    },
+    "./react": {
+      "types": "./src/react.d.ts",
+      "default": "./src/react.js"
+    }
   },
   "bin": {
     "watchforge": "bin/watchforge.js"
@@ -28,6 +48,7 @@
   "files": [
     "bin/**/*.js",
     "src/**/*.js",
+    "src/**/*.d.ts",
     "README.md",
     "CONFIGURATION_GUIDE.md",
     "LICENSE"
@@ -37,9 +58,13 @@
   },
   "type": "module",
   "peerDependencies": {
+    "express": ">=4.0.0",
     "react": ">=16.8.0"
   },
   "peerDependenciesMeta": {
+    "express": {
+      "optional": true
+    },
     "react": {
       "optional": true
     }
@@ -50,8 +75,8 @@
     "url": false
   },
   "dependencies": {
-    "express": "^5.2.1",
-    "rrweb": "^2.0.1"
+    "rrweb": "^2.0.1",
+    "source-map-js": "^1.2.1"
   },
   "devDependencies": {
     "rollup": "^4.60.0"

package/src/express.d.ts

@@ -0,0 +1,12 @@
+export function expressRequestMiddleware(): (
+  req: any,
+  res: any,
+  next: (error?: unknown) => void
+) => void;
+
+export function expressMiddleware(): (
+  err: Error,
+  req: any,
+  res: any,
+  next: (error?: unknown) => void
+) => void;

package/src/index.d.ts

@@ -0,0 +1,41 @@
+export interface WatchForgeRegisterOptions {
+  dsn: string;
+  app_env?: string;
+  release?: string | null;
+  debug?: boolean;
+  replaysSessionSampleRate?: number;
+  replaysOnErrorSampleRate?: number;
+  maskAllInputs?: boolean;
+  blockClass?: string;
+  ignoreClass?: string;
+  maskTextClass?: string;
+}
+
+export interface WatchForgeCaptureContext {
+  user?: Record<string, unknown>;
+  request?: Record<string, unknown>;
+  tags?: Record<string, unknown>;
+  extra?: Record<string, unknown>;
+  contexts?: Record<string, unknown>;
+}
+
+export function register(options: WatchForgeRegisterOptions): void;
+export function init(options: WatchForgeRegisterOptions): void;
+export function captureException(
+  error: unknown,
+  context?: WatchForgeCaptureContext
+): Promise<void>;
+export function captureMessage(
+  message: string,
+  level?: string,
+  context?: WatchForgeCaptureContext
+): Promise<void>;
+export function addBreadcrumb(breadcrumb: Record<string, unknown>): void;
+
+export {
+  startTransaction,
+  getCurrentTransaction,
+  finishTransaction,
+  Transaction,
+  Span,
+} from "./tracing.js";

package/src/index.js

@@ -13,5 +13,4 @@ export { init } from "./client.js";
 export { startTransaction, getCurrentTransaction, finishTransaction, Transaction, Span } from "./tracing.js";
 
 // Export framework integrations
-export { expressMiddleware, expressRequestMiddleware } from "./express.js";
-export { ErrorBoundary } from "./react.js";
+export { expressMiddleware, expressRequestMiddleware } from "./express.js";

package/src/next-server.d.ts

@@ -0,0 +1,26 @@
+import type {
+  WatchForgeCaptureContext,
+  WatchForgeRegisterOptions,
+} from "./index.js";
+
+export function register(options: WatchForgeRegisterOptions): void;
+
+export function captureException(
+  error: unknown,
+  context?: WatchForgeCaptureContext
+): Promise<void>;
+
+export function captureMessage(
+  message: string,
+  level?: string,
+  context?: WatchForgeCaptureContext
+): Promise<void>;
+
+export type NextRouteHandler<TContext = unknown> = (
+  request: Request,
+  context: TContext
+) => Response | Promise<Response>;
+
+export function withWatchForgeRouteHandler<TContext = unknown>(
+  handler: NextRouteHandler<TContext>
+): NextRouteHandler<TContext>;

package/src/next-server.js

@@ -0,0 +1,58 @@
+import {
+  captureException,
+  captureMessage,
+  register,
+} from "./client.js";
+
+export { captureException, captureMessage, register };
+
+function sanitizeHeaders(headers) {
+  if (!headers || typeof headers.entries !== "function") return {};
+
+  const sensitive = new Set([
+    "authorization",
+    "cookie",
+    "set-cookie",
+    "x-api-key",
+    "x-csrftoken",
+  ]);
+
+  return Object.fromEntries(
+    Array.from(headers.entries()).filter(
+      ([key]) => !sensitive.has(key.toLowerCase())
+    )
+  );
+}
+
+function getRequestContext(request) {
+  if (!request) return null;
+
+  return {
+    url: request.url || "",
+    method: request.method || "",
+    headers: sanitizeHeaders(request.headers),
+  };
+}
+
+export function withWatchForgeRouteHandler(handler) {
+  return async function watchForgeRouteHandler(request, context) {
+    try {
+      return await handler(request, context);
+    } catch (error) {
+      await captureException(error, {
+        request: getRequestContext(request),
+        tags: {
+          framework: "nextjs",
+          runtime: "server",
+        },
+        contexts: {
+          nextjs: {
+            router: "app",
+            route_handler: true,
+          },
+        },
+      });
+      throw error;
+    }
+  };
+}

package/src/next.d.ts

@@ -0,0 +1,11 @@
+import type { ReactElement, ReactNode } from "react";
+import type { WatchForgeRegisterOptions } from "./index.js";
+
+export interface WatchForgeProviderProps {
+  options: WatchForgeRegisterOptions;
+  children?: ReactNode;
+}
+
+export function WatchForgeProvider(
+  props: WatchForgeProviderProps
+): ReactElement | null;

package/src/next.js

@@ -0,0 +1,12 @@
+"use client";
+
+import React, { useEffect } from "react";
+import { register } from "./client.js";
+
+export function WatchForgeProvider({ options, children = null }) {
+  useEffect(() => {
+    register(options);
+  }, [options]);
+
+  return React.createElement(React.Fragment, null, children);
+}

package/src/react.d.ts

@@ -0,0 +1,8 @@
+import type { Component, ReactNode } from "react";
+
+export interface ErrorBoundaryProps {
+  children?: ReactNode;
+  fallback?: ReactNode;
+}
+
+export class ErrorBoundary extends Component<ErrorBoundaryProps> {}

package/src/stacktrace.js

@@ -12,8 +12,7 @@ const isNode =
 const LIBRARY_PATH_PATTERNS = [
   "/node_modules/",
   "node_modules\\",
-  "/webpack/",
-  "webpack-internal://",
+  "/webpack/runtime/",
 ];
 
 function isLibraryPath(filePath) {
@@ -69,16 +68,21 @@ export function buildStacktraceFromError(error) {
     if (!parsed) continue;
 
     const { function: functionName, file, lineno, colno } = parsed;
-    const filename = file.split("/").pop()?.split("?")[0] || file;
-    const inApp = !isLibraryPath(file);
+    const normalizedPath = normalizeSourcePath(file) || file;
+    const filename =
+      normalizedPath.split("/").pop()?.split("?")[0] ||
+      file.split("/").pop()?.split("?")[0] ||
+      file;
+    const inApp = !isLibraryPath(file) && !isLibraryPath(normalizedPath);
 
     frames.push({
       filename,
-      abs_path: file,
+      abs_path: normalizedPath,
+      raw_abs_path: file,
       lineno,
       colno,
       function: functionName,
-      module: null,
+      module: normalizedPath,
       context_line: null,
       pre_context: [],
       post_context: [],
@@ -110,6 +114,34 @@ function applySourceContext(frame, sourceLines, lineno) {
     .map((l) => l.replace(/\r$/, ""));
 }
 
+function normalizeSourcePath(source) {
+  if (!source) return "";
+
+  return String(source)
+    .replace(/^webpack-internal:\/\/\/?/, "")
+    .replace(/^webpack:\/\/(?:\([^)]*\)\/)?/, "")
+    .replace(/^webpack:\/\/[^/]+\//, "")
+    .replace(/^\([^)]*\)\//, "")
+    .replace(/^file:\/\//, "")
+    .split("?")[0]
+    .split("#")[0]
+    .replace(/\\/g, "/")
+    .replace(/^\/+/, "")
+    .replace(/^\.\//, "");
+}
+
+function sourceMatchesFrame(source, framePath) {
+  const normalizedSource = normalizeSourcePath(source);
+  const normalizedFrame = normalizeSourcePath(framePath);
+  if (!normalizedSource || !normalizedFrame) return false;
+
+  return (
+    normalizedSource === normalizedFrame ||
+    normalizedSource.endsWith(`/${normalizedFrame}`) ||
+    normalizedFrame.endsWith(`/${normalizedSource}`)
+  );
+}
+
 let nodeModulesPromise = null;
 const importNodeBuiltin = (specifier) =>
   new Function("specifier", "return import(specifier)")(specifier);
@@ -171,62 +203,291 @@ async function readNodeSourceLines(absPath) {
 
 async function enrichFrameWithNodeSource(frame) {
   if (!frame.in_app || !frame.lineno) return;
-  const lines = await readNodeSourceLines(frame.abs_path);
+  const lines = await readNodeSourceLines(frame.raw_abs_path || frame.abs_path);
   if (lines) applySourceContext(frame, lines, frame.lineno);
 }
 
-async function fetchBrowserSourceLines(absPath) {
-  if (!isBrowser || !absPath) return null;
+function getBrowserSourceFetchCandidates(absPath, rawAbsPath) {
+  const candidates = new Set();
+  const paths = [absPath, rawAbsPath].filter(Boolean);
 
-  try {
-    let url = absPath;
-    if (url.startsWith("webpack-internal://")) {
-      url = url.replace("webpack-internal:///", "/").replace("webpack-internal://", "/");
+  for (const path of paths) {
+    const normalized = normalizeSourcePath(path);
+    if (!normalized) continue;
+
+    if (path.startsWith("http://") || path.startsWith("https://")) {
+      candidates.add(path);
     }
 
-    if (!url.startsWith("http://") && !url.startsWith("https://")) {
-      if (url.startsWith("/")) {
-        url = `${window.location.origin}${url}`;
-      } else {
-        return null;
+    if (normalized.startsWith("/")) {
+      candidates.add(`${window.location.origin}${normalized}`);
+    } else {
+      candidates.add(`${window.location.origin}/${normalized}`);
+      candidates.add(new URL(normalized, window.location.href).href);
+    }
+
+    if (path.startsWith("webpack-internal://")) {
+      const stripped = path
+        .replace(/^webpack-internal:\/\/\/?/, "/")
+        .replace(/^webpack-internal:\/\//, "/");
+      candidates.add(`${window.location.origin}${stripped}`);
+    }
+  }
+
+  return [...candidates];
+}
+
+async function fetchBrowserSourceLines(absPath, rawAbsPath) {
+  if (!isBrowser || !absPath) return null;
+
+  const candidates = getBrowserSourceFetchCandidates(absPath, rawAbsPath);
+
+  for (const candidate of candidates) {
+    try {
+      const target = new URL(candidate, window.location.href);
+      if (target.origin !== window.location.origin) continue;
+
+      const response = await fetch(target.href, { credentials: "same-origin" });
+      if (!response.ok) continue;
+
+      const contentType = response.headers.get("content-type") || "";
+      if (
+        !contentType.includes("javascript") &&
+        !contentType.includes("text") &&
+        !contentType.includes("typescript") &&
+        !contentType.includes("json")
+      ) {
+        continue;
       }
+
+      const text = await response.text();
+      if (text.length > MAX_SOURCE_FILE_BYTES) continue;
+      if (!text.includes("\n") && !text.includes(";") && text.length > 500) continue;
+      return text.split("\n");
+    } catch {
+      // try next candidate
     }
+  }
 
-    const target = new URL(url, window.location.href);
-    if (target.origin !== window.location.origin) return null;
+  return null;
+}
+
+async function getSourceMapConsumer() {
+  try {
+    const mod = await import("source-map-js");
+    return mod.SourceMapConsumer || mod.default?.SourceMapConsumer || null;
+  } catch {
+    return null;
+  }
+}
+
+function getSourceMappingUrl(sourceText) {
+  const match = sourceText.match(/\/\/# sourceMappingURL=([^\s]+)\s*$/m);
+  return match?.[1] || null;
+}
 
-    const response = await fetch(target.href, { credentials: "same-origin" });
-    if (!response.ok) return null;
+async function fetchText(url) {
+  const response = await fetch(url, { credentials: "same-origin" });
+  if (!response.ok) return null;
+  const text = await response.text();
+  return text.length <= MAX_SOURCE_FILE_BYTES * 10 ? text : null;
+}
 
-    const contentType = response.headers.get("content-type") || "";
-    if (!contentType.includes("javascript") && !contentType.includes("text")) {
+async function fetchBrowserSourceMap(absPath) {
+  if (!isBrowser || !absPath) return null;
+  if (!absPath.startsWith("http://") && !absPath.startsWith("https://") && !absPath.startsWith("/")) {
+    return null;
+  }
+
+  try {
+    const scriptUrl = new URL(absPath, window.location.href);
+    if (scriptUrl.origin !== window.location.origin) return null;
+
+    const scriptText = await fetchText(scriptUrl.href);
+    if (!scriptText) return null;
+
+    const sourceMappingUrl = getSourceMappingUrl(scriptText);
+    if (!sourceMappingUrl) return null;
+
+    const mapUrl = new URL(sourceMappingUrl, scriptUrl.href);
+    if (mapUrl.origin !== window.location.origin && !sourceMappingUrl.startsWith("data:")) {
       return null;
     }
 
-    const text = await response.text();
-    if (text.length > MAX_SOURCE_FILE_BYTES) return null;
-    return text.split("\n");
+    if (sourceMappingUrl.startsWith("data:")) {
+      const encoded = sourceMappingUrl.split(",", 2)[1];
+      if (!encoded) return null;
+      const decoded = decodeURIComponent(escape(atob(encoded)));
+      return JSON.parse(decoded);
+    }
+
+    const mapText = await fetchText(mapUrl.href);
+    return mapText ? JSON.parse(mapText) : null;
   } catch {
     return null;
   }
 }
 
+async function findSourceMapForFrame(frame) {
+  const wanted = normalizeSourcePath(frame.abs_path || frame.module);
+  const scriptUrls = [];
+
+  if (frame.raw_abs_path?.startsWith("http://") || frame.raw_abs_path?.startsWith("https://")) {
+    scriptUrls.push(frame.raw_abs_path);
+  }
+  if (frame.abs_path?.startsWith("http://") || frame.abs_path?.startsWith("https://")) {
+    scriptUrls.push(frame.abs_path);
+  }
+
+  if (isBrowser) {
+    for (const script of document.querySelectorAll("script[src]")) {
+      const src = script.getAttribute("src");
+      if (!src) continue;
+      try {
+        const url = new URL(src, window.location.href);
+        if (url.origin === window.location.origin) {
+          scriptUrls.push(url.href);
+        }
+      } catch {
+        // ignore invalid script src
+      }
+    }
+  }
+
+  const seen = new Set();
+  for (const scriptUrl of scriptUrls) {
+    if (!scriptUrl || seen.has(scriptUrl)) continue;
+    seen.add(scriptUrl);
+
+    const sourceMap = await fetchBrowserSourceMap(scriptUrl);
+    if (!sourceMap) continue;
+
+    const sources = Array.isArray(sourceMap.sources) ? sourceMap.sources : [];
+    const hasMatch = sources.some((source) => sourceMatchesFrame(source, wanted));
+    if (hasMatch || !wanted) {
+      return { sourceMap, scriptUrl };
+    }
+  }
+
+  return null;
+}
+
+async function enrichFrameWithSourceMap(frame) {
+  const resolved = await findSourceMapForFrame(frame);
+  if (!resolved) return false;
+
+  const { sourceMap } = resolved;
+
+  try {
+    const SourceMapConsumer = await getSourceMapConsumer();
+    if (!SourceMapConsumer) return false;
+
+    const consumer = await new SourceMapConsumer(sourceMap);
+    let source = null;
+    let lineno = frame.lineno;
+    let colno = frame.colno;
+
+    if (frame.lineno && frame.colno != null) {
+      const original = consumer.originalPositionFor({
+        line: frame.lineno,
+        column: frame.colno,
+      });
+      if (original?.source && original?.line) {
+        source = original.source;
+        lineno = original.line;
+        colno = original.column ?? frame.colno;
+      }
+    }
+
+    if (!source) {
+      source = sourceMap.sources?.find((candidate) =>
+        sourceMatchesFrame(candidate, frame.abs_path)
+      );
+    }
+
+    if (!source || !lineno) {
+      consumer.destroy?.();
+      return false;
+    }
+
+    const content =
+      consumer.sourceContentFor?.(source, true) ||
+      sourceMap.sourcesContent?.[sourceMap.sources.indexOf(source)];
+
+    consumer.destroy?.();
+
+    if (!content) return false;
+
+    frame.abs_path = source;
+    frame.filename = normalizeSourcePath(source).split("/").pop() || frame.filename;
+    frame.lineno = lineno;
+    frame.colno = colno;
+    applySourceContext(frame, content.split("\n"), lineno);
+    return Boolean(frame.context_line);
+  } catch {
+    return false;
+  }
+}
+
+function getSourceContentFromWebpackFrame(frame) {
+  const globalObject = typeof globalThis !== "undefined" ? globalThis : window;
+  const webpackChunks =
+    Object.values(globalObject).find(
+      (value) =>
+        Array.isArray(value) &&
+        value.some((item) => Array.isArray(item) && item.length >= 2)
+    ) || [];
+
+  const framePath = normalizeSourcePath(
+    frame.abs_path || frame.module || frame.raw_abs_path
+  );
+  if (!framePath || !Array.isArray(webpackChunks)) return null;
+
+  for (const chunk of webpackChunks) {
+    const modules = Array.isArray(chunk) ? chunk[1] : null;
+    if (!modules || typeof modules !== "object") continue;
+
+    for (const [moduleId, factory] of Object.entries(modules)) {
+      if (!sourceMatchesFrame(moduleId, framePath)) continue;
+      const source = String(factory);
+      return source.includes("\n") ? source.split("\n") : null;
+    }
+  }
+
+  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);
+
+  const webpackLines = getSourceContentFromWebpackFrame(frame);
+  if (webpackLines) {
+    applySourceContext(frame, webpackLines, frame.lineno);
+    if (frame.context_line) return;
+  }
+
+  const lines = await fetchBrowserSourceLines(frame.abs_path, frame.raw_abs_path);
+  if (lines) {
+    applySourceContext(frame, lines, frame.lineno);
+    if (frame.context_line) return;
+  }
+
+  await enrichFrameWithSourceMap(frame);
 }
 
 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);
+  // Enrich the error frame first (last in-app frame), then nearby frames.
+  const targets = [...inAppFrames.slice(-5)].reverse();
 
   if (isNode) {
     await Promise.all(targets.map((frame) => enrichFrameWithNodeSource(frame)));
   } else if (isBrowser) {
-    await Promise.all(targets.map((frame) => enrichFrameWithBrowserSource(frame)));
+    for (const frame of targets) {
+      await enrichFrameWithBrowserSource(frame);
+    }
   }
 
   return stacktrace;

package/src/tracing.d.ts

@@ -0,0 +1,39 @@
+export interface Span {
+  span_id?: string;
+  op?: string;
+  description?: string;
+  start_timestamp?: string;
+  finish_timestamp?: string | null;
+  duration_ms?: number;
+  status?: string;
+  data?: Record<string, unknown>;
+  tags?: Record<string, unknown>;
+  [key: string]: unknown;
+}
+
+export interface Transaction {
+  trace_id?: string;
+  transaction?: string;
+  transaction_name?: string;
+  op?: string;
+  status?: string;
+  spans?: Span[];
+  data?: Record<string, unknown>;
+  tags?: Record<string, unknown>;
+  [key: string]: unknown;
+}
+
+export function initTracing(
+  dsn: string,
+  environment?: string,
+  debug?: boolean
+): void;
+
+export function startTransaction(
+  transaction: string,
+  transactionName?: string,
+  op?: string
+): Transaction;
+
+export function getCurrentTransaction(): Transaction | null;
+export function finishTransaction(status?: string): void;