feat: added error handling severity levels & named errors (#11)

* feat: added error handling severity levels

* feat: structured error handling with specific error types and severity levels

* docs: reorient roadmap

ROADMAP.md

···
 |         |   ✓   | [Refactor](#evaluator--binder-hardening)                                         |
 | v0.5.1  |   ✓   | [Error Handling & Diagnostics](#error-handling--diagnostics) (partial)           |
 | v0.6.0  |       | [Error Handling & Diagnostics](#error-handling--diagnostics)                     |
-| v0.7.0  |       | [Bundle Size Optimization](#bundle-size-optimization)                            |
-| v0.8.0  |       | [CSP Compatibility](#csp-compatibility)                                          |
-| v0.9.0  |       | [DOM Morphing & Streaming](#dom-morphing--streaming)                             |
-| v0.10.0 |       | [Scope Inheritance & State Management](#scope-inheritance--state-management)     |
-| v0.11.0 |       | [Background Requests & Reactive Polling](#background-requests--reactive-polling) |
-| v0.12.0 |       | [Attribute Prefix Support](#attribute-prefix-support)                            |
-| v0.13.0 |       | [Persistence & Offline](#persistence--offline) (advanced features)               |
-| v0.14.0 |       | [Inspector & Developer Tools](#inspector--developer-tools)                       |
+| v0.6.0  |       | [Bundle Size Optimization](#bundle-size-optimization)                            |
+| v0.6.0  |       | [IIFE Build Support](#iife-build-support)                                        |
+| v0.7.0  |       | [Testing & Benchmarking](#testing--benchmarking)                                 |
+| v0.7.0  |       | [CSP Compatibility](#csp-compatibility)                                          |
+| v0.8.0  |       | [DOM Morphing & Streaming](#dom-morphing--streaming)                             |
+| v0.9.0  |       | [Scope Inheritance & State Management](#scope-inheritance--state-management)     |
+| v0.10.0 |       | [Background Requests & Reactive Polling](#background-requests--reactive-polling) |
+| v0.11.0 |       | [Attribute Prefix Support](#attribute-prefix-support)                            |
+| v0.12.0 |       | [Persistence & Offline](#persistence--offline) (advanced features)               |
+| v0.13.0 |       | [Inspector & Developer Tools](#inspector--developer-tools)                       |
 | v1.0.0  |       | [Stable Release](#stable-release)                                                |
 
 ## Completed
···
     - ✓ v0.5.1: Centralized error boundary system for directives and effects
     - ✓ v0.5.1: Sandbox error wrapping with contextual hints (directive name, expression, element)
     - ✓ v0.5.1: `$volt.report(error, context)` API for plugin and app-level reporting
-    - v0.6.0: Enhanced console error messages with directive context
-    - v0.6.0: Differentiated error levels: warn, error, fatal
-    - v0.6.0: Documentation: "Understanding VoltX Errors" guide
+    - ✓ v0.6.0: Enhanced console error messages with directive context
+    - ✓ v0.6.0: Differentiated error levels: warn, error, fatal
+    - ✓ v0.6.0: Documentation: "Understanding VoltX Errors" guide
     - v0.6.0: Add error handling examples to demo
-    - v0.14.0: Visual in-DOM error overlays for development mode
-    - v0.14.0: Runtime health monitor tracking failures
-    - v0.14.0: Configurable global error policy
+    - v0.13.0: Visual in-DOM error overlays for development mode
+    - v0.13.0: Runtime health monitor tracking failures
+    - v0.13.0: Configurable global error policy
 
 ### Persistence & Offline
 
···
 **Deliverables:**
     - ✓ Persistent signals (localStorage, sessionStorage, indexedDb)
     - ✓ Storage plugin (`data-volt-persist`)
-    - v0.13.0: Storage modifiers on signals (`.local`, `.session`, `.ifmissing`)
-    - v0.13.0: Sync strategy API (merge, overwrite, patch) for conflict resolution
-    - v0.13.0: Cache invalidation strategies
-    - v0.13.0: Offline queue for deferred stream events and HTTP requests
-    - v0.13.0: Service Worker integration for offline-first apps
-    - v0.13.0: Background sync for deferred requests
-    - v0.13.0: Cross-tab synchronization via `BroadcastChannel`
+    - v0.12.0: Storage modifiers on signals (`.local`, `.session`, `.ifmissing`)
+    - v0.12.0: Sync strategy API (merge, overwrite, patch) for conflict resolution
+    - v0.12.0: Cache invalidation strategies
+    - v0.12.0: Offline queue for deferred stream events and HTTP requests
+    - v0.12.0: Service Worker integration for offline-first apps
+    - v0.12.0: Background sync for deferred requests
+    - v0.12.0: Cross-tab synchronization via `BroadcastChannel`
 
 ### Bundle Size Optimization
 
 **Goal:** Reduce bundle size to <15KB gzipped while maintaining full feature set.
 **Outcome:** Lightweight runtime footprint with comprehensive declarative capabilities.
 **Deliverables:**
-    - v0.7.0: Audit and tree-shake unused code paths
-    - v0.7.0: Optimize evaluator and binder implementations
-    - v0.7.0: Minimize plugin footprint, ensure lazy loading
-    - v0.7.0: Refactor expression compiler for smaller output
-    - v0.7.0: Compress constant strings and reduce runtime helpers
-    - v0.7.0: Optimize signal subscription management
-    - v0.7.0: Production mode stripping (remove dev-only error messages)
-    - v0.7.0: Aggressive minification pipeline tuning
-    - v0.7.0: Target: <15KB gzipped sustained
+    - v0.6.0: Audit and tree-shake unused code paths
+    - v0.6.0: Optimize evaluator and binder implementations
+    - v0.6.0: Minimize plugin footprint, ensure lazy loading
+    - v0.6.0: Refactor expression compiler for smaller output
+    - v0.6.0: Compress constant strings and reduce runtime helpers
+    - v0.6.0: Optimize signal subscription management
+    - v0.6.0: Production mode stripping (remove dev-only error messages)
+    - v0.6.0: Aggressive minification pipeline tuning
+    - v0.6.0: Target: <15KB gzipped sustained
+
+### IIFE Build Support
+
+**Goal:** Provide an IIFE build target for VoltX.js to support direct `<script>` tag usage without module systems.
+**Outcome:** VoltX.js can be used via CDN without build tools or module bundlers.
+**Deliverables:**
+    - v0.6.0: IIFE build output (voltx.iife.js) alongside ESM build
+    - v0.6.0: Global `Volt` namespace for browser environments
+    - v0.6.0: CDN-friendly distribution (unpkg, jsdelivr)
+    - v0.6.0: Update build pipeline to generate IIFE bundle
+    - v0.6.0: Document usage: `<script src="voltx.iife.min.js"></script>`
+    - v0.6.0: Ensure plugins work with IIFE build
+    - v0.6.0: Add IIFE examples to documentation
+
+### Testing & Benchmarking
+
+**Goal:** Establish comprehensive testing infrastructure and performance benchmarking.
+**Outcome:** VoltX.js has rigorous end-to-end testing and quantifiable performance metrics against competing frameworks.
+**Deliverables:**
+    - v0.7.0: Playwright-based integration test suite for real browser testing
+    - v0.7.0: End-to-end tests for all core directives and plugins
+    - v0.7.0: Cross-browser compatibility tests (Chrome, Firefox, Safari)
+    - v0.7.0: Memory usage and leak detection benchmarks
+    - v0.7.0: Bundle size tracking and regression detection
+    - v0.7.0: Reactivity performance benchmarks (signal updates, computed chains, effect execution)
+    - v0.7.0: DOM update performance benchmarks
+    - v0.7.0: CI integration for automated benchmark runs and regression alerts
 
 ### CSP Compatibility
 
 **Goal:** Make VoltX.js Content Security Policy compliant without 'unsafe-eval'.
 **Outcome:** VoltX.js can run in strict CSP environments (no Function constructor).
 **Deliverables:**
-    - v0.8.0: Research and design CSP-safe evaluator architecture
-    - v0.8.0: Evaluate trade-offs: AST interpreter vs limited expression subset
-    - v0.8.0: Implement CSP-safe expression evaluator (AST-based or restricted syntax)
-    - v0.8.0: Maintain expression feature parity where possible
-    - v0.8.0: Fallback mode detection for environments requiring CSP
-    - v0.8.0: Full test coverage for CSP mode
-    - v0.8.0: Documentation on CSP limitations and alternatives
-    - v0.8.0: Bundle split: standard build vs CSP build
+    - v0.7.0: Research and design CSP-safe evaluator architecture
+    - v0.7.0: Evaluate trade-offs: AST interpreter vs limited expression subset
+    - v0.7.0: Implement CSP-safe expression evaluator (AST-based or restricted syntax)
+    - v0.7.0: Maintain expression feature parity where possible
+    - v0.7.0: Fallback mode detection for environments requiring CSP
+    - v0.7.0: Full test coverage for CSP mode
+    - v0.7.0: Documentation on CSP limitations and alternatives
+    - v0.7.0: Bundle split: standard build vs CSP build
 
 ### DOM Morphing & Streaming
 
 **Goal:** Add intelligent DOM morphing and Server-Sent Events for real-time updates.
 **Outcome:** Built-in morphing and SSE streaming for seamless server-driven UI updates.
 **Deliverables:**
-    - v0.9.0: Integrate Idiomorph or implement lightweight morphing algorithm
-    - v0.9.0: `data-volt-morph` attribute for morphing-based swaps
-    - v0.9.0: Preserve focus, scroll, and input state during morphs
-    - v0.9.0: Server-Sent Events (SSE) integration
-    - v0.9.0: `data-volt-stream` attribute for SSE endpoints
-    - v0.9.0: Automatic reconnection with exponential backoff
-    - v0.9.0: Signal patching from backend SSE events
-    - v0.9.0: JSON Patch support for partial updates
-    - v0.9.0: `data-volt-ignore-morph` for selective exclusion
-    - v0.9.0: WebSocket as alternative to SSE
-    - v0.9.0: Unified streaming API across SSE/WebSocket
+    - v0.8.0: Integrate Idiomorph or implement lightweight morphing algorithm
+    - v0.8.0: `data-volt-morph` attribute for morphing-based swaps
+    - v0.8.0: Preserve focus, scroll, and input state during morphs
+    - v0.8.0: Server-Sent Events (SSE) integration
+    - v0.8.0: `data-volt-stream` attribute for SSE endpoints
+    - v0.8.0: Automatic reconnection with exponential backoff
+    - v0.8.0: Signal patching from backend SSE events
+    - v0.8.0: JSON Patch support for partial updates
+    - v0.8.0: `data-volt-ignore-morph` for selective exclusion
+    - v0.8.0: WebSocket as alternative to SSE
+    - v0.8.0: Unified streaming API across SSE/WebSocket
 
 ### Scope Inheritance & State Management
 
 **Goal:** Improve data scoping with optional inheritance for ergonomic nested components.
 **Outcome:** Flexible scoping patterns for complex component hierarchies.
 **Deliverables:**
-    - v0.10.0: Optional scope inheritance via `data-volt-scope="inherit"`
-    - v0.10.0: Child scopes inherit parent signals with override capability
-    - v0.10.0: $parent accessor for explicit parent scope access
-    - v0.10.0: Scoped context providers for dependency injection
-    - v0.10.0: Enhanced $store with namespacing and modules
-    - v0.10.0: Cross-scope signal sharing patterns
+    - v0.9.0: Optional scope inheritance via `data-volt-scope="inherit"`
+    - v0.9.0: Child scopes inherit parent signals with override capability
+    - v0.9.0: $parent accessor for explicit parent scope access
+    - v0.9.0: Scoped context providers for dependency injection
+    - v0.9.0: Enhanced $store with namespacing and modules
+    - v0.9.0: Cross-scope signal sharing patterns
 
 ### Background Requests & Reactive Polling
 
 **Goal:** Enable declarative background data fetching and periodic updates.
 **Outcome:** VoltX.js elements can fetch or refresh data automatically based on time, visibility, or reactive conditions.
 **Deliverables:**
-    - v0.11.0: `data-volt-visible` for fetching when element enters viewport (IntersectionObserver)
-    - v0.11.0: `data-volt-poll` attribute for periodic background requests
-    - v0.11.0: Configurable intervals, delays, and signal-based triggers
-    - v0.11.0: Automatic cancellation when elements unmount
-    - v0.11.0: Conditional polling tied to reactive signals
-    - v0.11.0: Background task scheduler with priority management
+    - v0.10.0: `data-volt-visible` for fetching when element enters viewport (IntersectionObserver)
+    - v0.10.0: `data-volt-poll` attribute for periodic background requests
+    - v0.10.0: Configurable intervals, delays, and signal-based triggers
+    - v0.10.0: Automatic cancellation when elements unmount
+    - v0.10.0: Conditional polling tied to reactive signals
+    - v0.10.0: Background task scheduler with priority management
 
 ### Attribute Prefix Support
 
 **Goal:** Support multiple attribute prefix options for developer preference.
 **Outcome:** VoltX.js supports `voltx-`, `vx-`, and `data-volt-` prefixes.
 **Deliverables:**
-    - v0.12.0: Add support for `voltx-*` and `vx-*` attribute prefixes
-    - v0.12.0: Recommend `vx-*` as primary in documentation
-    - v0.12.0: Maintain backward compatibility with `data-volt-*`
-    - v0.12.0: Update demo to use recommended prefix
+    - v0.11.0: Add support for `voltx-*` and `vx-*` attribute prefixes
+    - v0.11.0: Recommend `vx-*` as primary in documentation
+    - v0.11.0: Maintain backward compatibility with `data-volt-*`
+    - v0.11.0: Update demo to use recommended prefix
 
 ### Inspector & Developer Tools
 
 **Goal:** Improve developer experience and runtime introspection.
 **Outcome:** First-class developer ergonomics; VoltX.js is enjoyable to debug and extend.
 **Deliverables:**
-    - v0.14.0: Visual in-DOM error overlays for development mode
-    - v0.14.0: Runtime health monitor tracking failures
-    - v0.14.0: Configurable global error policy (silent, overlay, throw)
-    - v0.14.0: Developer overlay for inspecting signals, subscriptions, and effects
-    - v0.14.0: Time-travel debugging for signal history
-    - v0.14.0: Signal dependency graph visualization
-    - v0.14.0: Performance profiling tools
-    - v0.14.0: Browser console integration (`window.$volt.inspect()`)
-    - v0.14.0: Dev logging toggle (`Volt.debug = true`)
-    - v0.14.0: Request/response debugging (HTTP actions, SSE streams)
-    - v0.14.0: Browser DevTools extension with full integration
+    - v0.13.0: Visual in-DOM error overlays for development mode
+    - v0.13.0: Runtime health monitor tracking failures
+    - v0.13.0: Configurable global error policy (silent, overlay, throw)
+    - v0.13.0: Developer overlay for inspecting signals, subscriptions, and effects
+    - v0.13.0: Time-travel debugging for signal history
+    - v0.13.0: Signal dependency graph visualization
+    - v0.13.0: Performance profiling tools
+    - v0.13.0: Browser console integration (`window.$volt.inspect()`)
+    - v0.13.0: Dev logging toggle (`Volt.debug = true`)
+    - v0.13.0: Request/response debugging (HTTP actions, SSE streams)
+    - v0.13.0: Browser DevTools extension with full integration
 
 ### Stable Release
 
···
     - Community contribution guide & governance doc
 
 ## Parking Lot
-
-### IIFE Build Support
-
-Provide an IIFE (Immediately Invoked Function Expression) build target for VoltX.js to support direct `<script>` tag usage without module systems.
-
-**Deliverables:**
-
-- IIFE build output (voltx.iife.js) alongside ESM build
-- Global `Volt` namespace for browser environments
-- CDN-friendly distribution (unpkg, jsdelivr)
-- Update build pipeline to generate IIFE bundle
-- Document usage: `<script src="voltx.iife.min.js"></script>`
-- Ensure plugins work with IIFE build
-- Add IIFE examples to documentation
 
 ### Evaluator & Binder Hardening
 

docs/cli.md

···
 The CLI is available as `create-voltx` on npm:
 
 ```bash
-# Use with pnpm (recommended)
+# Use with pnpm
 pnpm create voltx my-app
 
 # Use with npm
···
 - Event handlers
 - Counter example
 
-Best for: Learning VoltX.js basics, simple interactive pages.
-
 ### With Router
 
 A multi-page application featuring:
···
 - Multiple routes (home, about, contact, 404)
 - Navigation with `data-volt-navigate`
 - Route matching with `data-volt-url`
-
-Best for: Multi-page applications, documentation sites, dashboards.
 
 ### With Plugins
 
···
 - VoltX.js CSS utilities
 - Semantic HTML
 - No JavaScript required
-
-Best for: Static sites, progressively enhanced pages, CSS-only projects.
 
 ## Configuration
 
···
 import { defineConfig } from 'vite';
 
 export default defineConfig({
-  // Custom Vite configuration
   server: {
     port: 3000,
   },
···
 ```
 
 See the [Vite documentation](https://vitejs.dev/config/) for all available options.
-
-## Troubleshooting
-
-### Dev Server Won't Start
-
-Ensure you're in a VoltX.js project directory with an `index.html` file:
-
-```bash
-ls index.html
-```
-
-If `index.html` is missing, you may not be in a VoltX.js project.
-
-### Download Fails
-
-Check your internet connection and try again. The CLI downloads assets from:
-
-```text
-https://cdn.jsdelivr.net/npm/voltx.js@{version}/dist/
-```
-
-If jsDelivr is blocked, manually download from the [npm package](https://www.npmjs.com/package/voltx.js).
-
-### Build Fails
-
-Ensure all dependencies are installed:
-
-```bash
-pnpm install
-```
-
-Check for syntax errors in your HTML, CSS, or JavaScript files.
-
-## Next Steps
-
-- Read the [Installation Guide](./installation) for framework setup
-- Explore [Usage Patterns](./usage/state) for state management

docs/usage/error-handling.md

···
+# Error Handling
+
+⚠️ Named error classes and enhanced error handling are unreleased as of writing. This documentation describes features planned for v0.6.0.
+
+VoltX categorizes all errors by source and severity, wrapping them in named error classes with rich debugging context. This system enables precise error identification, flexible handling strategies, and seamless integration with logging services.
+
+## Error Types
+
+Each error source maps to a specific error class:
+
+| Identifier       | Source      | Cause                                                                                                                               |
+| ---------------- | ----------- | ----------------------------------------------------------------------------------------------------------------------------------- |
+| `EvaluatorError` | `evaluator` | Expression evaluation fails in directives (`data-volt-text`, `data-volt-if`, etc.) or computed values                               |
+| `BindingError`   | `binding`   | Directive setup or execution fails (`data-volt-model` with missing signal, invalid `data-volt-for` syntax, missing parent elements) |
+| `EffectError`    | `effect`    | Effect callbacks, computed signals, or async effects fail during execution or cleanup                                               |
+| `HttpError`      | `http`      | HTTP directives encounter network errors, invalid swap strategies, missing target elements, or parsing failures                     |
+| `PluginError`    | `plugin`    | Custom plugin handlers fail during initialization or execution                                                                      |
+| `LifecycleError` | `lifecycle` | Lifecycle hooks (`beforeMount`, `afterMount`, `onMount`, etc.) fail during execution                                                |
+| `ChargeError`    | `charge`    | `charge()` encounters invalid `data-volt-state` JSON, malformed configuration, or initialization errors                             |
+| `UserError`      | `user`      | User code explicitly reports errors via `report()`                                                                                  |
+
+All error classes extend `VoltError` and set their `name` property accordingly (e.g., `error.name === "HttpError"`).
+
+## Severity Levels
+
+Errors have three severity levels that control console output and execution flow:
+
+**warn** — Non-critical issues logged via `console.warn`. Execution continues. Use for deprecations, missing optional features, or recoverable configuration issues.
+
+**error** (default) — Recoverable errors logged via `console.error`. Execution continues but the specific operation fails. Most runtime errors use this level.
+
+**fatal** — Unrecoverable errors logged via `console.error` and then thrown, halting execution. Reserve for critical initialization failures or corrupted state.
+
+## Error Context
+
+Every VoltX error includes contextual metadata for debugging:
+
+```ts
+interface VoltError {
+    name: string; // Error class name
+    source: ErrorSource; // Error category
+    level: ErrorLevel; // Severity level
+    directive?: string; // Failed directive (e.g., "data-volt-text")
+    expression?: string; // Failed expression
+    element?: HTMLElement; // DOM element where error occurred
+    cause: Error; // Original wrapped error
+    timestamp: number; // Unix timestamp (ms)
+    context: ErrorContext; // Full context including custom properties
+
+    // HTTP errors only
+    httpMethod?: string;
+    httpUrl?: string;
+    httpStatus?: number;
+
+    // Plugin errors only
+    pluginName?: string;
+
+    // Lifecycle errors only
+    hookName?: string;
+}
+```
+
+## Handling Errors
+
+### Registration
+
+Register global error handlers with `onError()`. Handlers execute in registration order and receive all errors:
+
+```ts
+import { onError } from "voltx.js";
+
+const cleanup = onError((error) => {
+    analytics.track("error", error.toJSON());
+
+    if (error instanceof HttpError) {
+        showToast(`Request failed: ${error.cause.message}`);
+    }
+});
+
+// Cleanup when done
+cleanup();
+```
+
+### Propagation Control
+
+Call `error.stopPropagation()` to prevent subsequent handlers from running:
+
+```ts
+onError((error) => {
+    if (error.source === "http") {
+        handleHttpError(error);
+        error.stopPropagation();
+    }
+});
+
+// This handler won't run for HTTP errors
+onError((error) => logToConsole(error));
+```
+
+### Cleanup
+
+Remove handlers individually via their cleanup function or clear all handlers with `clearErrorHandlers()`.
+
+## Console Fallback
+
+When no handlers are registered, errors log to console based on severity (`console.warn` for warn, `console.error` for error/fatal) with formatted context:
+
+```text
+[ERROR] [evaluator] Cannot read property 'foo' of undefined | Directive: data-volt-text | Expression: user.foo | Element: <div#app>
+Caused by: TypeError: Cannot read property 'foo' of undefined
+Element: <div id="app">...</div>
+```
+
+Fatal errors throw after logging.
+
+## Reporting Errors
+
+Report errors from user code using `report(error, context)`:
+
+```ts
+import { report } from "voltx.js";
+
+try {
+    processForm(formElement);
+} catch (error) {
+    report(error as Error, {
+        source: "user",
+        level: "warn",
+        element: formElement as HTMLElement,
+        formId: formElement.id,
+    });
+}
+```
+
+The `context` object accepts any custom properties beyond the standard fields.
+
+## Serialization
+
+All VoltX errors implement `toJSON()` for serialization to logging services or error tracking systems.
+
+### Schema
+
+```ts
+interface SerializedVoltError {
+    /** Error class name (e.g., "EvaluatorError", "HttpError") */
+    name: string;
+    /** Full formatted error message with context */
+    message: string;
+    /** Error source category */
+    source:
+        | "evaluator"
+        | "binding"
+        | "effect"
+        | "http"
+        | "plugin"
+        | "lifecycle"
+        | "charge"
+        | "user";
+
+    /** Severity level */
+    level: "warn" | "error" | "fatal";
+    /** Directive name (e.g., "data-volt-text") */
+    directive?: string;
+    /** Expression that failed */
+    expression?: string;
+    /** Unix timestamp in milliseconds */
+    timestamp: number;
+    /** Full error context including custom properties */
+    context: {
+        source: string;
+        level?: string;
+        element?: HTMLElement;
+        directive?: string;
+        expression?: string;
+        pluginName?: string;
+        httpMethod?: string;
+        httpUrl?: string;
+        httpStatus?: number;
+        hookName?: string;
+        [key: string]: unknown;
+    };
+    /** Original error that was wrapped */
+    cause: { name: string; message: string; stack?: string; };
+    /** VoltX error stack trace */
+    stack?: string;
+}
+```
+
+### Usage
+
+```ts
+import { onError } from "voltx.js";
+
+onError((error) => {
+    fetch("/api/errors", {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify(error.toJSON()),
+    });
+});
+```

lib/src/core/charge.ts

···
       if (typeof stateData !== "object" || isNil(stateData) || Array.isArray(stateData)) {
         report(new Error(`data-volt-state must be a JSON object, got ${typeof stateData}`), {
           source: "charge",
+          level: "fatal",
           element: el as HTMLElement,
           directive: "data-volt-state",
           expression: stateAttr,
···
     } catch (error) {
       report(error as Error, {
         source: "charge",
+        level: "fatal",
         element: el as HTMLElement,
         directive: "data-volt-state",
         expression: stateAttr,
···
       if (typeof data !== "object" || isNil(data) || Array.isArray(data)) {
         report(new Error(`data-volt-store script must contain a JSON object, got: ${typeof data}`), {
           source: "charge",
+          level: "fatal",
           element: script as HTMLElement,
           directive: "data-volt-store",
         });
···
 
       registerStore(data);
     } catch (error) {
-      report(error as Error, { source: "charge", element: script as HTMLElement, directive: "data-volt-store" });
+      report(error as Error, {
+        source: "charge",
+        level: "fatal",
+        element: script as HTMLElement,
+        directive: "data-volt-store",
+      });
     }
   }
 }

lib/src/core/error.ts

···
  *
  * @module core/error
  */
-import type { ErrorContext, ErrorHandler, ErrorSource } from "$types/volt";
+import type { ErrorContext, ErrorHandler, ErrorLevel, ErrorSource } from "$types/volt";
 
 /**
- * Enhanced error class with VoltX context
+ * Base error class with VoltX context
  *
- * Wraps original errors with rich debugging information including
- * source, element, directive, and expression details.
+ * Wraps original errors with rich debugging information including ource, element, directive, and expression details.
  */
 export class VoltError extends Error {
   /** Error source category */
   public readonly source: ErrorSource;
+  /** Error severity level */
+  public readonly level: ErrorLevel;
   /** DOM element where error occurred */
   public readonly element?: HTMLElement;
   /** Directive name */
···
     this.name = "VoltError";
     this.cause = cause;
     this.source = context.source;
+    this.level = context.level ?? "error";
     this.element = context.element;
     this.directive = context.directive;
     this.expression = context.expression;
···
     // V8-specific feature
     // See: https://github.com/microsoft/TypeScript/issues/3926
     if ((Error as any).captureStackTrace) {
-      (Error as any).captureStackTrace(this, VoltError);
+      (Error as any).captureStackTrace(this, this.constructor);
     }
   }
 
···
 
   private static buildMessage(cause: Error, context: ErrorContext): string {
     const parts: string[] = [];
+    const level = context.level ?? "error";
 
-    parts.push(`[${context.source}] ${cause.message}`);
+    parts.push(`[${level.toUpperCase()}] [${context.source}] ${cause.message}`);
 
     if (context.directive) {
       parts.push(`Directive: ${context.directive}`);
···
       name: this.name,
       message: this.message,
       source: this.source,
+      level: this.level,
       directive: this.directive,
       expression: this.expression,
       timestamp: this.timestamp,
···
 }
 
 /**
+ * Error during expression evaluation
+ *
+ * Thrown when evaluating expressions in directives like data-volt-text, data-volt-if, or any other binding that uses the expression evaluator.
+ */
+export class EvaluatorError extends VoltError {
+  constructor(cause: Error, context: ErrorContext) {
+    super(cause, { ...context, source: "evaluator" });
+    this.name = "EvaluatorError";
+  }
+}
+
+/**
+ * Error during directive binding
+ *
+ * Thrown when setting up or executing DOM bindings like data-volt-text, data-volt-class, data-volt-model, etc.
+ */
+export class BindingError extends VoltError {
+  constructor(cause: Error, context: ErrorContext) {
+    super(cause, { ...context, source: "binding" });
+    this.name = "BindingError";
+  }
+}
+
+/**
+ * Error during effect execution
+ *
+ * Thrown when effects, computed signals, or async effects fail during execution or cleanup.
+ */
+export class EffectError extends VoltError {
+  constructor(cause: Error, context: ErrorContext) {
+    super(cause, { ...context, source: "effect" });
+    this.name = "EffectError";
+  }
+}
+
+/**
+ * Error during HTTP operations
+ *
+ * Thrown when HTTP directives (data-volt-get, data-volt-post, etc.) encounter network errors, parsing failures, or swap strategy issues.
+ */
+export class HttpError extends VoltError {
+  constructor(cause: Error, context: ErrorContext) {
+    super(cause, { ...context, source: "http" });
+    this.name = "HttpError";
+  }
+}
+
+/**
+ * Error in plugin execution
+ *
+ * Thrown when custom plugins registered via registerPlugin fail during initialization or execution.
+ */
+export class PluginError extends VoltError {
+  constructor(cause: Error, context: ErrorContext) {
+    super(cause, { ...context, source: "plugin" });
+    this.name = "PluginError";
+  }
+}
+
+/**
+ * Error in lifecycle hooks
+ *
+ * Thrown when lifecycle hooks (beforeMount, afterMount, onMount, etc.) fail during execution.
+ */
+export class LifecycleError extends VoltError {
+  constructor(cause: Error, context: ErrorContext) {
+    super(cause, { ...context, source: "lifecycle" });
+    this.name = "LifecycleError";
+  }
+}
+
+/**
+ * Error during charge/initialization
+ *
+ * Thrown when charge() encounters errors during auto-discovery and mounting of [data-volt] elements, or when parsing data-volt-state.
+ */
+export class ChargeError extends VoltError {
+  constructor(cause: Error, context: ErrorContext) {
+    super(cause, { ...context, source: "charge" });
+    this.name = "ChargeError";
+  }
+}
+
+/**
+ * User-triggered error
+ *
+ * Errors explicitly reported by user code via the report() function
+ * with source: "user".
+ */
+export class UserError extends VoltError {
+  constructor(cause: Error, context: ErrorContext) {
+    super(cause, { ...context, source: "user" });
+    this.name = "UserError";
+  }
+}
+
+/**
  * Global error handler registry
  */
 let errorHandlers: ErrorHandler[] = [];
···
  * Register an error handler
  *
  * Multiple handlers can be registered and will be called in registration order.
- * Handlers can call `error.stopPropagation()` to prevent subsequent handlers
- * from being called.
+ * Handlers can call `error.stopPropagation()` to prevent subsequent handlers from being called.
  *
  * @param handler - Error handler function
  * @returns Cleanup function to unregister the handler
···
  * If no error handlers are registered, errors are logged to console as fallback.
  * Once handlers are registered, console logging is disabled.
  *
+ * Error levels determine console output and behavior:
+ * - warn: Non-critical issues logged with console.warn
+ * - error: Recoverable errors logged with console.error (default)
+ * - fatal: Unrecoverable errors logged with console.error and thrown to halt execution
+ *
  * @param error - Error to report (can be Error, unknown, or string)
  * @param context - Error context with source and additional details
  *
  * @example
  * ```ts
- * // Internal usage (by VoltX)
- * try {
- *   evaluate(expression, scope);
- * } catch (err) {
- *   report(err, {
- *     source: ErrorSource.Evaluator,
- *     element: ctx.element,
- *     directive: 'data-volt-text',
- *     expression: expression
- *   });
- * }
+ * // Warning for non-critical issues
+ * report(err, {
+ *   source: "binding",
+ *   level: "warn",
+ *   directive: "data-volt-deprecated"
+ * });
  *
- * // External usage (by plugins/apps)
- * try {
- *   myCustomLogic();
- * } catch (err) {
- *   report(err, {
- *     source: ErrorSource.User,
- *     customContext: 'My feature failed'
- *   });
- * }
+ * // Error for recoverable issues (default)
+ * report(err, {
+ *   source: "evaluator",
+ *   level: "error",
+ *   directive: "data-volt-text",
+ *   expression: expression
+ * });
+ *
+ * // Fatal error that halts execution
+ * report(err, {
+ *   source: "charge",
+ *   level: "fatal",
+ *   directive: "data-volt-state"
+ * });
  * ```
  */
 export function report(error: unknown, context: ErrorContext): void {
   const errorObj = error instanceof Error ? error : new Error(String(error));
-  const voltError = new VoltError(errorObj, context);
+
+  const voltError = createErrorBySource(errorObj, context);
 
   if (errorHandlers.length === 0) {
-    console.error(voltError.message);
-    console.error("Caused by:", voltError.cause);
+    const logFn = voltError.level === "warn" ? console.warn : console.error;
+
+    logFn(voltError.message);
+    logFn("Caused by:", voltError.cause);
     if (voltError.element) {
-      console.error("Element:", voltError.element);
+      logFn("Element:", voltError.element);
+    }
+
+    if (voltError.level === "fatal") {
+      throw voltError;
     }
     return;
   }
···
       }
     } catch (handlerError) {
       console.error("Error in error handler:", handlerError);
+    }
+  }
+
+  if (voltError.level === "fatal") {
+    throw voltError;
+  }
+}
+
+/**
+ * Create the appropriate error type based on the source
+ */
+function createErrorBySource(cause: Error, context: ErrorContext): VoltError {
+  switch (context.source) {
+    case "evaluator": {
+      return new EvaluatorError(cause, context);
+    }
+    case "binding": {
+      return new BindingError(cause, context);
+    }
+    case "effect": {
+      return new EffectError(cause, context);
+    }
+    case "http": {
+      return new HttpError(cause, context);
+    }
+    case "plugin": {
+      return new PluginError(cause, context);
+    }
+    case "lifecycle": {
+      return new LifecycleError(cause, context);
+    }
+    case "charge": {
+      return new ChargeError(cause, context);
+    }
+    case "user": {
+      return new UserError(cause, context);
+    }
+    default: {
+      return new VoltError(cause, context);
     }
   }
 }

lib/src/core/http.ts

···
     default: {
       report(new Error(`Unknown swap strategy: ${strategy as string}`), {
         source: "http",
+        level: "warn",
         element: target as HTMLElement,
       });
     }
···
   if (!target) {
     report(new Error(`Target element not found: ${targetConf}`), {
       source: "http",
+      level: "warn",
       element: defaultEl as HTMLElement,
       directive: "data-volt-target",
     });

lib/src/index.ts

···
 export { asyncEffect } from "$core/async-effect";
 export { mount } from "$core/binder";
 export { charge } from "$core/charge";
-export { clearErrorHandlers, onError, report } from "$core/error";
-export type { VoltError } from "$core/error";
+export {
+  BindingError,
+  ChargeError,
+  clearErrorHandlers,
+  EffectError,
+  EvaluatorError,
+  HttpError,
+  LifecycleError,
+  onError,
+  PluginError,
+  report,
+  UserError,
+  VoltError,
+} from "$core/error";
 export { parseHttpConfig, request, serializeForm, serializeFormToJSON, swap } from "$core/http";
 export {
   clearAllGlobalHooks,
···
   ComputedSignal,
   ErrorContext,
   ErrorHandler,
+  ErrorLevel,
   ErrorSource,
   GlobalHookName,
   GlobalStore,

lib/src/types/volt.d.ts

···
 export type ErrorSource = "evaluator" | "binding" | "effect" | "http" | "plugin" | "lifecycle" | "charge" | "user";
 
 /**
+ * Error severity level
+ *
+ * - `warn`: Non-critical issues that don't prevent operation (e.g., deprecated usage, missing optional features)
+ * - `error`: Recoverable errors that prevent specific operations (e.g., failed evaluations, missing elements)
+ * - `fatal`: Unrecoverable errors that should halt execution (e.g., critical initialization failures)
+ */
+export type ErrorLevel = "warn" | "error" | "fatal";
+
+/**
  * Context information for error reporting
  */
 export type ErrorContext = {
   /** Error source category */
   source: ErrorSource;
+  /** Error severity level (defaults to "error") */
+  level?: ErrorLevel;
   /** DOM element where error occurred */
   element?: HTMLElement;
   /** Directive name (e.g., "data-volt-text", "data-volt-on-click") */

lib/test/core/error.test.ts

···
-import { clearErrorHandlers, getErrorHandlerCount, onError, report, VoltError } from "$core/error";
-import type { ErrorContext, ErrorSource } from "$types/volt";
+import {
+  BindingError,
+  ChargeError,
+  clearErrorHandlers,
+  EffectError,
+  EvaluatorError,
+  getErrorHandlerCount,
+  HttpError,
+  LifecycleError,
+  onError,
+  PluginError,
+  report,
+  UserError,
+  VoltError,
+} from "$core/error";
+import type { ErrorContext, ErrorLevel, ErrorSource } from "$types/volt";
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 
 describe("VoltError", () => {
···
     for (const [i, source] of sources.entries()) {
       const voltError: VoltError = handler.mock.calls[i][0];
       expect(voltError.source).toBe(source);
+    }
+  });
+
+  it("creates correct error types based on source", () => {
+    const handler = vi.fn();
+    onError(handler);
+
+    const testCases: Array<{ source: ErrorSource; errorType: typeof VoltError; name: string }> = [
+      { source: "evaluator", errorType: EvaluatorError, name: "EvaluatorError" },
+      { source: "binding", errorType: BindingError, name: "BindingError" },
+      { source: "effect", errorType: EffectError, name: "EffectError" },
+      { source: "http", errorType: HttpError, name: "HttpError" },
+      { source: "plugin", errorType: PluginError, name: "PluginError" },
+      { source: "lifecycle", errorType: LifecycleError, name: "LifecycleError" },
+      { source: "charge", errorType: ChargeError, name: "ChargeError" },
+      { source: "user", errorType: UserError, name: "UserError" },
+    ];
+
+    for (const { source } of testCases) {
+      report(new Error(`Test ${source}`), { source });
+    }
+
+    expect(handler).toHaveBeenCalledTimes(testCases.length);
+
+    for (const [i, { errorType, name }] of testCases.entries()) {
+      const voltError = handler.mock.calls[i][0];
+      expect(voltError).toBeInstanceOf(errorType);
+      expect(voltError).toBeInstanceOf(VoltError);
+      expect(voltError.name).toBe(name);
+    }
+  });
+});
+
+describe("Error Levels", () => {
+  beforeEach(() => {
+    clearErrorHandlers();
+    vi.spyOn(console, "error").mockImplementation(() => {});
+    vi.spyOn(console, "warn").mockImplementation(() => {});
+  });
+
+  afterEach(() => {
+    clearErrorHandlers();
+    vi.restoreAllMocks();
+  });
+
+  it("defaults to error level when not specified", () => {
+    const cause = new Error("Test error");
+    const context: ErrorContext = { source: "binding" };
+
+    const voltError = new VoltError(cause, context);
+
+    expect(voltError.level).toBe("error");
+  });
+
+  it("includes error level in VoltError", () => {
+    const levels: Array<ErrorLevel> = ["warn", "error", "fatal"];
+
+    for (const level of levels) {
+      const cause = new Error(`Test ${level}`);
+      const context: ErrorContext = { source: "binding", level };
+
+      const voltError = new VoltError(cause, context);
+
+      expect(voltError.level).toBe(level);
+    }
+  });
+
+  it("includes error level in message", () => {
+    const levels: Array<ErrorLevel> = ["warn", "error", "fatal"];
+
+    for (const level of levels) {
+      const cause = new Error(`Test ${level}`);
+      const context: ErrorContext = { source: "binding", level };
+
+      const voltError = new VoltError(cause, context);
+
+      expect(voltError.message).toContain(`[${level.toUpperCase()}]`);
+    }
+  });
+
+  it("includes error level in JSON serialization", () => {
+    const cause = new Error("Test error");
+    const context: ErrorContext = { source: "binding", level: "warn" };
+
+    const voltError = new VoltError(cause, context);
+    const json = voltError.toJSON();
+
+    expect(json.level).toBe("warn");
+  });
+
+  it("uses console.warn for warn level without handlers", () => {
+    const error = new Error("Warning message");
+    const context: ErrorContext = { source: "binding", level: "warn" };
+
+    report(error, context);
+
+    expect(console.warn).toHaveBeenCalledTimes(2);
+    expect(console.warn).toHaveBeenCalledWith(expect.stringContaining("[WARN]"));
+    expect(console.warn).toHaveBeenCalledWith("Caused by:", error);
+    expect(console.error).not.toHaveBeenCalled();
+  });
+
+  it("uses console.error for error level without handlers", () => {
+    const error = new Error("Error message");
+    const context: ErrorContext = { source: "binding", level: "error" };
+
+    report(error, context);
+
+    expect(console.error).toHaveBeenCalledTimes(2);
+    expect(console.error).toHaveBeenCalledWith(expect.stringContaining("[ERROR]"));
+    expect(console.error).toHaveBeenCalledWith("Caused by:", error);
+    expect(console.warn).not.toHaveBeenCalled();
+  });
+
+  it("uses console.error for fatal level without handlers", () => {
+    const error = new Error("Fatal error");
+    const context: ErrorContext = { source: "charge", level: "fatal" };
+
+    expect(() => report(error, context)).toThrow(VoltError);
+
+    expect(console.error).toHaveBeenCalledTimes(2);
+    expect(console.error).toHaveBeenCalledWith(expect.stringContaining("[FATAL]"));
+    expect(console.error).toHaveBeenCalledWith("Caused by:", error);
+  });
+
+  it("throws error for fatal level after handlers", () => {
+    const handler = vi.fn();
+    onError(handler);
+
+    const error = new Error("Fatal error");
+    const context: ErrorContext = { source: "charge", level: "fatal" };
+
+    expect(() => report(error, context)).toThrow(VoltError);
+
+    expect(handler).toHaveBeenCalledTimes(1);
+    const voltError = handler.mock.calls[0][0];
+    expect(voltError.level).toBe("fatal");
+  });
+
+  it("does not throw for warn level", () => {
+    const error = new Error("Warning");
+    const context: ErrorContext = { source: "http", level: "warn" };
+
+    expect(() => report(error, context)).not.toThrow();
+  });
+
+  it("does not throw for error level", () => {
+    const error = new Error("Error");
+    const context: ErrorContext = { source: "binding", level: "error" };
+
+    expect(() => report(error, context)).not.toThrow();
+  });
+
+  it("passes error level to handlers", () => {
+    const handler = vi.fn();
+    onError(handler);
+
+    const levels: Array<ErrorLevel> = ["warn", "error", "fatal"];
+
+    for (const level of levels) {
+      try {
+        report(new Error(`Test ${level}`), { source: "binding", level });
+      } catch { /* No-op */ }
+    }
+
+    expect(handler).toHaveBeenCalledTimes(3);
+
+    for (const [i, level] of levels.entries()) {
+      const voltError: VoltError = handler.mock.calls[i][0];
+      expect(voltError.level).toBe(level);
     }
   });
 });