mutts 1.0.9 → 1.0.11

package/dist/debug.cjs

@@ -1,35 +1,994 @@
 'use strict';
 
-var debug = require('./chunks/index-VTO-b2vR.cjs');
+var proxy = require('./chunks/proxy-Cc79Lrzj.cjs');
 require('./chunks/async-core-CRLKP3l-.cjs');
 
+var _documentCurrentScript = typeof document !== 'undefined' ? document.currentScript : null;
+const lineageObjects = new WeakSet();
+/**
+ * Checks if an object is a lineage object
+ */
+function isLineage(obj) {
+    return obj && typeof obj === 'object' && lineageObjects.has(obj);
+}
+/**
+ * Parses a single stack line into a structured frame.
+ * @param line - A line from Error.stack
+ */
+function parseStackLine(line) {
+    // Node.js format: "    at functionName (file:line:column)"
+    // or "    at file:line:column"
+    const nodeMatch = line.match(/^\s*at\s+(?:(.+?)\s+\()?(?:(.+?):(\d+):(\d+))\)?$/);
+    // Browser format (Firefox/Safari): "functionName@file:line:column" or "file:line:column"
+    // Chrome/Edge use Node-like format but without "at" sometimes or with different prefixes
+    const browserMatch = line.match(/(?:(.+?)(?:\@|\(?))?(?:(.+?):(\d+):(\d+))(?:\@|\)?)$/);
+    const match = nodeMatch || browserMatch;
+    if (!match)
+        return null;
+    const [, functionName = 'anonymous', fileName, lineNumber, columnNumber] = match;
+    return {
+        functionName: functionName.trim(),
+        fileName,
+        lineNumber: parseInt(lineNumber, 10),
+        columnNumber: parseInt(columnNumber, 10),
+        raw: line.trim(),
+    };
+}
+let internalFile;
+/**
+ * Gets the current call stack
+ * @param skipFrames - Number of frames to skip
+ * @param error - Optional error to use as source of stack
+ */
+function getStackFrame(error = new Error()) {
+    if (!error.stack)
+        return [];
+    const lines = error.stack.split('\n');
+    const lastLine = lines.findIndex((line) => line.includes(proxy.effectMarker.enter));
+    if (lastLine !== -1)
+        lines.splice(lastLine);
+    const firstLine = lines.findLastIndex((line) => line.includes(proxy.effectMarker.leave));
+    if (firstLine !== -1)
+        lines.splice(0, firstLine + 1);
+    else {
+        // Dynamically identify the library's internal files if not already done
+        if (!internalFile && lines[1]) {
+            const selfFrame = parseStackLine(lines[1]);
+            if (selfFrame) {
+                internalFile = selfFrame.fileName;
+            }
+        }
+        // Determine the "base" directory of the library to skip other internal files
+        // We look for "src" or "dist" to be more specific than just the project root
+        const srcIndex = internalFile ? internalFile.lastIndexOf('/src/') : -1;
+        const distIndex = internalFile ? internalFile.lastIndexOf('/dist/') : -1;
+        internalFile ? (srcIndex !== -1 ? internalFile.substring(0, srcIndex + 5) :
+            (distIndex !== -1 ? internalFile.substring(0, distIndex + 6) :
+                internalFile.substring(0, internalFile.lastIndexOf('/') + 1))) : undefined;
+        let l;
+        for (l = 1; l < lines.length; l++) {
+            const frame = parseStackLine(lines[l]);
+            if (!frame)
+                continue;
+            // Robust skipping: if we are still in the internal area, skip it.
+            const isInternal = /Lineage$/.test(frame.functionName) ||
+                frame.functionName === 'eval' ||
+                [`getStackFrame`, `captureLineage`].includes(frame.functionName);
+            if (!isInternal)
+                break;
+        }
+        lines.splice(0, l);
+    }
+    return lines.map(parseStackLine).filter(Boolean);
+}
+/**
+ * Traces the lineage of the current execution through nested effects
+ * @param effect - Starting effect (defaults to active effect)
+ */
+function getLineage(effect, currentStack = getStackFrame()) {
+    const currentEffect = effect ?? proxy.getActiveEffect();
+    const segments = [];
+    if (!currentEffect) {
+        segments.push({
+            effect: undefined,
+            effectName: 'root',
+            stack: filterNodeModules(currentStack),
+        });
+        return segments;
+    }
+    let current = currentEffect;
+    let lastStack = currentStack;
+    while (current) {
+        const rootFn = proxy.getRoot(current);
+        // Too aggressive for now
+        //if(!rootFn.name) debugger
+        const filteredStack = filterNodeModules(lastStack);
+        segments.push({
+            effect: rootFn,
+            effectName: rootFn.name || 'anonymous',
+            stack: filteredStack,
+        });
+        // Move to parent
+        const node = proxy.getEffectNode(current);
+        const parent = node.parent;
+        const creationStack = node.creationStack;
+        if (parent) {
+            current = parent;
+            lastStack = creationStack ?? [];
+        }
+        else if (creationStack) {
+            segments.push({
+                effect: undefined,
+                effectName: 'root',
+                stack: filterNodeModules(creationStack),
+            });
+            break;
+        }
+        else {
+            break;
+        }
+    }
+    return segments;
+}
+/**
+ * Filters out node_modules frames and groups them
+ * @param frames - Array of stack frames
+ */
+function filterNodeModules(frames) {
+    const result = [];
+    let inNodeModules = false;
+    for (const frame of frames) {
+        const isNodeModule = frame.fileName.includes('/node_modules/'); //|| frame.fileName.includes('/dist/')
+        if (isNodeModule && !inNodeModules) {
+            // Start of node_modules block
+            inNodeModules = true;
+            result.push({
+                functionName: '...node_modules...',
+                fileName: '[filtered]',
+                lineNumber: 0,
+                columnNumber: 0,
+                raw: '    at ...node_modules...'
+            });
+        }
+        else if (!isNodeModule && inNodeModules) {
+            // End of node_modules block
+            inNodeModules = false;
+            result.push(frame);
+        }
+        else if (!isNodeModule) {
+            // Regular frame
+            result.push(frame);
+        }
+        // Skip frames inside node_modules
+    }
+    return result;
+}
+/**
+ * Formats lineage segments into a single stack-like string
+ * @param segments - Lineage segments
+ */
+function formatLineage(segments) {
+    const result = [];
+    for (let i = 0; i < segments.length; i++) {
+        const segment = segments[i];
+        if (i > 0) {
+            const triggerEffect = segments[i - 1].effect;
+            const triggerName = triggerEffect ? (proxy.getRoot(triggerEffect).name || 'anonymous') : 'root';
+            result.push(` --- effect: ${triggerName} ---`);
+        }
+        for (const frame of segment.stack) {
+            result.push(`    ${frame.raw}`);
+        }
+    }
+    return result.join('\n');
+}
+/**
+ * Logs lineage segments to console with grouping
+ * @param segments - Lineage segments
+ */
+function logLineage(segments) {
+    console.groupCollapsed(`🦴 Effect Lineage Trace (${segments.length} segment${segments.length === 1 ? '' : 's'})`);
+    for (let i = 0; i < segments.length; i++) {
+        const segment = segments[i];
+        // Add segment header
+        const isLast = i === segments.length - 1;
+        const prefix = i === 0 ? '📍' : isLast ? '└─' : '├─';
+        console.groupCollapsed(`${prefix} Effect:`, segment.effect ? segment.effect.name || 'anonymous' : 'root');
+        // Add stack frames
+        for (let j = 0; j < segment.stack.length; j++) {
+            const frame = segment.stack[j];
+            const isLastFrame = j === segment.stack.length - 1;
+            const framePrefix = isLastFrame ? '└─' : '├─';
+            if (frame.functionName === '...node_modules...') {
+                console.log(`%c${framePrefix} ${frame.functionName}`, 'color: #888; font-style: italic;');
+            }
+            else {
+                const fnStyle = frame.functionName === 'anonymous' ? 'color: #888;' : 'color: #1a7f37; font-weight: bold;';
+                const fileStyle = 'color: #0550ae;';
+                console.log(`%c${framePrefix} %c${frame.functionName} %c(${frame.fileName}:${frame.lineNumber}:${frame.columnNumber})`, 'color: #888;', fnStyle, fileStyle);
+            }
+        }
+        console.groupEnd();
+    }
+    console.groupEnd();
+}
+/**
+ * Captures and logs lineage to console
+ */
+function captureNodeLineage() {
+    logLineage(getLineage());
+}
+/**
+ * Custom formatter for Chrome DevTools to render lineage data nicely.
+ */
+const lineageFormatter = {
+    header: (obj) => {
+        if (isLineage(obj)) {
+            // Try to detect DevTools theme - default to dark colors if uncertain
+            const isDark = typeof window !== 'undefined' && window.matchMedia?.('(prefers-color-scheme: dark)').matches;
+            const headerColor = isDark ? '#cd9d5d' : '#704214';
+            return [
+                'span',
+                { style: `color: ${headerColor}; font-weight: bold;` },
+                `🦴 Effect Lineage (${obj.segments.length} segments)`,
+            ];
+        }
+        return null;
+    },
+    hasBody: (obj) => isLineage(obj),
+    body: (obj) => {
+        if (!isLineage(obj))
+            return null;
+        const segments = obj.segments;
+        // Try to detect DevTools theme
+        const isDark = typeof window !== 'undefined' && window.matchMedia?.('(prefers-color-scheme: dark)').matches;
+        const colors = isDark ? {
+            frameText: '#ccc',
+            functionName: '#ffffff',
+            segmentBg: '#2d2d2d',
+        } : {
+            frameText: '#555',
+            functionName: '#222',
+            segmentBg: '#eee',
+        };
+        const children = segments.map((segment, i) => {
+            const frames = segment.stack.map((frame) => [
+                'div',
+                { style: `margin-left: 20px; color: ${colors.frameText}; font-family: monospace; font-size: 11px;` },
+                ['span', { style: `color: ${colors.functionName};` }, `at ${frame.functionName} `],
+                ['span', {}, `${frame.fileName}:${frame.lineNumber}:${frame.columnNumber}`],
+            ]);
+            segment.effect;
+            const segmentHeader = [
+                'div',
+                { style: `margin-top: 5px; padding: 2px 5px; background: ${colors.segmentBg}; border-radius: 3px; font-weight: bold;` },
+                i === 0 ? '📍 Current: ' : '↖ Effect: ',
+                segment.effect?.name || 'anonymous',
+                segment.effect ? ['object', { object: segment.effect }] : 'root',
+            ];
+            return ['div', {}, segmentHeader, ...frames];
+        });
+        return ['div', { style: 'padding: 5px; line-height: 1.4;' }, ...children];
+    },
+};
+/**
+ * Wraps lineage data in a way that the Chrome Formatter can recognize.
+ */
+function wrapLineageForDebug(segments) {
+    const lineage = {
+        segments,
+        toString: () => formatLineage(segments ?? getLineage()),
+    };
+    lineageObjects.add(lineage);
+    return lineage;
+}
 
