pulse-js-framework 1.5.2 → 1.5.3

package/cli/release.js

@@ -460,17 +460,24 @@ Types:
   major     Bump major version (1.0.0 -> 2.0.0)
 
 Options:
-  --dry-run       Show what would be done without making changes
-  --no-push       Create commit and tag but don't push
-  --title <text>  Release title (e.g., "Performance Improvements")
-  --skip-prompt   Use empty changelog (for automated releases)
-  --from-commits  Auto-extract changelog from git commits since last tag
+  --dry-run        Show what would be done without making changes
+  --no-push        Create commit and tag but don't push
+  --title <text>   Release title (e.g., "Performance Improvements")
+  --skip-prompt    Use empty changelog (for automated releases)
+  --from-commits   Auto-extract changelog from git commits since last tag
+  --yes, -y        Auto-confirm all prompts
+  --changes <json> Pass changelog as JSON (e.g., '{"added":["Feature 1"],"fixed":["Bug 1"]}')
+  --added <items>  Comma-separated list of added features
+  --changed <items> Comma-separated list of changes
+  --fixed <items>  Comma-separated list of fixes
 
 Examples:
   pulse release patch
-  pulse release minor --title "New Features"
+  pulse release minor --title "New Features" -y
   pulse release major --dry-run
-  pulse release patch --from-commits --title "Bug Fixes"
+  pulse release patch --from-commits --title "Bug Fixes" -y
+  pulse release patch --title "Security" --fixed "XSS vulnerability,SQL injection" -y
+  pulse release patch --title "New API" --added "Feature A,Feature B" --fixed "Bug X" -y
   `);
 }
 
@@ -490,6 +497,7 @@ export async function runRelease(args) {
   const noPush = args.includes('--no-push');
   const skipPrompt = args.includes('--skip-prompt');
   const fromCommits = args.includes('--from-commits');
+  const autoConfirm = args.includes('--yes') || args.includes('-y');
 
   let title = '';
   const titleIndex = args.indexOf('--title');
@@ -497,6 +505,33 @@ export async function runRelease(args) {
     title = args[titleIndex + 1];
   }
 
+  // Parse --changes JSON option
+  let changesFromArgs = null;
+  const changesIndex = args.indexOf('--changes');
+  if (changesIndex !== -1 && args[changesIndex + 1]) {
+    try {
+      changesFromArgs = JSON.parse(args[changesIndex + 1]);
+    } catch (e) {
+      log.error('Invalid JSON for --changes option');
+      process.exit(1);
+    }
+  }
+
+  // Parse individual change type options
+  const addedIndex = args.indexOf('--added');
+  const changedIndex = args.indexOf('--changed');
+  const fixedIndex = args.indexOf('--fixed');
+  const removedIndex = args.indexOf('--removed');
+
+  if (!changesFromArgs && (addedIndex !== -1 || changedIndex !== -1 || fixedIndex !== -1 || removedIndex !== -1)) {
+    changesFromArgs = {
+      added: addedIndex !== -1 && args[addedIndex + 1] ? args[addedIndex + 1].split(',').map(s => s.trim()) : [],
+      changed: changedIndex !== -1 && args[changedIndex + 1] ? args[changedIndex + 1].split(',').map(s => s.trim()) : [],
+      fixed: fixedIndex !== -1 && args[fixedIndex + 1] ? args[fixedIndex + 1].split(',').map(s => s.trim()) : [],
+      removed: removedIndex !== -1 && args[removedIndex + 1] ? args[removedIndex + 1].split(',').map(s => s.trim()) : []
+    };
+  }
+
   // Read current version
   const pkg = JSON.parse(readFileSync(join(root, 'package.json'), 'utf-8'));
   const currentVersion = pkg.version;
@@ -517,10 +552,14 @@ export async function runRelease(args) {
     if (status.trim()) {
       log.warn('You have uncommitted changes:');
       log.info(status);
-      const proceed = await prompt('Continue anyway? (y/N) ');
-      if (proceed.toLowerCase() !== 'y') {
-        log.info('Aborted.');
-        process.exit(0);
+      if (!autoConfirm) {
+        const proceed = await prompt('Continue anyway? (y/N) ');
+        if (proceed.toLowerCase() !== 'y') {
+          log.info('Aborted.');
+          process.exit(0);
+        }
+      } else {
+        log.info('Auto-confirming with --yes flag');
       }
     }
   } catch (error) {
@@ -531,7 +570,24 @@ export async function runRelease(args) {
   // Collect changelog entries
   let changes = { added: [], changed: [], fixed: [], removed: [] };
 
-  if (fromCommits) {
+  // Use changes from command-line arguments if provided
+  if (changesFromArgs) {
+    changes = {
+      added: changesFromArgs.added || [],
+      changed: changesFromArgs.changed || [],
+      fixed: changesFromArgs.fixed || [],
+      removed: changesFromArgs.removed || []
+    };
+    const totalChanges = Object.values(changes).flat().length;
+    if (totalChanges > 0) {
+      log.info('');
+      log.info('Changelog entries from arguments:');
+      if (changes.added.length) log.info(`  Added: ${changes.added.length} items`);
+      if (changes.changed.length) log.info(`  Changed: ${changes.changed.length} items`);
+      if (changes.fixed.length) log.info(`  Fixed: ${changes.fixed.length} items`);
+      if (changes.removed.length) log.info(`  Removed: ${changes.removed.length} items`);
+    }
+  } else if (fromCommits) {
     // Auto-extract from git commits since last tag
     const lastTag = getLastTag();
     const commits = getCommitsSinceLastTag();
@@ -554,10 +610,10 @@ export async function runRelease(args) {
       }
     }
 
-    if (!title) {
+    if (!title && !autoConfirm) {
       title = await prompt('Release title (e.g., "Performance Improvements"): ');
     }
-  } else if (!skipPrompt) {
+  } else if (!skipPrompt && !autoConfirm) {
     if (!title) {
       title = await prompt('Release title (e.g., "Performance Improvements"): ');
     }
@@ -574,7 +630,7 @@ export async function runRelease(args) {
 
   const hasChanges = Object.values(changes).some(arr => arr.length > 0);
 
-  if (!hasChanges && !skipPrompt) {
+  if (!hasChanges && !skipPrompt && !autoConfirm) {
     const proceed = await prompt('No changelog entries. Continue? (y/N) ');
     if (proceed.toLowerCase() !== 'y') {
       log.info('Aborted.');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pulse-js-framework",
-  "version": "1.5.2",
+  "version": "1.5.3",
   "description": "A declarative DOM framework with CSS selector-based structure and reactive pulsations",
   "type": "module",
   "main": "index.js",

package/runtime/dom.js

@@ -28,6 +28,38 @@ const log = loggers.dom;
 // Cache hit returns a shallow copy to prevent mutation of cached config
 const selectorCache = new LRUCache(500);
 
+/**
+ * Safely insert a node before a reference node
+ * Returns false if the parent is detached (no parentNode)
+ * @private
+ * @param {Node} newNode - Node to insert
+ * @param {Node} refNode - Reference node (insert before this)
+ * @returns {boolean} True if insertion succeeded
+ */
+function safeInsertBefore(newNode, refNode) {
+  if (!refNode.parentNode) {
+    log.warn('Cannot insert node: reference node has no parent (may be detached)');
+    return false;
+  }
+  refNode.parentNode.insertBefore(newNode, refNode);
+  return true;
+}
+
+/**
+ * Resolve a selector string or element to a DOM element
+ * @private
+ * @param {string|HTMLElement} target - CSS selector or DOM element
+ * @param {string} context - Context name for error messages
+ * @returns {{element: HTMLElement|null, selector: string}} Resolved element and original selector
+ */
+function resolveSelector(target, context = 'target') {
+  if (typeof target === 'string') {
+    const element = document.querySelector(target);
+    return { element, selector: target };
+  }
+  return { element: target, selector: '(element)' };
+}
+
 // Lifecycle tracking
 let mountCallbacks = [];
 let unmountCallbacks = [];
@@ -58,8 +90,13 @@ export function onUnmount(fn) {
 
 /**
  * Parse a CSS selector-like string into element configuration
- * Supports: tag, #id, .class, [attr=value]
- * Results are cached for performance.
+ * Results are cached for performance using LRU cache.
+ *
+ * Supported syntax:
+ * - Tag: `div`, `span`, `custom-element`
+ * - ID: `#app`, `#my-id`, `#_private`
+ * - Classes: `.class`, `.my-class`, `.-modifier`
+ * - Attributes: `[attr]`, `[attr=value]`, `[attr="quoted value"]`, `[attr='single quoted']`
  *
  * Examples:
  *   "div" -> { tag: "div" }
