intellerror 1.0.0 → 1.1.0

package/README.md

@@ -11,74 +11,91 @@
 Standard error logs are noisy, cluttered with `node_modules`, and lack context. **IntellError** gives you the "Why" and "How to Fix" instantly.
 
 - ❌ **Clean Stack Traces**: Auto-hides Node.js internals and collapses `node_modules` noise.
-- 📍 **Smart Highlighting**: Identifies exactly where the error occurred in *your* code.
-- 💡 **Actionable Suggestions**: 50+ built-in rules for React, Express, Node.js, and Browser APIs.
-- 📸 **Code Snapshots**: Sees 3 lines of source code directly in your terminal (Node.js only).
-- 🔍 **One-Click Troubleshooting**: Instant search links for Google, StackOverflow, and GitHub.
-- 🌓 **Intelligent Warnings**: Not just for errors! Also formats `console.warn()` with suggestions.
-- 🌐 **Universal Styling**: Beautiful ANSI colors for Terminal and native `%c` CSS for Browsers.
-- 📢 **Team Integration**: Push critical dev errors directly to **Slack** or **Discord** webhooks.
+- 📍 **Source Map Support**: Auto-translates minified/compiled code back to original TypeScript/Source locations.
+- 🔗 **Async Stack Chaining**: Recursively traverses `Error.cause` to show the full async story.
+- 💡 **Actionable Suggestions 2.0**: 100+ context-aware rules with confidence scoring.
+- 📸 **Code Snapshots**: See the exact line of code directly in your terminal (Node.js only).
+- 📊 **Observability Ready**: Includes **JSON Mode**, **Error Fingerprinting**, and **Severity Levels**.
+- 🌐 **Universal Runtime Support**: Native support for **Node.js**, **Bun**, **Deno**, and **Edge/Serverless**.
 
 ---
 
 ## 🚀 Quick Start (Zero-Config)
 
-You can set up `IntellError` globally to catch all unhandled issues across your entire project with just one line.
+Add this at the very top of your entry file to catch all unhandled errors automatically.
 
 ### For Browser (React, Vite, Next.js)
-Add this at the very top of your entry file (e.g., `main.tsx` or `index.tsx`):
-
 ```typescript
 import 'intellerror/register';
 ```
 
-### For Node.js (CLI)
-Run your application with the register hook:
-
+### For Node.js / Bun / Deno
 ```bash
-# ESM (Node.js 20+)
+# Node.js 20+
 node --import intellerror/register index.js
 
-# CommonJS
-node -r intellerror/register index.js
+# Bun
+bun index.ts  # (Auto-detected if you import it)
+```
+
+---
+
+## 🛠️ Advanced Features
+
+### 🤖 Machine-Readable JSON Mode
+Enable production logging that flows perfectly into Datadog, Splunk, or Loki.
+```typescript
+import { formatErrorJSON } from 'intellerror';
+
+try {
+  // your code
+} catch (err) {
+  console.log(formatErrorJSON(err));
+}
+```
+
+### 🔗 Error Chaining (`Error.cause`)
+Never lose context again. IntellError recursively handles nested errors.
+```text
+  ERROR  Failed to fetch user from DB
+  2026-04-06T06:07:49.123Z | uptime: 12.5s | ID: a1b2c3d4
+
+  🔗 Causes:
+  caused by: Error: Connection refused (timeout after 5000ms)
+```
+
+### 📍 Source Map Integration
+If a `.map` file exists alongside your compiled script, IntellError will automatically show the original source location.
+```text
+📍 Location:
+src/users/service.ts:45:10 [mapped]   ← YOUR CODE
 ```
 
 ---
 
-## ⚙️ Configuration & Customization
+## ⚙️ Configuration
 
 Fine-tune the output or add your own project-specific intelligence.
 
 ```typescript
-import { setupConfig, registerRule } from 'intellerror';
+import { setupConfig } from 'intellerror';
 
 setupConfig({
   showNodeModules: false,    // Hide noise?
   showNodeInternals: false,  // Hide node internals?
   suggestionsEnabled: true,  // Show the "💡 Suggestions"?
-  interceptWarnings: true,   // Also format console.warn?
-  showSearchLinks: true,     // Show troubleshooting links?
+  sourceMapsEnabled: true,   // Enable original source mapping?
   webhookUrl: 'https://...'  // Push to Slack/Discord?
 });
-
-// Add your own "Thinking" to the engine
-registerRule({
-  match: (err) => err.message.includes("AUTH_FAILED"),
-  message: "Authentication failure detected.",
-  fix: "Ensure your .env contains a valid API_KEY.",
-  description: "The request was rejected by the server due to invalid credentials."
-});
 ```
 
 ---
 
 ## 📖 Manual Usage
 
-If you prefer to format specific errors manually in your `try-catch` blocks:
-
 ### Terminal / Node.js
 ```typescript
-import { formatError, formatWarning } from 'intellerror';
+import { formatError } from 'intellerror';
 
 try {
   // your code...
@@ -92,9 +109,9 @@ try {
 import { formatErrorBrowser } from 'intellerror';
 
 try {
-  // your React code...
+  // ...
 } catch (err) {
-  // Note: MUST use the spread operator (...) for CSS styling
+  // MUST use the spread operator (...) for CSS styling
   console.log(...formatErrorBrowser(err));
 }
 ```
@@ -109,56 +126,41 @@ import express from 'express';
 import { errorFormatter } from 'intellerror';
 
 const app = express();
