feat: standard error diagnostics, stack traces, and formatting

Author: Thanga-Ganapathy

crates/engine/src/convert.rs

@@ -87,7 +87,10 @@ pub(crate) fn build_exception<'s>(
     let class = err.exception_class();
 
     // Fallback/dynamic constructor lookup for classes V8 doesn't provide natively.
-    let try_construct = |scope: &mut v8::PinScope<'s, '_>, class_name: &str, args: &[v8::Local<'s, v8::Value>]| -> Option<v8::Local<'s, v8::Value>> {
+    let try_construct = |scope: &mut v8::PinScope<'s, '_>,
+                         class_name: &str,
+                         args: &[v8::Local<'s, v8::Value>]|
+     -> Option<v8::Local<'s, v8::Value>> {
         let context = scope.get_current_context();
         let global = context.global(scope);
         let key = v8::String::new(scope, class_name)?;
@@ -102,19 +105,18 @@ pub(crate) fn build_exception<'s>(
     };
 
     if let ExceptionClass::DomException(name) = class {
-        if let Some(msg_val) = v8::String::new(scope, &err.exception_message()) {
-            if let Some(name_val) = v8::String::new(scope, name) {
-                if let Some(ex) = try_construct(scope, "DOMException", &[msg_val.into(), name_val.into()]) {
-                    return ex;
-                }
-            }
-        }
-    } else if let ExceptionClass::UriError = class {
-        if let Some(msg_val) = v8::String::new(scope, &err.exception_message()) {
-            if let Some(ex) = try_construct(scope, "URIError", &[msg_val.into()]) {
-                return ex;
-            }
+        if let Some(msg_val) = v8::String::new(scope, &err.exception_message())
+            && let Some(name_val) = v8::String::new(scope, name)
+            && let Some(ex) =
+                try_construct(scope, "DOMException", &[msg_val.into(), name_val.into()])
+        {
+            return ex;
         }
+    } else if let ExceptionClass::UriError = class
+        && let Some(msg_val) = v8::String::new(scope, &err.exception_message())
+        && let Some(ex) = try_construct(scope, "URIError", &[msg_val.into()])
+    {
+        return ex;
     }
 
     let text = match class.dom_exception_name() {
@@ -145,10 +147,56 @@ pub(crate) fn describe_exception(
     scope: &mut v8::PinnedRef<'_, v8::TryCatch<v8::HandleScope>>,
     fallback: &str,
 ) -> String {
-    match scope.exception() {
-        Some(exception) => js_to_string(scope, exception),
-        None => fallback.to_string(),
+    let exception = match scope.exception() {
+        Some(e) => e,
+        None => return fallback.to_string(),
+    };
+
+    if let Ok(obj) = v8::Local::<v8::Object>::try_from(exception) {
+        let key = v8::String::new(scope, "stack").unwrap();
+        if let Some(stack_val) = obj.get(scope, key.into())
+            && stack_val.is_string()
+        {
+            return stack_val.to_rust_string_lossy(scope);
+        }
+    }
+
+    if let Some(msg) = scope.message() {
+        let text = msg.get(scope).to_rust_string_lossy(scope);
+        // Fallback to building a minimal trace from v8::Message if .stack is missing
+        if let Some(trace) = msg.get_stack_trace(scope)
+            && trace.get_frame_count() > 0
+            && let Some(frame) = trace.get_frame(scope, 0)
+        {
+            let file = frame
+                .get_script_name_or_source_url(scope)
+                .map(|s| s.to_rust_string_lossy(scope))
+                .unwrap_or_else(|| "<unknown>".to_string());
+            let line = frame.get_line_number();
+            let col = frame.get_column();
+            return format!("{text}\n    at {file}:{line}:{col}");
+        }
+        return text;
+    }
+
+    js_to_string(scope, exception)
+}
+
+/// Formats an exception value (e.g. from an unhandled promise rejection) by
+/// extracting its `.stack` property if available, otherwise stringifying it.
+pub(crate) fn format_exception(
+    scope: &mut v8::PinScope<'_, '_>,
+    exception: v8::Local<v8::Value>,
+) -> String {
+    if let Ok(obj) = v8::Local::<v8::Object>::try_from(exception) {
+        let key = v8::String::new(scope, "stack").unwrap();
+        if let Some(stack_val) = obj.get(scope, key.into())
+            && stack_val.is_string()
+        {
+            return stack_val.to_rust_string_lossy(scope);
+        }
     }
+    js_to_string(scope, exception)
 }
 
 /// Coerces any V8 value to a Rust `String` via JS `String(value)` semantics.

crates/engine/src/module.rs

@@ -293,7 +293,7 @@ pub(crate) fn eval_state(
         v8::PromiseState::Fulfilled => ModuleEvalState::Completed,
         v8::PromiseState::Rejected => {
             let reason = promise.result(scope);
-            ModuleEvalState::Failed(js_to_string(scope, reason))
+            ModuleEvalState::Failed(crate::convert::format_exception(scope, reason))
         }
     }
 }

crates/engine/src/op.rs

@@ -24,7 +24,7 @@ use es_runtime_common::{
     Capability, CapabilitySet, Error as CommonError, ExceptionClass, IntoException,
 };
 
-use crate::convert::{build_exception, js_to_string, marshal, throw, value_to_js};
+use crate::convert::{build_exception, marshal, throw, value_to_js};
 use crate::error::{Error, Result};
 use crate::value::Value;
 
@@ -696,7 +696,7 @@ pub(crate) fn take_unhandled_rejections(
         .iter()
         .map(|value| {
             let value = v8::Local::new(scope, value);
-            js_to_string(scope, value)
+            crate::convert::format_exception(scope, value)
         })
         .collect()
 }

crates/runtime-cli/src/main.rs

@@ -186,13 +186,34 @@ fn parse_args() -> Result<Config, String> {
     }
     Err(format!("missing script argument\n\n{USAGE}"))
 }
+use std::io::IsTerminal;
+
+fn print_error(err: &str) {
+    let use_color = std::io::stderr().is_terminal() && std::env::var_os("NO_COLOR").is_none();
+    if !use_color {
+        eprintln!("error: {}", err);
+        return;
+    }
+
+    let mut lines = err.lines();
+    if let Some(first) = lines.next() {
+        eprintln!("\x1b[1;31merror\x1b[0m: {}", first);
+    }
+    for line in lines {
+        if line.starts_with("    at ") {
+            eprintln!("\x1b[2m{}\x1b[0m", line);
+        } else {
+            eprintln!("{}", line);
+        }
+    }
+}
 
 #[tokio::main(flavor = "current_thread")]
 async fn main() -> ExitCode {
     match run().await {
         Ok(()) => ExitCode::SUCCESS,
         Err(err) => {
-            eprintln!("esrun: {err}");
+            print_error(&err);
             ExitCode::FAILURE
         }
     }
@@ -347,18 +368,18 @@ async fn run() -> Result<(), String> {
     // evaluation. Report it as the primary error — its rejection also shows up
     // in `rejections`, so it is the one uncaught-rejection we don't re-report.
     if let ModuleEvalState::Failed(message) = runtime.module_eval_state() {
-        eprintln!("Uncaught: {message}");
-        return Err(format!("{label}: module evaluation failed"));
+        return Err(format!("uncaught exception in {label}\n{message}"));
     }
 
     if !rejections.is_empty() {
-        for message in &rejections {
-            eprintln!("Uncaught (in promise): {message}");
+        let mut msg = format!("{} unhandled promise rejection(s)\n", rejections.len());
+        for (i, message) in rejections.iter().enumerate() {
+            if i > 0 {
+                msg.push('\n');
+            }
+            msg.push_str(message);
         }
-        return Err(format!(
-            "{} unhandled promise rejection(s)",
-            rejections.len()
-        ));
+        return Err(msg);
     }
     Ok(())
 }

crates/runtime-cli/tests/modules.rs

@@ -87,8 +87,9 @@ fn top_level_throw_fails_with_uncaught_report() {
     assert!(stdout(&out).contains("before throw"), "{}", stdout(&out));
     // ...and the throw is reported once as Uncaught.
     let stderr = stderr(&out);
-    assert!(stderr.contains("Uncaught"), "{stderr}");
+    assert!(stderr.contains("error: uncaught exception"), "{stderr}");
     assert!(stderr.contains("fixture boom"), "{stderr}");
+    assert!(stderr.contains("at file://"), "{stderr}");
 }
 
 #[test]
@@ -419,3 +420,20 @@ fn version_flag_succeeds() {
     assert!(out.status.success());
     assert!(stdout(&out).contains("esrun"), "{}", stdout(&out));
 }
+
+#[test]
+fn unhandled_rejection_reports_stack_trace() {
+    let out = esrun()
+        .arg("-e")
+        .arg("setTimeout(() => { Promise.reject(new TypeError('async boom')); }, 0);")
+        .output()
+        .expect("spawn esrun");
+    assert!(!out.status.success(), "should exit non-zero");
+    let stderr = stderr(&out);
+    assert!(
+        stderr.contains("error: 1 unhandled promise rejection(s)"),
+        "{stderr}"
+    );
+    assert!(stderr.contains("TypeError: async boom"), "{stderr}");
+    assert!(stderr.contains("at file://"), "{stderr}");
+}

docs/API.md

@@ -331,3 +331,7 @@ await server.stop();
 
 <!-- Reference links -->
 [D27]: ./DECISIONS.md
+
+## Error Diagnostics
+
+When exceptions are thrown by ES-Runtime during module evaluation or unhandled promise rejections, the original `Error` subclasses and their stack traces are preserved. The CLI automatically extracts these diagnostics and prints them elegantly with ANSI colors. The stack trace will highlight exact lines and columns of errors: `TypeError: message \n    at fn (file:line:col)`.

docs/DECISIONS.md

@@ -35,12 +35,7 @@ Status: **Locked** · **Proposed** · **Open** (needs maintainer sign-off) · **
 >   deferred to Phase 2, when the op system gives a second consumer to design it
 >   against; extracting it then must not change the public types. *Reason:*
 >   avoid speculative abstraction before there is a second implementor/consumer.
-> - **Uncaught-exception JS class not preserved.** `engine::Error::Execution`
->   carries only the stringified exception message, so it maps to a generic JS
->   `Error` rather than the original subclass (`TypeError`, etc.). *Reason:*
->   reconstructing the class requires reading the thrown object's constructor and
->   re-mapping; deferred to Phase 2 when ops re-enter JS. *Impact:* lossy error
->   class on the JS round-trip.
+> - ~~**Uncaught-exception JS class not preserved.**~~ *Resolved (Phase 8):* Exception classes (including `DOMException` names) and JS stack traces (`at fn (file:line:col)`) are now preserved and surfaced through `engine::Error` into the CLI.
 > - **Primitive-only value marshaling.** `engine::Value` marshals JS primitives
 >   plus, since Phase 6, `Value::Bytes` (`Uint8Array`/typed-array views, **copied**
 >   to/from `Vec<u8>`). Every other value still collapses to

docs/SPEC.md

@@ -147,11 +147,6 @@ Productionizing the standalone runtime *and* stabilizing the embeddable API. ESM
 - **`URLPattern`** → later (not covered by the `url` crate). Minor WHATWG URL conformance gaps tracked vs WPT (D18).
 - **ES module loading** — ☑ **implemented**: static `import`/`export`, **dynamic `import()`** (resolving with the module namespace after the imported module fully evaluates; shares instances with static imports via the realm module map), `import.meta.url`, native top-level await, **local `file:` modules** and **`node_modules` resolution for ES module packages** via the capability-checked `ModuleLoader` provider (DECISIONS D21, D22, D23). `exports` resolution covers string targets, the `import`/`default` conditions, and **subpath patterns** (`"./*"`). **Deferred:** import attributes / JSON modules, remote (`http:`) modules, and the remaining `node_modules` edges (full condition precedence beyond `import`/`default`, `imports`/`#internal`, self-reference). **Rejected by design:** CommonJS packages and `node:` builtins (§125).
 - **`reportError` ErrorEvent dispatch** and **sub-millisecond `performance.now`** are minimal in Phase 4; full behavior lands with the event loop / clock refinements.
-- **Error model & diagnostics standardization** → planned, sequenced *after* the in-flight module/perf work. Today an uncaught error surfaces as a stringified message with no stack and a redundant CLI restatement (e.g. `Uncaught: TypeError: …` then `esrun: <file>: module evaluation failed`), provider errors are doubly nested (`module loading failed: provider error: …`), and there is no color. Scope:
-  - **Stack traces + source position** — capture and surface the JS stack (`at fn (file:line:col)`) for uncaught exceptions, module top-level throws, and unhandled rejections, via V8's `Message`/`StackTrace` API. Resolves part of the D3a leak ("exception class/stack not preserved"; DECISIONS D3a/D12).
-  - **Stable error codes** — a taxonomy on the layer error enums (module not-found / resolution / unsupported-CommonJS / capability-denied / eval-throw …) for tooling and tests, surfaced in messages.
-  - **CLI output format** — one coherent error block instead of the current two lines; de-nest provider errors to a single clear line + code; unify the `Uncaught:` / `Uncaught (in promise):` / `esrun: <label>:` prefixes.
-  - **Optional color** — red header, dimmed paths/stack, gated on TTY detection and the `NO_COLOR` convention; never colored when piped/redirected.
   - Spans `engine` (stack/position + error-class preservation), `runtime` (typed codes), and `default-providers`/`runtime-cli` (formatting + color).
 
 ---

site/app/docs/errors/page.jsx

@@ -0,0 +1,34 @@
+import DocsShell from "../../../components/DocsShell.jsx";
+import CodeBlock from "../../../components/CodeBlock.jsx";
+
+export default function ErrorDiagnostics() {
+  return (
+    <DocsShell active="/docs/errors">
+      <p className="text-sm font-medium text-brand-600">Runtime</p>
+      <h1 className="mt-2 text-4xl font-bold tracking-tight text-zinc-900">
+        Error Diagnostics
+      </h1>
+      <p className="mt-4 text-lg leading-relaxed text-zinc-600">
+        ES-Runtime guarantees native exception class preservation and accurate stack
+        trace reporting. Instead of swallowing errors as generic string blocks, the
+        runtime retains exact subclasses (like <code className="rounded bg-zinc-100 px-1 py-0.5 text-[13px]">TypeError</code>, <code className="rounded bg-zinc-100 px-1 py-0.5 text-[13px]">DOMException</code>) and precise source mapping points.
+      </p>
+
+      <h2 className="mt-12 text-xl font-semibold text-zinc-900">Stack Traces</h2>
+      <p className="mt-3 leading-relaxed text-zinc-600">
+        When an unhandled exception or unhandled promise rejection bubbles to the 
+        top level, <code className="rounded bg-zinc-100 px-1 py-0.5 text-[13px]">esrun</code> 
+        elegantly formats the error trace in your CLI:
+      </p>
+
+      <div className="mt-4">
+        <CodeBlock code={`error: uncaught exception in my-script.mjs\nTypeError: network connection refused\n    at fetchData (file:///path/to/script.mjs:10:5)\n    at file:///path/to/script.mjs:2:1`} title="Terminal" lang="text" />
+      </div>
+
+      <div className="mt-6 rounded-xl border border-brand-200 bg-brand-50 p-5 leading-relaxed text-brand-900">
+        <strong>Good to know:</strong> The CLI handles color formatting seamlessly and adjusts gracefully 
+        if piped into other tools or if <code className="rounded bg-white/70 px-1.5 py-0.5 text-[13px]">NO_COLOR</code> is set.
+      </div>
+    </DocsShell>
+  );
+}

site/components/DocsShell.jsx

@@ -35,6 +35,7 @@ const NAV = [
     items: [
       { href: "/docs/modules", label: "Module system" },
       { href: "/docs/security", label: "Security model" },
+      { href: "/docs/errors", label: "Error diagnostics" },
     ],
   },
 ];