@@ -67,6 +104,10 @@ export function onUnmount(fn) {
  *   ".container" -> { tag: "div", classes: ["container"] }
  *   "button.primary.large" -> { tag: "button", classes: ["primary", "large"] }
  *   "input[type=text][placeholder=Name]" -> { tag: "input", attrs: { type: "text", placeholder: "Name" } }
+ *   "div[data-id=\"complex-123\"]" -> { tag: "div", attrs: { "data-id": "complex-123" } }
+ *
+ * @param {string} selector - CSS selector-like string
+ * @returns {{tag: string, id: string|null, classes: string[], attrs: Object}} Parsed configuration
  */
 export function parseSelector(selector) {
   if (!selector || selector === '') {
@@ -101,32 +142,43 @@ export function parseSelector(selector) {
     remaining = remaining.slice(tagMatch[0].length);
   }
 
-  // Match ID
-  const idMatch = remaining.match(/#([a-zA-Z][a-zA-Z0-9-_]*)/);
+  // Match ID (supports starting with letter, underscore, or hyphen followed by valid chars)
+  const idMatch = remaining.match(/#([a-zA-Z_-][a-zA-Z0-9-_]*)/);
   if (idMatch) {
     config.id = idMatch[1];
     remaining = remaining.replace(idMatch[0], '');
   }
 
-  // Match classes
-  const classMatches = remaining.matchAll(/\.([a-zA-Z][a-zA-Z0-9-_]*)/g);
+  // Match classes (supports starting with letter, underscore, or hyphen)
+  const classMatches = remaining.matchAll(/\.([a-zA-Z_-][a-zA-Z0-9-_]*)/g);
   for (const match of classMatches) {
     config.classes.push(match[1]);
   }
 
-  // Match attributes
-  const attrMatches = remaining.matchAll(/\[([a-zA-Z][a-zA-Z0-9-_]*)(?:=([^\]]+))?\]/g);
+  // Match attributes - improved regex handles quoted values with special characters
+  // Matches: [attr], [attr=value], [attr="quoted value"], [attr='quoted value']
+  const attrRegex = /\[([a-zA-Z_][a-zA-Z0-9-_]*)(?:=(?:"([^"]*)"|'([^']*)'|([^\]]*)))?\]/g;
+  const attrMatches = remaining.matchAll(attrRegex);
   for (const match of attrMatches) {
     const key = match[1];
-    let value = match[2] || '';
-    // Remove quotes if present
-    if ((value.startsWith('"') && value.endsWith('"')) ||
-        (value.startsWith("'") && value.endsWith("'"))) {
-      value = value.slice(1, -1);
-    }
+    // Value can be in match[2] (double-quoted), match[3] (single-quoted), or match[4] (unquoted)
+    const value = match[2] ?? match[3] ?? match[4] ?? '';
     config.attrs[key] = value;
   }
 
+  // Validate: check for unparsed content (malformed selector parts)
+  // Remove all parsed parts to see if anything remains
+  let unparsed = remaining
+    .replace(/#[a-zA-Z_-][a-zA-Z0-9-_]*/g, '')  // Remove IDs
+    .replace(/\.[a-zA-Z_-][a-zA-Z0-9-_]*/g, '') // Remove classes
+    .replace(/\[([a-zA-Z_][a-zA-Z0-9-_]*)(?:=(?:"[^"]*"|'[^']*'|[^\]]*))?\]/g, '') // Remove attrs
+    .trim();
+
+  if (unparsed) {
+    log.warn(`Selector "${selector}" contains unrecognized parts: "${unparsed}". ` +
+      'Supported syntax: tag#id.class[attr=value]');
+  }
+
   // Cache the result (LRU cache handles eviction automatically)
   selectorCache.set(selector, config);
 
@@ -217,7 +269,11 @@ function appendChild(parent, child) {
             }
           }
         }
-        placeholder.parentNode.insertBefore(fragment, placeholder.nextSibling);
+        if (placeholder.parentNode) {
+          placeholder.parentNode.insertBefore(fragment, placeholder.nextSibling);
+        } else {
+          log.warn('Cannot insert reactive children: placeholder has no parent node');
+        }
       }
     });
   }
@@ -552,12 +608,8 @@ export function model(element, pulseValue) {
  * @throws {Error} If target element is not found
  */
 export function mount(target, element) {
-  const originalTarget = target;
-  if (typeof target === 'string') {
-    target = document.querySelector(target);
-  }
-  if (!target) {
-    const selector = typeof originalTarget === 'string' ? originalTarget : '(element)';
+  const { element: resolved, selector } = resolveSelector(target, 'mount');
+  if (!resolved) {
     throw new Error(
       `[Pulse] Mount target not found: "${selector}". ` +
       `Ensure the element exists in the DOM before mounting. ` +
@@ -565,7 +617,7 @@ export function mount(target, element) {
       `or place your script at the end of <body>.`
     );
   }
-  target.appendChild(element);
+  resolved.appendChild(element);
   return () => {
     element.remove();
   };
@@ -649,12 +701,10 @@ export function show(condition, element) {
  * Portal - render children into a different DOM location
  */
 export function portal(children, target) {
-  const resolvedTarget = typeof target === 'string'
-    ? document.querySelector(target)
-    : target;
+  const { element: resolvedTarget, selector } = resolveSelector(target, 'portal');
 
   if (!resolvedTarget) {
-    log.warn('Portal target not found:', target);
+    log.warn(`Portal target not found: "${selector}"`);
     return document.createComment('portal-target-not-found');
   }
 

package/runtime/logger.js

@@ -39,6 +39,13 @@ let globalLevel = LogLevel.INFO;
 /** @type {LogFormatter|null} */
 let globalFormatter = null;
 
+/**
+ * Namespace formatting helpers
+ * @private
+ */
+const NAMESPACE_SEPARATOR = ':';
+const formatNamespace = (ns) => `[${ns}]`;
+
 /**
  * @callback LogFormatter
  * @param {'error'|'warn'|'info'|'debug'} level - The log level
@@ -97,13 +104,14 @@ export function setFormatter(formatter) {
 function formatArgs(namespace, args) {
   if (!namespace) return args;
 
+  const prefix = formatNamespace(namespace);
   // If first arg is a string, prepend namespace
   if (typeof args[0] === 'string') {
-    return [`[${namespace}] ${args[0]}`, ...args.slice(1)];
+    return [`${prefix} ${args[0]}`, ...args.slice(1)];
   }
 
   // Otherwise, add namespace as first arg
-  return [`[${namespace}]`, ...args];
+  return [prefix, ...args];
 }
 
 /**
@@ -217,7 +225,7 @@ export function createLogger(namespace = null, options = {}) {
      */
     group(label) {
       if (shouldLog(LogLevel.DEBUG)) {
-        console.group(namespace ? `[${namespace}] ${label}` : label);
+        console.group(namespace ? `${formatNamespace(namespace)} ${label}` : label);
       }
     },
 
@@ -264,7 +272,7 @@ export function createLogger(namespace = null, options = {}) {
      */
     child(childNamespace) {
       const combined = namespace
-        ? `${namespace}:${childNamespace}`
+        ? `${namespace}${NAMESPACE_SEPARATOR}${childNamespace}`
         : childNamespace;
       return createLogger(combined, options);
     }

package/runtime/lru-cache.js

@@ -15,13 +15,21 @@ export class LRUCache {
   /**
    * Create an LRU cache
    * @param {number} capacity - Maximum number of items to store
+   * @param {Object} [options] - Configuration options
+   * @param {boolean} [options.trackMetrics=false] - Enable hit/miss/eviction tracking
    */
-  constructor(capacity) {
+  constructor(capacity, options = {}) {
     if (capacity <= 0) {
       throw new Error('LRU cache capacity must be greater than 0');
     }
     this._capacity = capacity;
     this._cache = new Map();
+
+    // Metrics tracking
+    this._trackMetrics = options.trackMetrics || false;
+    this._hits = 0;
+    this._misses = 0;
+    this._evictions = 0;
   }
 
   /**
@@ -32,9 +40,12 @@ export class LRUCache {
    */
   get(key) {
     if (!this._cache.has(key)) {
+      if (this._trackMetrics) this._misses++;
       return undefined;
     }
 
+    if (this._trackMetrics) this._hits++;
+
     // Move to end (most recently used) by re-inserting
     const value = this._cache.get(key);
     this._cache.delete(key);
@@ -57,6 +68,7 @@ export class LRUCache {
       // Remove oldest (first item in Map)
       const oldest = this._cache.keys().next().value;
       this._cache.delete(oldest);
+      if (this._trackMetrics) this._evictions++;
     }
 
     this._cache.set(key, value);
@@ -136,6 +148,46 @@ export class LRUCache {
   forEach(callback) {
     this._cache.forEach((value, key) => callback(value, key, this));
   }
+
+  /**
+   * Get cache performance metrics
+   * Only available if trackMetrics option was enabled
+   * @returns {{hits: number, misses: number, evictions: number, hitRate: number, size: number, capacity: number}}
+   * @example
+   * const cache = new LRUCache(100, { trackMetrics: true });
+   * // ... use cache ...
+   * const stats = cache.getMetrics();
+   * console.log(`Hit rate: ${(stats.hitRate * 100).toFixed(1)}%`);
+   */
+  getMetrics() {
+    const total = this._hits + this._misses;
+    return {
+      hits: this._hits,
+      misses: this._misses,
+      evictions: this._evictions,
+      hitRate: total > 0 ? this._hits / total : 0,
+      size: this._cache.size,
+      capacity: this._capacity
+    };
+  }
+
+  /**
+   * Reset all metrics counters to zero
+   * Useful for measuring metrics over specific time periods
+   */
+  resetMetrics() {
+    this._hits = 0;
+    this._misses = 0;
+    this._evictions = 0;
+  }
+
+  /**
+   * Enable or disable metrics tracking
+   * @param {boolean} enabled - Whether to track metrics
+   */
+  setMetricsTracking(enabled) {
+    this._trackMetrics = enabled;
+  }
 }
 
 export default LRUCache;

package/runtime/pulse.js

@@ -69,6 +69,14 @@ const log = loggers.pulse;
  * @property {Map<string, Set<EffectFn>>} effectRegistry - Module ID to effects mapping for HMR
  */
 
+/**
+ * Maximum number of effect re-run iterations before aborting.
+ * Prevents infinite loops when effects trigger each other cyclically.
+ * Set to 100 to allow deep chain reactions while catching most real loops.
+ * @type {number}
+ */
+const MAX_EFFECT_ITERATIONS = 100;
+
 /**
  * Global reactive context - holds all tracking state.
  * Exported for testing purposes (use resetContext() to reset).
@@ -515,10 +523,9 @@ function flushEffects() {
 
   context.isRunningEffects = true;
   let iterations = 0;
-  const maxIterations = 100; // Prevent infinite loops
 
   try {
-    while (context.pendingEffects.size > 0 && iterations < maxIterations) {
+    while (context.pendingEffects.size > 0 && iterations < MAX_EFFECT_ITERATIONS) {
       iterations++;
       const effects = [...context.pendingEffects];
       context.pendingEffects.clear();
@@ -528,8 +535,8 @@ function flushEffects() {
       }
     }
 
-    if (iterations >= maxIterations) {
-      log.warn('Maximum effect iterations reached. Possible infinite loop.');
+    if (iterations >= MAX_EFFECT_ITERATIONS) {
+      log.warn(`Maximum effect iterations (${MAX_EFFECT_ITERATIONS}) reached. Possible infinite loop.`);
       context.pendingEffects.clear();
     }
   } finally {
@@ -586,6 +593,8 @@ export function computed(fn, options = {}) {
 
     // Track which pulses this depends on
     let trackedDeps = new Set();
+    // Track subscription cleanup functions to prevent memory leaks
+    let subscriptionCleanups = [];
 
     p.get = function() {
       if (dirty) {
@@ -603,18 +612,21 @@ export function computed(fn, options = {}) {
           dirty = false;
 
           // Cleanup old subscriptions
-          for (const dep of trackedDeps) {
-            dep._unsubscribe(markDirty);
+          for (const unsubscribe of subscriptionCleanups) {
+            unsubscribe();
           }
+          subscriptionCleanups = [];
+          trackedDeps.clear();
 
           // Set up new subscriptions
           trackedDeps = tempEffect.dependencies;
           for (const dep of trackedDeps) {
-            dep.subscribe(() => {
+            const unsubscribe = dep.subscribe(() => {
               dirty = true;
               // Notify our own subscribers
               p._triggerNotify();
             });
+            subscriptionCleanups.push(unsubscribe);
           }
 
           p._init(cachedValue);
@@ -632,7 +644,14 @@ export function computed(fn, options = {}) {
       return cachedValue;
     };
 
-    const markDirty = { run: () => { dirty = true; }, dependencies: new Set(), cleanups: [] };
+    // Cleanup function for lazy computed
+    cleanup = () => {
+      for (const unsubscribe of subscriptionCleanups) {
+        unsubscribe();
+      }
+      subscriptionCleanups = [];
+      trackedDeps.clear();
+    };
   } else {
     // Eager computed - updates immediately when dependencies change
     cleanup = effect(() => {

package/runtime/router.js

@@ -225,8 +225,14 @@ function createMiddlewareRunner(middlewares) {
       if (aborted || redirectPath) return;
       if (index >= middlewares.length) return;
 
+      const middlewareIndex = index;
       const middleware = middlewares[index++];
-      await middleware(ctx, next);
+      try {
+        await middleware(ctx, next);
+      } catch (error) {
+        log.error(`Middleware error at index ${middlewareIndex}:`, error);
+        throw error; // Re-throw to halt navigation
+      }
     }
 
     await next();
@@ -417,23 +423,58 @@ function matchRoute(pattern, path) {
   return params;
 }
 
+// Query string validation limits
+const QUERY_LIMITS = {
+  maxTotalLength: 2048,     // 2KB max for entire query string
+  maxValueLength: 1024,     // 1KB max per individual value
+  maxParams: 50             // Maximum number of query parameters
+};
+
 /**
- * Parse query string into object
+ * Parse query string into object with validation
+ * @param {string} search - Query string (with or without leading ?)
+ * @returns {Object} Parsed query parameters
  */
 function parseQuery(search) {
-  const params = new URLSearchParams(search);
+  if (!search) return {};
+
+  // Remove leading ? if present
+  const queryStr = search.startsWith('?') ? search.slice(1) : search;
+
+  // Validate total length
+  if (queryStr.length > QUERY_LIMITS.maxTotalLength) {
+    log.warn(`Query string exceeds maximum length (${QUERY_LIMITS.maxTotalLength} chars). Truncating.`);
+  }
+
+  const params = new URLSearchParams(queryStr.slice(0, QUERY_LIMITS.maxTotalLength));
   const query = {};
+  let paramCount = 0;
+
   for (const [key, value] of params) {
+    // Check parameter count limit
+    if (paramCount >= QUERY_LIMITS.maxParams) {
+      log.warn(`Query string exceeds maximum parameters (${QUERY_LIMITS.maxParams}). Ignoring excess.`);
+      break;
+    }
+
+    // Validate and potentially truncate value length
+    let safeValue = value;
+    if (value.length > QUERY_LIMITS.maxValueLength) {
+      log.warn(`Query parameter "${key}" exceeds maximum length. Truncating.`);
+      safeValue = value.slice(0, QUERY_LIMITS.maxValueLength);
+    }
+
     if (key in query) {
       // Multiple values for same key
       if (Array.isArray(query[key])) {
-        query[key].push(value);
+        query[key].push(safeValue);
       } else {
-        query[key] = [query[key], value];
+        query[key] = [query[key], safeValue];
       }
     } else {
-      query[key] = value;
+      query[key] = safeValue;
     }
+    paramCount++;
   }
   return query;
 }
@@ -460,6 +501,10 @@ export function createRouter(options = {}) {
   const currentQuery = pulse({});
   const currentMeta = pulse({});
   const isLoading = pulse(false);
+  const routeError = pulse(null);
+
+  // Route error handler (configurable)
+  let onRouteError = options.onRouteError || null;
 
   // Scroll positions for history
   const scrollPositions = new Map();
@@ -793,25 +838,65 @@ export function createRouter(options = {}) {
           router
         };
 
-        // Call handler and render result
-        const result = typeof route.handler === 'function'
-          ? route.handler(ctx)
-          : route.handler;
+        // Helper to handle errors
+        const handleError = (error) => {
+          routeError.set(error);
+          log.error('Route component error:', error);
+
+          if (onRouteError) {
+            try {
+              const errorView = onRouteError(error, ctx);
+              if (errorView instanceof Node) {
+                container.replaceChildren(errorView);
+                currentView = errorView;
+                return true;
+              }
+            } catch (handlerError) {
+              log.error('Route error handler threw:', handlerError);
+            }
+          }
+
+          const errorEl = el('div.route-error', [
+            el('h2', 'Route Error'),
+            el('p', error.message || 'Failed to load route component')
+          ]);
+          container.replaceChildren(errorEl);
+          currentView = errorEl;
+          return true;
+        };
+
+        // Call handler and render result (with error handling)
+        let result;
+        try {
+          result = typeof route.handler === 'function'
+            ? route.handler(ctx)
+            : route.handler;
+        } catch (error) {
+          handleError(error);
+          return;
+        }
 
         if (result instanceof Node) {
           container.appendChild(result);
           currentView = result;
+          routeError.set(null);
         } else if (result && typeof result.then === 'function') {
           // Async component
           isLoading.set(true);
-          result.then(component => {
-            isLoading.set(false);
-            const view = typeof component === 'function' ? component(ctx) : component;
-            if (view instanceof Node) {
-              container.appendChild(view);
-              currentView = view;
-            }
-          });
+          routeError.set(null);
+          result
+            .then(component => {
+              isLoading.set(false);
+              const view = typeof component === 'function' ? component(ctx) : component;
+              if (view instanceof Node) {
+                container.appendChild(view);
+                currentView = view;
+              }
+            })
+            .catch(error => {
+              isLoading.set(false);
+              handleError(error);
+            });
         }
       }
     });
@@ -868,6 +953,17 @@ export function createRouter(options = {}) {
   /**
    * Check if a route matches the given path
    */
+  /**
+   * Check if a path matches the current route
+   * @param {string} path - Path to check
+   * @param {boolean} [exact=false] - If true, requires exact match; if false, matches prefixes
+   * @returns {boolean} True if path is active
+   * @example
+   * // Current path: /users/123
+   * router.isActive('/users');      // true (prefix match)
+   * router.isActive('/users', true); // false (not exact)
+   * router.isActive('/users/123', true); // true (exact match)
+   */
   function isActive(path, exact = false) {
     const current = currentPath.get();
     if (exact) {
@@ -877,7 +973,12 @@ export function createRouter(options = {}) {
   }
 
   /**
-   * Get all matched routes (for nested routes)
+   * Get all routes that match a given path (useful for nested routes)
+   * @param {string} path - Path to match against routes
+   * @returns {Array<{route: Object, params: Object}>} Array of matched routes with extracted params
+   * @example
+   * const matches = router.getMatchedRoutes('/admin/users/123');
+   * // Returns: [{route: adminRoute, params: {}}, {route: userRoute, params: {id: '123'}}]
    */
   function getMatchedRoutes(path) {
     const matches = [];
@@ -891,53 +992,107 @@ export function createRouter(options = {}) {
   }
 
   /**
-   * Go back in history
+   * Navigate back in browser history
+   * Equivalent to browser back button
+   * @returns {void}
+   * @example
+   * router.back(); // Go to previous page
    */
   function back() {
     window.history.back();
   }
 
   /**
-   * Go forward in history
+   * Navigate forward in browser history
+   * Equivalent to browser forward button
+   * @returns {void}
+   * @example
+   * router.forward(); // Go to next page (if available)
    */
   function forward() {
     window.history.forward();
   }
 
   /**
-   * Go to specific history entry
+   * Navigate to a specific position in browser history
+   * @param {number} delta - Number of entries to move (negative = back, positive = forward)
+   * @returns {void}
+   * @example
+   * router.go(-2); // Go back 2 pages
+   * router.go(1);  // Go forward 1 page
    */
   function go(delta) {
     window.history.go(delta);
   }
 
+  /**
+   * Set route error handler
+   * @param {function} handler - Error handler (error, ctx) => Node
+   * @returns {function} Previous handler
+   */
+  function setErrorHandler(handler) {
+    const prev = onRouteError;
+    onRouteError = handler;
+    return prev;
+  }
+
+  /**
+   * Router instance with reactive state and navigation methods.
+   *
+   * Reactive properties (use .get() to read value, auto-updates in effects):
+   * - path: Current URL path as string
+   * - route: Current matched route object or null
+   * - params: Route params object, e.g., {id: '123'}
+   * - query: Query params object, e.g., {page: '1'}
+   * - meta: Route meta data object
+   * - loading: Boolean indicating async route loading
+   * - error: Current route error or null
+   *
+   * @example
+   * // Read reactive state
+   * router.path.get();   // '/users/123'
+   * router.params.get(); // {id: '123'}
+   *
+   * // Subscribe to changes
+   * effect(() => {
+   *   console.log('Path changed:', router.path.get());
+   * });
+   *
+   * // Navigate
+   * router.navigate('/users/456');
+   * router.back();
+   */
   const router = {
-    // Reactive state (read-only)
+    // Reactive state (read-only) - use .get() to read, subscribe with effects
     path: currentPath,
     route: currentRoute,
     params: currentParams,
     query: currentQuery,
     meta: currentMeta,
     loading: isLoading,
+    error: routeError,
 
-    // Methods
+    // Navigation methods
     navigate,
     start,
     link,
     outlet,
+    back,
+    forward,
+    go,
+
+    // Guards and middleware
     use,
     beforeEach,
     beforeResolve,
     afterEach,
-    back,
-    forward,
-    go,
+    setErrorHandler,
 
     // Route inspection
     isActive,
     getMatchedRoutes,
 
-    // Utils
+    // Utility functions
     matchRoute,
     parseQuery
   };

package/runtime/store.js

@@ -58,6 +58,56 @@ const MAX_NESTING_DEPTH = 10;
  */
 const DANGEROUS_KEYS = new Set(['__proto__', 'constructor', 'prototype']);
 
+/**
+ * Invalid value types that cannot be stored in state
+ * @type {Set<string>}
+ */
+const INVALID_TYPES = new Set(['function', 'symbol']);
+
+/**
+ * Validate state values, rejecting functions, symbols, and circular references
+ * @private
+ * @param {*} value - Value to validate
+ * @param {string} path - Current path for error messages
+ * @param {WeakSet} seen - Set of objects already visited (for circular detection)
+ * @throws {TypeError} If value contains invalid types or circular references
+ */
+function validateStateValue(value, path = 'state', seen = new WeakSet()) {
+  const valueType = typeof value;
+
+  // Check for invalid types
+  if (INVALID_TYPES.has(valueType)) {
+    throw new TypeError(
+      `Invalid state value at "${path}": ${valueType}s cannot be stored in state. ` +
+      `State values must be primitives, arrays, or plain objects.`
+    );
+  }
+
+  // Check objects for circular references and nested invalid types
+  if (value !== null && valueType === 'object') {
+    // Check for circular reference
+    if (seen.has(value)) {
+      throw new TypeError(
+        `Circular reference detected at "${path}". ` +
+        `State must not contain circular references.`
+      );
+    }
+    seen.add(value);
+
+    // Validate array elements
+    if (Array.isArray(value)) {
+      for (let i = 0; i < value.length; i++) {
+        validateStateValue(value[i], `${path}[${i}]`, seen);
+      }
+    } else {
+      // Validate object properties
+      for (const [key, val] of Object.entries(value)) {
+        validateStateValue(val, `${path}.${key}`, seen);
+      }
+    }
+  }
+}
+
 /**
  * Safely deserialize persisted state, preventing prototype pollution
  * and property injection attacks.
@@ -122,6 +172,9 @@ function safeDeserialize(savedState, schema) {
 export function createStore(initialState = {}, options = {}) {
   const { persist = false, storageKey = 'pulse-store' } = options;
 
+  // Validate initial state
+  validateStateValue(initialState, 'initialState');
+
   // Load persisted state if enabled
   let state = initialState;
   if (persist && typeof localStorage !== 'undefined') {

package/runtime/utils.js

@@ -22,10 +22,10 @@ const HTML_ESCAPES = {
 };
 
 /**
- * Regex for HTML special characters
+ * Regex for HTML special characters (auto-generated from HTML_ESCAPES keys)
  * @private
  */
-const HTML_ESCAPE_REGEX = /[&<>"']/g;
+const HTML_ESCAPE_REGEX = new RegExp(`[${Object.keys(HTML_ESCAPES).join('')}]`, 'g');
 
 /**
  * Escape HTML special characters to prevent XSS attacks.