+/**
+ * Displays a floating reactive panel in the browser showing the lineage of triggered effects.
+ */
+function showLineagePanel() {
+    if (typeof document === 'undefined')
+        return;
+    // Detect color scheme preference
+    const isDarkMode = window.matchMedia && window.matchMedia('(prefers-color-scheme: dark)').matches;
+    // Color schemes
+    const colors = isDarkMode ? {
+        panelBg: 'rgba(30, 30, 30, 0.95)',
+        panelBorder: '#444',
+        headerBg: '#8B4513',
+        headerText: '#ffffff',
+        closeBtn: '#ffffff',
+        placeholderText: '#999',
+        segmentBorder: '#8B4513',
+        titleText: '#ffffff',
+        frameText: '#ccc',
+        atText: '#888',
+        linkText: '#58a6ff',
+    } : {
+        panelBg: 'rgba(255, 255, 255, 0.95)',
+        panelBorder: '#ddd',
+        headerBg: '#704214',
+        headerText: '#ffffff',
+        closeBtn: '#ffffff',
+        placeholderText: '#666',
+        segmentBorder: '#704214',
+        titleText: '#222',
+        frameText: '#555',
+        atText: '#999',
+        linkText: '#005cc5',
+    };
+    const state = proxy.reactive({
+        activeLineage: [],
+        isVisible: true,
+    });
+    // onEffectTrigger tracks "this effect" (here nothing) — not useful for a global panel.
+    // Would need zone-based events to track all triggers. Panel is cosmetic/experimental (260206).
+    // UI Creation
+    const panel = document.createElement('div');
+    panel.id = 'mutts-lineage-panel';
+    Object.assign(panel.style, {
+        position: 'fixed',
+        bottom: '20px',
+        right: '20px',
+        width: '400px',
+        maxHeight: '80vh',
+        backgroundColor: colors.panelBg,
+        backdropFilter: 'blur(10px)',
+        border: `1px solid ${colors.panelBorder}`,
+        borderRadius: '12px',
+        boxShadow: '0 10px 25px rgba(0,0,0,0.15)',
+        zIndex: '999999',
+        fontFamily: 'Inter, system-ui, sans-serif',
+        fontSize: '12px',
+        display: 'flex',
+        flexDirection: 'column',
+        overflow: 'hidden',
+        transition: 'opacity 0.3s, transform 0.3s',
+    });
+    const header = document.createElement('div');
+    Object.assign(header.style, {
+        padding: '12px 16px',
+        background: colors.headerBg,
+        color: colors.headerText,
+        fontWeight: '600',
+        display: 'flex',
+        justifyContent: 'space-between',
+        alignItems: 'center',
+        cursor: 'grab',
+    });
+    header.innerHTML = '<span><span style="font-size: 14px; margin-right: 5px;">🦴</span> Mutts Lineage</span>';
+    const closeBtn = document.createElement('button');
+    closeBtn.innerText = '×';
+    Object.assign(closeBtn.style, {
+        background: 'none',
+        border: 'none',
+        color: colors.closeBtn,
+        fontSize: '20px',
+        cursor: 'pointer',
+        padding: '0 5px',
+    });
+    closeBtn.onclick = () => {
+        state.isVisible = false;
+    };
+    header.appendChild(closeBtn);
+    panel.appendChild(header);
+    const content = document.createElement('div');
+    Object.assign(content.style, {
+        padding: '16px',
+        overflowY: 'auto',
+        flex: '1',
+    });
+    panel.appendChild(content);
+    document.body.appendChild(panel);
+    // Reactivity: Update Visibility
+    proxy.effect(() => {
+        panel.style.opacity = state.isVisible ? '1' : '0';
+        panel.style.pointerEvents = state.isVisible ? 'all' : 'none';
+        panel.style.transform = state.isVisible ? 'translateY(0)' : 'translateY(20px)';
+    });
+    // Reactivity: Update Content
+    proxy.effect(() => {
+        if (state.activeLineage.length === 0) {
+            content.innerHTML = `<div style="color: ${colors.placeholderText}; font-style: italic; text-align: center; margin-top: 20px;">No effect triggered yet...</div>`;
+            return;
+        }
+        content.innerHTML = '';
+        state.activeLineage.forEach((segment, i) => {
+            const segDiv = document.createElement('div');
+            Object.assign(segDiv.style, {
+                marginBottom: '16px',
+                borderLeft: `2px solid ${colors.segmentBorder}`,
+                paddingLeft: '12px',
+            });
+            const title = document.createElement('div');
+            Object.assign(title.style, {
+                fontWeight: 'bold',
+                marginBottom: '6px',
+                color: colors.titleText,
+            });
+            const effectName = segment.effect ? (proxy.getRoot(segment.effect).name || 'anonymous') : 'root';
+            title.innerText = i === 0 ? `📍 Current: ${effectName}` : `↖ Effect: ${effectName}`;
+            segDiv.appendChild(title);
+            segment.stack.forEach(frame => {
+                const frameDiv = document.createElement('div');
+                Object.assign(frameDiv.style, {
+                    color: colors.frameText,
+                    marginBottom: '3px',
+                    fontSize: '11px',
+                    whiteSpace: 'nowrap',
+                    overflow: 'hidden',
+                    textOverflow: 'ellipsis',
+                    cursor: 'pointer',
+                });
+                frameDiv.title = frame.raw;
+                frameDiv.innerHTML = `<span style="color: ${colors.atText}">at</span> ${frame.functionName} <span style="color: ${colors.linkText}; text-decoration: underline;">(${frame.fileName.split('/').pop()}:${frame.lineNumber})</span>`;
+                segDiv.appendChild(frameDiv);
+            });
+            content.appendChild(segDiv);
+        });
+    });
+}
 
