@signaltree/core 3.0.2 → 4.0.1

package/dist/index.js

@@ -0,0 +1,4900 @@
+import { isSignal, signal, computed, effect, inject, DestroyRef } from '@angular/core';
+import { DEFAULT_PATH_CACHE_SIZE, isBuiltInObject, deepEqual, LRUCache, deepClone } from '@signaltree/shared';
+export { deepEqual, deepEqual as equal, isBuiltInObject, parsePath } from '@signaltree/shared';
+
+/**
+ * SignalTree Constants
+ * Centralized configuration values and messages
+ */
+const SIGNAL_TREE_CONSTANTS = {
+    /** Cache configuration */
+    MAX_PATH_CACHE_SIZE: DEFAULT_PATH_CACHE_SIZE,
+    /** Performance thresholds */
+    LAZY_THRESHOLD: 50,
+    ESTIMATE_MAX_DEPTH: 3,
+    ESTIMATE_SAMPLE_SIZE_ARRAY: 3,
+    ESTIMATE_SAMPLE_SIZE_OBJECT: 5,
+    /** Default values */
+    DEFAULT_CACHE_SIZE: 100,
+    DEFAULT_BATCH_SIZE: 10,
+};
+// Full developer-facing messages
+const DEV_MESSAGES = {
+    NULL_OR_UNDEFINED: 'null/undefined',
+    CIRCULAR_REF: 'circular ref',
+    UPDATER_INVALID: 'updater invalid',
+    LAZY_FALLBACK: 'lazy fallback',
+    SIGNAL_CREATION_FAILED: 'signal creation failed',
+    UPDATE_PATH_NOT_FOUND: 'update path not found',
+    UPDATE_FAILED: 'update failed',
+    ROLLBACK_FAILED: 'rollback failed',
+    CLEANUP_ERROR: 'cleanup error',
+    PRESET_UNKNOWN: 'unknown preset',
+    STRATEGY_SELECTION: 'strategy select',
+    TREE_DESTROYED: 'destroyed',
+    UPDATE_TRANSACTION: 'update tx',
+    BATCH_NOT_ENABLED: 'batching disabled',
+    MEMOIZE_NOT_ENABLED: 'memoize disabled',
+    MIDDLEWARE_NOT_AVAILABLE: 'middleware missing',
+    ENTITY_HELPERS_NOT_AVAILABLE: 'entity helpers missing',
+    ASYNC_ACTIONS_NOT_AVAILABLE: 'async actions missing',
+    TIME_TRAVEL_NOT_AVAILABLE: 'time travel missing',
+    OPTIMIZE_NOT_AVAILABLE: 'optimize missing',
+    UPDATE_OPTIMIZED_NOT_AVAILABLE: 'update optimized missing',
+    CACHE_NOT_AVAILABLE: 'cache missing',
+    PERFORMANCE_NOT_ENABLED: 'performance disabled',
+    ENHANCER_ORDER_FAILED: 'enhancer order failed',
+    ENHANCER_CYCLE_DETECTED: 'enhancer cycle',
+    ENHANCER_REQUIREMENT_MISSING: 'enhancer req missing',
+    ENHANCER_PROVIDES_MISSING: 'enhancer provides missing',
+    ENHANCER_FAILED: 'enhancer failed',
+    ENHANCER_NOT_FUNCTION: 'enhancer not function',
+    EFFECT_NO_CONTEXT: 'no angular context',
+    SUBSCRIBE_NO_CONTEXT: 'no angular context',
+};
+// Compact production messages (very short numeric codes) to keep bundles minimal.
+// We map each key to a short numeric string like '0','1','2' to minimize bytes.
+const PROD_MESSAGES = (() => {
+    const out = {};
+    let i = 0;
+    for (const k of Object.keys(DEV_MESSAGES)) {
+        out[k] = String(i++);
+    }
+    return out;
+})();
+// Avoid referencing the bare `process` identifier to keep builds free of Node
+// type assumptions; use globalThis to check env when available.
+const _isProdByEnv = Boolean(typeof globalThis === 'object' &&
+    globalThis !== null &&
+    'process' in globalThis &&
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    typeof globalThis.process === 'object' &&
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    'env' in globalThis.process &&
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    globalThis.process.env.NODE_ENV === 'production');
+const _isDev = typeof ngDevMode !== 'undefined' ? Boolean(ngDevMode) : !_isProdByEnv;
+const SIGNAL_TREE_MESSAGES = Object.freeze(_isDev
+    ? DEV_MESSAGES
+    : PROD_MESSAGES);
+
+/** Symbol key for enhancer metadata */
+const ENHANCER_META = Symbol('signaltree:enhancer:meta');
+
+/**
+ * Helper to create an enhancer with metadata attached
+ *
+ * @param meta - Metadata describing the enhancer
+ * @param enhancerFn - The enhancer function
+ * @returns Enhancer function with metadata attached
+ *
+ * @example
+ * ```typescript
+ * const myEnhancer = createEnhancer(
+ *   {
+ *     name: 'myEnhancer',
+ *     provides: ['feature1'],
+ *     requires: ['feature2']
+ *   },
+ *   (tree) => {
+ *     // Enhance the tree
+ *     return { ...tree, feature1: true };
+ *   }
+ * );
+ * ```
+ */
+function createEnhancer(meta, enhancerFn) {
+    const fn = enhancerFn;
+    try {
+        fn.metadata = meta;
+        // Also attach under symbol for third-party compatibility
+        try {
+            fn[ENHANCER_META] = meta;
+        }
+        catch {
+            // Ignore if property can't be set
+        }
+    }
+    catch {
+        // Ignore errors
+    }
+    return fn;
+}
+/**
+ * Resolve enhancer order using topological sort based on dependencies
+ *
+ * @param enhancers - Array of enhancers to order
+ * @param availableCapabilities - Set of already available capabilities
+ * @param debugMode - Whether to log debug information
+ * @returns Ordered array of enhancers
+ */
+function resolveEnhancerOrder(enhancers, availableCapabilities = new Set(), debugMode = false) {
+    // Build nodes with metadata
+    const nodes = enhancers.map((e, idx) => ({
+        fn: e,
+        name: e.metadata && e.metadata.name
+            ? String(e.metadata.name)
+            : `enhancer#${idx}`,
+        requires: new Set(e.metadata?.requires ?? []),
+        provides: new Set(e.metadata?.provides ?? []),
+    }));
+    // Build dependency graph
+    const adj = new Map();
+    const nameToNode = new Map();
+    for (const n of nodes) {
+        nameToNode.set(n.name, n);
+        adj.set(n.name, new Set());
+    }
+    // Create edges based on requirements
+    for (const a of nodes) {
+        for (const b of nodes) {
+            if (a === b)
+                continue;
+            for (const req of b.requires) {
+                // Skip if requirement is already satisfied
+                if (availableCapabilities.has(req))
+                    continue;
+                if (a.provides.has(req)) {
+                    // a must come before b
+                    const set = adj.get(a.name);
+                    if (set)
+                        set.add(b.name);
+                }
+            }
+        }
+    }
+    // Kahn's algorithm for topological sort
+    const inDegree = new Map();
+    for (const entry of adj.keys())
+        inDegree.set(entry, 0);
+    for (const [, outs] of adj) {
+        for (const to of outs)
+            inDegree.set(to, (inDegree.get(to) || 0) + 1);
+    }
+    const queue = [];
+    for (const [name, deg] of inDegree.entries()) {
+        if (deg === 0)
+            queue.push(name);
+    }
+    const ordered = [];
+    while (queue.length > 0) {
+        const n = queue.shift();
+        if (!n)
+            break;
+        ordered.push(n);
+        const outs = adj.get(n);
+        if (!outs)
+            continue;
+        for (const m of outs) {
+            inDegree.set(m, (inDegree.get(m) || 0) - 1);
+            if (inDegree.get(m) === 0)
+                queue.push(m);
+        }
+    }
+    // Check for cycles
+    if (ordered.length !== nodes.length) {
+        if (debugMode) {
+            console.warn(SIGNAL_TREE_MESSAGES.ENHANCER_CYCLE_DETECTED);
+        }
+        return enhancers;
+    }
+    // Map ordered names back to enhancer functions
+    return ordered.map((name) => {
+        const n = nameToNode.get(name);
+        return (n ? n.fn : enhancers[0]);
+    });
+}
+
+/**
+ * Memory Manager for SignalTree
+ * Provides automatic cleanup and memory leak prevention for lazy-loaded signal trees
+ * @packageDocumentation
+ */
+/**
+ * SignalMemoryManager
+ *
+ * Manages memory for lazy-loaded signal trees using WeakRef and FinalizationRegistry.
+ * Provides automatic cleanup when signals are no longer referenced, preventing memory leaks.
+ *
+ * Features:
+ * - WeakRef caches allow garbage collection when signals are unused
+ * - FinalizationRegistry automatically cleans up after GC
+ * - Stats API for memory profiling and monitoring
+ * - Manual dispose() for explicit cleanup
+ *
+ * @example
+ * ```ts
+ * const manager = new SignalMemoryManager({
+ *   enableAutoCleanup: true,
+ *   onCleanup: (path, stats) => {
+ *     console.log(`Cleaned up signal at ${path}`, stats);
+ *   }
+ * });
+ *
+ * // Cache a signal
+ * manager.cacheSignal('user.name', nameSignal);
+ *
+ * // Get cached signal (returns undefined if GC'd)
+ * const signal = manager.getSignal('user.name');
+ *
+ * // Get memory stats
+ * const stats = manager.getStats();
+ * console.log(`Memory: ${stats.estimatedMemoryBytes} bytes`);
+ *
+ * // Dispose all cached signals
+ * manager.dispose();
+ * ```
+ */
+class SignalMemoryManager {
+    cache = new Map();
+    registry = null;
+    config;
+    // Statistics
+    stats = {
+        cleanedUpSignals: 0,
+        peakCachedSignals: 0,
+        manualDisposes: 0,
+    };
+    constructor(config = {}) {
+        this.config = {
+            enableAutoCleanup: config.enableAutoCleanup ?? true,
+            debugMode: config.debugMode ?? false,
+            onCleanup: config.onCleanup ??
+                (() => {
+                    // Default no-op
+                }),
+        };
+        // Set up FinalizationRegistry for automatic cleanup
+        if (this.config.enableAutoCleanup &&
+            typeof FinalizationRegistry !== 'undefined') {
+            this.registry = new FinalizationRegistry((path) => {
+                this.handleCleanup(path);
+            });
+        }
+        if (this.config.debugMode) {
+            console.log('[SignalMemoryManager] Initialized', {
+                autoCleanup: this.config.enableAutoCleanup,
+                hasRegistry: !!this.registry,
+            });
+        }
+    }
+    /**
+     * Cache a signal with WeakRef for automatic garbage collection
+     *
+     * @param path - Dot-notation path to the signal
+     * @param signal - The signal to cache
+     */
+    cacheSignal(path, signal) {
+        // Create WeakRef to allow GC
+        const ref = new WeakRef(signal);
+        // Store in cache
+        const entry = {
+            ref,
+            path,
+            cachedAt: Date.now(),
+        };
+        this.cache.set(path, entry);
+        // Register for automatic cleanup
+        if (this.registry) {
+            this.registry.register(signal, path, signal);
+        }
+        // Update peak stats
+        const currentSize = this.cache.size;
+        if (currentSize > this.stats.peakCachedSignals) {
+            this.stats.peakCachedSignals = currentSize;
+        }
+        if (this.config.debugMode) {
+            console.log(`[SignalMemoryManager] Cached signal: ${path}`, {
+                cacheSize: currentSize,
+                peak: this.stats.peakCachedSignals,
+            });
+        }
+    }
+    /**
+     * Get a cached signal
+     * Returns undefined if the signal has been garbage collected
+     *
+     * @param path - Dot-notation path to the signal
+     * @returns The signal or undefined if GC'd
+     */
+    getSignal(path) {
+        const entry = this.cache.get(path);
+        if (!entry) {
+            return undefined;
+        }
+        // Try to dereference the WeakRef
+        const signal = entry.ref.deref();
+        if (!signal) {
+            // Signal was garbage collected, remove from cache
+            this.cache.delete(path);
+            if (this.config.debugMode) {
+                console.log(`[SignalMemoryManager] Signal GC'd: ${path}`);
+            }
+            return undefined;
+        }
+        return signal;
+    }
+    /**
+     * Check if a signal is cached (even if potentially GC'd)
+     *
+     * @param path - Dot-notation path to the signal
+     * @returns true if the path exists in cache
+     */
+    hasSignal(path) {
+        return this.cache.has(path);
+    }
+    /**
+     * Remove a signal from the cache
+     *
+     * @param path - Dot-notation path to the signal
+     * @returns true if the signal was removed
+     */
+    removeSignal(path) {
+        const entry = this.cache.get(path);
+        if (!entry) {
+            return false;
+        }
+        // Unregister from FinalizationRegistry
+        const signal = entry.ref.deref();
+        if (signal && this.registry) {
+            this.registry.unregister(signal);
+        }
+        this.cache.delete(path);
+        if (this.config.debugMode) {
+            console.log(`[SignalMemoryManager] Removed signal: ${path}`);
+        }
+        return true;
+    }
+    /**
+     * Handle automatic cleanup from FinalizationRegistry
+     * @private
+     */
+    handleCleanup(path) {
+        this.cache.delete(path);
+        this.stats.cleanedUpSignals++;
+        const currentStats = this.getStats();
+        if (this.config.debugMode) {
+            console.log(`[SignalMemoryManager] Auto cleanup: ${path}`, currentStats);
+        }
+        this.config.onCleanup(path, currentStats);
+    }
+    /**
+     * Get current memory statistics
+     *
+     * @returns Current memory stats
+     */
+    getStats() {
+        // Clean up stale entries (where WeakRef.deref() returns undefined)
+        let validSignals = 0;
+        for (const [path, entry] of this.cache.entries()) {
+            if (entry.ref.deref()) {
+                validSignals++;
+            }
+            else {
+                // Remove stale entry
+                this.cache.delete(path);
+            }
+        }
+        // Rough estimate: each signal ~100 bytes (very approximate)
+        const estimatedMemoryBytes = validSignals * 100;
+        return {
+            cachedSignals: validSignals,
+            cleanedUpSignals: this.stats.cleanedUpSignals,
+            peakCachedSignals: this.stats.peakCachedSignals,
+            manualDisposes: this.stats.manualDisposes,
+            estimatedMemoryBytes,
+        };
+    }
+    /**
+     * Dispose all cached signals and clean up resources
+     * Call this when destroying a SignalTree to prevent memory leaks
+     */
+    dispose() {
+        if (this.config.debugMode) {
+            console.log('[SignalMemoryManager] Disposing', {
+                cachedSignals: this.cache.size,
+            });
+        }
+        // Unregister all signals from FinalizationRegistry
+        if (this.registry) {
+            for (const entry of this.cache.values()) {
+                const signal = entry.ref.deref();
+                if (signal) {
+                    this.registry.unregister(signal);
+                }
+            }
+        }
+        // Clear cache
+        this.cache.clear();
+        this.stats.manualDisposes++;
+        if (this.config.debugMode) {
+            console.log('[SignalMemoryManager] Disposed', this.getStats());
+        }
+    }
+    /**
+     * Get all cached signal paths (for debugging)
+     *
+     * @returns Array of cached signal paths
+     */
+    getCachedPaths() {
+        const paths = [];
+        for (const [path, entry] of this.cache.entries()) {
+            // Only include if signal is still alive
+            if (entry.ref.deref()) {
+                paths.push(path);
+            }
+        }
+        return paths;
+    }
+    /**
+     * Clear all stale entries (where signals have been GC'd)
+     * Useful for freeing up cache Map memory
+     *
+     * @returns Number of stale entries removed
+     */
+    clearStale() {
+        let removed = 0;
+        for (const [path, entry] of this.cache.entries()) {
+            if (!entry.ref.deref()) {
+                this.cache.delete(path);
+                removed++;
+            }
+        }
+        if (this.config.debugMode && removed > 0) {
+            console.log(`[SignalMemoryManager] Cleared ${removed} stale entries`);
+        }
+        return removed;
+    }
+    /**
+     * Reset all statistics
+     */
+    resetStats() {
+        this.stats = {
+            cleanedUpSignals: 0,
+            peakCachedSignals: 0,
+            manualDisposes: 0,
+        };
+        if (this.config.debugMode) {
+            console.log('[SignalMemoryManager] Stats reset');
+        }
+    }
+}
+
+/**
+ * DiffEngine - Efficient change detection for tree updates
+ * @packageDocumentation
+ */
+/**
+ * Type of change detected
+ */
+var ChangeType;
+(function (ChangeType) {
+    ChangeType["ADD"] = "add";
+    ChangeType["UPDATE"] = "update";
+    ChangeType["DELETE"] = "delete";
+    ChangeType["REPLACE"] = "replace";
+})(ChangeType || (ChangeType = {}));
+/**
+ * DiffEngine
+ *
+ * Efficiently detects changes between two objects to minimize unnecessary updates.
+ *
+ * Features:
+ * - Deep object comparison
+ * - Circular reference detection
+ * - Configurable equality checking
+ * - Array diffing (ordered and unordered)
+ * - Path tracking for precise updates
+ *
+ * @example
+ * ```ts
+ * const engine = new DiffEngine();
+ *
+ * const current = { user: { name: 'Alice', age: 30 } };
+ * const updates = { user: { name: 'Alice', age: 31 } };
+ *
+ * const diff = engine.diff(current, updates);
+ *
+ * console.log(diff.changes);
+ * // [{ type: 'update', path: ['user', 'age'], value: 31, oldValue: 30 }]
+ * ```
+ */
+class DiffEngine {
+    defaultOptions = {
+        maxDepth: 100,
+        detectDeletions: false,
+        ignoreArrayOrder: false,
+        equalityFn: (a, b) => a === b,
+        keyValidator: undefined,
+    };
+    /**
+     * Diff two objects and return changes
+     *
+     * @param current - Current state
+     * @param updates - Updated state
+     * @param options - Diff options
+     * @returns Diff result with all changes
+     */
+    diff(current, updates, options = {}) {
+        const opts = { ...this.defaultOptions, ...options };
+        const changes = [];
+        const visited = new WeakSet();
+        this.traverse(current, updates, [], changes, visited, opts, 0);
+        return {
+            changes,
+            hasChanges: changes.length > 0,
+        };
+    }
+    /**
+     * Traverse and compare objects recursively
+     */
+    traverse(curr, upd, path, changes, visited, opts, depth) {
+        // Depth limit
+        if (depth > opts.maxDepth) {
+            return;
+        }
+        // Handle primitives
+        if (typeof upd !== 'object' || upd === null) {
+            if (!opts.equalityFn(curr, upd)) {
+                changes.push({
+                    type: curr === undefined ? ChangeType.ADD : ChangeType.UPDATE,
+                    path: [...path],
+                    value: upd,
+                    oldValue: curr,
+                });
+            }
+            return;
+        }
+        // Circular reference detection
+        if (visited.has(upd)) {
+            return;
+        }
+        visited.add(upd);
+        // Handle arrays
+        if (Array.isArray(upd)) {
+            this.diffArrays(curr, upd, path, changes, visited, opts, depth);
+            return;
+        }
+        // Handle objects
+        if (!curr || typeof curr !== 'object' || Array.isArray(curr)) {
+            // Type mismatch - replace entire subtree
+            changes.push({
+                type: ChangeType.REPLACE,
+                path: [...path],
+                value: upd,
+                oldValue: curr,
+            });
+            return;
+        }
+        // Diff object properties
+        const currObj = curr;
+        const updObj = upd;
+        for (const key in updObj) {
+            if (Object.prototype.hasOwnProperty.call(updObj, key)) {
+                // Validate key for security (e.g., prevent prototype pollution)
+                if (opts.keyValidator && !opts.keyValidator(key)) {
+                    // Skip dangerous keys silently
+                    continue;
+                }
+                this.traverse(currObj[key], updObj[key], [...path, key], changes, visited, opts, depth + 1);
+            }
+        }
+        // Check for deletions if enabled
+        if (opts.detectDeletions) {
+            for (const key in currObj) {
+                if (Object.prototype.hasOwnProperty.call(currObj, key) &&
+                    !(key in updObj)) {
+                    changes.push({
+                        type: ChangeType.DELETE,
+                        path: [...path, key],
+                        oldValue: currObj[key],
+                    });
+                }
+            }
+        }
+    }
+    /**
+     * Diff arrays
+     */
+    diffArrays(curr, upd, path, changes, visited, opts, depth) {
+        if (!Array.isArray(curr)) {
+            // Not an array - replace
+            changes.push({
+                type: ChangeType.REPLACE,
+                path: [...path],
+                value: upd,
+                oldValue: curr,
+            });
+            return;
+        }
+        if (opts.ignoreArrayOrder) {
+            this.diffArraysUnordered(curr, upd, path, changes, opts);
+        }
+        else {
+            this.diffArraysOrdered(curr, upd, path, changes, visited, opts, depth);
+        }
+    }
+    /**
+     * Diff arrays in order (index-based)
+     */
+    diffArraysOrdered(curr, upd, path, changes, visited, opts, depth) {
+        // Check each index
+        const maxLength = Math.max(curr.length, upd.length);
+        for (let i = 0; i < maxLength; i++) {
+            if (i >= upd.length) {
+                // Deletion (if enabled)
+                if (opts.detectDeletions) {
+                    changes.push({
+                        type: ChangeType.DELETE,
+                        path: [...path, i],
+                        oldValue: curr[i],
+                    });
+                }
+            }
+            else if (i >= curr.length) {
+                // Addition
+                changes.push({
+                    type: ChangeType.ADD,
+                    path: [...path, i],
+                    value: upd[i],
+                });
+            }
+            else {
+                // Potential update
+                this.traverse(curr[i], upd[i], [...path, i], changes, visited, opts, depth + 1);
+            }
+        }
+    }
+    /**
+     * Diff arrays ignoring order (value-based)
+     */
+    diffArraysUnordered(curr, upd, path, changes, opts) {
+        // Build value sets
+        const currSet = new Set(curr.map((v) => this.stringify(v)));
+        const updSet = new Set(upd.map((v) => this.stringify(v)));
+        // Find additions
+        upd.forEach((value, index) => {
+            const str = this.stringify(value);
+            if (!currSet.has(str)) {
+                changes.push({
+                    type: ChangeType.ADD,
+                    path: [...path, index],
+                    value,
+                });
+            }
+        });
+        // Find deletions (if enabled)
+        if (opts.detectDeletions) {
+            curr.forEach((value, index) => {
+                const str = this.stringify(value);
+                if (!updSet.has(str)) {
+                    changes.push({
+                        type: ChangeType.DELETE,
+                        path: [...path, index],
+                        oldValue: value,
+                    });
+                }
+            });
+        }
+    }
+    /**
+     * Stringify value for set comparison
+     */
+    stringify(value) {
+        try {
+            return JSON.stringify(value);
+        }
+        catch {
+            return String(value);
+        }
+    }
+}
+
+/**
+ * Node in the Trie structure
+ */
+class TrieNode {
+    value = null;
+    children = new Map();
+}
+/**
+ * PathIndex
+ *
+ * Fast signal lookup using a Trie (prefix tree) data structure.
+ * Provides O(k) lookup time where k is the path length, regardless of total signals.
+ *
+ * Features:
+ * - Trie-based indexing for O(k) lookup
+ * - WeakRef caching for memory efficiency
+ * - Automatic cleanup of stale references
+ * - Prefix matching for batch operations
+ * - Path normalization
+ *
+ * @example
+ * ```ts
+ * const index = new PathIndex();
+ *
+ * // Index signals
+ * index.set(['user', 'name'], nameSignal);
+ * index.set(['user', 'email'], emailSignal);
+ *
+ * // Fast lookup
+ * const signal = index.get(['user', 'name']);
+ *
+ * // Prefix matching
+ * const userSignals = index.getByPrefix(['user']);
+ * // Returns: { name: nameSignal, email: emailSignal }
+ *
+ * // Check if path exists
+ * if (index.has(['user', 'name'])) {
+ *   // ...
+ * }
+ * ```
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+class PathIndex {
+    root = new TrieNode();
+    pathCache = new Map();
+    stats = {
+        hits: 0,
+        misses: 0,
+        sets: 0,
+        cleanups: 0,
+    };
+    /**
+     * Set a value at the given path
+     *
+     * @param path - Path segments
+     * @param value - Value to store
+     */
+    set(path, signal) {
+        const pathStr = this.pathToString(path);
+        const ref = new WeakRef(signal);
+        // Update trie
+        let node = this.root;
+        for (const segment of path) {
+            const key = String(segment);
+            if (!node.children.has(key)) {
+                node.children.set(key, new TrieNode());
+            }
+            const nextNode = node.children.get(key);
+            if (!nextNode) {
+                throw new Error(`Failed to get node for key: ${key}`);
+            }
+            node = nextNode;
+        }
+        node.value = ref;
+        // Update cache for fast string lookups
+        this.pathCache.set(pathStr, ref);
+        this.stats.sets++;
+    }
+    /**
+     * Get value at the given path
+     *
+     * @param path - Path segments
+     * @returns Value if found and not GC'd, null otherwise
+     */
+    get(path) {
+        const pathStr = this.pathToString(path);
+        // Try cache first
+        const cached = this.pathCache.get(pathStr);
+        if (cached) {
+            const value = cached.deref();
+            if (value) {
+                this.stats.hits++;
+                return value;
+            }
+            // Clean up dead reference
+            this.pathCache.delete(pathStr);
+            this.stats.cleanups++;
+        }
+        // Try trie
+        let node = this.root;
+        for (const segment of path) {
+            const key = String(segment);
+            node = node.children.get(key);
+            if (!node) {
+                this.stats.misses++;
+                return null;
+            }
+        }
+        if (node.value) {
+            const value = node.value.deref();
+            if (value) {
+                // Re-cache for next time
+                this.pathCache.set(pathStr, node.value);
+                this.stats.hits++;
+                return value;
+            }
+            // Clean up dead reference
+            node.value = null;
+            this.stats.cleanups++;
+        }
+        this.stats.misses++;
+        return null;
+    }
+    /**
+     * Check if path exists in index
+     *
+     * @param path - Path segments
+     * @returns True if path exists and value is not GC'd
+     */
+    has(path) {
+        return this.get(path) !== null;
+    }
+    /**
+     * Get all values matching a prefix
+     *
+     * @param prefix - Path prefix
+     * @returns Map of relative paths to values
+     */
+    getByPrefix(prefix) {
+        const results = new Map();
+        // Find the node at prefix
+        let node = this.root;
+        for (const segment of prefix) {
+            const key = String(segment);
+            node = node.children.get(key);
+            if (!node) {
+                return results; // Empty map
+            }
+        }
+        // Collect all descendants
+        this.collectDescendants(node, [], results);
+        return results;
+    }
+    /**
+     * Delete value at path
+     *
+     * @param path - Path segments
+     * @returns True if deleted, false if not found
+     */
+    delete(path) {
+        const pathStr = this.pathToString(path);
+        // Remove from cache
+        this.pathCache.delete(pathStr);
+        // Remove from trie
+        let node = this.root;
+        const nodes = [node];
+        for (const segment of path) {
+            const key = String(segment);
+            node = node.children.get(key);
+            if (!node) {
+                return false;
+            }
+            nodes.push(node);
+        }
+        // Clear value
+        const hadValue = node.value !== null;
+        node.value = null;
+        // Clean up empty nodes (from leaf to root)
+        for (let i = nodes.length - 1; i > 0; i--) {
+            const current = nodes[i];
+            if (current.value === null && current.children.size === 0) {
+                const parent = nodes[i - 1];
+                const segment = path[i - 1];
+                parent.children.delete(String(segment));
+            }
+            else {
+                break; // Stop if node has value or children
+            }
+        }
+        return hadValue;
+    }
+    /**
+     * Clear all entries
+     */
+    clear() {
+        this.root = new TrieNode();
+        this.pathCache.clear();
+    }
+    /**
+     * Get statistics
+     *
+     * @returns Index statistics
+     */
+    getStats() {
+        const total = this.stats.hits + this.stats.misses;
+        const hitRate = total > 0 ? this.stats.hits / total : 0;
+        return {
+            ...this.stats,
+            hitRate,
+            cacheSize: this.pathCache.size,
+        };
+    }
+    /**
+     * Build index from a tree structure
+     *
+     * @param tree - Tree object to index
+     * @param path - Current path (for recursion)
+     */
+    buildFromTree(tree, path = []) {
+        if (!tree) {
+            return;
+        }
+        // Check if it's a signal using Angular's isSignal
+        if (isSignal(tree)) {
+            this.set(path, tree);
+            return;
+        }
+        // Only continue if it's an object (not a signal or primitive)
+        if (typeof tree !== 'object') {
+            return;
+        }
+        // Recursively index children
+        for (const [key, value] of Object.entries(tree)) {
+            this.buildFromTree(value, [...path, key]);
+        }
+    }
+    /**
+     * Convert path to string for caching
+     */
+    pathToString(path) {
+        return path.join('.');
+    }
+    /**
+     * Collect all descendant values recursively
+     */
+    collectDescendants(node, currentPath, results) {
+        // Add current node's value if it exists
+        if (node.value) {
+            const value = node.value.deref();
+            if (value) {
+                results.set(this.pathToString(currentPath), value);
+            }
+        }
+        // Recursively collect children
+        for (const [key, child] of node.children) {
+            this.collectDescendants(child, [...currentPath, key], results);
+        }
+    }
+}
+
+/**
+ * OptimizedUpdateEngine
+ *
+ * High-performance update engine using path indexing and diffing to minimize
+ * unnecessary signal updates.
+ *
+ * Features:
+ * - Diff-based updates (only update what changed)
+ * - Path indexing for O(k) lookups
+ * - Automatic batching for large updates
+ * - Priority-based patch ordering
+ * - Skip unchanged values
+ *
+ * @example
+ * ```ts
+ * const tree = signalTree(data, { useLazySignals: true });
+ * const engine = new OptimizedUpdateEngine(tree);
+ *
+ * // Optimized update - only changes what's different
+ * const result = engine.update({
+ *   user: { name: 'Alice' } // Only updates if name changed
+ * });
+ *
+ * console.log(result.changedPaths); // ['user.name']
+ * console.log(result.duration); // ~2ms
+ * ```
+ */
+class OptimizedUpdateEngine {
+    pathIndex;
+    diffEngine;
+    constructor(tree) {
+        this.pathIndex = new PathIndex();
+        this.diffEngine = new DiffEngine();
+        // Build initial index
+        this.pathIndex.buildFromTree(tree);
+    }
+    /**
+     * Update tree with optimizations
+     *
+     * @param tree - Current tree state
+     * @param updates - Updates to apply
+     * @param options - Update options
+     * @returns Update result
+     */
+    update(tree, updates, options = {}) {
+        const startTime = performance.now();
+        // Step 1: Generate diff to find actual changes
+        const diffOptions = {};
+        if (options.maxDepth !== undefined)
+            diffOptions.maxDepth = options.maxDepth;
+        if (options.ignoreArrayOrder !== undefined)
+            diffOptions.ignoreArrayOrder = options.ignoreArrayOrder;
+        if (options.equalityFn !== undefined)
+            diffOptions.equalityFn = options.equalityFn;
+        const diff = this.diffEngine.diff(tree, updates, diffOptions);
+        if (diff.changes.length === 0) {
+            // No actual changes, skip update entirely
+            return {
+                changed: false,
+                duration: performance.now() - startTime,
+                changedPaths: [],
+            };
+        }
+        // Step 2: Convert diff to optimized patches
+        const patches = this.createPatches(diff.changes);
+        // Step 3: Sort patches for optimal application order
+        const sortedPatches = this.sortPatches(patches);
+        // Step 4: Apply patches with optional batching
+        const result = options.batch
+            ? this.batchApplyPatches(tree, sortedPatches, options.batchSize)
+            : this.applyPatches(tree, sortedPatches);
+        const duration = performance.now() - startTime;
+        return {
+            changed: true,
+            duration,
+            changedPaths: result.appliedPaths,
+            stats: {
+                totalPaths: diff.changes.length,
+                optimizedPaths: patches.length,
+                batchedUpdates: result.batchCount,
+            },
+        };
+    }
+    /**
+     * Rebuild path index from current tree state
+     *
+     * @param tree - Current tree
+     */
+    rebuildIndex(tree) {
+        this.pathIndex.clear();
+        this.pathIndex.buildFromTree(tree);
+    }
+    /**
+     * Get path index statistics
+     */
+    getIndexStats() {
+        return this.pathIndex.getStats();
+    }
+    /**
+     * Creates optimized patches from diff changes
+     */
+    createPatches(changes) {
+        const patches = [];
+        const processedPaths = new Set();
+        for (const change of changes) {
+            const pathStr = change.path.join('.');
+            // Skip if parent path already processed (optimization)
+            let skipPath = false;
+            for (const processed of processedPaths) {
+                if (pathStr.startsWith(processed + '.')) {
+                    skipPath = true;
+                    break;
+                }
+            }
+            if (skipPath) {
+                continue;
+            }
+            // Create patch based on change type
+            const patch = this.createPatch(change);
+            patches.push(patch);
+            // Mark path as processed
+            processedPaths.add(pathStr);
+            // If this is an object replacement, skip child paths
+            if (change.type === ChangeType.REPLACE &&
+                typeof change.value === 'object') {
+                processedPaths.add(pathStr);
+            }
+        }
+        return patches;
+    }
+    /**
+     * Creates a single patch from a change
+     */
+    createPatch(change) {
+        return {
+            type: change.type,
+            path: change.path,
+            value: change.value,
+            oldValue: change.oldValue,
+            priority: this.calculatePriority(change),
+            signal: this.pathIndex.get(change.path),
+        };
+    }
+    /**
+     * Calculates update priority for optimal ordering
+     */
+    calculatePriority(change) {
+        let priority = 0;
+        // Shallow updates have higher priority
+        priority += (10 - change.path.length) * 10;
+        // Array updates have lower priority (more expensive)
+        if (change.path.some((p) => typeof p === 'number')) {
+            priority -= 20;
+        }
+        // Replace operations have higher priority than nested updates
+        if (change.type === ChangeType.REPLACE) {
+            priority += 30;
+        }
+        return priority;
+    }
+    /**
+     * Sorts patches for optimal application
+     */
+    sortPatches(patches) {
+        return patches.sort((a, b) => {
+            // Sort by priority (higher first)
+            if (a.priority !== b.priority) {
+                return b.priority - a.priority;
+            }
+            // Then by path depth (shallow first)
+            return a.path.length - b.path.length;
+        });
+    }
+    /**
+     * Applies patches directly (no batching)
+     */
+    applyPatches(tree, patches) {
+        const appliedPaths = [];
+        let updateCount = 0;
+        for (const patch of patches) {
+            if (this.applyPatch(patch, tree)) {
+                appliedPaths.push(patch.path.join('.'));
+                updateCount++;
+            }
+        }
+        return {
+            appliedPaths,
+            updateCount,
+            batchCount: 1,
+        };
+    }
+    /**
+     * Applies patches with batching for better performance
+     */
+    batchApplyPatches(tree, patches, batchSize = 50) {
+        const batches = [];
+        for (let i = 0; i < patches.length; i += batchSize) {
+            batches.push(patches.slice(i, i + batchSize));
+        }
+        const appliedPaths = [];
+        let updateCount = 0;
+        // Process patches in batches
+        for (const currentBatch of batches) {
+            for (const patch of currentBatch) {
+                if (this.applyPatch(patch, tree)) {
+                    appliedPaths.push(patch.path.join('.'));
+                    updateCount++;
+                }
+            }
+        }
+        return {
+            appliedPaths,
+            updateCount,
+            batchCount: batches.length,
+        };
+    }
+    /**
+     * Applies a single patch to the tree object
+     */
+    applyPatch(patch, tree) {
+        try {
+            // First, try to update via signal if available
+            if (patch.signal && isSignal(patch.signal) && 'set' in patch.signal) {
+                const currentValue = patch.signal();
+                // Only update if value actually changed
+                if (this.isEqual(currentValue, patch.value)) {
+                    return false;
+                }
+                // Update the signal - this will handle reactivity
+                patch.signal.set(patch.value);
+                // After successful ADD, update the index
+                if (patch.type === ChangeType.ADD && patch.value !== undefined) {
+                    this.pathIndex.set(patch.path, patch.signal);
+                }
+                return true;
+            } // Fallback: Navigate to parent object and update directly
+            let current = tree;
+            for (let i = 0; i < patch.path.length - 1; i++) {
+                const key = patch.path[i];
+                current = current[key];
+                if (!current || typeof current !== 'object') {
+                    return false;
+                }
+            }
+            const lastKey = patch.path[patch.path.length - 1];
+            // Only update if value actually changed
+            if (this.isEqual(current[lastKey], patch.value)) {
+                return false;
+            }
+            // Apply update directly to object
+            current[lastKey] = patch.value;
+            return true;
+        }
+        catch (error) {
+            console.error(`Failed to apply patch at ${patch.path.join('.')}:`, error);
+            return false;
+        }
+    }
+    /**
+     * Check equality
+     */
+    isEqual(a, b) {
+        // Fast path for primitives
+        if (a === b) {
+            return true;
+        }
+        if (typeof a !== typeof b) {
+            return false;
+        }
+        if (typeof a !== 'object' || a === null || b === null) {
+            return false;
+        }
+        // Deep equality for objects (simple version)
+        try {
+            return JSON.stringify(a) === JSON.stringify(b);
+        }
+        catch {
+            return false;
+        }
+    }
+}
+
+/**
+ * Security validator for SignalTree to prevent common vulnerabilities
+ * @packageDocumentation
+ */
+/**
+ * Built-in dangerous keys that can lead to prototype pollution
+ */
+const DANGEROUS_KEYS = ['__proto__', 'constructor', 'prototype'];
+/**
+ * Basic HTML tag pattern for XSS detection
+ */
+const HTML_TAG_PATTERN = /<[^>]*>/g;
+/**
+ * Dangerous HTML patterns that should always be blocked
+ */
+const DANGEROUS_HTML_PATTERNS = [
+    /<script\b[^<]*(?:(?!<\/script>)<[^<]*)*<\/script>/gi,
+    /on\w+\s*=/gi, // Event handlers like onclick=
+    /javascript:/gi,
+    /<iframe\b/gi,
+    /<object\b/gi,
+    /<embed\b/gi,
+];
+/**
+ * SecurityValidator prevents common security vulnerabilities in SignalTree
+ *
+ * Features:
+ * - Prototype pollution prevention (blocks __proto__, constructor, prototype)
+ * - XSS prevention (sanitizes string values)
+ * - Security event callbacks for monitoring
+ * - Configurable validation rules
+ *
+ * @example
+ * ```ts
+ * const validator = new SecurityValidator({
+ *   preventPrototypePollution: true,
+ *   preventXSS: true,
+ *   onSecurityEvent: (event) => console.warn('Security event:', event)
+ * });
+ *
+ * // This will throw an error
+ * validator.validateKey('__proto__');
+ *
+ * // This will sanitize the value
+ * const safe = validator.validateValue('<script>alert("xss")</script>');
+ * ```
+ */
+class SecurityValidator {
+    config;
+    dangerousKeys;
+    constructor(config = {}) {
+        this.config = {
+            preventPrototypePollution: config.preventPrototypePollution ?? true,
+            preventXSS: config.preventXSS ?? false,
+            preventFunctions: config.preventFunctions ?? true,
+            customDangerousKeys: config.customDangerousKeys ?? [],
+            onSecurityEvent: config.onSecurityEvent ??
+                (() => {
+                    // Default no-op callback
+                }),
+            sanitizationMode: config.sanitizationMode ?? 'strict',
+        };
+        // Build set of dangerous keys for O(1) lookup
+        this.dangerousKeys = new Set([
+            ...DANGEROUS_KEYS,
+            ...this.config.customDangerousKeys,
+        ]);
+    }
+    /**
+     * Validate a key to prevent prototype pollution
+     *
+     * @param key - The key to validate
+     * @throws Error if the key is dangerous and validation is enabled
+     */
+    validateKey(key) {
+        if (!this.config.preventPrototypePollution) {
+            return;
+        }
+        if (this.dangerousKeys.has(key)) {
+            const event = {
+                type: 'dangerous-key-blocked',
+                key,
+                reason: `Dangerous key "${key}" blocked to prevent prototype pollution`,
+                timestamp: Date.now(),
+            };
+            this.config.onSecurityEvent(event);
+            throw new Error(`[SignalTree Security] Dangerous key "${key}" is not allowed. ` +
+                `This key can lead to prototype pollution attacks. ` +
+                `Blocked keys: ${Array.from(this.dangerousKeys).join(', ')}`);
+        }
+    }
+    /**
+     * Validate and sanitize a value to prevent XSS and block functions
+     *
+     * @param value - The value to validate
+     * @returns The sanitized value (or original if not a string or validation disabled)
+     * @throws Error if value is a function and preventFunctions is enabled
+     */
+    validateValue(value) {
+        // Block function values to ensure serializable state
+        if (this.config.preventFunctions && typeof value === 'function') {
+            const event = {
+                type: 'function-value-blocked',
+                value,
+                reason: 'Function values are not allowed - state must be serializable',
+                timestamp: Date.now(),
+            };
+            this.config.onSecurityEvent(event);
+            throw new Error(`[SignalTree Security] Function values are not allowed in state trees. ` +
+                `Functions cannot be serialized, breaking features like time-travel, ` +
+                `persistence, debugging, and SSR. ` +
+                `\n\nTo fix this:` +
+                `\n  - Store function references outside the tree` +
+                `\n  - Use method names (strings) and a function registry` +
+                `\n  - Use computed signals for derived values` +
+                `\n\nBlocked value: ${value.toString().substring(0, 100)}...`);
+        }
+        if (!this.config.preventXSS || typeof value !== 'string') {
+            return value;
+        }
+        // Check for dangerous patterns first
+        let hasDangerousPattern = false;
+        for (const pattern of DANGEROUS_HTML_PATTERNS) {
+            // Reset lastIndex for global regexes
+            pattern.lastIndex = 0;
+            if (pattern.test(value)) {
+                hasDangerousPattern = true;
+                break;
+            }
+        }
+        if (hasDangerousPattern) {
+            const event = {
+                type: 'xss-attempt-blocked',
+                value,
+                reason: 'Dangerous HTML pattern detected and sanitized',
+                timestamp: Date.now(),
+            };
+            this.config.onSecurityEvent(event);
+            // In strict mode, remove all HTML
+            // In permissive mode, we still block dangerous patterns
+            return this.sanitize(value);
+        }
+        // Apply general sanitization based on mode
+        return this.sanitize(value);
+    }
+    /**
+     * Sanitize a string value based on the configured mode
+     *
+     * @param value - The string to sanitize
+     * @returns The sanitized string
+     */
+    sanitize(value) {
+        if (this.config.sanitizationMode === 'strict') {
+            // First remove dangerous patterns, then all HTML tags
+            let sanitized = value;
+            for (const pattern of DANGEROUS_HTML_PATTERNS) {
+                // Reset lastIndex for global regexes
+                pattern.lastIndex = 0;
+                sanitized = sanitized.replace(pattern, '');
+            }
+            // Then remove all remaining HTML tags
+            return sanitized.replace(HTML_TAG_PATTERN, '');
+        }
+        else {
+            // Permissive mode: only remove dangerous patterns
+            let sanitized = value;
+            for (const pattern of DANGEROUS_HTML_PATTERNS) {
+                // Reset lastIndex for global regexes
+                pattern.lastIndex = 0;
+                sanitized = sanitized.replace(pattern, '');
+            }
+            return sanitized;
+        }
+    }
+    /**
+     * Validate both key and value (convenience method)
+     *
+     * @param key - The key to validate
+     * @param value - The value to validate
+     * @returns The sanitized value
+     */
+    validateKeyValue(key, value) {
+        this.validateKey(key);
+        return this.validateValue(value);
+    }
+    /**
+     * Check if a key is dangerous without throwing
+     *
+     * @param key - The key to check
+     * @returns true if the key is dangerous
+     */
+    isDangerousKey(key) {
+        return this.dangerousKeys.has(key);
+    }
+    /**
+     * Get the current configuration
+     */
+    getConfig() {
+        return { ...this.config };
+    }
+}
+/**
+ * Create a SecurityValidator with common presets
+ */
+const SecurityPresets = {
+    /**
+     * Strict security: All protections enabled (recommended for production)
+     */
+    strict: () => new SecurityValidator({
+        preventPrototypePollution: true,
+        preventXSS: true,
+        preventFunctions: true,
+        sanitizationMode: 'strict',
+    }),
+    /**
+     * Standard security: Prototype pollution and function blocking (default)
+     */
+    standard: () => new SecurityValidator({
+        preventPrototypePollution: true,
+        preventXSS: false,
+        preventFunctions: true,
+    }),
+    /**
+     * Permissive security: Only prototype pollution prevention
+     * WARNING: Allows functions, breaking serialization features
+     */
+    permissive: () => new SecurityValidator({
+        preventPrototypePollution: true,
+        preventXSS: false,
+        preventFunctions: false,
+    }),
+    /**
+     * Disabled: No security validations
+     * DANGER: Not recommended - allows prototype pollution and functions
+     */
+    disabled: () => new SecurityValidator({
+        preventPrototypePollution: false,
+        preventXSS: false,
+        preventFunctions: false,
+    }),
+};
+
+/** Symbol to mark callable signals - using global symbol to match across files */
+const CALLABLE_SIGNAL_SYMBOL = Symbol.for('NodeAccessor');
+/**
+ * Checks if a value is a node accessor created by makeNodeAccessor
+ */
+function isNodeAccessor$1(value) {
+    return (typeof value === 'function' && value && CALLABLE_SIGNAL_SYMBOL in value);
+}
+/**
+ * Checks if a value is either an Angular signal or a callable signal
+ * This is useful for packages that need to work with both types
+ */
+function isAnySignal(value) {
+    return isSignal(value) || isNodeAccessor$1(value);
+}
+function composeEnhancers(...enhancers) {
+    return (tree) => enhancers.reduce((t, e) => e(t), tree);
+}
+/**
+ * Creates a lazy signal tree using Proxy for on-demand signal creation
+ */
+function createLazySignalTree(obj, equalityFn, basePath = '', memoryManager) {
+    const signalCache = new Map();
+    const nestedProxies = new Map();
+    const nestedCleanups = new Map();
+    const cleanup = () => {
+        nestedCleanups.forEach((fn) => {
+            try {
+                fn();
+            }
+            catch (error) {
+                console.warn('Error during nested cleanup:', error);
+            }
+        });
+        nestedCleanups.clear();
+        signalCache.clear();
+        nestedProxies.clear();
+        // Clear from memory manager if provided
+        if (memoryManager) {
+            memoryManager.dispose();
+        }
+    };
+    const proxy = new Proxy(obj, {
+        get(target, prop) {
+            if (prop === '__cleanup__')
+                return cleanup;
+            if (typeof prop === 'symbol') {
+                return target[prop];
+            }
+            if (prop === 'valueOf' || prop === 'toString') {
+                return target[prop];
+            }
+            const key = prop;
+            const path = basePath ? `${basePath}.${key}` : key;
+            if (!(key in target))
+                return undefined;
+            const value = target[key];
+            if (isSignal(value))
+                return value;
+            // Check memory manager cache first
+            if (memoryManager) {
+                const cached = memoryManager.getSignal(path);
+                if (cached)
+                    return cached;
+            }
+            if (signalCache.has(path))
+                return signalCache.get(path);
+            if (nestedProxies.has(path))
+                return nestedProxies.get(path);
+            if (value &&
+                typeof value === 'object' &&
+                !Array.isArray(value) &&
+                !isSignal(value) &&
+                !isBuiltInObject(value)) {
+                try {
+                    const nestedProxy = createLazySignalTree(value, equalityFn, path, memoryManager);
+                    nestedProxies.set(path, nestedProxy);
+                    const proxyWithCleanup = nestedProxy;
+                    if (typeof proxyWithCleanup.__cleanup__ === 'function') {
+                        nestedCleanups.set(path, proxyWithCleanup.__cleanup__);
+                    }
+                    return nestedProxy;
+                }
+                catch (error) {
+                    console.warn(`Failed to create lazy proxy for path "${path}":`, error);
+                    const fallbackSignal = signal(value, { equal: equalityFn });
+                    signalCache.set(path, fallbackSignal);
+                    // Cache in memory manager
+                    if (memoryManager) {
+                        memoryManager.cacheSignal(path, fallbackSignal);
+                    }
+                    return fallbackSignal;
+                }
+            }
+            try {
+                const newSignal = signal(value, { equal: equalityFn });
+                signalCache.set(path, newSignal);
+                // Cache in memory manager
+                if (memoryManager) {
+                    memoryManager.cacheSignal(path, newSignal);
+                }
+                return newSignal;
+            }
+            catch (error) {
+                console.warn(`Failed to create signal for path "${path}":`, error);
+                return value;
+            }
+        },
+        set(target, prop, value) {
+            if (typeof prop === 'symbol') {
+                target[prop] = value;
+                return true;
+            }
+            const key = prop;
+            const path = basePath ? `${basePath}.${key}` : key;
+            try {
+                target[key] = value;
+                const cachedSignal = signalCache.get(path);
+                if (cachedSignal && 'set' in cachedSignal) {
+                    cachedSignal.set(value);
+                }
+                if (nestedProxies.has(path)) {
+                    const nestedCleanup = nestedCleanups.get(path);
+                    if (nestedCleanup) {
+                        nestedCleanup();
+                        nestedCleanups.delete(path);
+                    }
+                    nestedProxies.delete(path);
+                }
+                return true;
+            }
+            catch (error) {
+                console.warn(`Failed to set value for path "${path}":`, error);
+                return false;
+            }
+        },
+        has(target, prop) {
+            return prop in target;
+        },
+        ownKeys(target) {
+            return Reflect.ownKeys(target);
+        },
+        getOwnPropertyDescriptor(target, prop) {
+            return Reflect.getOwnPropertyDescriptor(target, prop);
+        },
+    });
+    return proxy;
+}
+function unwrap(node) {
+    if (node === null || node === undefined) {
+        return node;
+    }
+    // Handle callable signals first
+    if (isNodeAccessor$1(node)) {
+        // For NodeAccessors, don't call them - read from their properties directly
+        // This prevents infinite recursion when NodeAccessor calls unwrap(accessor)
+        const result = {};
+        for (const key in node) {
+            if (!Object.prototype.hasOwnProperty.call(node, key))
+                continue;
+            // Skip function prototype properties only, not user properties
+            if (key === 'length' || key === 'prototype')
+                continue;
+            // Special handling for 'name' - if it's a signal or NodeAccessor, include it
+            if (key === 'name') {
+                const value = node[key];
+                if (!isSignal(value) && !isNodeAccessor$1(value)) {
+                    // Skip if it's just the function name property
+                    continue;
+                }
+            }
+            const value = node[key];
+            if (isNodeAccessor$1(value)) {
+                result[key] = unwrap(value);
+            }
+            else if (isSignal(value)) {
+                const unwrappedValue = value();
+                if (typeof unwrappedValue === 'object' &&
+                    unwrappedValue !== null &&
+                    !Array.isArray(unwrappedValue) &&
+                    !isBuiltInObject(unwrappedValue)) {
+                    result[key] = unwrap(unwrappedValue);
+                }
+                else {
+                    result[key] = unwrappedValue;
+                }
+            }
+            else if (typeof value === 'object' &&
+                value !== null &&
+                !Array.isArray(value) &&
+                !isBuiltInObject(value)) {
+                result[key] = unwrap(value);
+            }
+            else {
+                result[key] = value;
+            }
+        }
+        return result;
+    }
+    if (isSignal(node)) {
+        const value = node();
+        if (typeof value === 'object' &&
+            value !== null &&
+            !Array.isArray(value) &&
+            !isBuiltInObject(value)) {
+            return unwrap(value);
+        }
+        return value;
+    }
+    if (typeof node !== 'object') {
+        return node;
+    }
+    if (Array.isArray(node)) {
+        return node;
+    }
+    if (isBuiltInObject(node)) {
+        return node;
+    }
+    const result = {};
+    for (const key in node) {
+        if (!Object.prototype.hasOwnProperty.call(node, key))
+            continue;
+        if (key === 'set' || key === 'update') {
+            const v = node[key];
+            if (typeof v === 'function')
+                continue;
+        }
+        const value = node[key];
+        if (isNodeAccessor$1(value)) {
+            const unwrappedValue = value();
+            if (typeof unwrappedValue === 'object' &&
+                unwrappedValue !== null &&
+                !Array.isArray(unwrappedValue) &&
+                !isBuiltInObject(unwrappedValue)) {
+                result[key] = unwrap(unwrappedValue);
+            }
+            else {
+                result[key] = unwrappedValue;
+            }
+        }
+        else if (isSignal(value)) {
+            const unwrappedValue = value();
+            if (typeof unwrappedValue === 'object' &&
+                unwrappedValue !== null &&
+                !Array.isArray(unwrappedValue) &&
+                !isBuiltInObject(unwrappedValue)) {
+                result[key] = unwrap(unwrappedValue);
+            }
+            else {
+                result[key] = unwrappedValue;
+            }
+        }
+        else if (typeof value === 'object' &&
+            value !== null &&
+            !Array.isArray(value) &&
+            !isBuiltInObject(value)) {
+            result[key] = unwrap(value);
+        }
+        else {
+            result[key] = value;
+        }
+    }
+    const symbols = Object.getOwnPropertySymbols(node);
+    for (const sym of symbols) {
+        const value = node[sym];
+        if (isNodeAccessor$1(value)) {
+            const unwrappedValue = value();
+            if (typeof unwrappedValue === 'object' &&
+                unwrappedValue !== null &&
+                !Array.isArray(unwrappedValue) &&
+                !isBuiltInObject(unwrappedValue)) {
+                result[sym] = unwrap(unwrappedValue);
+            }
+            else {
+                result[sym] = unwrappedValue;
+            }
+        }
+        else if (isSignal(value)) {
+            const unwrappedValue = value();
+            if (typeof unwrappedValue === 'object' &&
+                unwrappedValue !== null &&
+                !Array.isArray(unwrappedValue) &&
+                !isBuiltInObject(unwrappedValue)) {
+                result[sym] = unwrap(unwrappedValue);
+            }
+            else {
+                result[sym] = unwrappedValue;
+            }
+        }
+        else if (typeof value === 'object' &&
+            value !== null &&
+            !Array.isArray(value) &&
+            !isBuiltInObject(value)) {
+            result[sym] = unwrap(value);
+        }
+        else {
+            result[sym] = value;
+        }
+    }
+    return result;
+}
+
+// Global symbol for NodeAccessor identification
+const NODE_ACCESSOR_SYMBOL = Symbol.for('NodeAccessor');
+// Note: Callable syntax is supported via optional build-time transform only.
+// No runtime Proxy wrapping is applied to writable signals to keep zero-cost semantics.
+/**
+ * Creates a callable NodeAccessor for nested objects WITHOUT a backing signal
+ * This accessor reads from and writes to child signals directly
+ */
+function makeNodeAccessor() {
+    const accessor = function (arg) {
+        if (arguments.length === 0) {
+            // Read from child signals - use the accessor itself as the context
+            return unwrap(accessor);
+        }
+        if (typeof arg === 'function') {
+            const updater = arg;
+            const currentValue = unwrap(accessor);
+            const newValue = updater(currentValue);
+            recursiveUpdate(accessor, newValue);
+        }
+        else {
+            // Direct set
+            recursiveUpdate(accessor, arg);
+        }
+    };
+    accessor[NODE_ACCESSOR_SYMBOL] = true;
+    return accessor;
+}
+/**
+ * Creates a NodeAccessor for the root tree that manages a backing signal
+ */
+function makeRootNodeAccessor(readSignal, writeSignal) {
+    const accessor = function (arg) {
+        if (arguments.length === 0) {
+            return readSignal();
+        }
+        if (typeof arg === 'function') {
+            const updater = arg;
+            writeSignal.set(updater(readSignal()));
+        }
+        else {
+            writeSignal.set(arg);
+        }
+    };
+    accessor[NODE_ACCESSOR_SYMBOL] = true;
+    return accessor;
+}
+function recursiveUpdate(target, updates) {
+    if (!updates || typeof updates !== 'object') {
+        return;
+    }
+    let targetObj;
+    // Handle NodeAccessor (function) as target
+    if (isNodeAccessor(target)) {
+        targetObj = target;
+    }
+    else if (target && typeof target === 'object') {
+        targetObj = target;
+    }
+    else {
+        return;
+    }
+    const updatesObj = updates;
+    for (const key in updatesObj) {
+        if (!(key in targetObj)) {
+            continue;
+        }
+        const targetProp = targetObj[key];
+        const updateValue = updatesObj[key];
+        if (isSignal(targetProp)) {
+            // Leaf signal - check if it's writable
+            if ('set' in targetProp && typeof targetProp.set === 'function') {
+                targetProp.set(updateValue);
+            }
+        }
+        else if (isNodeAccessor(targetProp)) {
+            // For nested objects, check if updateValue is an object for recursive update
+            if (updateValue && typeof updateValue === 'object') {
+                recursiveUpdate(targetProp, updateValue);
+            }
+            else {
+                // Direct value assignment
+                targetProp(updateValue);
+            }
+        }
+    }
+}
+/**
+ * Checks if a value is a NodeAccessor
+ */
+function isNodeAccessor(value) {
+    return (typeof value === 'function' &&
+        value &&
+        value[NODE_ACCESSOR_SYMBOL] === true);
+}
+// ============================================
+// PERFORMANCE HEURISTICS
+// ============================================
+function estimateObjectSize(obj, maxDepth = SIGNAL_TREE_CONSTANTS.ESTIMATE_MAX_DEPTH, currentDepth = 0) {
+    if (currentDepth >= maxDepth)
+        return 1;
+    if (obj === null || obj === undefined)
+        return 0;
+    if (typeof obj !== 'object')
+        return 1;
+    let size = 0;
+    try {
+        if (Array.isArray(obj)) {
+            size = obj.length;
+            const sampleSize = Math.min(SIGNAL_TREE_CONSTANTS.ESTIMATE_SAMPLE_SIZE_ARRAY, obj.length);
+            for (let i = 0; i < sampleSize; i++) {
+                size += estimateObjectSize(obj[i], maxDepth, currentDepth + 1) * 0.1;
+            }
+        }
+        else {
+            const keys = Object.keys(obj);
+            size = keys.length;
+            const sampleSize = Math.min(SIGNAL_TREE_CONSTANTS.ESTIMATE_SAMPLE_SIZE_OBJECT, keys.length);
+            for (let i = 0; i < sampleSize; i++) {
+                const value = obj[keys[i]];
+                size += estimateObjectSize(value, maxDepth, currentDepth + 1) * 0.5;
+            }
+        }
+    }
+    catch {
+        return 1;
+    }
+    return Math.floor(size);
+}
+function shouldUseLazy(obj, config, precomputedSize) {
+    if (config.useLazySignals !== undefined)
+        return config.useLazySignals;
+    if (config.debugMode || config.enableDevTools)
+        return false;
+    if (config.batchUpdates && config.useMemoization)
+        return true;
+    const estimatedSize = precomputedSize ?? estimateObjectSize(obj);
+    return estimatedSize > SIGNAL_TREE_CONSTANTS.LAZY_THRESHOLD;
+}
+// ============================================
+// SECURITY VALIDATION
+// ============================================
+/**
+ * Validates an object tree using SecurityValidator if configured
+ * Throws if validation fails
+ */
+function validateTree(obj, config, path = []) {
+    if (!config.security) {
+        return; // No validation needed
+    }
+    const validator = new SecurityValidator(config.security);
+    function validate(value, currentPath) {
+        // Validate primitives and null/undefined
+        if (value === null || value === undefined) {
+            return;
+        }
+        if (typeof value !== 'object') {
+            // Validate the value (this will catch functions)
+            validator.validateValue(value);
+            return;
+        }
+        // Skip built-in objects
+        if (isBuiltInObject(value)) {
+            return;
+        }
+        // Validate arrays
+        if (Array.isArray(value)) {
+            value.forEach((item, index) => {
+                validate(item, [...currentPath, String(index)]);
+            });
+            return;
+        }
+        // Validate object keys and values
+        // Use Reflect.ownKeys to catch all keys including __proto__
+        const keys = [
+            ...Object.keys(value),
+            ...Object.getOwnPropertyNames(value),
+        ];
+        const uniqueKeys = [...new Set(keys)];
+        for (const key of uniqueKeys) {
+            if (typeof key === 'symbol')
+                continue;
+            // Validate the key
+            try {
+                validator.validateKey(key);
+            }
+            catch (error) {
+                const err = error;
+                throw new Error(`${err.message}\nPath: ${[...currentPath, key].join('.')}`);
+            }
+            // Get the value
+            const val = value[key];
+            // Validate the value
+            try {
+                validator.validateValue(val);
+            }
+            catch (error) {
+                const err = error;
+                throw new Error(`${err.message}\nPath: ${[...currentPath, key].join('.')}`);
+            }
+            // Recursively validate nested objects
+            validate(val, [...currentPath, key]);
+        }
+    }
+    validate(obj, path);
+}
+function createEqualityFn(useShallowComparison) {
+    return useShallowComparison ? Object.is : deepEqual;
+}
+// ============================================
+// SIGNAL CREATION
+// ============================================
+function createSignalStore(obj, equalityFn) {
+    if (obj === null || obj === undefined || typeof obj !== 'object') {
+        return signal(obj, { equal: equalityFn });
+    }
+    if (Array.isArray(obj)) {
+        return signal(obj, { equal: equalityFn });
+    }
+    if (isBuiltInObject(obj)) {
+        return signal(obj, { equal: equalityFn });
+    }
+    const store = {};
+    const processedObjects = new WeakSet();
+    if (processedObjects.has(obj)) {
+        console.warn(SIGNAL_TREE_MESSAGES.CIRCULAR_REF);
+        return signal(obj, { equal: equalityFn });
+    }
+    processedObjects.add(obj);
+    try {
+        for (const [key, value] of Object.entries(obj)) {
+            try {
+                if (typeof key === 'symbol')
+                    continue;
+                if (isSignal(value)) {
+                    // Preserve existing signals as-is
+                    store[key] = value;
+                    continue;
+                }
+                if (value === null || value === undefined) {
+                    store[key] = signal(value, {
+                        equal: equalityFn,
+                    });
+                }
+                else if (typeof value !== 'object') {
+                    store[key] = signal(value, {
+                        equal: equalityFn,
+                    });
+                }
+                else if (Array.isArray(value) || isBuiltInObject(value)) {
+                    store[key] = signal(value, {
+                        equal: equalityFn,
+                    });
+                }
+                else {
+                    // Nested object - create recursive structure
+                    const branch = createSignalStore(value, equalityFn);
+                    // Create a NodeAccessor for this nested object (no backing signal)
+                    const callableBranch = makeNodeAccessor();
+                    // Copy all the nested signal properties onto the callable branch
+                    for (const branchKey in branch) {
+                        if (Object.prototype.hasOwnProperty.call(branch, branchKey)) {
+                            try {
+                                Object.defineProperty(callableBranch, branchKey, {
+                                    value: branch[branchKey],
+                                    enumerable: true,
+                                    configurable: true,
+                                });
+                            }
+                            catch {
+                                // Skip if property can't be defined
+                            }
+                        }
+                    }
+                    store[key] = callableBranch;
+                }
+            }
+            catch (error) {
+                console.warn(`${SIGNAL_TREE_MESSAGES.SIGNAL_CREATION_FAILED} "${key}":`, error);
+                store[key] = signal(value, {
+                    equal: equalityFn,
+                });
+            }
+        }
+        const symbols = Object.getOwnPropertySymbols(obj);
+        for (const sym of symbols) {
+            const value = obj[sym];
+            try {
+                if (isSignal(value)) {
+                    store[sym] = value;
+                }
+                else {
+                    store[sym] = signal(value, {
+                        equal: equalityFn,
+                    });
+                }
+            }
+            catch (error) {
+                console.warn(SIGNAL_TREE_MESSAGES.SIGNAL_CREATION_FAILED, error);
+            }
+        }
+    }
+    catch (error) {
+        throw new Error(`Failed to create signal store: ${error instanceof Error ? error.message : 'Unknown error'}`);
+    }
+    return store;
+}
+// ============================================
+// TREE ENHANCEMENT
+// ============================================
+function enhanceTree(tree, config = {}) {
+    const isLazy = config.useLazySignals ?? shouldUseLazy(tree.state, config);
+    // with() enhancer composition
+    tree.with = ((...enhancers) => {
+        if (enhancers.length === 0) {
+            return tree;
+        }
+        const coreCapabilities = new Set();
+        if (config.batchUpdates)
+            coreCapabilities.add('batchUpdate');
+        if (config.useMemoization)
+            coreCapabilities.add('memoize');
+        if (config.enableTimeTravel)
+            coreCapabilities.add('undo');
+        if (config.enableDevTools)
+            coreCapabilities.add('connectDevTools');
+        try {
+            for (const key of Object.keys(tree))
+                coreCapabilities.add(String(key));
+        }
+        catch {
+            // Ignore reflection issues
+        }
+        const hasMetadata = enhancers.some((e) => Boolean(e.metadata && (e.metadata.requires || e.metadata.provides)));
+        let orderedEnhancers = enhancers;
+        if (hasMetadata) {
+            try {
+                orderedEnhancers = resolveEnhancerOrder(enhancers, coreCapabilities, config.debugMode);
+            }
+            catch (err) {
+                console.warn(SIGNAL_TREE_MESSAGES.ENHANCER_ORDER_FAILED, err);
+            }
+        }
+        const provided = new Set(coreCapabilities);
+        let currentTree = tree;
+        for (let i = 0; i < orderedEnhancers.length; i++) {
+            const enhancer = orderedEnhancers[i];
+            if (typeof enhancer !== 'function') {
+                throw new Error(SIGNAL_TREE_MESSAGES.ENHANCER_NOT_FUNCTION.replace('%d', String(i)));
+            }
+            const reqs = enhancer.metadata?.requires ?? [];
+            for (const r of reqs) {
+                if (!(r in currentTree) && !provided.has(r)) {
+                    const name = enhancer.metadata?.name ?? `enhancer#${i}`;
+                    const msg = SIGNAL_TREE_MESSAGES.ENHANCER_REQUIREMENT_MISSING.replace('%s', name).replace('%s', r);
+                    if (config.debugMode) {
+                        throw new Error(msg);
+                    }
+                    else {
+                        console.warn(msg);
+                    }
+                }
+            }
+            try {
+                const result = enhancer(currentTree);
+                if (result !== currentTree)
+                    currentTree = result;
+                const provs = enhancer.metadata?.provides ?? [];
+                for (const p of provs)
+                    provided.add(p);
+                if (config.debugMode && provs.length > 0) {
+                    for (const p of provs) {
+                        if (!(p in currentTree)) {
+                            console.warn(SIGNAL_TREE_MESSAGES.ENHANCER_PROVIDES_MISSING.replace('%s', enhancer.metadata?.name ?? String(i)).replace('%s', p));
+                        }
+                    }
+                }
+            }
+            catch (error) {
+                const name = enhancer.metadata?.name || `enhancer at index ${i}`;
+                console.error(SIGNAL_TREE_MESSAGES.ENHANCER_FAILED.replace('%s', name), error);
+                if (config.debugMode) {
+                    console.error('[SignalTree] Enhancer stack trace:', enhancer);
+                    console.error('[SignalTree] Tree state at failure:', currentTree);
+                }
+                throw error;
+            }
+        }
+        return currentTree;
+    });
+    // destroy unchanged
+    tree.destroy = () => {
+        try {
+            if (isLazy) {
+                const state = tree.state;
+                if (state && typeof state === 'object' && '__cleanup__' in state) {
+                    const cleanup = state.__cleanup__;
+                    if (typeof cleanup === 'function') {
+                        cleanup();
+                    }
+                }
+            }
+            if (config.debugMode) {
+                console.log(SIGNAL_TREE_MESSAGES.TREE_DESTROYED);
+            }
+        }
+        catch (error) {
+            console.error(SIGNAL_TREE_MESSAGES.CLEANUP_ERROR, error);
+        }
+    };
+    // Add stub implementations for advanced features
+    addStubMethods(tree, config);
+    return tree;
+}
+function addStubMethods(tree, config) {
+    tree.batchUpdate = (updater) => {
+        console.warn(SIGNAL_TREE_MESSAGES.BATCH_NOT_ENABLED);
+        tree((current) => {
+            const partial = updater(current);
+            return { ...current, ...partial };
+        });
+    };
+    tree.memoize = (fn, cacheKey) => {
+        console.warn(SIGNAL_TREE_MESSAGES.MEMOIZE_NOT_ENABLED);
+        return computed(() => fn(tree()));
+    };
+    // Memoization helper stubs (overridden by withMemoization)
+    tree.memoizedUpdate = (updater) => {
+        if (config.debugMode) {
+            console.warn(SIGNAL_TREE_MESSAGES.MEMOIZE_NOT_ENABLED);
+        }
+        // Fallback: apply the update without caching
+        tree((current) => ({ ...current, ...updater(current) }));
+    };
+    tree.clearMemoCache = () => {
+        if (config.debugMode) {
+            console.warn(SIGNAL_TREE_MESSAGES.MEMOIZE_NOT_ENABLED);
+        }
+        // no-op
+    };
+    tree.getCacheStats = () => ({
+        size: 0,
+        hitRate: 0,
+        totalHits: 0,
+        totalMisses: 0,
+        keys: [],
+    });
+    // Memoization helper methods are only present when withMemoization is applied
+    tree.effect = (fn) => {
+        try {
+            effect(() => fn(tree()));
+        }
+        catch (error) {
+            if (config.debugMode) {
+                console.warn(SIGNAL_TREE_MESSAGES.EFFECT_NO_CONTEXT, error);
+            }
+        }
+    };
+    tree.subscribe = (fn) => {
+        try {
+            const destroyRef = inject(DestroyRef);
+            let isDestroyed = false;
+            const effectRef = effect(() => {
+                if (!isDestroyed) {
+                    fn(tree());
+                }
+            });
+            const unsubscribe = () => {
+                isDestroyed = true;
+                effectRef.destroy();
+            };
+            destroyRef.onDestroy(unsubscribe);
+            return unsubscribe;
+        }
+        catch (error) {
+            if (config.debugMode) {
+                console.warn(SIGNAL_TREE_MESSAGES.SUBSCRIBE_NO_CONTEXT, error);
+            }
+            fn(tree());
+            return () => {
+                // No-op
+            };
+        }
+    };
+    // Performance stubs
+    tree.optimize = () => {
+        if (config.debugMode) {
+            console.warn(SIGNAL_TREE_MESSAGES.OPTIMIZE_NOT_AVAILABLE);
+        }
+    };
+    tree.clearCache = () => {
+        if (config.debugMode) {
+            console.warn(SIGNAL_TREE_MESSAGES.CACHE_NOT_AVAILABLE);
+        }
+    };
+    tree.invalidatePattern = () => {
+        if (config.debugMode) {
+            console.warn(SIGNAL_TREE_MESSAGES.PERFORMANCE_NOT_ENABLED);
+        }
+        return 0;
+    };
+    // Initialize optimized update engine
+    const treeWithEngine = tree;
+    if (!treeWithEngine.updateEngine) {
+        treeWithEngine.updateEngine = new OptimizedUpdateEngine(tree);
+    }
+    tree.updateOptimized = (updates, options = {}) => {
+        const treeWithEngine = tree;
+        const engine = treeWithEngine.updateEngine;
+        if (!engine) {
+            // Fallback to basic update
+            if (config.debugMode) {
+                console.warn(SIGNAL_TREE_MESSAGES.UPDATE_OPTIMIZED_NOT_AVAILABLE);
+            }
+            tree((current) => ({ ...current, ...updates }));
+            return {
+                changed: true,
+                duration: 0,
+                changedPaths: Object.keys(updates),
+                stats: undefined,
+            };
+        }
+        return engine.update(tree(), updates, options);
+    };
+    tree.getMetrics = () => {
+        return {
+            updates: 0,
+            computations: 0,
+            cacheHits: 0,
+            cacheMisses: 0,
+            averageUpdateTime: 0,
+        };
+    };
+    // Middleware stubs
+    tree.addTap = (middleware) => {
+        if (config.debugMode) {
+            console.warn(SIGNAL_TREE_MESSAGES.MIDDLEWARE_NOT_AVAILABLE);
+        }
+    };
+    tree.removeTap = (id) => {
+        if (config.debugMode) {
+            console.warn(SIGNAL_TREE_MESSAGES.MIDDLEWARE_NOT_AVAILABLE);
+        }
+    };
+    // Entity helpers stub
+    tree.entities = () => {
+        if (config.debugMode) {
+            console.warn(SIGNAL_TREE_MESSAGES.ENTITY_HELPERS_NOT_AVAILABLE);
+        }
+        return {};
+    };
+    // Async action stub
+    tree.asyncAction = (operation, asyncConfig = {}) => {
+        if (config.debugMode) {
+            console.warn(SIGNAL_TREE_MESSAGES.ASYNC_ACTIONS_NOT_AVAILABLE);
+        }
+        return {};
+    };
+    // Time travel stubs
+    tree.undo = () => {
+        if (config.debugMode) {
+            console.warn(SIGNAL_TREE_MESSAGES.TIME_TRAVEL_NOT_AVAILABLE);
+        }
+    };
+    tree.redo = () => {
+        if (config.debugMode) {
+            console.warn(SIGNAL_TREE_MESSAGES.TIME_TRAVEL_NOT_AVAILABLE);
+        }
+    };
+    tree.getHistory = () => {
+        if (config.debugMode) {
+            console.warn(SIGNAL_TREE_MESSAGES.TIME_TRAVEL_NOT_AVAILABLE);
+        }
+        return [];
+    };
+    tree.resetHistory = () => {
+        if (config.debugMode) {
+            console.warn(SIGNAL_TREE_MESSAGES.TIME_TRAVEL_NOT_AVAILABLE);
+        }
+    };
+}
+// ============================================
+// CORE CREATION FUNCTION
+// ============================================
+function create(obj, config = {}) {
+    if (obj === null || obj === undefined) {
+        throw new Error(SIGNAL_TREE_MESSAGES.NULL_OR_UNDEFINED);
+    }
+    // Validate the tree if security is configured
+    validateTree(obj, config);
+    const estimatedSize = estimateObjectSize(obj);
+    const equalityFn = createEqualityFn(config.useShallowComparison ?? false);
+    // ARRAY ROOT MODE: arrays are treated as single signals
+    if (Array.isArray(obj)) {
+        const signalState = signal(obj, {
+            equal: equalityFn,
+        });
+        const tree = makeRootNodeAccessor(signalState, signalState);
+        // Add state and $ properties that reference the signal itself
+        Object.defineProperty(tree, 'state', {
+            value: signalState,
+            enumerable: false,
+        });
+        Object.defineProperty(tree, '$', { value: signalState, enumerable: false });
+        enhanceTree(tree, config);
+        return tree;
+    }
+    const useLazy = shouldUseLazy(obj, config, estimatedSize);
+    if (config.debugMode) {
+        console.log(SIGNAL_TREE_MESSAGES.STRATEGY_SELECTION.replace('%s', useLazy ? 'lazy' : 'eager').replace('%d', String(estimatedSize)));
+    }
+    let signalState;
+    let memoryManager;
+    try {
+        if (useLazy && typeof obj === 'object') {
+            memoryManager = new SignalMemoryManager();
+            signalState = createLazySignalTree(obj, equalityFn, '', // basePath
+            memoryManager);
+        }
+        else {
+            signalState = createSignalStore(obj, equalityFn);
+        }
+    }
+    catch (error) {
+        if (useLazy) {
+            console.warn(SIGNAL_TREE_MESSAGES.LAZY_FALLBACK, error);
+            signalState = createSignalStore(obj, equalityFn);
+            memoryManager = undefined; // Reset memory manager on fallback
+        }
+        else {
+            throw error;
+        }
+    }
+    // Create callable tree function for the root
+    const tree = function (arg) {
+        if (arguments.length === 0) {
+            return unwrap(signalState);
+        }
+        if (typeof arg === 'function') {
+            const updater = arg;
+            const currentValue = unwrap(signalState);
+            const newValue = updater(currentValue);
+            // Use recursive update to preserve signals
+            recursiveUpdate(signalState, newValue);
+        }
+        else {
+            // Direct set - use recursive update
+            recursiveUpdate(signalState, arg);
+        }
+    };
+    // Mark as NodeAccessor
+    Object.defineProperty(tree, NODE_ACCESSOR_SYMBOL, {
+        value: true,
+        enumerable: false,
+    });
+    // Add state and $ properties first (these are safe)
+    Object.defineProperty(tree, 'state', {
+        value: signalState,
+        enumerable: false,
+    });
+    Object.defineProperty(tree, '$', { value: signalState, enumerable: false });
+    // Add dispose() method for manual cleanup when using lazy signals (stub)
+    if (memoryManager) {
+        Object.defineProperty(tree, 'dispose', {
+            value: () => {
+                memoryManager?.dispose();
+                const cleanup = signalState.__cleanup__;
+                if (typeof cleanup === 'function') {
+                    cleanup();
+                }
+            },
+            enumerable: false,
+            writable: false,
+        });
+    }
+    // Enhance tree with methods
+    enhanceTree(tree, config);
+    // Attach signal state properties to the tree AFTER enhancement
+    // This prevents conflicts with built-in methods
+    for (const key in signalState) {
+        if (Object.prototype.hasOwnProperty.call(signalState, key)) {
+            // Skip if the property already exists (from enhancement)
+            if (!(key in tree)) {
+                try {
+                    Object.defineProperty(tree, key, {
+                        value: signalState[key],
+                        enumerable: true,
+                        configurable: true,
+                    });
+                }
+                catch {
+                    // Skip if property can't be defined
+                }
+            }
+        }
+    }
+    return tree;
+}
+// ============================================
+// PRESET CONFIGURATIONS
+// ============================================
+const presetConfigs = {
+    basic: {
+        useLazySignals: false,
+        debugMode: false,
+    },
+    performance: {
+        useLazySignals: true,
+        batchUpdates: true,
+        useMemoization: true,
+        useShallowComparison: true,
+    },
+    development: {
+        useLazySignals: false,
+        debugMode: true,
+        enableDevTools: true,
+        trackPerformance: true,
+    },
+    production: {
+        useLazySignals: true,
+        batchUpdates: true,
+        useMemoization: true,
+        debugMode: false,
+    },
+};
+function signalTree(obj, configOrPreset) {
+    if (typeof configOrPreset === 'string') {
+        const config = presetConfigs[configOrPreset];
+        if (!config) {
+            console.warn(SIGNAL_TREE_MESSAGES.PRESET_UNKNOWN.replace('%s', configOrPreset));
+            return create(obj, {});
+        }
+        return create(obj, config);
+    }
+    const config = configOrPreset || {};
+    return create(obj, config);
+}
+
+/** Global queue for batched updates awaiting processing */
+let updateQueue = [];
+/** Flag to prevent recursive batch processing */
+let isUpdating = false;
+/** Timeout ID for scheduled flush operations */
+let flushTimeoutId;
+/** Current batching configuration */
+let currentBatchingConfig = {};
+/**
+ * Enhanced queue management with priority and deduplication
+ * Returns true if queue was flushed immediately, false if scheduled for later
+ */
+function addToQueue(update, config = currentBatchingConfig) {
+    const maxSize = config.maxBatchSize ?? 100;
+    // Remove duplicates based on path if available
+    if (update.path) {
+        updateQueue = updateQueue.filter((existing) => existing.path !== update.path);
+    }
+    updateQueue.push(update);
+    // Check if we should flush immediately due to maxBatchSize
+    // Flush when we exceed maxBatchSize, not when we reach it
+    if (updateQueue.length > maxSize) {
+        // Flush immediately when max batch size is exceeded
+        flushUpdates();
+        return true; // Indicate that queue was flushed
+    }
+    // Schedule auto-flush if not already scheduled
+    scheduleFlush(config);
+    return false; // Indicate that queue was scheduled for later
+}
+/**
+ * Schedules automatic queue flushing with configurable timing
+ */
+function scheduleFlush(config) {
+    if (flushTimeoutId !== undefined) {
+        clearTimeout(flushTimeoutId);
+    }
+    const delay = config.autoFlushDelay ?? 16; // Default to 60fps
+    flushTimeoutId = setTimeout(() => {
+        flushUpdates();
+    }, delay);
+}
+/**
+ * Processes the update queue immediately with race condition protection.
+ * Handles updates that arrive during flush execution.
+ */
+function flushUpdates() {
+    if (isUpdating)
+        return;
+    let queue;
+    do {
+        if (updateQueue.length === 0)
+            return;
+        isUpdating = true;
+        queue = updateQueue;
+        updateQueue = []; // Clear queue atomically
+        // Clear any pending flush timeout
+        if (flushTimeoutId !== undefined) {
+            clearTimeout(flushTimeoutId);
+            flushTimeoutId = undefined;
+        }
+        // Sort by depth (deepest first) for optimal update propagation
+        queue.sort((a, b) => (b.depth ?? 0) - (a.depth ?? 0));
+        try {
+            queue.forEach(({ fn }) => fn());
+        }
+        finally {
+            isUpdating = false;
+        }
+        // Process any updates that were added during flush
+    } while (updateQueue.length > 0);
+}
+/**
+ * Core batching function that intelligently queues updates and processes them in optimized microtasks.
+ * Updates are sorted by depth (deepest first) for optimal update propagation and minimal re-computations.
+ *
+ * @param fn - The update function to batch
+ * @param path - Optional state path for update grouping and optimization
+ *
+ * @example
+ * ```typescript
+ * // Simple batched update
+ * batchUpdates(() => tree.update(() => ({ count: 1 })));
+ *
+ * // Path-aware batching for nested updates
+ * batchUpdates(() => tree.update(() => ({ user: { name: 'John' } })), 'user.name');
+ *
+ * // Multiple updates get automatically batched
+ * batchUpdates(() => tree.update(() => ({ loading: true })));
+ * batchUpdates(() => tree.update(() => ({ error: null })));
+ * // Both execute in single microtask
+ * ```
+ */
+function batchUpdates(fn, path) {
+    const startTime = performance.now();
+    const depth = 0;
+    const update = { fn, startTime, depth, path };
+    // Use enhanced queue management
+    const wasFlushed = addToQueue(update, currentBatchingConfig);
+    // Only schedule additional flush if queue wasn't already flushed
+    if (!wasFlushed) {
+        // Check if we need to process immediately due to timeout
+        const isTimedOut = currentBatchingConfig.batchTimeoutMs &&
+            updateQueue.length > 0 &&
+            startTime - updateQueue[0].startTime >=
+                currentBatchingConfig.batchTimeoutMs;
+        if (isTimedOut) {
+            flushUpdates();
+        }
+        else if (!isUpdating && updateQueue.length > 0) {
+            // Schedule flush but don't set isUpdating until the microtask runs
+            queueMicrotask(() => {
+                flushUpdates();
+            });
+        }
+    }
+}
+/**
+ * Enhances a SignalTree with intelligent batching capabilities for optimal performance.
+ * Automatically groups rapid state updates into efficient batch cycles to eliminate UI thrashing.
+ *
+ * @template T - The state object type extending StateObject
+ * @param config - Configuration options for batching behavior
+ * @returns Function that enhances a SignalTree with batching capabilities
+ *
+ * @example
+ * ```typescript
+ * // Basic batching with default settings
+ * const tree = create(initialState).with(withBatching());
+ *
+ * // High-performance batching for demanding applications
+ * const tree = create(initialState).with(withBatching({
+ *   maxBatchSize: 50,
+ *   autoFlushDelay: 8, // ~120fps
+ *   batchTimeoutMs: 50
+ * }));
+ *
+ * // Conservative batching for stable UIs
+ * const tree = create(initialState).with(withBatching({
+ *   maxBatchSize: 10,
+ *   autoFlushDelay: 100,
+ *   batchTimeoutMs: 200
+ * }));
+ *
+ * // Use batching methods
+ * tree.batchUpdate((state) => ({
+ *   users: [...state.users, newUser],
+ *   loading: false,
+ *   error: null
+ * }));
+ * Uses unconstrained recursive typing - no limitations on T
+ * ```
+ */
+function withBatching(config = {}) {
+    const { enabled = true } = config;
+    // Update global config for this batching instance
+    currentBatchingConfig = { ...currentBatchingConfig, ...config };
+    return (tree) => {
+        if (!enabled) {
+            return tree;
+        }
+        // Store the original callable tree function
+        const originalTreeCall = tree.bind(tree);
+        // Create enhanced tree function that batches update operations
+        const enhancedTree = function (...args) {
+            if (args.length === 0) {
+                // Get operation - call original directly
+                return originalTreeCall();
+            }
+            else {
+                // Set or update operation - batch it
+                batchUpdates(() => {
+                    if (args.length === 1) {
+                        const arg = args[0];
+                        if (typeof arg === 'function') {
+                            originalTreeCall(arg);
+                        }
+                        else {
+                            originalTreeCall(arg);
+                        }
+                    }
+                });
+            }
+        };
+        // Copy all properties and methods from original tree
+        Object.setPrototypeOf(enhancedTree, Object.getPrototypeOf(tree));
+        Object.assign(enhancedTree, tree);
+        // Ensure state and $ properties are preserved
+        if ('state' in tree) {
+            Object.defineProperty(enhancedTree, 'state', {
+                value: tree.state,
+                enumerable: false,
+                configurable: true,
+            });
+        }
+        // Ensure $ alias is preserved
+        if ('$' in tree) {
+            Object.defineProperty(enhancedTree, '$', {
+                value: tree['$'],
+                enumerable: false,
+                configurable: true,
+            });
+        }
+        // Replace the stub batchUpdate method with actual batching logic
+        enhancedTree.batchUpdate = (updater) => {
+            batchUpdates(() => {
+                const current = originalTreeCall();
+                const updates = updater(current);
+                // Apply updates to individual properties
+                Object.entries(updates).forEach(([key, value]) => {
+                    const property = enhancedTree.state[key];
+                    if (property && 'set' in property) {
+                        // It's a WritableSignal - use .set()
+                        property.set(value);
+                    }
+                    else if (isNodeAccessor$1(property)) {
+                        // It's a NodeAccessor - use callable syntax
+                        property(value);
+                    }
+                });
+            });
+        };
+        return enhancedTree;
+    };
+}
+/**
+ * Convenience function to enable batching with default settings.
+ * Equivalent to withBatching({ enabled: true }) but more concise for common usage.
+ *
+ * @template T - The state object type extending StateObject
+ * @returns Function that enhances a SignalTree with default batching settings
+ *
+ * @example
+ * ```typescript
+ * // Simple batching enablement
+ * const tree = create(initialState).with(enableBatching());
+ *
+ * // Equivalent to:
+ * const tree = create(initialState).with(withBatching({ enabled: true }));
+ * Uses unconstrained recursive typing - no limitations on T
+ * ```
+ */
+/**
+ * Creates high-performance batching configuration optimized for demanding applications.
+ * Uses aggressive batching settings for maximum performance in high-frequency update scenarios.
+ * Uses unconstrained recursive typing - no limitations on T
+ *
+ * @template T - The state object type extending StateObject
+ * @returns Function that enhances a SignalTree with high-performance batching
+ *
+ * @example
+ * ```typescript
+ * // For performance-critical applications
+ * const gameTree = create(gameState).with(withHighPerformanceBatching());
+ *
+ * // Perfect for:
+ * // - Real-time games
+ * // - High-frequency data updates
+ * // - Animation-heavy UIs
+ * // - Large dataset operations
+ *
+ * // Automatically includes:
+ * // - Large batch sizes (200 updates)
+ * // - Immediate processing (0ms timeout)
+ * // - Aggressive optimization
+ * Uses unconstrained recursive typing - no limitations on T
+ * ```
+ */
+function withHighPerformanceBatching() {
+    return withBatching({
+        enabled: true,
+        maxBatchSize: 200,
+        batchTimeoutMs: 0,
+    });
+}
+/**
+ * Manually flushes all pending batched updates immediately.
+ * Forces synchronous execution of queued updates, bypassing normal batching delays.
+ * Useful for testing scenarios or when immediate state consistency is required.
+ *
+ * @example
+ * ```typescript
+ * // Queue some updates
+ * tree.batchUpdate(() => ({ count: 1 }));
+ * tree.batchUpdate(() => ({ name: 'test' }));
+ *
+ * // In tests, ensure updates are applied immediately
+ * flushBatchedUpdates();
+ * expect(tree().count).toBe(1);
+ * expect(tree().name).toBe('test');
+ *
+ * // Before critical operations that need current state
+ * flushBatchedUpdates();
+ * const currentState = tree(); // Guaranteed to be up-to-date
+ *
+ * // In animation frames for precise timing
+ * requestAnimationFrame(() => {
+ *   flushBatchedUpdates(); // Ensure updates are applied before render
+ *   updateUI();
+ * });
+ * ```
+ */
+function flushBatchedUpdates() {
+    if (updateQueue.length > 0) {
+        // Force flush regardless of isUpdating state
+        const queue = updateQueue.slice();
+        updateQueue = [];
+        isUpdating = false; // Reset the updating flag
+        // Sort by depth (deepest first) for optimal update propagation
+        queue.sort((a, b) => (b.depth ?? 0) - (a.depth ?? 0));
+        queue.forEach(({ fn }) => {
+            fn();
+        });
+    }
+}
+/**
+ * Checks if there are pending batched updates waiting to be processed.
+ * Useful for testing, debugging, or conditional logic based on update queue state.
+ *
+ * @returns True if updates are queued, false if queue is empty
+ *
+ * @example
+ * ```typescript
+ * // Check before critical operations
+ * tree.batchUpdate(() => ({ loading: true }));
+ *
+ * if (hasPendingUpdates()) {
+ *   console.log('Updates are queued for processing');
+ *   flushBatchedUpdates(); // Process them now if needed
+ * }
+ *
+ * // In testing
+ * tree.batchUpdate(() => ({ count: 1 }));
+ * expect(hasPendingUpdates()).toBe(true);
+ *
+ * flushBatchedUpdates();
+ * expect(hasPendingUpdates()).toBe(false);
+ *
+ * // Conditional behavior
+ * function performCriticalOperation() {
+ *   if (hasPendingUpdates()) {
+ *     flushBatchedUpdates(); // Ensure consistent state
+ *   }
+ *   // Proceed with operation
+ * }
+ * ```
+ */
+function hasPendingUpdates() {
+    return updateQueue.length > 0;
+}
+/**
+ * Gets the current number of updates waiting in the batch queue.
+ * Useful for performance monitoring, debugging, and batch size optimization.
+ *
+ * @returns Number of queued updates
+ *
+ * @example
+ * ```typescript
+ * // Performance monitoring
+ * function monitorBatchPerformance() {
+ *   const queueSize = getBatchQueueSize();
+ *
+ *   if (queueSize > 50) {
+ *     console.warn(`Large batch queue detected: ${queueSize} updates`);
+ *   }
+ *
+ *   // Log metrics
+ *   console.log(`Current queue size: ${queueSize}`);
+ * }
+ *
+ * // Debug batching behavior
+ * tree.batchUpdate(() => ({ a: 1 }));
+ * tree.batchUpdate(() => ({ b: 2 }));
+ * tree.batchUpdate(() => ({ c: 3 }));
+ *
+ * console.log(`Queue size: ${getBatchQueueSize()}`); // 3
+ *
+ * flushBatchedUpdates();
+ * console.log(`Queue size after flush: ${getBatchQueueSize()}`); // 0
+ *
+ * // Optimize batch configuration
+ * const currentQueueSize = getBatchQueueSize();
+ * if (currentQueueSize > 100) {
+ *   // Consider reducing maxBatchSize or autoFlushDelay
+ *   console.log('Consider optimizing batch configuration');
+ * }
+ * ```
+ */
+function getBatchQueueSize() {
+    return updateQueue.length;
+}
+
+// Global memoization cache with size limits and TTL
+const MAX_CACHE_SIZE = 1000;
+const DEFAULT_TTL = 5 * 60 * 1000; // 5 minutes
+// Use Map for global cache management (we keep iteration for diagnostics).
+// Note: we avoid starting any global timers at module import to prevent
+// background timer leaks in long-running processes; cleanup is performed
+// opportunistically inside hot paths (probabilistic) or via explicit APIs.
+const memoizationCache = new Map();
+function createMemoCacheStore(maxSize, enableLRU) {
+    if (enableLRU) {
+        const cache = new LRUCache(maxSize);
+        const shadow = new Map();
+        const pruneShadow = () => {
+            while (shadow.size > cache.size()) {
+                const oldestKey = shadow.keys().next().value;
+                if (oldestKey === undefined) {
+                    break;
+                }
+                shadow.delete(oldestKey);
+            }
+        };
+        return {
+            get: (key) => {
+                const value = cache.get(key);
+                if (value !== undefined) {
+                    shadow.set(key, value);
+                }
+                else if (shadow.has(key)) {
+                    shadow.delete(key);
+                }
+                return value;
+            },
+            set: (key, value) => {
+                cache.set(key, value);
+                shadow.set(key, value);
+                pruneShadow();
+            },
+            delete: (key) => {
+                cache.delete(key);
+                shadow.delete(key);
+            },
+            clear: () => {
+                cache.clear();
+                shadow.clear();
+            },
+            size: () => shadow.size,
+            forEach: (callback) => {
+                shadow.forEach((value, key) => callback(value, key));
+            },
+            keys: () => shadow.keys(),
+        };
+    }
+    const store = new Map();
+    return {
+        get: (key) => store.get(key),
+        set: (key, value) => {
+            store.set(key, value);
+        },
+        delete: (key) => store.delete(key),
+        clear: () => store.clear(),
+        size: () => store.size,
+        forEach: (callback) => {
+            store.forEach((value, key) => callback(value, key));
+        },
+        keys: () => store.keys(),
+    };
+}
+function getCleanupInterval(tree) {
+    return tree._memoCleanupInterval;
+}
+function setCleanupInterval(tree, interval) {
+    if (interval === undefined) {
+        delete tree._memoCleanupInterval;
+        return;
+    }
+    tree._memoCleanupInterval = interval;
+}
+function clearCleanupInterval(tree) {
+    const interval = getCleanupInterval(tree);
+    if (!interval) {
+        return;
+    }
+    try {
+        clearInterval(interval);
+    }
+    catch {
+        /* best-effort cleanup */
+    }
+    setCleanupInterval(tree);
+}
+function resetMemoizationCaches() {
+    memoizationCache.forEach((cache, tree) => {
+        cache.clear();
+        clearCleanupInterval(tree);
+    });
+    memoizationCache.clear();
+}
+/**
+ * Cleanup the cache interval on app shutdown
+ */
+function cleanupMemoizationCache() {
+    resetMemoizationCaches();
+}
+/**
+ * Shallow equality check for dependency comparison
+ * Much faster than deep equality for objects with primitive values
+ * Optimized: Uses for...in instead of Object.keys() to avoid array allocations
+ */
+function shallowEqual(a, b) {
+    if (a === b)
+        return true;
+    if (a == null || b == null)
+        return false;
+    if (typeof a !== typeof b)
+        return false;
+    if (typeof a === 'object' && typeof b === 'object') {
+        const objA = a;
+        const objB = b;
+        // Count properties in objA and check equality
+        let countA = 0;
+        for (const key in objA) {
+            if (!Object.prototype.hasOwnProperty.call(objA, key))
+                continue;
+            countA++;
+            // Early exit if key missing or value different
+            if (!(key in objB) || objA[key] !== objB[key])
+                return false;
+        }
+        // Count properties in objB to ensure same number
+        let countB = 0;
+        for (const key in objB) {
+            if (Object.prototype.hasOwnProperty.call(objB, key))
+                countB++;
+        }
+        return countA === countB;
+    }
+    return false;
+}
+/**
+ * Generate cache key for memoization
+ */
+function generateCacheKey(fn, args) {
+    try {
+        return `${fn.name || 'anonymous'}_${JSON.stringify(args)}`;
+    }
+    catch {
+        // Fallback for cyclic or non-serializable args
+        return `${fn.name || 'anonymous'}_${args.length}`;
+    }
+}
+/**
+ * Get equality function based on strategy
+ */
+function getEqualityFn(strategy) {
+    switch (strategy) {
+        case 'shallow':
+            return shallowEqual;
+        case 'reference':
+            return (a, b) => a === b;
+        case 'deep':
+        default:
+            return deepEqual;
+    }
+}
+/**
+ * Memoization function that caches expensive computations with enhanced cache management
+ */
+function memoize(fn, keyFn, config = {}) {
+    const maxSize = config.maxCacheSize ?? MAX_CACHE_SIZE;
+    const ttl = config.ttl ?? DEFAULT_TTL;
+    // Use shallow equality by default to avoid expensive deep comparisons
+    const equality = getEqualityFn(config.equality ?? 'shallow');
+    // Disable LRU by default to avoid hidden CPU overhead
+    const enableLRU = config.enableLRU ?? false;
+    const cache = createMemoCacheStore(maxSize, enableLRU);
+    const cleanExpiredEntries = () => {
+        if (!ttl)
+            return; // Skip if TTL is disabled
+        const now = Date.now();
+        cache.forEach((entry, key) => {
+            if (entry.timestamp && now - entry.timestamp > ttl) {
+                cache.delete(key);
+            }
+        });
+    };
+    return (...args) => {
+        // Probabilistic cleanup to avoid paying cleanup cost on every hot call.
+        // Runs ~1% of the time when TTL is enabled.
+        if (ttl && Math.random() < 0.01) {
+            cleanExpiredEntries();
+        }
+        const key = keyFn
+            ? keyFn(...args)
+            : generateCacheKey(fn, args);
+        const cached = cache.get(key);
+        // If using custom key function, trust the key; otherwise check equality
+        if (cached && (keyFn || equality(cached.deps, args))) {
+            if (enableLRU) {
+                cached.hitCount += 1;
+            }
+            return cached.value;
+        }
+        const result = fn(...args);
+        cache.set(key, {
+            value: result,
+            deps: args,
+            timestamp: Date.now(),
+            hitCount: 1,
+        });
+        return result;
+    };
+}
+/**
+ * High-performance memoization function optimized for speed
+ * Uses shallow equality and minimal cache management overhead
+ */
+function memoizeShallow(fn, keyFn) {
+    return memoize(fn, keyFn, {
+        equality: 'shallow',
+        enableLRU: false,
+        ttl: undefined,
+        maxCacheSize: 100,
+    });
+}
+/**
+ * Lightweight memoization function with reference equality only
+ * Maximum performance for scenarios where exact reference matches are sufficient
+ */
+function memoizeReference(fn, keyFn) {
+    return memoize(fn, keyFn, {
+        equality: 'reference',
+        enableLRU: false,
+        ttl: undefined,
+        maxCacheSize: 50,
+    });
+}
+/**
+ * Preset memoization configurations optimized for common use cases
+ * These presets are the same ones used in SignalTree's benchmarks
+ */
+const MEMOIZATION_PRESETS = {
+    /**
+     * Optimized for selectors and frequently-accessed computed values
+     * - Fast reference-only equality checks (~0.3μs)
+     * - Small cache (10 entries) for minimal overhead
+     * - No LRU management (eliminates bookkeeping cost)
+     * - Best for: Selectors, derived values, stable references
+     */
+    selector: {
+        equality: 'reference',
+        maxCacheSize: 10,
+        enableLRU: false,
+        ttl: undefined,
+    },
+    /**
+     * Balanced configuration for general computed values
+     * - Shallow equality checks (~5-15μs) for object comparisons
+     * - Medium cache (100 entries) for reasonable coverage
+     * - No LRU (good performance/memory balance)
+     * - Best for: General computations, objects with primitives
+     */
+    computed: {
+        equality: 'shallow',
+        maxCacheSize: 100,
+        enableLRU: false,
+        ttl: undefined,
+    },
+    /**
+     * Thorough configuration for complex nested state
+     * - Deep equality checks (~50-200μs) for nested objects
+     * - Large cache (1000 entries) for complex scenarios
+     * - LRU enabled for intelligent cache management
+     * - 5-minute TTL to prevent stale data
+     * - Best for: Complex nested objects, thorough comparisons needed
+     */
+    deepState: {
+        equality: 'deep',
+        maxCacheSize: 1000,
+        enableLRU: true,
+        ttl: 5 * 60 * 1000,
+    },
+    /**
+     * Minimal overhead for high-frequency operations
+     * - Reference-only equality (fastest possible)
+     * - Tiny cache (5 entries) for minimal memory
+     * - No bells and whistles
+     * - Best for: Hot paths, microseconds matter, immutable data
+     */
+    highFrequency: {
+        equality: 'reference',
+        maxCacheSize: 5,
+        enableLRU: false,
+        ttl: undefined,
+    },
+};
+/**
+ * Convenience function: Memoization optimized for selectors
+ * Uses reference equality and small cache for maximum performance
+ *
+ * @example
+ * ```typescript
+ * const tree = signalTree(state).with(withSelectorMemoization());
+ * const activeUsers = computed(() =>
+ *   tree.state.users().filter(u => u.active)
+ * );
+ * ```
+ */
+function withSelectorMemoization() {
+    return withMemoization(MEMOIZATION_PRESETS.selector);
+}
+/**
+ * Convenience function: Memoization optimized for computed values
+ * Uses shallow equality for balanced performance
+ *
+ * @example
+ * ```typescript
+ * const tree = signalTree(state).with(withComputedMemoization());
+ * const metrics = computed(() =>
+ *   calculateExpensiveMetrics(tree.state.data())
+ * );
+ * ```
+ */
+function withComputedMemoization() {
+    return withMemoization(MEMOIZATION_PRESETS.computed);
+}
+/**
+ * Convenience function: Memoization for complex nested state
+ * Uses deep equality and LRU management
+ *
+ * @example
+ * ```typescript
+ * const tree = signalTree(state).with(withDeepStateMemoization());
+ * // Handles complex nested object comparisons
+ * ```
+ */
+function withDeepStateMemoization() {
+    return withMemoization(MEMOIZATION_PRESETS.deepState);
+}
+/**
+ * Convenience function: Minimal memoization for hot paths
+ * Maximum performance with minimal overhead
+ *
+ * @example
+ * ```typescript
+ * const tree = signalTree(state).with(withHighFrequencyMemoization());
+ * // For operations called thousands of times per second
+ * ```
+ */
+function withHighFrequencyMemoization() {
+    return withMemoization(MEMOIZATION_PRESETS.highFrequency);
+}
+/**
+ * Enhances a SignalTree with memoization capabilities
+ * Uses unconstrained recursive typing - no limitations on T
+ */
+function withMemoization(config = {}) {
+    const { enabled = true, maxCacheSize = 1000, ttl, 
+    // Default behavior: deep equality and LRU enabled to preserve
+    // memoization semantics expected by existing consumers/tests.
+    equality = 'deep', enableLRU = true, } = config;
+    return (tree) => {
+        const originalTreeCall = tree.bind(tree);
+        const applyUpdateResult = (result) => {
+            Object.entries(result).forEach(([propKey, value]) => {
+                const property = tree.state[propKey];
+                if (property && 'set' in property) {
+                    property.set(value);
+                }
+                else if (isNodeAccessor$1(property)) {
+                    property(value);
+                }
+            });
+        };
+        if (!enabled) {
+            const memoTree = tree;
+            memoTree.memoizedUpdate = (updater) => {
+                const currentState = originalTreeCall();
+                const result = updater(currentState);
+                applyUpdateResult(result);
+            };
+            memoTree.clearMemoCache = () => {
+                /* no-op when memoization disabled */
+            };
+            memoTree.getCacheStats = () => ({
+                size: 0,
+                hitRate: 0,
+                totalHits: 0,
+                totalMisses: 0,
+                keys: [],
+            });
+            return memoTree;
+        }
+        // Initialize cache for this tree
+        const cache = createMemoCacheStore(maxCacheSize, enableLRU);
+        memoizationCache.set(tree, cache);
+        const equalityFn = getEqualityFn(equality);
+        // Add memoized update method
+        tree.memoizedUpdate = (updater, cacheKey) => {
+            const currentState = originalTreeCall();
+            // Determine cache key: prefer explicit keyFn-like behavior if not provided
+            const key = cacheKey ||
+                generateCacheKey(updater, [
+                    currentState,
+                ]);
+            // Check cache
+            const cached = cache.get(key);
+            if (cached && equalityFn(cached.deps, [currentState])) {
+                // Apply cached result - use callable interface to set the partial update
+                const cachedUpdate = cached.value;
+                applyUpdateResult(cachedUpdate);
+                return;
+            }
+            // Compute new result
+            const result = updater(currentState);
+            // Cache the result
+            cache.set(key, {
+                value: result,
+                deps: [currentState],
+                timestamp: Date.now(),
+                hitCount: 1,
+            });
+            // Apply update using callable interface
+            applyUpdateResult(result);
+        };
+        // Add cache management methods
+        tree.clearMemoCache = (key) => {
+            if (key) {
+                cache.delete(key);
+            }
+            else {
+                cache.clear();
+            }
+        };
+        tree.getCacheStats = () => {
+            let totalHits = 0;
+            let totalMisses = 0;
+            cache.forEach((entry) => {
+                totalHits += entry.hitCount || 0;
+                // For simplicity, we'll estimate misses as half of hits
+                totalMisses += Math.floor((entry.hitCount || 0) / 2);
+            });
+            const hitRate = totalHits + totalMisses > 0 ? totalHits / (totalHits + totalMisses) : 0;
+            return {
+                size: cache.size(),
+                hitRate,
+                totalHits,
+                totalMisses,
+                keys: Array.from(cache.keys()),
+            };
+        };
+        // If we created a periodic cleanup for this tree, ensure callers can clear it
+        const maybeInterval = getCleanupInterval(tree);
+        if (maybeInterval) {
+            // When the tree cache is cleared, also clear the interval
+            const origClear = tree.clearMemoCache.bind(tree);
+            tree.clearMemoCache = (key) => {
+                origClear(key);
+                clearCleanupInterval(tree);
+            };
+        }
+        // Intentionally do NOT attach memoization helpers to `tree.$` to preserve
+        // the "callable-only nodes" invariant for serialization safety.
+        // Clean up expired entries if TTL is set
+        if (ttl) {
+            const cleanup = () => {
+                const now = Date.now();
+                cache.forEach((entry, key) => {
+                    if (entry.timestamp && now - entry.timestamp > ttl) {
+                        cache.delete(key);
+                    }
+                });
+            };
+            // Run cleanup periodically
+            const intervalId = setInterval(cleanup, ttl);
+            // Store interval ID for cleanup (handle Node.js vs browser differences)
+            setCleanupInterval(tree, intervalId);
+        }
+        return tree;
+    };
+}
+/**
+ * High-performance memoization with aggressive caching
+ * Uses unconstrained recursive typing - no limitations on T
+ */
+function withHighPerformanceMemoization() {
+    return withMemoization({
+        enabled: true,
+        maxCacheSize: 10000,
+        ttl: 300000, // 5 minutes
+        equality: 'shallow', // Faster than deep equality
+        enableLRU: true,
+    });
+}
+/**
+ * Lightweight memoization optimized for performance-critical scenarios
+ * Disables expensive cache management features for maximum speed
+ */
+function withLightweightMemoization() {
+    return withMemoization({
+        enabled: true,
+        maxCacheSize: 100, // Smaller cache to reduce management overhead
+        ttl: undefined, // No TTL to avoid timestamp checks
+        equality: 'reference', // Fastest equality check
+        enableLRU: false, // No LRU to avoid hit count tracking
+    });
+}
+/**
+ * Shallow equality memoization for objects with primitive values
+ * Good balance between performance and correctness
+ */
+function withShallowMemoization() {
+    return withMemoization({
+        enabled: true,
+        maxCacheSize: 1000,
+        ttl: 60000, // 1 minute
+        equality: 'shallow',
+        enableLRU: true,
+    });
+}
+/**
+ * Clear all memoization caches
+ */
+function clearAllCaches() {
+    resetMemoizationCaches();
+}
+/**
+ * Get global cache statistics
+ */
+function getGlobalCacheStats() {
+    // Note: We keep a Map keyed by tree objects to allow listing and diagnostics
+    // (WeakMap would prevent traversal). This function summarizes those diagnostics.
+    let totalSize = 0;
+    let totalHits = 0;
+    let treeCount = 0;
+    memoizationCache.forEach((cache) => {
+        treeCount++;
+        totalSize += cache.size();
+        cache.forEach((entry) => {
+            totalHits += entry.hitCount || 0;
+        });
+    });
+    return {
+        treeCount,
+        totalSize,
+        totalHits,
+        averageCacheSize: treeCount > 0 ? totalSize / treeCount : 0,
+    };
+}
+
+/**
+ * Internal time travel state management
+ */
+class TimeTravelManager {
+    tree;
+    config;
+    restoreStateFn;
+    history = [];
+    currentIndex = -1;
+    maxHistorySize;
+    includePayload;
+    actionNames;
+    constructor(tree, config = {}, restoreStateFn) {
+        this.tree = tree;
+        this.config = config;
+        this.restoreStateFn = restoreStateFn;
+        this.maxHistorySize = config.maxHistorySize ?? 50;
+        this.includePayload = config.includePayload ?? true;
+        this.actionNames = {
+            update: 'UPDATE',
+            set: 'SET',
+            batch: 'BATCH',
+            ...config.actionNames,
+        };
+        // Add initial state to history
+        this.addEntry('INIT', this.tree());
+    }
+    /**
+     * Add a new entry to the history
+     */
+    addEntry(action, state, payload) {
+        // If we're not at the end of history, remove everything after current position
+        if (this.currentIndex < this.history.length - 1) {
+            this.history = this.history.slice(0, this.currentIndex + 1);
+        }
+        // Create new entry
+        const entry = {
+            state: deepClone(state),
+            timestamp: Date.now(),
+            action: this.actionNames[action] || action,
+            ...(this.includePayload && payload !== undefined && { payload }),
+        };
+        this.history.push(entry);
+        this.currentIndex = this.history.length - 1;
+        // Enforce max history size
+        if (this.history.length > this.maxHistorySize) {
+            this.history.shift();
+            this.currentIndex--;
+        }
+    }
+    undo() {
+        if (!this.canUndo()) {
+            return false;
+        }
+        this.currentIndex--;
+        const entry = this.history[this.currentIndex];
+        this.restoreState(entry.state);
+        return true;
+    }
+    redo() {
+        if (!this.canRedo()) {
+            return false;
+        }
+        this.currentIndex++;
+        const entry = this.history[this.currentIndex];
+        this.restoreState(entry.state);
+        return true;
+    }
+    getHistory() {
+        return this.history.map((entry) => ({
+            ...entry,
+            state: deepClone(entry.state),
+        }));
+    }
+    resetHistory() {
+        const currentState = this.tree();
+        this.history = [];
+        this.currentIndex = -1;
+        this.addEntry('RESET', currentState);
+    }
+    jumpTo(index) {
+        if (index < 0 || index >= this.history.length) {
+            return false;
+        }
+        this.currentIndex = index;
+        const entry = this.history[index];
+        this.restoreState(entry.state);
+        return true;
+    }
+    getCurrentIndex() {
+        return this.currentIndex;
+    }
+    canUndo() {
+        return this.currentIndex > 0;
+    }
+    canRedo() {
+        return this.currentIndex < this.history.length - 1;
+    }
+    /**
+     * Restore state without triggering time travel middleware
+     */
+    restoreState(state) {
+        if (this.restoreStateFn) {
+            this.restoreStateFn(state);
+        }
+        else {
+            // Fallback if no restoration function provided
+            this.tree(state);
+        }
+    }
+}
+/**
+ * Enhances a SignalTree with comprehensive time travel capabilities.
+ *
+ * Adds undo/redo functionality, state history management, and snapshot features.
+ * Automatically tracks state changes and provides methods to navigate through
+ * the application's state history with configurable limits and optimizations.
+ *
+ * @template T - The state object type
+ * @param config - Configuration options for time travel behavior
+ * @returns Function that enhances a SignalTree with time travel capabilities
+ *
+ * @example
+ * ```typescript
+ * // Basic time travel enhancement
+ * const store = signalTree({ count: 0, text: '' }).with(withTimeTravel());
+ *
+ * // Make some changes
+ * store.count.set(1);
+ * store.text.set('hello');
+ * store.count.set(2);
+ *
+ * // Access time travel interface
+ * const timeTravel = store.__timeTravel;
+ *
+ * // Navigate history
+ * console.log(timeTravel.canUndo()); // true
+ * timeTravel.undo(); // count: 1, text: 'hello'
+ * timeTravel.undo(); // count: 1, text: ''
+ * timeTravel.undo(); // count: 0, text: ''
+ *
+ * timeTravel.redo(); // count: 1, text: ''
+ * console.log(timeTravel.canRedo()); // true
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Advanced configuration
+ * const store = signalTree({
+ *   document: { title: '', content: '' },
+ *   settings: { theme: 'light' }
+ * }).with(withTimeTravel({
+ *   maxHistorySize: 50,        // Limit memory usage
+ *   includePayload: true,      // Store action metadata
+ *   actionNames: {             // Custom action names
+ *     'update_title': 'Update Document Title',
+ *     'change_theme': 'Change Theme'
+ *   }
+ * }));
+ *
+ * // Named actions with metadata
+ * store.update(() => ({ document: { title: 'New Title' } }), 'update_title');
+ *
+ * // View detailed history
+ * const history = store.__timeTravel.getHistory();
+ * console.log(history[0].action); // 'Update Document Title'
+ * console.log(history[0].timestamp); // Date when change occurred
+ * ```
+ */
+function withTimeTravel(config = {}) {
+    return (tree) => {
+        // Store the original callable tree function
+        const originalTreeCall = tree.bind(tree);
+        // Flag to prevent time travel during restoration
+        let isRestoring = false;
+        // Create time travel manager with restoration function
+        const timeTravelManager = new TimeTravelManager(tree, config, (state) => {
+            isRestoring = true;
+            try {
+                originalTreeCall(state);
+            }
+            finally {
+                isRestoring = false;
+            }
+        });
+        // Create enhanced tree function that includes time travel tracking
+        const enhancedTree = function (...args) {
+            if (args.length === 0) {
+                // Get operation - call original directly
+                return originalTreeCall();
+            }
+            else {
+                // Set or update operation - track for time travel
+                if (isRestoring) {
+                    // During restoration, just call original update
+                    if (args.length === 1) {
+                        const arg = args[0];
+                        if (typeof arg === 'function') {
+                            return originalTreeCall(arg);
+                        }
+                        else {
+                            return originalTreeCall(arg);
+                        }
+                    }
+                    return;
+                }
+                const beforeState = originalTreeCall();
+                // Execute the actual update using the original callable interface
+                let result;
+                if (args.length === 1) {
+                    const arg = args[0];
+                    if (typeof arg === 'function') {
+                        result = originalTreeCall(arg);
+                    }
+                    else {
+                        result = originalTreeCall(arg);
+                    }
+                }
+                const afterState = originalTreeCall();
+                // Only add to history if state actually changed
+                const statesEqual = deepEqual(beforeState, afterState);
+                if (!statesEqual) {
+                    timeTravelManager.addEntry('update', afterState);
+                }
+                return result;
+            }
+        };
+        // Copy all properties and methods from original tree
+        Object.setPrototypeOf(enhancedTree, Object.getPrototypeOf(tree));
+        Object.assign(enhancedTree, tree);
+        // Ensure state and $ properties are preserved
+        if ('state' in tree) {
+            Object.defineProperty(enhancedTree, 'state', {
+                value: tree.state,
+                enumerable: false,
+                configurable: true,
+            });
+        }
+        // Ensure $ alias is preserved
+        if ('$' in tree) {
+            Object.defineProperty(enhancedTree, '$', {
+                value: tree['$'],
+                enumerable: false,
+                configurable: true,
+            });
+        }
+        // Override DX-friendly methods to forward to the time travel manager
+        // These shadow the core stubs when the enhancer is applied
+        enhancedTree.undo = () => {
+            timeTravelManager.undo();
+        };
+        enhancedTree.redo = () => {
+            timeTravelManager.redo();
+        };
+        enhancedTree.getHistory = () => timeTravelManager.getHistory();
+        enhancedTree.resetHistory =
+            () => {
+                timeTravelManager.resetHistory();
+            };
+        // Additional helpers exposed directly on the tree for better DX
+        enhancedTree.jumpTo = (index) => {
+            timeTravelManager.jumpTo(index);
+        };
+        enhancedTree.canUndo = () => timeTravelManager.canUndo();
+        enhancedTree.canRedo = () => timeTravelManager.canRedo();
+        enhancedTree.getCurrentIndex =
+            () => timeTravelManager.getCurrentIndex();
+        return Object.assign(enhancedTree, {
+            __timeTravel: timeTravelManager,
+        });
+    };
+}
+/**
+ * Convenience function to enable basic time travel
+ */
+function enableTimeTravel(maxHistorySize) {
+    return withTimeTravel({ maxHistorySize });
+}
+/**
+ * Get time travel interface from an enhanced tree
+ */
+function getTimeTravel(tree) {
+    return tree.__timeTravel;
+}
+
+/**
+ * Creates entity helpers for a specific entity collection
+ * This properly handles the SignalTree's TreeNode type structure
+ *
+ * CRITICAL: In SignalTree, arrays become WritableSignal<Array>
+ * So `users: User[]` in the original state becomes `users: WritableSignal<User[]>` in tree.state
+ */
+function createEntityHelpers(tree, entityKey) {
+    // Get the signal from the deeply signalified state
+    // The state property is of type TreeNode<T>
+    const getEntitySignal = () => {
+        // Access the state property - it's already a signal due to TreeNode
+        // We need to use type assertion here because TypeScript can't track the deep signalification
+        const stateProperty = tree.state[entityKey];
+        // Check if it exists
+        if (!stateProperty) {
+            throw new Error(`Entity key '${String(entityKey)}' does not exist in the state`);
+        }
+        // Due to TreeNode, if the original was an array, it's now WritableSignal<Array>
+        if (!isAnySignal(stateProperty)) {
+            throw new Error(`Entity key '${String(entityKey)}' is not a signal. This should not happen with SignalTree.`);
+        }
+        // Cast to WritableSignal and verify it contains an array
+        const signal = stateProperty;
+        const value = signal();
+        if (!Array.isArray(value)) {
+            throw new Error(`Entity key '${String(entityKey)}' does not contain an array. Current type: ${typeof value}`);
+        }
+        return signal;
+    };
+    // Helper function to set values on both WritableSignal and callable signals
+    const setSignalValue = (signal, value) => {
+        if (isNodeAccessor$1(signal)) {
+            // Callable signal - use function call
+            signal(value);
+        }
+        else {
+            // WritableSignal - use .set() method
+            signal.set(value);
+        }
+    };
+    return {
+        add: (entity) => {
+            const entitySignal = getEntitySignal();
+            const currentEntities = entitySignal();
+            // Check for duplicate
+            if (currentEntities.some((e) => e.id === entity.id)) {
+                throw new Error(`Entity with id '${entity.id}' already exists`);
+            }
+            setSignalValue(entitySignal, [...currentEntities, entity]);
+        },
+        update: (id, updates) => {
+            const entitySignal = getEntitySignal();
+            const currentEntities = entitySignal();
+            const updatedEntities = currentEntities.map((entity) => entity.id === id ? { ...entity, ...updates } : entity);
+            setSignalValue(entitySignal, updatedEntities);
+        },
+        remove: (id) => {
+            const entitySignal = getEntitySignal();
+            const currentEntities = entitySignal();
+            const filteredEntities = currentEntities.filter((entity) => entity.id !== id);
+            setSignalValue(entitySignal, filteredEntities);
+        },
+        upsert: (entity) => {
+            const entitySignal = getEntitySignal();
+            const currentEntities = entitySignal();
+            const index = currentEntities.findIndex((e) => e.id === entity.id);
+            if (index >= 0) {
+                // Update existing
+                const updatedEntities = [...currentEntities];
+                updatedEntities[index] = entity;
+                setSignalValue(entitySignal, updatedEntities);
+            }
+            else {
+                // Add new
+                setSignalValue(entitySignal, [...currentEntities, entity]);
+            }
+        },
+        selectById: (id) => {
+            const entitySignal = getEntitySignal();
+            return computed(() => entitySignal().find((entity) => entity.id === id));
+        },
+        selectBy: (predicate) => {
+            const entitySignal = getEntitySignal();
+            return computed(() => entitySignal().filter(predicate));
+        },
+        selectIds: () => {
+            const entitySignal = getEntitySignal();
+            return computed(() => entitySignal().map((entity) => entity.id));
+        },
+        selectAll: () => {
+            const entitySignal = getEntitySignal();
+            return entitySignal;
+        },
+        selectTotal: () => {
+            const entitySignal = getEntitySignal();
+            return computed(() => entitySignal().length);
+        },
+        clear: () => {
+            const entitySignal = getEntitySignal();
+            setSignalValue(entitySignal, []);
+        },
+    };
+}
+/**
+ * Enhances a SignalTree with entity management capabilities
+ * Works with SignalTree's TreeNode type structure
+ *
+ * The key insight: The state is already deeply signalified, so array properties
+ * like `users: User[]` become `users: WritableSignal<User[]>` in tree.state
+ */
+function withEntities(config = {}) {
+    const { enabled = true } = config;
+    return function enhanceWithEntities(tree) {
+        if (!enabled) {
+            // When disabled, return the original tree object unchanged
+            // Cast is safe here because we're not actually adding the method
+            return tree;
+        }
+        // Type-safe enhancement that adds entities method using Object.assign
+        // This approach preserves the generic method signature better than direct property assignment
+        const enhancedTree = Object.assign(tree, {
+            entities(entityKey) {
+                return createEntityHelpers(tree, entityKey);
+            },
+        });
+        return enhancedTree;
+    };
+}
+/**
+ * Convenience function to enable entities with default config
+ */
+function enableEntities() {
+    return withEntities({ enabled: true });
+}
+/**
+ * High-performance entity management configuration
+ */
+function withHighPerformanceEntities() {
+    return withEntities({
+        enabled: true});
+}
+
+/**
+ * Type markers for special object serialization
+ * Using compact symbols to minimize serialized size
+ */
+const TYPE_MARKERS = {
+    DATE: '§d',
+    REGEXP: '§r',
+    MAP: '§m',
+    SET: '§s',
+    UNDEFINED: '§u',
+    NAN: '§n',
+    INFINITY: '§i',
+    NEG_INFINITY: '§-i',
+    BIGINT: '§b',
+    SYMBOL: '§y',
+    CIRCULAR: '§c',
+};
+
+/**
+ * Default serialization config
+ */
+const DEFAULT_CONFIG = {
+    includeMetadata: true,
+    replacer: undefined,
+    reviver: undefined,
+    preserveTypes: true,
+    maxDepth: 50,
+    handleCircular: true,
+};
+/**
+ * Safely unwrap object with circular reference detection
+ */
+function unwrapObjectSafely(obj, visited = new WeakSet(), depth = 0, maxDepth = 50, preserveTypes = true) {
+    // Prevent infinite recursion
+    if (depth > maxDepth)
+        return '[Max Depth Exceeded]';
+    // Primitives and non-objects
+    if (obj === null || typeof obj !== 'object') {
+        if (!preserveTypes)
+            return obj;
+        if (obj === undefined)
+            return { [TYPE_MARKERS.UNDEFINED]: true };
+        if (typeof obj === 'number') {
+            if (Number.isNaN(obj))
+                return { [TYPE_MARKERS.NAN]: true };
+            if (obj === Infinity)
+                return { [TYPE_MARKERS.INFINITY]: true };
+            if (obj === -Infinity)
+                return { [TYPE_MARKERS.NEG_INFINITY]: true };
+            return obj;
+        }
+        if (typeof obj === 'bigint')
+            return { [TYPE_MARKERS.BIGINT]: String(obj) };
+        if (typeof obj === 'symbol')
+            return { [TYPE_MARKERS.SYMBOL]: String(obj) };
+        return obj;
+    }
+    // Handle callable signals (no longer need complex branch wrapper detection)
+    if (typeof obj === 'function') {
+        try {
+            // Check if it's a callable signal by trying to invoke it
+            const result = obj();
+            return unwrapObjectSafely(result, visited, depth + 1, maxDepth, preserveTypes);
+        }
+        catch {
+            // Not a callable signal, treat as regular function (non-serializable)
+            return '[Function]';
+        }
+    }
+    // If object already visited, mark as circular
+    if (visited.has(obj))
+        return '[Circular Reference]';
+    // Unwrap signals
+    if (isSignal(obj))
+        return obj();
+    // Preserve special types
+    if (preserveTypes) {
+        if (obj instanceof Date)
+            return { [TYPE_MARKERS.DATE]: obj.toISOString() };
+        if (obj instanceof RegExp)
+            return {
+                [TYPE_MARKERS.REGEXP]: { source: obj.source, flags: obj.flags },
+            };
+        if (obj instanceof Map) {
+            return { [TYPE_MARKERS.MAP]: Array.from(obj.entries()) };
+        }
+        if (obj instanceof Set) {
+            return { [TYPE_MARKERS.SET]: Array.from(obj.values()) };
+        }
+    }
+    else {
+        if (obj instanceof Date || obj instanceof RegExp)
+            return obj;
+    }
+    visited.add(obj);
+    try {
+        if (Array.isArray(obj)) {
+            const arr = obj.map((item) => unwrapObjectSafely(item, visited, depth + 1, maxDepth, preserveTypes));
+            visited.delete(obj);
+            return arr;
+        }
+        const out = {};
+        for (const [k, v] of Object.entries(obj)) {
+            // Skip runtime helpers when they are plain functions (not signals)
+            if ((k === 'set' || k === 'update') &&
+                typeof v === 'function' &&
+                !isSignal(v))
+                continue;
+            if (isSignal(v)) {
+                out[k] = unwrapObjectSafely(v(), visited, depth + 1, maxDepth, preserveTypes);
+            }
+            else if (typeof v === 'function' && k !== 'set' && k !== 'update') {
+                // Handle callable signals - these are functions but not helper methods
+                try {
+                    const callResult = v();
+                    out[k] = unwrapObjectSafely(callResult, visited, depth + 1, maxDepth, preserveTypes);
+                }
+                catch {
+                    // If calling fails, skip this property
+                    continue;
+                }
+            }
+            else {
+                out[k] = unwrapObjectSafely(v, visited, depth + 1, maxDepth, preserveTypes);
+            }
+        }
+        visited.delete(obj);
+        return out;
+    }
+    catch {
+        visited.delete(obj);
+        return '[Serialization Error]';
+    }
+}
+/**
+ * Detects circular references in an object
+ */
+function detectCircularReferences(obj, path = '', seen = new WeakSet(), paths = new Map()) {
+    const circular = [];
+    if (obj === null || typeof obj !== 'object') {
+        return circular;
+    }
+    // Check if we've seen this object before
+    if (seen.has(obj)) {
+        // Found a circular reference
+        const targetPath = paths.get(obj) || '';
+        circular.push({ path, targetPath });
+        return circular; // Don't recurse into circular references
+    }
+    // Mark this object as seen
+    seen.add(obj);
+    paths.set(obj, path);
+    // Recursively check children
+    if (Array.isArray(obj)) {
+        const arrObj = obj;
+        for (let i = 0; i < arrObj.length; i++) {
+            const itemPath = path ? `${path}[${i}]` : `[${i}]`;
+            const childCircular = detectCircularReferences(arrObj[i], itemPath, seen, paths);
+            circular.push(...childCircular);
+        }
+    }
+    else {
+        for (const [key, value] of Object.entries(obj)) {
+            const propPath = path ? `${path}.${key}` : key;
+            const childCircular = detectCircularReferences(value, propPath, seen, paths);
+            circular.push(...childCircular);
+        }
+    }
+    // Remove from seen set when backing out (allows siblings to reference same objects)
+    seen.delete(obj);
+    return circular;
+}
+/**
+ * Custom replacer that handles circular references only
+ */
+function createReplacer(config) {
+    const seen = new WeakSet();
+    const circularPaths = new Map();
+    return function replacer(key, value) {
+        // Apply custom replacer first if provided
+        if (config.replacer) {
+            value = config.replacer.call(this, key, value);
+        }
+        // Skip signals - we already unwrapped them
+        if (isSignal(value)) {
+            return value();
+        }
+        // Handle circular references
+        if (value && typeof value === 'object') {
+            if (seen.has(value)) {
+                if (config.handleCircular) {
+                    const targetPath = circularPaths.get(value) || '';
+                    return { [TYPE_MARKERS.CIRCULAR]: targetPath };
+                }
+                return undefined;
+            }
+            seen.add(value);
+            const currentPath = key || '';
+            circularPaths.set(value, currentPath);
+        }
+        // All special type handling is now done in unwrapObjectSafely
+        return value;
+    };
+}
+/**
+ * Resolves circular references after parsing
+ */
+function resolveCircularReferences(obj, circularPaths) {
+    for (const { path, targetPath } of circularPaths) {
+        const pathParts = path.split(/\.|\[|\]/).filter(Boolean);
+        const targetParts = targetPath.split(/\.|\[|\]/).filter(Boolean);
+        // Navigate to the circular reference location
+        let current = obj;
+        for (let i = 0; i < pathParts.length - 1; i++) {
+            current = current[pathParts[i]];
+            if (!current)
+                break;
+        }
+        // Navigate to the target
+        let target = obj;
+        for (const part of targetParts) {
+            target = target[part];
+            if (!target)
+                break;
+        }
+        // Set the circular reference
+        if (current && target) {
+            current[pathParts[pathParts.length - 1]] = target;
+        }
+    }
+}
+/**
+ * Enhances a SignalTree with serialization capabilities
+ */
+function withSerialization(defaultConfig = {}) {
+    const enhancer = (tree) => {
+        const enhanced = tree;
+        /**
+         * Get plain object representation
+         */
+        enhanced.toJSON = () => {
+            // Delegate to the tree's public unwrap() which already strips helper
+            // methods like `set`/`update`. Keep unwrapObjectSafely for
+            // serialize() where we need type-preserving markers.
+            return tree();
+        };
+        /**
+         * Restore from plain object
+         */
+        enhanced.fromJSON = (data, metadata) => {
+            // Convert special type markers back to their actual types
+            const restoreSpecialTypes = (value) => {
+                if (!value || typeof value !== 'object') {
+                    return value;
+                }
+                // Check for type markers
+                if (TYPE_MARKERS.UNDEFINED in value) {
+                    return undefined;
+                }
+                if (TYPE_MARKERS.NAN in value) {
+                    return NaN;
+                }
+                if (TYPE_MARKERS.INFINITY in value) {
+                    return Infinity;
+                }
+                if (TYPE_MARKERS.NEG_INFINITY in value) {
+                    return -Infinity;
+                }
+                if (TYPE_MARKERS.BIGINT in value) {
+                    return BigInt(value[TYPE_MARKERS.BIGINT]);
+                }
+                if (TYPE_MARKERS.SYMBOL in value) {
+                    return Symbol.for(value[TYPE_MARKERS.SYMBOL]);
+                }
+                if (TYPE_MARKERS.DATE in value) {
+                    return new Date(value[TYPE_MARKERS.DATE]);
+                }
+                if (TYPE_MARKERS.REGEXP in value) {
+                    const regexpData = value[TYPE_MARKERS.REGEXP];
+                    return new RegExp(regexpData.source, regexpData.flags);
+                }
+                if (TYPE_MARKERS.MAP in value) {
+                    return new Map(value[TYPE_MARKERS.MAP]);
+                }
+                if (TYPE_MARKERS.SET in value) {
+                    return new Set(value[TYPE_MARKERS.SET]);
+                }
+                // Handle arrays
+                if (Array.isArray(value)) {
+                    return value.map(restoreSpecialTypes);
+                }
+                // Handle objects
+                const result = {};
+                for (const [k, v] of Object.entries(value)) {
+                    result[k] = restoreSpecialTypes(v);
+                }
+                return result;
+            };
+            // Restore special types in the data
+            const restoredData = restoreSpecialTypes(data);
+            // Helper to resolve a signal from the root alias (`tree.$`) using the
+            // accumulated path so keys that collide with branch methods (like "set")
+            // still map to the child signals.
+            function resolveAliasSignal(path, key) {
+                let node = tree.$;
+                if (path && node) {
+                    for (const part of path.split('.')) {
+                        if (!part)
+                            continue;
+                        const next = node[part];
+                        if (!next ||
+                            (typeof next !== 'object' && typeof next !== 'function')) {
+                            node = undefined;
+                            break;
+                        }
+                        node = next;
+                    }
+                }
+                const candidate = node?.[key];
+                return isSignal(candidate)
+                    ? candidate
+                    : undefined;
+            }
+            function updateSignals(target, source, path = '') {
+                if (!target || !source)
+                    return;
+                for (const key in source) {
+                    if (!Object.prototype.hasOwnProperty.call(source, key))
+                        continue;
+                    const sourceValue = source[key];
+                    const direct = target[key];
+                    // Prefer the real signal if present; otherwise resolve from root alias
+                    const targetSignal = isSignal(direct)
+                        ? direct
+                        : // Check if it's a callable signal (function with set method)
+                            typeof direct === 'function' &&
+                                'set' in direct &&
+                                typeof direct.set === 'function'
+                                ? direct
+                                : resolveAliasSignal(path, key);
+                    if (targetSignal) {
+                        targetSignal.set(sourceValue);
+                        continue;
+                    }
+                    if (sourceValue &&
+                        typeof sourceValue === 'object' &&
+                        !Array.isArray(sourceValue) &&
+                        direct &&
+                        (typeof direct === 'object' ||
+                            (typeof direct === 'function' && !('set' in direct))) &&
+                        !isSignal(direct)) {
+                        updateSignals(direct, sourceValue, path ? `${path}.${key}` : key);
+                    }
+                }
+            }
+            // If the serialized data contains a compact nodeMap, use it to apply
+            // updates deterministically: 'r' => root set, 'b' => set on branch
+            const nodeMap = metadata?.nodeMap;
+            if (nodeMap && Object.keys(nodeMap).length > 0) {
+                // Root marker
+                if (nodeMap[''] === 'r') {
+                    const rootAlias = tree.$;
+                    if (rootAlias && typeof rootAlias.set === 'function') {
+                        rootAlias.set(restoredData);
+                        // Don't return; still perform targeted updates below to ensure
+                        // type-preserving restoration for all branches.
+                    }
+                }
+                // For branch entries, apply child signal .set directly when possible
+                for (const [path, kind] of Object.entries(nodeMap)) {
+                    if (path === '')
+                        continue; // root handled
+                    if (kind !== 'b')
+                        continue;
+                    // Navigate to path and set the node if a WritableSignal is found
+                    const parts = path.split(/\.|\[|\]/).filter(Boolean);
+                    let node = tree.$;
+                    for (const p of parts) {
+                        if (!node)
+                            break;
+                        node =
+                            node[p] ?? undefined;
+                    }
+                    if (node &&
+                        (isSignal(node) ||
+                            (typeof node === 'function' &&
+                                'set' in node &&
+                                typeof node.set === 'function'))) {
+                        // Extract the corresponding value from restoredData
+                        let current = restoredData;
+                        for (const p of parts) {
+                            if (current == null) {
+                                current = undefined;
+                                break;
+                            }
+                            if (typeof current === 'object') {
+                                current = current[p];
+                            }
+                            else {
+                                current = undefined;
+                                break;
+                            }
+                        }
+                        try {
+                            node.set(current);
+                        }
+                        catch {
+                            /* ignore per-path failures */
+                        }
+                    }
+                }
+                // After applying nodeMap-targeted sets, perform a best-effort deep update for remaining keys
+                updateSignals(tree.state, restoredData);
+                return;
+            }
+            updateSignals(tree.state, restoredData);
+        };
+        // Encode/decode helpers that work on already-unwrapped plain data
+        function encodeSpecials(v, preserveTypes) {
+            if (!preserveTypes)
+                return v;
+            if (v === undefined)
+                return { [TYPE_MARKERS.UNDEFINED]: true };
+            if (typeof v === 'number') {
+                if (Number.isNaN(v))
+                    return { [TYPE_MARKERS.NAN]: true };
+                if (v === Infinity)
+                    return { [TYPE_MARKERS.INFINITY]: true };
+                if (v === -Infinity)
+                    return { [TYPE_MARKERS.NEG_INFINITY]: true };
+                return v;
+            }
+            if (typeof v === 'bigint')
+                return { [TYPE_MARKERS.BIGINT]: String(v) };
+            if (typeof v === 'symbol')
+                return { [TYPE_MARKERS.SYMBOL]: String(v) };
+            if (v instanceof Date)
+                return { [TYPE_MARKERS.DATE]: v.toISOString() };
+            if (v instanceof RegExp)
+                return {
+                    [TYPE_MARKERS.REGEXP]: { source: v.source, flags: v.flags },
+                };
+            if (v instanceof Map)
+                return { [TYPE_MARKERS.MAP]: Array.from(v.entries()) };
+            if (v instanceof Set)
+                return { [TYPE_MARKERS.SET]: Array.from(v.values()) };
+            if (Array.isArray(v))
+                return v.map((x) => encodeSpecials(x, preserveTypes));
+            if (v && typeof v === 'object') {
+                const out = {};
+                for (const [k, val] of Object.entries(v))
+                    out[k] = encodeSpecials(val, preserveTypes);
+                return out;
+            }
+            return v;
+        }
+        /**
+         * Serialize to JSON string
+         */
+        enhanced.serialize = (config) => {
+            const fullConfig = {
+                ...DEFAULT_CONFIG,
+                ...defaultConfig,
+                ...config,
+            };
+            // Use a safe local unwrap to avoid accidental dropping of keys like
+            // 'set' which may collide with branch helpers; let encodeSpecials
+            // handle special type markers.
+            const raw = unwrapObjectSafely(tree.state, new WeakSet(), 0, fullConfig.maxDepth, fullConfig.preserveTypes);
+            const state = encodeSpecials(raw, fullConfig.preserveTypes);
+            // Detect circular references if needed
+            const circularPaths = fullConfig.handleCircular
+                ? detectCircularReferences(state)
+                : [];
+            // Prepare data
+            const data = {
+                data: state,
+            };
+            // Build a compact nodeMap by traversing the callable proxy alias (tree.$)
+            // and marking any signal-like branch node we encounter. Also mark a
+            // root-as-signal marker ('r') if the root alias exposes a .set().
+            const nodeMap = {};
+            try {
+                const rootAlias = tree.$;
+                if (rootAlias && typeof rootAlias.set === 'function') {
+                    nodeMap[''] = 'r';
+                }
+                const visited = new WeakSet();
+                const isBranch = (v) => isSignal(v) ||
+                    (typeof v === 'function' &&
+                        'set' in v &&
+                        typeof v.set === 'function');
+                const walkAlias = (obj, path = '') => {
+                    if (!obj || (typeof obj !== 'object' && typeof obj !== 'function'))
+                        return;
+                    const ref = obj;
+                    if (visited.has(ref))
+                        return;
+                    visited.add(ref);
+                    if (path && isBranch(obj)) {
+                        nodeMap[path] = 'b';
+                    }
+                    // Traverse own enumerable properties (callable proxies expose children here)
+                    for (const [k, v] of Object.entries(obj)) {
+                        const childPath = path ? `${path}.${k}` : k;
+                        walkAlias(v, childPath);
+                    }
+                };
+                if (rootAlias)
+                    walkAlias(rootAlias);
+            }
+            catch {
+                // Do not block serialization on nodeMap errors
+            }
+            // Add metadata if requested
+            if (fullConfig.includeMetadata) {
+                data.metadata = {
+                    timestamp: Date.now(),
+                    version: '1.0.0',
+                    ...(circularPaths.length > 0 && { circularRefs: circularPaths }),
+                    ...(Object.keys(nodeMap).length > 0 && { nodeMap }),
+                };
+            }
+            // Serialize with custom replacer
+            const replacer = createReplacer(fullConfig);
+            const json = JSON.stringify(data, replacer, 2);
+            // Extra debug: if JSON contains MAP or SET markers, print compact preview
+            return json;
+        };
+        /**
+         * Deserialize from JSON string
+         */
+        enhanced.deserialize = (json, config) => {
+            const fullConfig = {
+                ...DEFAULT_CONFIG,
+                ...defaultConfig,
+                ...config,
+            };
+            try {
+                // Parse with simple JSON.parse (no custom reviver)
+                const parsed = JSON.parse(json);
+                // Extract data and metadata
+                const { data, metadata } = parsed;
+                // Resolve circular references if present
+                if (metadata?.circularRefs && fullConfig.handleCircular) {
+                    resolveCircularReferences(data, metadata.circularRefs);
+                }
+                // Apply parsed data to the tree; fromJSON will handle type restoration
+                enhanced.fromJSON(data, metadata);
+                // Log restoration if in debug mode
+                if (tree.__config?.debugMode) {
+                    console.log('[SignalTree] State restored from serialized data', {
+                        timestamp: metadata?.timestamp,
+                        version: metadata?.version,
+                    });
+                }
+            }
+            catch (error) {
+                console.error('[SignalTree] Failed to deserialize:', error);
+                throw new Error(`Failed to deserialize SignalTree state: ${error instanceof Error ? error.message : 'Unknown error'}`);
+            }
+        };
+        /**
+         * Create a snapshot
+         */
+        enhanced.snapshot = () => {
+            const state = enhanced.toJSON();
+            const circularPaths = detectCircularReferences(state);
+            return {
+                data: JSON.parse(JSON.stringify(state)), // Deep clone
+                metadata: {
+                    timestamp: Date.now(),
+                    version: '1.0.0',
+                    ...(circularPaths.length > 0 && { circularRefs: circularPaths }),
+                },
+            };
+        };
+        /**
+         * Restore from snapshot
+         */
+        enhanced.restore = (snapshot) => {
+            const { data, metadata } = snapshot;
+            // Resolve circular references if present
+            if (metadata?.circularRefs) {
+                resolveCircularReferences(data, metadata.circularRefs);
+            }
+            enhanced.fromJSON(data, metadata);
+        };
+        return enhanced;
+    };
+    enhancer.metadata = {
+        name: 'serialization',
+    };
+    return enhancer;
+}
+/**
+ * Convenience function to enable serialization with defaults
+ */
+function enableSerialization() {
+    return withSerialization({
+        includeMetadata: true,
+        preserveTypes: true,
+        handleCircular: true,
+    });
+}
+/**
+ * Adds persistence capabilities to a SerializableSignalTree
+ */
+function withPersistence(config) {
+    const { key, storage = typeof window !== 'undefined' ? window.localStorage : undefined, autoSave = true, debounceMs = 1000, autoLoad = true, ...serializationConfig } = config;
+    if (!storage) {
+        throw new Error('No storage adapter available. Provide a storage adapter in the config.');
+    }
+    // Narrow storage for TypeScript and linter: from here on it's defined.
+    const storageAdapter = storage;
+    function enhancer(tree) {
+        // First enhance with serialization
+        const serializable = withSerialization(serializationConfig)(tree);
+        // Add persistence methods
+        const enhanced = serializable;
+        // Cache to avoid redundant storage writes. Use a metadata-free cache key
+        // so timestamps in metadata don't cause false positives for changes.
+        let lastCacheKey = null;
+        /**
+         * Save current state to storage
+         */
+        enhanced.save = async () => {
+            try {
+                // Compute a deterministic cache key that excludes metadata (timestamps)
+                const cacheKey = enhanced.serialize({
+                    ...serializationConfig,
+                    includeMetadata: false,
+                });
+                // Only write to storage if the state has changed (by cacheKey), unless skipCache is true
+                if (config.skipCache || cacheKey !== lastCacheKey) {
+                    // Persist the full payload (respecting includeMetadata from config)
+                    const serialized = enhanced.serialize(serializationConfig);
+                    await Promise.resolve(storageAdapter.setItem(key, serialized));
+                    lastCacheKey = cacheKey;
+                    if (tree.__config?.debugMode) {
+                        console.log(`[SignalTree] State saved to storage key: ${key}`);
+                    }
+                }
+                else if (tree.__config?.debugMode) {
+                    console.log(`[SignalTree] State unchanged, skipping storage write for key: ${key}`);
+                }
+            }
+            catch (error) {
+                console.error('[SignalTree] Failed to save state:', error);
+                throw error; // Re-throw for tests to catch
+            }
+        };
+        /**
+         * Load state from storage
+         */
+        enhanced.load = async () => {
+            try {
+                const data = await Promise.resolve(storageAdapter.getItem(key));
+                if (data) {
+                    enhanced.deserialize(data, serializationConfig);
+                    // Reset cache after loading new data using a metadata-free key
+                    lastCacheKey = enhanced.serialize({
+                        ...serializationConfig,
+                        includeMetadata: false,
+                    });
+                    if (tree.__config?.debugMode) {
+                        console.log(`[SignalTree] State loaded from storage key: ${key}`);
+                    }
+                }
+            }
+            catch (error) {
+                console.error('[SignalTree] Failed to load state:', error);
+                throw error; // Re-throw for tests to catch
+            }
+        };
+        /**
+         * Clear state from storage
+         */
+        enhanced.clear = async () => {
+            try {
+                await Promise.resolve(storageAdapter.removeItem(key));
+                lastCacheKey = null;
+                if (tree.__config?.debugMode) {
+                    console.log(`[SignalTree] State cleared from storage key: ${key}`);
+                }
+            }
+            catch (error) {
+                console.error('[SignalTree] Failed to clear state:', error);
+                throw error; // Re-throw for tests to catch
+            }
+        };
+        // Auto-load on creation if enabled
+        if (autoLoad) {
+            // Use setTimeout to avoid blocking initialization and timing issues
+            setTimeout(() => {
+                enhanced.load().catch((error) => {
+                    console.warn('[SignalTree] Auto-load failed:', error);
+                });
+            }, 0);
+        }
+        // Auto-save on updates if enabled
+        if (autoSave) {
+            let saveTimeout;
+            // Hook into state changes to trigger auto-save
+            const triggerAutoSave = () => {
+                // Debounce saves
+                if (saveTimeout) {
+                    clearTimeout(saveTimeout);
+                }
+                saveTimeout = setTimeout(() => {
+                    enhanced.save().catch((error) => {
+                        console.error('[SignalTree] Auto-save failed:', error);
+                    });
+                }, debounceMs);
+            };
+            // Watch for any signal changes in the tree
+            const watchSignals = (obj, path = '') => {
+                if (!obj || typeof obj !== 'object')
+                    return;
+                for (const [key, value] of Object.entries(obj)) {
+                    if (isSignal(value)) {
+                        // Create an effect to watch this signal
+                        const signal = value;
+                        let previousValue = signal();
+                        // Periodically check for changes (this is a simplified approach)
+                        // In a real implementation, you'd want to use Angular's effect() or similar
+                        const checkForChanges = () => {
+                            const currentValue = signal();
+                            if (currentValue !== previousValue) {
+                                previousValue = currentValue;
+                                triggerAutoSave();
+                            }
+                            setTimeout(checkForChanges, 50); // Check every 50ms
+                        };
+                        setTimeout(checkForChanges, 0);
+                    }
+                    else if (value && typeof value === 'object') {
+                        watchSignals(value, path ? `${path}.${key}` : key);
+                    }
+                }
+            };
+            // Start watching signals
+            watchSignals(tree.state);
+            // Store cleanup function for testing
+            enhanced.__flushAutoSave = () => {
+                if (saveTimeout) {
+                    clearTimeout(saveTimeout);
+                    saveTimeout = undefined;
+                    return enhanced.save();
+                }
+                return Promise.resolve();
+            };
+        }
+        return enhanced;
+    }
+    enhancer.metadata = { name: 'persistence' };
+    return enhancer;
+}
+/**
+ * Create a custom storage adapter
+ */
+function createStorageAdapter(getItem, setItem, removeItem) {
+    return { getItem, setItem, removeItem };
+}
+/**
+ * IndexedDB storage adapter for large state trees
+ */
+function createIndexedDBAdapter(dbName = 'SignalTreeDB', storeName = 'states') {
+    let db = null;
+    const openDB = async () => {
+        if (db)
+            return db;
+        return new Promise((resolve, reject) => {
+            const request = indexedDB.open(dbName, 1);
+            request.onerror = () => reject(request.error);
+            request.onsuccess = () => {
+                db = request.result;
+                resolve(db);
+            };
+            request.onupgradeneeded = (event) => {
+                const database = event.target.result;
+                if (!database.objectStoreNames.contains(storeName)) {
+                    database.createObjectStore(storeName);
+                }
+            };
+        });
+    };
+    return {
+        async getItem(key) {
+            const database = await openDB();
+            return new Promise((resolve, reject) => {
+                const transaction = database.transaction([storeName], 'readonly');
+                const store = transaction.objectStore(storeName);
+                const request = store.get(key);
+                request.onerror = () => reject(request.error);
+                request.onsuccess = () => resolve(request.result || null);
+            });
+        },
+        async setItem(key, value) {
+            const database = await openDB();
+            return new Promise((resolve, reject) => {
+                const transaction = database.transaction([storeName], 'readwrite');
+                const store = transaction.objectStore(storeName);
+                const request = store.put(value, key);
+                request.onerror = () => reject(request.error);
+                request.onsuccess = () => resolve();
+            });
+        },
+        async removeItem(key) {
+            const database = await openDB();
+            return new Promise((resolve, reject) => {
+                const transaction = database.transaction([storeName], 'readwrite');
+                const store = transaction.objectStore(storeName);
+                const request = store.delete(key);
+                request.onerror = () => reject(request.error);
+                request.onsuccess = () => resolve();
+            });
+        },
+    };
+}
+// Type-only exports (none)
+/**
+ * Helpers to apply enhancers with explicit typing to avoid depending on
+ * complex `.with()` overload inference in tests and tooling.
+ */
+function applySerialization(tree) {
+    return withSerialization()(tree);
+}
+function applyPersistence(tree, cfg) {
+    return withPersistence(cfg)(tree);
+}
+
+/**
+ * Pre-configured SignalTree configurations for common use cases.
+ *
+ * - **basic**: Minimal configuration with no advanced features
+ * - **performance**: Optimized for speed with batching and memoization
+ * - **development**: Full debugging features including time-travel and devtools
+ * - **production**: Optimized for production with performance features only
+ */
+const TREE_PRESETS = {
+    basic: {
+        batchUpdates: false,
+        useMemoization: false,
+        trackPerformance: false,
+        enableTimeTravel: false,
+        enableDevTools: false,
+        debugMode: false,
+    },
+    performance: {
+        batchUpdates: true,
+        useMemoization: true,
+        trackPerformance: false,
+        enableTimeTravel: false,
+        enableDevTools: false,
+        debugMode: false,
+        useShallowComparison: true,
+        maxCacheSize: 200,
+    },
+    development: {
+        batchUpdates: true,
+        useMemoization: true,
+        trackPerformance: true,
+        enableTimeTravel: true,
+        enableDevTools: true,
+        debugMode: true,
+        maxCacheSize: 100,
+    },
+    production: {
+        batchUpdates: true,
+        useMemoization: true,
+        trackPerformance: false,
+        enableTimeTravel: false,
+        enableDevTools: false,
+        debugMode: false,
+        useShallowComparison: true,
+        maxCacheSize: 200,
+    },
+};
+/**
+ * Helper function to create a tree configuration from a preset.
+ * Can be used to start with a preset and then customize specific options.
+ *
+ * @param preset - The preset name to use as a base
+ * @param overrides - Optional overrides to apply on top of the preset
+ * @returns Complete tree configuration
+ *
+ * @example
+ * ```typescript
+ * // Use development preset with custom tree name
+ * const config = createPresetConfig('development', { treeName: 'MyApp' });
+ *
+ * // Use performance preset but enable debug mode
+ * const debugPerf = createPresetConfig('performance', { debugMode: true });
+ * ```
+ */
+function createPresetConfig(preset, overrides = {}) {
+    const baseConfig = TREE_PRESETS[preset];
+    return {
+        ...baseConfig,
+        ...overrides,
+    };
+}
+/**
+ * Validates that a preset configuration is valid.
+ * Useful for development-time checks.
+ *
+ * @param preset - The preset to validate
+ * @returns True if valid, throws error if invalid
+ */
+function validatePreset(preset) {
+    if (!TREE_PRESETS[preset]) {
+        throw new Error(`Invalid preset: ${preset}. Valid presets are: ${Object.keys(TREE_PRESETS).join(', ')}`);
+    }
+    return true;
+}
+/**
+ * Gets the list of available preset names.
+ *
+ * @returns Array of preset names
+ */
+function getAvailablePresets() {
+    return Object.keys(TREE_PRESETS);
+}
+/**
+ * Creates a custom preset by combining multiple existing presets.
+ * Later presets in the array take precedence over earlier ones.
+ *
+ * @param presets - Array of presets to combine
+ * @param overrides - Optional final overrides
+ * @returns Combined configuration
+ *
+ * @example
+ * ```typescript
+ * // Combine basic preset with some performance features
+ * const config = combinePresets(['basic', 'performance'], { enableDevTools: true });
+ * ```
+ */
+function combinePresets(presets, overrides = {}) {
+    let combined = {};
+    for (const preset of presets) {
+        validatePreset(preset);
+        combined = { ...combined, ...TREE_PRESETS[preset] };
+    }
+    return { ...combined, ...overrides };
+}
+/**
+ * Convenience helper for creating a development-ready SignalTree.
+ * Composes dev-only enhancers (devtools, time-travel, async) into a single
+ * enhancer function that can be applied to a tree. This keeps packages
+ * independent while offering a one-line dev onboarding.
+ */
+function createDevTree(overrides = {}) {
+    const config = createPresetConfig('development', overrides);
+    // Compose enhancers in a predictable left-to-right order. We import the
+    // enhancers lazily so consumers who don't install dev packages won't fail at
+    // module-eval time.
+    const enhancers = [];
+    // Helper to access CommonJS-style require at runtime without forcing Node types
+    function tryRequire(id) {
+        const maybeReq = globalThis.require;
+        if (typeof maybeReq !== 'function')
+            return undefined;
+        try {
+            return maybeReq(id);
+        }
+        catch {
+            return undefined;
+        }
+    }
+    try {
+        const mod = tryRequire('@signaltree/devtools');
+        const withDevtools = mod && (mod.withDevtools ?? mod.withDevTools ?? mod.default ?? mod);
+        if (typeof withDevtools === 'function')
+            enhancers.push(withDevtools);
+    }
+    catch (e) {
+    }
+    try {
+        const mod = tryRequire('@signaltree/time-travel');
+        const withTimeTravel = mod && (mod.withTimeTravel ?? mod.default ?? mod);
+        if (typeof withTimeTravel === 'function')
+            enhancers.push(withTimeTravel);
+    }
+    catch (e) {
+    }
+    const composed = composeEnhancers(...enhancers);
+    return {
+        config,
+        enhancer: composed,
+    };
+}
+
+export { ENHANCER_META, SIGNAL_TREE_CONSTANTS, SIGNAL_TREE_MESSAGES, SecurityPresets, SecurityValidator, TREE_PRESETS, applyPersistence, applySerialization, cleanupMemoizationCache, clearAllCaches, combinePresets, composeEnhancers, createDevTree, createEnhancer, createIndexedDBAdapter, createLazySignalTree, createPresetConfig, createStorageAdapter, enableEntities, enableSerialization, enableTimeTravel, flushBatchedUpdates, getAvailablePresets, getBatchQueueSize, getGlobalCacheStats, getTimeTravel, hasPendingUpdates, isAnySignal, isNodeAccessor$1 as isNodeAccessor, memoize, memoizeReference, memoizeShallow, resolveEnhancerOrder, signalTree, validatePreset, withBatching, withComputedMemoization, withDeepStateMemoization, withEntities, withHighFrequencyMemoization, withHighPerformanceBatching, withHighPerformanceEntities, withHighPerformanceMemoization, withLightweightMemoization, withMemoization, withPersistence, withSelectorMemoization, withSerialization, withShallowMemoization, withTimeTravel };
+//# sourceMappingURL=index.js.map