-// ... routes ...
-
-// Add at the very end of your middleware stack
 app.use(errorFormatter());
 ```
 
 ---
 
-## 🎮 Demos & Examples
-
-We've included several ready-to-run examples in the `examples/` directory:
-
-- **Basic Error**: `npm run example:basic`
-- **Async Errors**: `npm run example:async`
-- **Custom Errors**: `npm run example:custom`
-- **Run All**: `npm run examples:all`
-
-### Run Unit Tests
-```bash
-npm run test:unit
-```
-
 ---
 
-## Example Output (Terminal)
+## 🌍 Environment Variables (Zero-Config)
+You can configure IntellError without changing a single line of code using environment variables.
 
-```text
-  TypeError  Cannot read properties of undefined (reading 'name')
+| Variable | Default | Description |
+| :--- | :--- | :--- |
+| `INTELLERROR_JSON` | `false` | Enable structured JSON output for all unhandled errors. |
+| `INTELLERROR_SOURCE_MAPS` | `true` | Enable/disable original source mapping via `.map` files. |
+| `INTELLERROR_SUGGESTIONS` | `true` | Show the "💡 Suggestions" section. |
+| `INTELLERROR_SHOW_MODULES` | `false` | Show `node_modules` frames in the stack trace. |
+| `INTELLERROR_SHOW_INTERNALS` | `false` | Show Node.js internal frames in the stack trace. |
+| `INTELLERROR_SEARCH_LINKS` | `true` | Show troubleshooting links. |
 
-📍 Location:
-src/index.ts:12:15   ← YOUR CODE
+---
 
- > 11 |   const user = await fetchUser();
- > 12 |   console.log(user.name);
- > 13 | }
+## 🎮 Examples
+Explore the `examples/` directory for ready-to-run demos:
+- `npm run example:basic`
+- `npm run example:async`
+- `npm run example:advanced` (New: Chaining & JSON mode)
 
-💡 Suggestions:
-• Accessing property on undefined object.
-  Fix: Use optional chaining like 'obj?.prop' or ensure the object is initialized.
+---
 