-exports.buildReactivityGraph = debug.buildReactivityGraph;
-exports.captureNodeLineage = debug.captureNodeLineage;
-exports.debugOptions = debug.debugOptions;
-exports.effectMarker = debug.effectMarker;
-exports.enableDevTools = debug.enableDevTools;
-exports.forceEnableGraphTracking = debug.forceEnableGraphTracking;
-exports.formatLineage = debug.formatLineage;
-exports.getDependencies = debug.getDependencies;
-exports.getDependencyGraph = debug.getDependencyGraph;
-exports.getDependents = debug.getDependents;
-exports.getLineage = debug.getLineage;
-exports.getMutationHistory = debug.getMutationHistory;
-exports.getStackFrame = debug.getStackFrame;
-exports.getTriggerChain = debug.getTriggerChain;
-exports.isDevtoolsEnabled = debug.isDevtoolsEnabled;
-exports.lineageFormatter = debug.lineageFormatter;
-exports.logError = debug.logError;
-exports.nodeLineage = debug.nodeLineage;
-exports.nodeLineageLegacy = debug.nodeLineageLegacy;
-exports.parseStackLine = debug.parseStackLine;
-exports.recordTriggerLink = debug.recordTriggerLink;
-exports.registerEffectForDebug = debug.registerEffectForDebug;
-exports.registerObjectForDebug = debug.registerObjectForDebug;
-exports.setEffectName = debug.setEffectName;
-exports.setObjectName = debug.setObjectName;
-exports.showLineagePanel = debug.showLineagePanel;
-exports.wrapLineageForDebug = debug.wrapLineageForDebug;
+/**
+ * Debug utilities for the reactivity system
+ * - Captures effect metadata (names, parent relationships)
+ * - Records cause → consequence edges with object/prop labels
+ * - Provides graph data for tooling (DevTools panel, etc.)
+ */
+/**
+ * Log an error with detailed context if error logging is enabled
+ */
+function logError(error, context, effect) {
+    if (!proxy.options.introspection?.logErrors)
+        return;
+    const contextStr = context === 'throw' ? '🔴 Thrown' : '🟡 Caught';
+    console.group(`${contextStr} Error: ${error.message}`);
+    console.error('Error:', error);
+    // Try to get effect name if available
+    if (effect && typeof effect === 'object' && effect.name) {
+        console.log('Effect:', effect.name);
+    }
+    console.groupEnd();
+}
+// Log initialization for debugging
+const EXTERNAL_SOURCE = Symbol('external-source');
+let devtoolsEnabled = false;
+// Registry for debugging (populated lazily when DevTools are enabled)
+const debugEffectRegistry = new Set();
+const debugObjectRegistry = new Set();
+// Human-friendly names
+const effectNames = new WeakMap();
+const objectNames = new WeakMap();
+let effectCounter = 0;
+let objectCounter = 0;
+const triggerGraph = new Map();
+function ensureEffectName(effect) {
+    let name = effectNames.get(effect);
+    if (!name) {
+        const root = proxy.getRoot(effect);
+        name = root?.name?.trim() || `effect_${++effectCounter}`;
+    }
+    effectNames.set(effect, name);
+    return name;
+}
+function ensureObjectName(obj) {
+    let name = objectNames.get(obj);
+    if (!name) {
+        // Try Symbol.toStringTag first (standard way to customize object string representation)
+        const toStringTag = obj?.[Symbol.toStringTag];
+        const ctorName = obj?.constructor?.name;
+        const base = toStringTag || (ctorName && ctorName !== 'Object' ? ctorName : 'object');
+        name = `${base}_${++objectCounter}`;
+        objectNames.set(obj, name);
+    }
+    return name;
+}
+function describeProp(obj, prop) {
+    const objectName = ensureObjectName(obj);
+    if (prop === proxy.allProps)
+        return `${objectName}.*`;
+    if (typeof prop === 'symbol')
+        return `${objectName}.${prop.description ?? prop.toString()}`;
+    return `${objectName}.${String(prop)}`;
+}
+function addEffectToRegistry(effect) {
+    if (!effect || debugEffectRegistry.has(effect))
+        return;
+    debugEffectRegistry.add(effect);
+    const deps = proxy.effectToReactiveObjects.get(effect);
+    if (deps) {
+        for (const obj of deps) {
+            documentObject(obj);
+        }
+    }
+}
+function documentObject(obj) {
+    if (!debugObjectRegistry.has(obj)) {
+        dbRegisterObject(obj);
+    }
+}
+function dbRegisterObject(obj) {
+    debugObjectRegistry.add(obj);
+    ensureObjectName(obj);
+}
+function ensureParentChains(effects) {
+    const queue = Array.from(effects);
+    for (let i = 0; i < queue.length; i++) {
+        const effect = queue[i];
+        const parent = proxy.getEffectNode(effect).parent;
+        if (parent && !effects.has(parent)) {
+            effects.add(parent);
+            queue.push(parent);
+        }
+    }
+}
+function ensureTriggerContainers(source) {
+    let targetMap = triggerGraph.get(source);
+    if (!targetMap) {
+        targetMap = new Map();
+        triggerGraph.set(source, targetMap);
+    }
+    return targetMap;
+}
+function ensureTriggerRecord(source, target, label, obj, prop, evolution) {
+    const targetMap = ensureTriggerContainers(source);
+    let labelMap = targetMap.get(target);
+    if (!labelMap) {
+        labelMap = new Map();
+        targetMap.set(target, labelMap);
+    }
+    let record = labelMap.get(label);
+    if (!record) {
+        record = { label, object: obj, prop, evolution, count: 0, lastTriggered: Date.now() };
+        labelMap.set(label, record);
+    }
+    return record;
+}
+/**
+ * Assign a debug-friendly name to an effect (shown in DevTools)
+ */
+function setEffectName(effect, name) {
+    effectNames.set(effect, name);
+}
+/**
+ * Assign a debug-friendly name to a reactive object
+ */
+function setObjectName(obj, name) {
+    objectNames.set(obj, name);
+    debugObjectRegistry.add(obj);
+}
+/**
+ * Register an effect so it appears in the DevTools graph
+ */
+function registerEffectForDebug(effect) {
+    if (!effect || !devtoolsEnabled)
+        return;
+    addEffectToRegistry(effect);
+}
+/**
+ * Register a reactive object so it appears in the DevTools graph
+ */
+function registerObjectForDebug(obj) {
+    if (!devtoolsEnabled)
+        return;
+    documentObject(obj);
+}
+/**
+ * Records a cause → consequence relationship between effects.
+ * @param source - The effect performing the write (undefined if external/user input)
+ * @param target - The effect that re-ran because of the write
+ * @param obj - The reactive object that changed
+ * @param prop - The property that changed
+ * @param evolution - The type of change (set/add/del/bunch)
+ */
+function recordTriggerLink(source, target, obj, prop, evolution) {
+    if (proxy.options.introspection?.enableHistory) {
+        addToMutationHistory(source, target, obj, prop, evolution);
+    }
+    if (!devtoolsEnabled)
+        return;
+    addEffectToRegistry(target);
+    if (source)
+        addEffectToRegistry(source);
+    const descriptor = describeProp(obj, prop);
+    const record = ensureTriggerRecord(source ?? EXTERNAL_SOURCE, target, descriptor, obj, prop, evolution);
+    record.count += 1;
+    record.lastTriggered = Date.now();
+    documentObject(obj);
+}
+/**
+ * Traces back the chain of triggers that led to a specific effect
+ * @param effect The effect to trace back
+ * @param limit Max depth
+ */
+function getTriggerChain(effect, limit = 5) {
+    const chain = [];
+    let current = effect;
+    for (let i = 0; i < limit; i++) {
+        // Find who triggered 'current'
+        // We need to reverse search the triggerGraph (source -> target)
+        // This is expensive O(Edges) but okay for error reporting
+        let foundSource;
+        let foundReason = '';
+        search: for (const [source, targetMap] of triggerGraph) {
+            for (const [target, labelMap] of targetMap) {
+                if (target === current) {
+                    // Found a source! Use the most recent trigger record
+                    let lastTime = 0;
+                    for (const record of labelMap.values()) {
+                        if (record.lastTriggered > lastTime) {
+                            lastTime = record.lastTriggered;
+                            foundReason = record.label;
+                            foundSource = source === EXTERNAL_SOURCE ? undefined : source;
+                        }
+                    }
+                    if (foundSource || foundReason)
+                        break search;
+                }
+            }
+        }
+        if (foundSource) {
+            chain.push(`${ensureEffectName(foundSource)} -> (${foundReason}) -> ${ensureEffectName(current)}`);
+            current = foundSource;
+        }
+        else if (foundReason) {
+            chain.push(`External -> (${foundReason}) -> ${ensureEffectName(current)}`);
+            break;
+        }
+        else {
+            break;
+        }
+    }
+    return chain.reverse();
+}
+function buildEffectNodes(allEffects) {
+    const nodes = [];
+    const nodeByEffect = new Map();
+    const ordered = Array.from(allEffects);
+    for (const effect of ordered) {
+        const label = ensureEffectName(effect);
+        const node = {
+            id: `effect_${nodes.length}`,
+            label,
+            type: 'effect',
+            depth: 0,
+            debugName: label,
+        };
+        nodes.push(node);
+        nodeByEffect.set(effect, node);
+    }
+    const depthCache = new Map();
+    const computeDepth = (effect) => {
+        if (!effect)
+            return 0;
+        const cached = depthCache.get(effect);
+        if (cached !== undefined)
+            return cached;
+        const parent = proxy.getEffectNode(effect).parent;
+        const depth = computeDepth(parent) + (parent ? 1 : 0);
+        depthCache.set(effect, depth);
+        return depth;
+    };
+    for (const [effect, node] of nodeByEffect) {
+        node.depth = computeDepth(effect);
+        const parent = proxy.getEffectNode(effect).parent;
+        if (parent) {
+            const parentNode = nodeByEffect.get(parent);
+            if (parentNode) {
+                node.parentId = parentNode.id;
+            }
+        }
+    }
+    return { nodes, nodeByEffect };
+}
+/**
+ * Builds a graph representing current reactive state (effects, objects, and trigger edges)
+ */
+function buildReactivityGraph() {
+    const nodes = [];
+    const edges = [];
+    const nodeIds = new Map();
+    const allEffects = new Set(debugEffectRegistry);
+    ensureParentChains(allEffects);
+    const { nodes: effectNodes, nodeByEffect } = buildEffectNodes(allEffects);
+    for (const node of effectNodes)
+        nodes.push(node);
+    for (const [effect, node] of nodeByEffect) {
+        nodeIds.set(effect, node.id);
+    }
+    // Object nodes (optional, used for dependency inspection)
+    for (const obj of debugObjectRegistry) {
+        const id = `object_${nodes.length}`;
+        nodes.push({ id, label: ensureObjectName(obj), type: 'state', debugName: objectNames.get(obj) });
+        nodeIds.set(obj, id);
+    }
+    // External source node (user/system outside of effects)
+    if (triggerGraph.has(EXTERNAL_SOURCE)) {
+        const externalId = `effect_external`;
+        nodes.push({ id: externalId, label: 'External', type: 'external', depth: 0 });
+        nodeIds.set(EXTERNAL_SOURCE, externalId);
+    }
+    // Dependency edges (effect → object)
+    for (const effect of allEffects) {
+        const effectId = nodeIds.get(effect);
+        if (!effectId)
+            continue;
+        const deps = proxy.effectToReactiveObjects.get(effect);
+        if (!deps)
+            continue;
+        for (const obj of deps) {
+            const objId = nodeIds.get(obj);
+            if (!objId)
+                continue;
+            edges.push({
+                id: `${effectId}->${objId}`,
+                source: effectId,
+                target: objId,
+                type: 'dependency',
+                label: 'depends',
+            });
+        }
+    }
+    // Cause edges (effect/object/prop → effect)
+    for (const [source, targetMap] of triggerGraph) {
+        for (const [targetEffect, labelMap] of targetMap) {
+            const targetId = nodeIds.get(targetEffect);
+            if (!targetId)
+                continue;
+            const sourceId = nodeIds.get(source);
+            if (!sourceId)
+                continue;
+            for (const record of labelMap.values()) {
+                edges.push({
+                    id: `${sourceId}->${targetId}:${record.label}`,
+                    source: sourceId,
+                    target: targetId,
+                    type: 'cause',
+                    label: record.count > 1 ? `${record.label} (${record.count})` : record.label,
+                    count: record.count,
+                });
+            }
+        }
+    }
+    return {
+        nodes,
+        edges,
+        meta: {
+            generatedAt: Date.now(),
+            devtoolsEnabled,
+        },
+    };
+}
+const captureLineage = () => wrapLineageForDebug(getLineage());
+/**
+ * Enables the DevTools bridge and exposes the debug API on window/global.
+ * Call as early as possible in development builds.
+ */
+function enableDevTools() {
+    const globalScope = (typeof globalThis !== 'undefined'
+        ? globalThis
+        : typeof window !== 'undefined'
+            ? window
+            : typeof global !== 'undefined'
+                ? global
+                : undefined);
+    if (!globalScope)
+        return;
+    if (devtoolsEnabled)
+        return;
+    devtoolsEnabled = true;
+    if (proxy.options.introspection) {
+        proxy.options.introspection.logErrors = true;
+    }
+    globalScope.__MUTTS_DEBUG__ = {
+        getGraph: buildReactivityGraph,
+        logLineage(tag) {
+            logLineage(getLineage());
+            return '🦴 Effect Lineage Trace' + (tag ? ` (${tag})` : '');
+        },
+        get browserLineage() {
+            return captureLineage();
+        },
+        getLineage,
+        captureLineage: getStackFrame,
+        formatLineage,
+        showLineagePanel,
+        setEffectName,
+        setObjectName,
+        registerEffect: registerEffectForDebug,
+        registerObject: registerObjectForDebug,
+    };
+    // @ts-ignore - devtoolsFormatters is a Chrome-specific array
+    if (globalScope.devtoolsFormatters) {
+        globalScope.devtoolsFormatters.push(lineageFormatter);
+    }
+    else {
+        globalScope.devtoolsFormatters = [lineageFormatter];
+    }
+    proxy.setDebugHooks({
+        isDevtoolsEnabled: () => devtoolsEnabled,
+        registerEffect: registerEffectForDebug,
+        getTriggerChain: getTriggerChain,
+        captureStack: getStackFrame,
+        captureLineage,
+        formatStack: (stack) => {
+            if (typeof stack === 'string') {
+                return [
+                    `\n    ${stack
+                        .split('\n')
+                        .slice(1)
+                        .map((l) => l.trim())
+                        .join('\n    ')}`,
+                ];
+            }
+            if (isLineage(stack)) {
+                return ['\n', stack];
+            }
+            return ['\n', stack];
+        },
+        recordTriggerLink: recordTriggerLink,
+        decorateError: (error, trigger) => {
+            if (proxy.options.introspection?.logErrors &&
+                error &&
+                typeof error === 'object' &&
+                'stack' in error &&
+                !('lineage' in error)) {
+                const lineage = getLineage(trigger, getStackFrame(error));
+                error.lineage = wrapLineageForDebug(lineage);
+            }
+        },
+    });
+    const originalWarn = proxy.options.warn;
+    proxy.options.warn = (...args) => {
+        const lineage = captureLineage();
+        originalWarn(...args, lineage);
+    };
+}
+function forceEnableGraphTracking() {
+    devtoolsEnabled = true;
+}
+function isDevtoolsEnabled() {
+    return devtoolsEnabled;
+}
+/**
+ * Returns the raw dependency graph data structure.
+ * This is useful for programmatic analysis of the reactive system.
+ */
+function getDependencyGraph() {
+    return {
+        nodes: buildReactivityGraph().nodes,
+        edges: buildReactivityGraph().edges,
+    };
+}
+/**
+ * Capture a complete snapshot of the current reactive state
+ */
+function snapshot() {
+    return {
+        graph: getDependencyGraph(),
+        history: getMutationHistory(),
+        timestamp: Date.now(),
+    };
+}
+/**
+ * Returns a list of effects that depend on the given object.
+ */
+function getDependents(obj) {
+    const dependents = [];
+    // Scan the trigger graph for effects triggered by this object
+    // This is O(E) where E is the number of edges, might need optimization for large graphs
+    // but acceptable for introspection
+    for (const [_source, targetMap] of triggerGraph) {
+        for (const [targetEffect, labelMap] of targetMap) {
+            for (const record of labelMap.values()) {
+                if (record.object === obj) {
+                    dependents.push(targetEffect);
+                }
+            }
+        }
+    }
+    // Also check direct dependencies (dependency graph)
+    // We don't have a direct obj -> effect map without walking all effects
+    // unless we use `watchers` from tracking.ts but that's internal
+    return [...new Set(dependents)];
+}
+/**
+ * Returns a list of objects that the given effect depends on.
+ */
+function getDependencies(effect) {
+    const deps = proxy.effectToReactiveObjects.get(effect);
+    return deps ? Array.from(deps) : [];
+}
+const mutationHistory = [];
+let mutationCounter = 0;
+function addToMutationHistory(source, target, obj, prop, evolution) {
+    const record = {
+        id: ++mutationCounter,
+        timestamp: Date.now(),
+        source: source ? ensureEffectName(source) : 'External',
+        target: ensureEffectName(target),
+        objectName: ensureObjectName(obj),
+        prop: String(prop),
+        type: evolution.type,
+    };
+    mutationHistory.push(record);
+    if (mutationHistory.length > (proxy.options.introspection?.historySize ?? 50)) {
+        mutationHistory.shift();
+    }
+}
+/**
+ * Get the recent mutation history
+ */
+function getMutationHistory() {
+    return [...mutationHistory];
+}
+// --- Auto DevTools Initialization ---
+// Automatically enable devtools in development environments
+/**
+ * Checks if we're in a development environment
+ * Detection order:
+ * 1. process.env.NODE_ENV (Node.js)
+ * 2. import.meta.env.DEV (Vite)
+ * 3. import.meta.env.PROD === false (Vite alternative)
+ * 4. Assumes development if none of the above are set (safe default)
+ */
+function isDevelopmentMode() {
+    // Check for explicit production flag first
+    if (typeof process !== 'undefined' && process.env?.NODE_ENV === 'production') {
+        return false;
+    }
+    // Check for Vite's DEV flag
+    if (typeof ({ url: (typeof document === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('debug.cjs', document.baseURI).href)) }) !== 'undefined') {
+        const meta = ({ url: (typeof document === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('debug.cjs', document.baseURI).href)) });
+        if (meta.env?.PROD === true) {
+            return false;
+        }
+        if (meta.env?.DEV === true) {
+            return true;
+        }
+    }
+    // Check for custom global override
+    if (typeof globalThis !== 'undefined' && '__MUTTS_DEV_MODE__' in globalThis) {
+        return globalThis.__MUTTS_DEV_MODE__ !== false;
+    }
+    // Default to development (safer to enable in dev than disable in prod)
+    return true;
+}
+// Auto-enable devtools when the module loads in development
+if (isDevelopmentMode() && !devtoolsEnabled) {
+    enableDevTools();
+    // Optional: Log that devtools were enabled (only in development)
+    if (typeof console !== 'undefined' && console.info) {
+        // Do not log these in when mode === 'test'
+        console.info('🦴 Mutts DevTools enabled automatically in development mode');
+    }
+}
+
+exports.buildReactivityGraph = buildReactivityGraph;
+exports.captureLineage = captureLineage;
+exports.captureNodeLineage = captureNodeLineage;
+exports.enableDevTools = enableDevTools;
+exports.forceEnableGraphTracking = forceEnableGraphTracking;
+exports.formatLineage = formatLineage;
+exports.getDependencies = getDependencies;
+exports.getDependencyGraph = getDependencyGraph;
+exports.getDependents = getDependents;
+exports.getLineage = getLineage;
+exports.getMutationHistory = getMutationHistory;
+exports.getStackFrame = getStackFrame;
+exports.getTriggerChain = getTriggerChain;
+exports.isDevtoolsEnabled = isDevtoolsEnabled;
+exports.isLineage = isLineage;
+exports.lineageFormatter = lineageFormatter;
+exports.logError = logError;
+exports.logLineage = logLineage;
+exports.parseStackLine = parseStackLine;
+exports.recordTriggerLink = recordTriggerLink;
+exports.registerEffectForDebug = registerEffectForDebug;
+exports.registerObjectForDebug = registerObjectForDebug;
+exports.setEffectName = setEffectName;
+exports.setObjectName = setObjectName;
+exports.showLineagePanel = showLineagePanel;
+exports.snapshot = snapshot;
+exports.wrapLineageForDebug = wrapLineageForDebug;
 //# sourceMappingURL=debug.cjs.map