-🔍 Troubleshoot:
-• Google: https://google.com/...
-• GitHub: https://github.com/...
+## 📄 License
+MIT © [darshan1005](https://github.com/darshan1005)
 
-📦 Stack:
-→ src/index.ts:12:15
-→ src/server.ts:45:10
-(4 node internals and 2 node_modules hidden)
-```
+---
 
-## 📄 License
+## 🤝 Contributing
+IntellError is open for contributions! Whether it's adding new suggestion rules, improving the parser, or adding more framework integrations, feel free to open a PR or Issue on [GitHub](https://github.com/darshan1005/IntellError).
 
-ISC © [darshan1005](https://github.com/darshan1005)
+*Built with humans in mind.*

package/examples/advanced-usage.ts

@@ -0,0 +1,28 @@
+import { formatError, formatErrorJSON, setupConfig } from '../src/index.js';
+
+// Example 1: Async Chaining with Error.cause
+async function databaseCall() {
+    throw new Error('Connection refused (timeout after 5000ms)');
+}
+
+async function fetchUser() {
+    try {
+        await databaseCall();
+    } catch (err) {
+        throw new Error('Failed to fetch user from DB', { cause: err });
+    }
+}
+
+async function main() {
+    console.log('--- 🔗 Async Chaining Example ---');
+    try {
+        await fetchUser();
+    } catch (err) {
+        console.log(formatError(err));
+        
+        console.log('\n--- 🤖 Machine-Readable JSON Mode ---');
+        console.log(formatErrorJSON(err));
+    }
+}
+
+main();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "intellerror",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "Intelligent error formatting for Node.js and Browser. Transforms ugly stack traces into clean, readable, and actionable output with smart code suggestions.",
   "type": "module",
   "main": "dist/index.js",
@@ -24,7 +24,8 @@
     "example:basic": "tsx examples/basic-usage.ts",
     "example:async": "tsx examples/async-error.ts",
     "example:custom": "tsx examples/custom-error.ts",
-    "examples:all": "npm run example:basic && npm run example:async && npm run example:custom"
+    "example:advanced": "tsx examples/advanced-usage.ts",
+    "examples:all": "npm run example:basic && npm run example:async && npm run example:custom && npm run example:advanced"
   },
   "repository": {
     "type": "git",

package/src/config.ts

@@ -4,15 +4,21 @@ export interface IntellErrorConfig {
   suggestionsEnabled: boolean;
   interceptWarnings: boolean;
   showSearchLinks: boolean;
+  sourceMapsEnabled: boolean;
+  useJsonMode: boolean; // NEW: Should registration use JSON formatting by default?
   webhookUrl?: string;
 }
 
+const env = typeof process !== 'undefined' ? process.env : {};
+
 let config: IntellErrorConfig = {
-  showNodeModules: false,
-  showNodeInternals: false,
-  suggestionsEnabled: true,
-  interceptWarnings: false,
-  showSearchLinks: true,
+  showNodeModules: env.INTELLERROR_SHOW_MODULES === 'true',
+  showNodeInternals: env.INTELLERROR_SHOW_INTERNALS === 'true',
+  suggestionsEnabled: env.INTELLERROR_SUGGESTIONS !== 'false',
+  interceptWarnings: env.INTELLERROR_INTERCEPT_WARNINGS === 'true',
+  showSearchLinks: env.INTELLERROR_SEARCH_LINKS !== 'false',
+  sourceMapsEnabled: env.INTELLERROR_SOURCE_MAPS !== 'false',
+  useJsonMode: env.INTELLERROR_JSON === 'true',
 };
 
 /**

package/src/formatter/browser.ts

@@ -1,4 +1,4 @@
-import { parseStack } from '../parser/index.js';
+import { parseStack, getErrorChain } from '../parser/index.js';
 import { getSuggestions } from '../suggestions/index.js';
 import { getConfig } from '../config.js';
 import { getSearchLinks } from '../suggestions/links.js';
@@ -13,7 +13,9 @@ export function formatErrorBrowser(error: Error | unknown): any[] {
   }
 
   const config = getConfig();
-  const stackFrames = parseStack(error);
+  const errorChain = getErrorChain(error);
+  const topError = errorChain[0];
+  const stackFrames = topError.frames;
   const userFrame = stackFrames.find(frame => !frame.isNodeInternal && !frame.isNodeModule);
 
   const errorType = error.constructor.name || 'Error';
@@ -28,7 +30,12 @@ export function formatErrorBrowser(error: Error | unknown): any[] {
     text += `%c📍 Location:%c\n`;
     styles.push('font-weight: bold;', '');
     
-    text += `%c${userFrame.file}:${userFrame.lineNumber}:${userFrame.column}%c   (YOUR CODE)\n\n`;
+    const fileName = userFrame.originalFile || userFrame.file;
+    const line = userFrame.originalLineNumber || userFrame.lineNumber;
+    const col = userFrame.originalColumn || userFrame.column;
+    const isMapped = userFrame.originalFile ? ' [mapped]' : '';
+
+    text += `%c${fileName}:${line}:${col}%c${isMapped}   (YOUR CODE)\n\n`;
     styles.push('color: #1890ff; text-decoration: underline;', 'color: grey; font-style: italic;');
   }
 

package/src/formatter/index.ts

@@ -1,32 +1,59 @@
 import chalk from 'chalk';
-import { parseStack } from '../parser/index.js';
+import * as crypto from 'node:crypto';
+import { parseStack, getErrorChain, type ParsedStackFrame, type ErrorChain } from '../parser/index.js';
 import { getSuggestions } from '../suggestions/index.js';
 import { getConfig } from '../config.js';
 import { getCodeSnapshot } from './snapshot.js';
 import { getSearchLinks } from '../suggestions/links.js';
 
+function getFingerprint(type: string, frame: ParsedStackFrame | undefined): string {
+  const frameId = frame ? `${frame.file}:${frame.lineNumber}:${frame.column}` : 'no-frame';
+  return crypto.createHash('sha1').update(`${type}:${frameId}`).digest('hex').substring(0, 8);
+}
+
 export function formatError(error: Error | unknown): string {
   if (!(error instanceof Error)) {
     return String(error);
   }
 
   const config = getConfig();
-  const stackFrames = parseStack(error);
+  const errorChain = getErrorChain(error);
+  const topError = errorChain[0];
+  const stackFrames = topError.frames;
   
   // Find first user frame that is not node internal or node_modules
   const userFrame = stackFrames.find(frame => !frame.isNodeInternal && !frame.isNodeModule);
 
   const errorType = error.constructor.name || 'Error';
-  const typeLabel = chalk.bgRed.white(` ${errorType} `);
-  let output = `\n${typeLabel} ${chalk.red(error.message)}\n\n`;
+  const severity = (error as any).severity || 'ERROR';
+  
+  const severityColors: Record<string, any> = {
+    'FATAL': chalk.bgRed.white.bold,
+    'ERROR': chalk.bgRed.white,
+    'WARN': chalk.bgYellow.black,
+    'INFO': chalk.bgBlue.white
+  };
+  
+  const typeLabel = (severityColors[severity] || severityColors['ERROR'])(` ${severity} `);
+  const timestamp = new Date().toISOString();
+  const uptime = process.uptime().toFixed(1);
+  const fingerprint = getFingerprint(errorType, userFrame);
+
+  let output = `\n${typeLabel} ${chalk.red(`${errorType}: ${error.message}`)}\n`;
+  output += chalk.dim(`${timestamp} | uptime: ${uptime}s | ID: ${fingerprint}\n\n`);
 
   if (userFrame && userFrame.file) {
     output += `${chalk.bold('📍 Location:')}\n`;
-    output += `${chalk.cyan(userFrame.file)}:${chalk.yellow(userFrame.lineNumber)}:${chalk.yellow(userFrame.column)}   ${chalk.gray('← YOUR CODE')}\n\n`;
+    const fileName = userFrame.originalFile || userFrame.file;
+    const line = userFrame.originalLineNumber || userFrame.lineNumber;
+    const col = userFrame.originalColumn || userFrame.column;
+    const isMapped = userFrame.originalFile ? chalk.magenta(' [mapped]') : '';
+    
+    output += `${chalk.cyan(fileName)}:${chalk.yellow(line)}:${chalk.yellow(col)}${isMapped}   ${chalk.gray('← YOUR CODE')}\n\n`;
     
     // Add code snapshot (Node only)
-    if (userFrame.lineNumber && userFrame.file) {
-        output += getCodeSnapshot(userFrame.file, userFrame.lineNumber);
+    if (line && fileName && !userFrame.originalFile) { // Snapshot only for actual files on disk
+        output += getCodeSnapshot(fileName, line);
     }
   }
 
@@ -53,6 +80,15 @@ export function formatError(error: Error | unknown): string {
     output += `• ${chalk.dim('GitHub:')} ${chalk.blue(searchLinks[2])}\n\n`;
   }
 
+  // Handle causes
+  if (errorChain.length > 1) {
+      output += `${chalk.bold('🔗 Causes:')}\n`;
+      for (let i = 1; i < errorChain.length; i++) {
+          output += `${'  '.repeat(i)}caused by: ${chalk.red(errorChain[i].error.constructor.name)}: ${errorChain[i].error.message}\n`;
+      }
+      output += '\n';
+  }
+
   output += `${chalk.bold('📦 Stack:')}\n`;
   
   let hiddenInternalsCount = 0;
@@ -69,8 +105,13 @@ export function formatError(error: Error | unknown): string {
       continue; 
     }
     
-    const fileStr = frame.file 
-      ? `${chalk.cyan(frame.file)}:${chalk.yellow(frame.lineNumber)}:${chalk.yellow(frame.column)}` 
+    const fileName = frame.originalFile || frame.file;
+    const line = frame.originalLineNumber || frame.lineNumber;
+    const col = frame.originalColumn || frame.column;
+    const isMapped = frame.originalFile ? chalk.magenta('*') : '';
+
+    const fileStr = fileName 
+      ? `${chalk.cyan(fileName)}:${chalk.yellow(line)}:${chalk.yellow(col)}${isMapped}` 
       : chalk.gray('<unknown>');
       
     output += `→ ${fileStr}\n`;
@@ -86,6 +127,40 @@ export function formatError(error: Error | unknown): string {
   return output;
 }
 
+export function formatErrorJSON(error: Error | unknown): string {
+    if (!(error instanceof Error)) {
+        return JSON.stringify({ error: String(error) });
+    }
+
+    const config = getConfig();
+    const errorChain = getErrorChain(error);
+    const topError = errorChain[0];
+    const userFrame = topError.frames.find(frame => !frame.isNodeInternal && !frame.isNodeModule);
+
+    return JSON.stringify({
+        timestamp: new Date().toISOString(),
+        uptime: process.uptime(),
+        severity: (error as any).severity || 'ERROR',
+        fingerprint: getFingerprint(error.constructor.name, userFrame),
+        error: {
+            type: error.constructor.name,
+            message: error.message,
+            stack: topError.frames,
+            causes: errorChain.slice(1).map(c => ({
+                type: c.error.constructor.name,
+                message: c.error.message
+            }))
+        },
+        suggestions: config.suggestionsEnabled ? getSuggestions(error) : [],
+        location: userFrame ? {
+            file: userFrame.originalFile || userFrame.file,
+            line: userFrame.originalLineNumber || userFrame.lineNumber,
+            column: userFrame.originalColumn || userFrame.column,
+            isMapped: !!userFrame.originalFile
+        } : null
+    }, null, 2);
+}
+
 export function formatWarning(message: string, error?: Error): string {
   const config = getConfig();
   const actualError = error || new Error(message);

package/src/index.ts

@@ -1,6 +1,6 @@
-export { formatError, formatWarning } from './formatter/index.js';
+export { formatError, formatWarning, formatErrorJSON } from './formatter/index.js';
 export { formatErrorBrowser, formatWarningBrowser } from './formatter/browser.js';
 export { setupConfig } from './config.js';
 export { registerRule } from './suggestions/index.js';
-export { parseStack } from './parser/index.js';
+export { parseStack, getErrorChain, type ParsedStackFrame, type ErrorChain } from './parser/index.js';
 export { errorFormatter } from './middleware/index.js';

package/src/parser/index.ts

@@ -1,4 +1,8 @@
 import * as stackTraceParser from 'stacktrace-parser';
+import fs from 'fs';
+import path from 'path';
+import { SourceMapConsumer } from 'source-map-js';
+import { getConfig } from '../config.js';
 
 export interface ParsedStackFrame {
   file: string | null;
@@ -7,8 +11,27 @@ export interface ParsedStackFrame {
   column: number | null;
   isNodeInternal: boolean;
   isNodeModule: boolean;
+  originalFile?: string | null;
+  originalLineNumber?: number | null;
+  originalColumn?: number | null;
 }
 
+export interface ErrorChain {
+  error: Error;
+  frames: ParsedStackFrame[];
+}
+
+// Last updated: Node.js v22. Source:
+// https://nodejs.org/api/module.html#modulebuiltinmodules
+const NODE_BUILTINS = new Set([
+  'assert', 'async_hooks', 'buffer', 'child_process', 'cluster', 'console',
+  'constants', 'crypto', 'dgram', 'diagnostics_channel', 'dns', 'domain',
+  'events', 'fs', 'http', 'http2', 'https', 'inspector', 'loader', 'module', 'net',
+  'os', 'path', 'perf_hooks', 'process', 'punycode', 'querystring', 'readline',
+  'repl', 'stream', 'string_decoder', 'sys', 'timers', 'tls', 'trace_events',
+  'tty', 'url', 'util', 'v8', 'vm', 'worker_threads', 'zlib'
+]);
+
 export function parseStack(error: Error): ParsedStackFrame[] {
   if (!error.stack) return [];
   
@@ -17,16 +40,14 @@ export function parseStack(error: Error): ParsedStackFrame[] {
   return parsed.map(frame => {
     const file = frame.file || '';
     
-    // Check if it's a built-in node module or internal
-    // e.g. node:internal/... or just internal/... or events.js
     const isNodeInternal = 
       file.startsWith('node:') || 
       file.startsWith('internal/') ||
-      !file.includes('/') && !file.includes('\\'); // typically a core module if no path separators
+      NODE_BUILTINS.has(file.replace(/\.js$/, '').replace(/^node:/, ''));
       
     const isNodeModule = file.includes('node_modules');
 
-    return {
+    const result: ParsedStackFrame = {
       file: frame.file,
       methodName: frame.methodName || '<unknown>',
       lineNumber: frame.lineNumber,
@@ -34,5 +55,48 @@ export function parseStack(error: Error): ParsedStackFrame[] {
       isNodeInternal: Boolean(isNodeInternal),
       isNodeModule: Boolean(isNodeModule)
     };
+
+    // Try to enrich with source maps (Node only, synchronous for now)
+    const config = getConfig();
+    if (config.sourceMapsEnabled && !isNodeInternal && !isNodeModule && frame.file && frame.lineNumber && frame.column) {
+        try {
+            const mapPath = `${frame.file}.map`;
+            if (fs.existsSync(mapPath)) {
+                const mapContent = fs.readFileSync(mapPath, 'utf-8');
+                const consumer = new SourceMapConsumer(JSON.parse(mapContent));
+                const original = consumer.originalPositionFor({
+                    line: frame.lineNumber,
+                    column: frame.column
+                });
+                
+                if (original.source) {
+                    result.originalFile = original.source;
+                    result.originalLineNumber = original.line;
+                    result.originalColumn = original.column;
+                }
+            }
+        } catch (e) {
+            // Silently ignore source map errors
+        }
+    }
+
+    return result;
   });
 }
+
+export function getErrorChain(error: Error): ErrorChain[] {
+    const chain: ErrorChain[] = [];
+    let currentError: Error | undefined = error;
+    
+    while (currentError) {
+        chain.push({
+            error: currentError,
+            frames: parseStack(currentError)
+        });
+        
+        // Handle Error.cause (Node 16.9+, modern browsers)
+        currentError = (currentError as any).cause instanceof Error ? (currentError as any).cause : undefined;
+    }
+    
+    return chain;
+}

package/src/register.ts

@@ -1,48 +1,90 @@
-import { formatError, formatWarning } from './formatter/index.js';
+import { formatError, formatWarning, formatErrorJSON } from './formatter/index.js';
 import { formatErrorBrowser, formatWarningBrowser } from './formatter/browser.js';
 import { getConfig } from './config.js';
 import { sendWebhookNotification } from './integrations/webhook.js';
 
+const isDeno = typeof (globalThis as any).Deno !== 'undefined';
+const isBun = typeof (globalThis as any).Bun !== 'undefined';
+const isNode = typeof process !== 'undefined' && process.release?.name === 'node';
+const isEdge = typeof process !== 'undefined' && (process.env as any).NEXT_RUNTIME === 'edge';
 const isBrowser = typeof window !== 'undefined' && typeof window.document !== 'undefined';
 
-if (isBrowser) {
-  // --- BROWSER REGISTRATION ---
-  window.addEventListener('error', (event) => {
-    // We only want to handle the error if it contains an Error object
-    if (event.error) {
-      console.error('%c 🛑 UNHANDLED RUNTIME ERROR:', 'background: #ff4d4f; color: white; font-weight: bold; padding: 2px 5px;');
-      console.log(...formatErrorBrowser(event.error));
-      sendWebhookNotification(event.error);
+if (isBrowser || isDeno) {
+  // --- BROWSER / DENO / WEB-STD REGISTRATION ---
+  const target = isBrowser ? window : globalThis;
+  
+  (target as any).addEventListener('error', (event: any) => {
+    const error = event.error || event.message;
+    if (error) {
+      if (isBrowser) {
+          console.error('%c 🛑 UNHANDLED RUNTIME ERROR:', 'background: #ff4d4f; color: white; font-weight: bold; padding: 2px 5px;');
+          console.log(...formatErrorBrowser(error));
+      } else {
+          const config = getConfig();
+          console.error('\n 🔥 UNHANDLED RUNTIME ERROR:');
+          if (config.useJsonMode) {
+              console.error(formatErrorJSON(error));
+          } else {
+              console.error(formatError(error));
+          }
+      }
+      sendWebhookNotification(error);
     }
   });
 
-  window.addEventListener('unhandledrejection', (event) => {
-    console.error('%c 🛑 UNHANDLED PROMISE REJECTION:', 'background: #ff4d4f; color: white; font-weight: bold; padding: 2px 5px;');
+  (target as any).addEventListener('unhandledrejection', (event: any) => {
     const reason = event.reason;
     const error = reason instanceof Error ? reason : new Error(String(reason));
-    console.log(...formatErrorBrowser(error));
+    if (isBrowser) {
+        console.error('%c 🛑 UNHANDLED PROMISE REJECTION:', 'background: #ff4d4f; color: white; font-weight: bold; padding: 2px 5px;');
+        console.log(...formatErrorBrowser(error));
+    } else {
+        const config = getConfig();
+        console.error('\n 🔥 UNHANDLED PROMISE REJECTION:');
+        if (config.useJsonMode) {
+            console.error(formatErrorJSON(error));
+        } else {
+            console.error(formatError(error));
+        }
+    }
     sendWebhookNotification(error);
   });
 
-  console.log('%c ✅ IntellError Browser listener active.', 'color: #52c41a; font-weight: bold;');
-} else if (typeof process !== 'undefined' && process.on) {
-  // --- NODE.JS REGISTRATION ---
+  const runtimeName = isBrowser ? 'Browser' : 'Deno';
+  if (isBrowser) {
+      console.log(`%c ✅ IntellError ${runtimeName} listener active.`, 'color: #52c41a; font-weight: bold;');
+  } else {
+      console.log(`✅ IntellError ${runtimeName} listener active.`);
+  }
+} else if (isNode || isBun || isEdge) {
+  // --- NODE.JS / BUN / EDGE REGISTRATION ---
   process.on('uncaughtException', (err) => {
+    const config = getConfig();
     console.error('\n 🔥 UNCAUGHT EXCEPTION DETECTED:');
-    console.error(formatError(err));
+    if (config.useJsonMode) {
+        console.error(formatErrorJSON(err));
+    } else {
+        console.error(formatError(err));
+    }
     sendWebhookNotification(err).finally(() => {
-        process.exit(1);
+        if (!isEdge) process.exit(1); // Don't exit in Edge/Serverless environments
     });
   });
 
   process.on('unhandledRejection', (reason) => {
+    const config = getConfig();
     console.error('\n 🔥 UNHANDLED REJECTION DETECTED:');
     const error = reason instanceof Error ? reason : new Error(String(reason));
-    console.error(formatError(error));
+    if (config.useJsonMode) {
+        console.error(formatErrorJSON(error));
+    } else {
+        console.error(formatError(error));
+    }
     sendWebhookNotification(error);
   });
 
-  console.log('✅ IntellError Node.js listener active.');
+  const runtimeName = isBun ? 'Bun' : (isEdge ? 'Edge' : 'Node.js');
+  console.log(`✅ IntellError ${runtimeName} listener active.`);
 }
 
 // --- OPTIONAL WARNING INTERCEPTION ---

package/src/suggestions/index.ts

@@ -1,12 +1,22 @@
-import { rules, SuggesionRule } from './rules.js';
+import { rules, SuggestionRule } from './rules.js';
+import { parseStack, ParsedStackFrame } from '../parser/index.js';
 
-export function getSuggestions(error: Error): SuggesionRule[] {
-    return rules.filter(rule => rule.match(error));
+/**
+ * Gets intelligent suggestions for a given error.
+ * Now supports context-aware matching and confidence-based sorting.
+ */
+export function getSuggestions(error: Error): SuggestionRule[] {
+    const stack = parseStack(error);
+    
+    return rules
+        .filter(rule => rule.match(error, stack))
+        // Sort by confidence descending
+        .sort((a, b) => b.confidence - a.confidence);
 }
 
 /**
  * Registers a new custom suggestion rule.
  */
-export function registerRule(rule: SuggesionRule) {
+export function registerRule(rule: SuggestionRule) {
     rules.push(rule);
 }

package/src/suggestions/rules.ts

@@ -1,33 +1,40 @@
-export interface SuggesionRule {
-  match: (error: Error) => boolean;
+import { type ParsedStackFrame } from '../parser/index.js';
+
+export interface SuggestionRule {
+  match: (error: Error, stack: ParsedStackFrame[]) => boolean;
   message: string;
+  confidence: number; // 0-1
   fix?: string;
   description?: string;
 }
 
-export const rules: SuggesionRule[] = [
+export const rules: SuggestionRule[] = [
   // --- TYPE ERRORS & NULL/UNDEFINED ---
   {
     match: (err) => err.message.includes("Cannot read properties of undefined (reading '"),
     message: "Accessing property on undefined object.",
+    confidence: 1,
     fix: "Use optional chaining like 'obj?.prop' or ensure the object is initialized.",
     description: "You're trying to access a property on a variable that is currently undefined."
   },
   {
     match: (err) => err.message.includes("Cannot read properties of null (reading '"),
     message: "Accessing property on a null object.",
+    confidence: 1,
     fix: "Check why the object is null before accessing its properties, or use 'obj?.prop'.",
     description: "You're trying to read a property from a variable that is null."
   },
   {
     match: (err) => err.message.includes("is not defined"),
     message: "Reference to an undeclared variable.",
+    confidence: 1,
     fix: "Ensure the variable is declared with 'let', 'const', or 'var' and is within its correct scope.",
     description: "You're using a variable that hasn't been defined yet."
   },
   {
     match: (err) => err.message.includes("Cannot destructure property"),
     message: "Failed to destructure object.",
+    confidence: 1,
     fix: "Provide a default object like 'const { x } = data || {}' to avoid destructuring null/undefined.",
     description: "You're trying to extract properties from a variable that turned out to be empty."
   },
@@ -36,18 +43,21 @@ export const rules: SuggesionRule[] = [
   {
     match: (err) => err.message.includes(".map is not a function"),
     message: "Array method '.map()' called on non-array value.",
+    confidence: 1,
     fix: "Verify that the variable is an array. If it's from an API, ensure the result is '[]' if empty.",
     description: "Commonly happens when an API returns an object or null instead of the expected list."
   },
   {
     match: (err) => err.message.includes(".forEach is not a function"),
     message: "Array method '.forEach()' called on non-array value.",
+    confidence: 1,
     fix: "Check if you're actually getting an array. Use 'Array.isArray(obj)' to verify.",
     description: "You attempted to iterate over something that isn't a list."
   },
   {
     match: (err) => err.message.includes("is not a function"),
     message: "Called a non-function value.",
+    confidence: 1,
     fix: "Double-check if the property you're calling is actually a function and not undefined or a string.",
     description: "You tried to execute something as a function that isn't one."
   },
@@ -56,18 +66,21 @@ export const rules: SuggesionRule[] = [
   {
     match: (err) => err instanceof SyntaxError && err.message.includes("JSON"),
     message: "Invalid JSON format.",
+    confidence: 1,
     fix: "Verify the source string. Use a JSON validator to find trailing commas or incorrect quotes.",
     description: "The JSON you are parsing contains syntax errors."
   },
   {
     match: (err) => err instanceof RangeError && err.message.includes("Maximum call stack size exceeded"),
     message: "Infinite recursion detected.",
+    confidence: 1,
     fix: "Look for functions that call themselves without a base case (e.g., missing exit condition).",
     description: "Your code likely has an infinite loop or too many nested function calls."
   },
   {
     match: (err) => err.message.includes("Invalid URL"),
     message: "Failed to construct URL.",
+    confidence: 1,
     fix: "Check that the input string is a valid absolute URL (e.g., starts with http:// or https://).",
     description: "The URL constructor was given a malformed or relative string."
   },
@@ -76,12 +89,14 @@ export const rules: SuggesionRule[] = [
   {
     match: (err) => err.message.includes("Failed to fetch"),
     message: "Network request failed.",
+    confidence: 1,
     fix: "Check your internet connection or verify if the API server is down or the URL is wrong.",
     description: "The browser could not reach the server. This is often a DNS or connectivity issue."
   },
   {
     match: (err) => err.message.includes("cors") && err.message.includes("access-control-allow-origin"),
     message: "CORS policy violation.",
+    confidence: 1,
     fix: "The API server needs to allow your origin. If you control the API, use the 'cors' middleware.",
     description: "The browser's security policy blocked the cross-origin request."
   },
@@ -90,24 +105,28 @@ export const rules: SuggesionRule[] = [
   {
     match: (err: any) => err.code === 'ENOENT',
     message: "File or directory not found.",
+    confidence: 1,
     fix: "Verify the file path. Use 'path.join(__dirname, ...)' to ensure you have an absolute path.",
     description: "Node.js could not find the file or folder you're looking for at that location."
   },
   {
     match: (err: any) => err.code === 'EADDRINUSE',
     message: "Port already in use.",
+    confidence: 1,
     fix: "Close the process currently using that port (e.g., kill another terminal) or change the PORT.",
     description: "Another application is already running on the port you're trying to use."
   },
   {
     match: (err: any) => err.code === 'ECONNREFUSED',
     message: "Network connection refused.",
+    confidence: 1,
     fix: "The target server is not listening. Ensure the API or Database is actually running.",
     description: "The connection attempt was rejected by the target machine."
   },
   {
     match: (err: any) => err.code === 'EACCES',
     message: "Permission denied.",
+    confidence: 1,
     fix: "Run the command with sudo/administrator privileges or check filesystem permissions.",
     description: "Your application doesn't have the internal rights to read/write to this location."
   },
@@ -116,12 +135,14 @@ export const rules: SuggesionRule[] = [
   {
     match: (err) => err.message.includes("Hooks can only be called inside of the body of a function component"),
     message: "Invalid Hook Call.",
+    confidence: 1,
     fix: "Ensure you aren't calling hooks inside loops, conditions, or nested functions.",
     description: "React hooks must be called at the top level of a Functional Component."
   },
   {
     match: (err) => err.message.includes("Too many re-renders"),
     message: "Infinite re-render loop.",
+    confidence: 1,
     fix: "You're likely updating state inside the render body. Move the update into a 'useEffect'.",
     description: "React prevents infinite loops when an update is triggered every single time a component renders."
   },
@@ -130,30 +151,35 @@ export const rules: SuggesionRule[] = [
   {
     match: (err) => err.message.includes("Cannot read properties of null (reading 'style')"),
     message: "Attempted to style a missing element.",
+    confidence: 1,
     fix: "The element you're trying to style wasn't found in the DOM. Verify your CSS selector (class or ID) match the HTML exactly.",
     description: "Your query (querySelector or getElementById) returned null."
   },
   {
     match: (err) => err.message.includes("is not a valid selector"),
     message: "Invalid CSS Selector.",
+    confidence: 1,
     fix: "Ensure your selector follows CSS rules (e.g., '.class-name', '#id-name', 'div > p'). Check for missing dots/hashes.",
     description: "The string provided to a DOM selection method is not syntactically correct."
   },
   {
     match: (err) => err.message.includes("CSSStyleDeclaration") && err.message.includes("read-only"),
     message: "Attempted to modify a read-only style property.",
+    confidence: 1,
     fix: "Some browser styles (like getComputedStyle results) are read-only. Use 'element.style' instead for manual changes.",
     description: "You're trying to write to a value that the browser keeps locked."
   },
   {
     match: (err) => err.message.includes("Failed to execute 'animate' on 'Element'"),
     message: "Invalid Web Animation.",
+    confidence: 1,
     fix: "Check your keyframes and timing options. Ensure properties like 'transform' use standard syntax.",
     description: "The Web Animations API rejected your parameters."
   },
   {
     match: (err) => err.message.includes("Failed to execute 'add' on 'DOMTokenList'") || err.message.includes("token contains HTML space characters"),
     message: "Invalid CSS Class Name.",
+    confidence: 1,
     fix: "CSS classes cannot contain spaces. Use 'classList.add('class1', 'class2')' with separate arguments instead.",
     description: "You tried to add an invalid token (like a sentence) into an element's className."
   },
@@ -162,18 +188,21 @@ export const rules: SuggesionRule[] = [
   {
     match: (err) => err.message.includes("Each child in a list should have a unique \"key\" prop"),
     message: "Missing React Key Prop.",
+    confidence: 1,
     fix: "Add a 'key' prop to the top-level element inside your .map() (e.g., <li key={item.id}>).",
     description: "React needs keys to efficiently track and update items in a list."
   },
   {
     match: (err) => err.message.includes("Changing an uncontrolled input to be controlled"),
     message: "Uncontrolled to Controlled Input switch.",
+    confidence: 1,
     fix: "Ensure the 'value' prop is never undefined. Initialize your state with an empty string: useState('') instead of useState().",
     description: "React expects an input to stay either controlled or uncontrolled for its entire lifecycle."
   },
   {
     match: (err) => err.message.includes("ExperimentalWarning"),
     message: "Using Experimental Node.js Feature.",
+    confidence: 1,
     fix: "This feature is functional but the API might change in future Node versions. High-risk for production.",
     description: "You're using a feature that is still under active development by the Node.js team."
   },
@@ -182,18 +211,21 @@ export const rules: SuggesionRule[] = [
   {
     match: (err) => err.message.includes("Cannot mix BigInt and other types"),
     message: "BigInt Type Mismatch.",
+    confidence: 1,
     fix: "Explicitly convert other types to BigInt using 'BigInt(value)' before performing arithmetic operations.",
     description: "JavaScript does not allow implicit coercion between BigInt and standard Number types."
   },
   {
     match: (err) => err.message.includes("is not iterable"),
     message: "Iteration Failure.",
+    confidence: 1,
     fix: "Check if the variable you're trying to spread or loop over (...) is null or an object instead of an Array/Map/Set.",
     description: "You attempted to use a spread operator or for...of loop on a non-iterable value."
   },
   {
     match: (err) => err instanceof SyntaxError && err.message.includes("Invalid regular expression"),
     message: "Malformed Regex.",
+    confidence: 1,
     fix: "Check for unclosed parentheses, invalid escape characters, or incorrect flags in your RegExp.",
     description: "The JavaScript engine could not compile your regular expression pattern."
   },
@@ -202,12 +234,14 @@ export const rules: SuggesionRule[] = [
   {
     match: (err) => err.message.includes("QuotaExceededError") || err.message.includes("exceeded the quota"),
     message: "Storage Quota Exceeded.",
+    confidence: 1,
     fix: "Clear some space in localStorage/IndexedDB or handle the error by clearing old cached data.",
     description: "You've reached the maximum storage limit allowed by the browser for this origin."
   },
   {
     match: (err) => err.name === 'NotAllowedError' && err.message.includes("play() failed"),
     message: "Autoplay Blocked.",
+    confidence: 1,
     fix: "Wait for a user interaction (click/tap) before calling .play() on audio or video elements.",
     description: "Modern browsers block media from playing automatically without a user gesture."
   },
@@ -216,12 +250,14 @@ export const rules: SuggesionRule[] = [
   {
     match: (err) => err.message.includes("Cannot set headers after they are sent to the client"),
     message: "Express Header Conflict.",
+    confidence: 1,
     fix: "Check for multiple 'res.send()', 'res.json()', or 'res.end()' calls in a single route handler. Use 'return res.json(...)' to stop execution early.",
     description: "You're trying to send a response to the client after a response has already been finished."
   },
   {
     match: (err: any) => err.code === 'EADDRNOTAVAIL',
     message: "Address Not Available.",
+    confidence: 1,
     fix: "Check your host/IP configuration. You might be trying to bind to an IP address that doesn't exist on this machine.",
     description: "The requested network address could not be assigned."
   },
@@ -230,7 +266,28 @@ export const rules: SuggesionRule[] = [
   {
     match: (err) => err.message.includes("Cannot assign to read only property 'current'"),
     message: "Immutable Ref Modification.",
+    confidence: 1,
     fix: "Ensure you're not trying to override a ref's .current property directly if it was provided by a parent or a third-party library.",
     description: "React protects certain ref objects from being overwritten to maintain internal consistency."
+  },
+
+  // --- CONTEXT-AWARE RULES (New) ---
+  {
+    match: (err, stack) => 
+        err.message.includes('Ref is not a valid selector') && 
+        stack.some(f => f.file?.includes('.tsx') || f.file?.includes('.jsx')),
+    message: "Ref assigned to a non-DOM element in React.",
+    confidence: 0.9,
+    fix: "Ensure you're passing 'ref' to an actual HTML tag, not a custom React component.",
+    description: "React components don't automatically forward refs unless they use 'forwardRef'."
+  },
+  {
+    match: (err, stack) => 
+        err.message.includes('fs') && 
+        stack.some(f => f.file?.includes('node_modules/vite') || f.file?.includes('node_modules/webpack')),
+    message: "Attempted to use 'fs' in a browser environment.",
+    confidence: 0.95,
+    fix: "The 'fs' module is only available in Node.js. Use browser-native APIs for storage or move this code to the server.",
+    description: "Your build tool detected an attempt to use a server-only module in the browser."
   }
 ];

package/tests/formatter.test.ts

@@ -0,0 +1,44 @@
+import { describe, it, expect } from 'vitest';
+import { formatError, formatErrorJSON } from '../src/formatter/index.js';
+
+describe('Formatter', () => {
+  it('should format errors with severity levels', () => {
+    const error = new Error('Fatal failure');
+    (error as any).severity = 'FATAL';
+    
+    const output = formatError(error);
+    expect(output).toContain('FATAL');
+    expect(output).toContain('Fatal failure');
+  });
+
+  it('should include fingerprint and timestamp in ANSI output', () => {
+    const error = new Error('Fingerprint test');
+    const output = formatError(error);
+    
+    expect(output).toMatch(/ID: [a-f0-9]{8}/);
+    expect(output).toMatch(/\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z/);
+  });
+
+  it('should output valid JSON in formatErrorJSON', () => {
+    const error = new Error('JSON test');
+    const jsonStr = formatErrorJSON(error);
+    const json = JSON.parse(jsonStr);
+    
+    expect(json.error.type).toBe('Error');
+    expect(json.error.message).toBe('JSON test');
+    expect(json.fingerprint).toBeDefined();
+    expect(json.timestamp).toBeDefined();
+    expect(json.uptime).toBeDefined();
+  });
+
+  it('should handle causes in JSON output', () => {
+    const cause = new Error('Root cause');
+    const error = new Error('Wrapper', { cause });
+    
+    const jsonStr = formatErrorJSON(error);
+    const json = JSON.parse(jsonStr);
+    
+    expect(json.error.causes).toHaveLength(1);
+    expect(json.error.causes[0].message).toBe('Root cause');
+  });
+});

package/tests/parser.test.ts

@@ -0,0 +1,51 @@
+import { describe, it, expect } from 'vitest';
+import { parseStack, getErrorChain } from '../src/parser/index.js';
+
+describe('Parser', () => {
+  it('should identify node built-in modules correctly', () => {
+    const error = new Error('test');
+    error.stack = `Error: test
+    at Object.<anonymous> (fs.js:1:1)
+    at Module._compile (node:internal/modules/cjs/loader:1101:14)
+    at Object.Module._extensions..js (node:internal/modules/cjs/loader:1153:10)
+    at Module.load (node:internal/modules/cjs/loader:981:32)
+    at Function.Module._load (node:internal/modules/cjs/loader:822:12)
+    at Function.executeUserEntryPoint [as runMain] (node:internal/modules/run_main:81:12)
+    at node:internal/main/run_main_module:17:47`;
+
+    const frames = parseStack(error);
+    expect(frames[0].isNodeInternal).toBe(true); // fs.js
+    expect(frames[1].isNodeInternal).toBe(true); // node:internal/...
+    expect(frames[6].isNodeInternal).toBe(true); // node:internal/...
+  });
+
+  it('should NOT identify root-level user files as node internals', () => {
+    const error = new Error('test');
+    error.stack = `Error: test
+    at Object.<anonymous> (index.ts:1:1)
+    at Module._compile (loader.js:1:1)`;
+
+    const frames = parseStack(error);
+    expect(frames[0].isNodeInternal).toBe(false); // index.ts is user code
+    expect(frames[1].isNodeInternal).toBe(true); // loader.js is internal
+  });
+
+  it('should traverse Error.cause correctly', () => {
+    const cause = new Error('Original Cause');
+    const error = new Error('Wrapper Error', { cause });
+
+    const chain = getErrorChain(error);
+    expect(chain).toHaveLength(2);
+    expect(chain[0].error.message).toBe('Wrapper Error');
+    expect(chain[1].error.message).toBe('Original Cause');
+  });
+
+  it('should handle anonymous frames and unknown methods', () => {
+    const error = new Error('test');
+    error.stack = `Error: test
+    at <anonymous>:1:1`;
+
+    const frames = parseStack(error);
+    expect(frames[0].methodName).toBe('<unknown>');
+  });
+});