@memlab/mcp-server 2.0.3 → 2.1.1

package/dist/tools/detached-dom.js

@@ -8,8 +8,8 @@
  * @oncall memory_lab
  */
 import { z } from 'zod';
-import { getSnapshot } from '../heap-state.js';
-import { queryNodes, formatQueryNodesResult, errorResult, textResult, } from '../utils.js';
+import { getSnapshot, getSnapshotEnv } from '../heap-state.js';
+import { queryNodes, formatQueryNodesResult, formatBytes, formatNumber, markdownTable, errorResult, toolResult, } from '../utils.js';
 function isDetachedDOMNode(node) {
     if (node.id <= 3)
         return false;
@@ -17,13 +17,60 @@ function isDetachedDOMNode(node) {
         return true;
     return node.name.startsWith('Detached ');
 }
+function extractElementTag(name) {
+    // V8 names detached DOM as "Detached <div>" or "Detached <div class="...">"
+    const match = name.match(/^(?:Detached\s+)?<(\w+)/);
+    return match ? match[1] : name;
+}
+function extractTestId(node) {
+    // Look for data-testid in the node name (V8 includes attributes)
+    const testIdMatch = node.name.match(/data-testid="([^"]+)"/);
+    if (testIdMatch)
+        return testIdMatch[1];
+    return '(no testid)';
+}
+function getFirstNonFrameworkRetainer(node) {
+    const frameworkNames = new Set([
+        'system / Context',
+        '(GC roots)',
+        '(Strong roots)',
+        '(Builtins)',
+        '(Startup object cache)',
+    ]);
+    let cur = node;
+    const visited = new Set([node.id]);
+    while (cur && cur.hasPathEdge) {
+        const edge = cur.pathEdge;
+        if (!edge)
+            break;
+        const from = edge.fromNode;
+        if (visited.has(from.id))
+            break;
+        visited.add(from.id);
+        if (!frameworkNames.has(from.name) &&
+            !from.name.startsWith('system / ') &&
+            from.type !== 'hidden' &&
+            from.type !== 'array' &&
+            from.type !== 'synthetic' &&
+            from.type !== 'native') {
+            const edgeName = String(edge.name_or_index);
+            return `${from.name} (${from.type}) .${edgeName}`;
+        }
+        cur = from;
+    }
+    return '(unknown)';
+}
 export function registerDetachedDom(server) {
-    server.tool('memlab_detached_dom', 'Find detached DOM elements still retained in memory. These are common sources of memory leaks — DOM nodes removed from the document but kept alive by JavaScript references. Supports count-only and ids-only modes for large result sets.', {
+    server.tool('memlab_detached_dom', 'Find detached DOM elements still retained in memory. These are common sources of memory leaks — DOM nodes removed from the document but kept alive by JavaScript references. Supports count-only and ids-only modes for large result sets. Use group_by to aggregate by element tag, retainer pattern, or data-testid.', {
         output_mode: z
             .enum(['full', 'count', 'ids'])
             .optional()
             .default('full')
             .describe('Output verbosity: "full" returns node summaries (default), "count" returns only the total count, "ids" returns only node IDs'),
+        group_by: z
+            .enum(['element', 'retainer', 'testid'])
+            .optional()
+            .describe('Group detached DOM nodes instead of listing individually. "element" groups by HTML tag (div, span, button), "retainer" groups by first non-framework retainer (the component/module holding them), "testid" groups by data-testid attribute.'),
         offset: z
             .number()
             .optional()
@@ -34,16 +81,115 @@ export function registerDetachedDom(server) {
             .optional()
             .default(20)
             .describe('Maximum number of results (default 20, up to 10000 for ids mode)'),
-    }, async ({ output_mode, offset, limit }) => {
+    }, async ({ output_mode, group_by, offset, limit }) => {
         try {
+            const env = getSnapshotEnv();
+            if (env === 'node') {
+                return toolResult('This is a Node.js snapshot — DOM nodes do not exist in this environment.\n\n' +
+                    'For Node.js memory investigation, try instead:\n' +
+                    '- `memlab_duplicated_strings` — find duplicated string instances\n' +
+                    '- `memlab_closure_inspection` — inspect closure captured variables\n' +
+                    '- `memlab_largest_objects` — find objects consuming the most memory\n' +
+                    '- `memlab_class_histogram` — per-class instance counts and sizes');
+            }
             const snapshot = getSnapshot();
+            if (group_by) {
+                const groups = new Map();
+                let totalDetached = 0;
+                let totalRetainedAll = 0;
+                snapshot.nodes.forEach(node => {
+                    if (!isDetachedDOMNode(node))
+                        return;
+                    totalDetached++;
+                    totalRetainedAll += node.retainedSize;
+                    let key;
+                    switch (group_by) {
+                        case 'element':
+                            key = extractElementTag(node.name);
+                            break;
+                        case 'retainer':
+                            key = getFirstNonFrameworkRetainer(node);
+                            break;
+                        case 'testid':
+                            key = extractTestId(node);
+                            break;
+                    }
+                    const existing = groups.get(key);
+                    if (existing) {
+                        existing.count++;
+                        existing.totalRetained += node.retainedSize;
+                        if (node.retainedSize > existing.maxRetainedSize) {
+                            existing.exampleId = node.id;
+                            existing.maxRetainedSize = node.retainedSize;
+                        }
+                    }
+                    else {
+                        groups.set(key, {
+                            count: 1,
+                            totalRetained: node.retainedSize,
+                            exampleId: node.id,
+                            maxRetainedSize: node.retainedSize,
+                        });
+                    }
+                });
+                if (groups.size === 0) {
+                    return toolResult('No detached DOM nodes found.');
+                }
+                const sorted = [...groups.entries()]
+                    .sort((a, b) => b[1].totalRetained - a[1].totalRetained)
+                    .slice(0, limit);
+                const groupLabel = group_by === 'element'
+                    ? 'Element'
+                    : group_by === 'retainer'
+                        ? 'Retainer'
+                        : 'data-testid';
+                const headers = [
+                    groupLabel,
+                    'Count',
+                    'Total Retained',
+                    '% of Detached',
+                    'Example ID',
+                ];
+                const rightCols = new Set([1, 2, 3]);
+                const rows = sorted.map(([key, stats]) => {
+                    const pct = totalRetainedAll > 0
+                        ? ((stats.totalRetained / totalRetainedAll) * 100).toFixed(1) +
+                            '%'
+                        : '-';
+                    return [
+                        key.length > 60 ? key.slice(0, 57) + '...' : key,
+                        formatNumber(stats.count),
+                        formatBytes(stats.totalRetained),
+                        pct,
+                        `@${stats.exampleId}`,
+                    ];
+                });
+                const lines = [
+                    `Detached DOM grouped by ${group_by}: ${formatNumber(totalDetached)} total nodes, ${formatBytes(totalRetainedAll)} total retained`,
+                    '',
+                    markdownTable(headers, rows, rightCols),
+                ];
+                if (sorted.length > 0) {
+                    lines.push('', `**Suggested action:** Use \`memlab_retainer_summary\` with node_ids from the top group's example to trace the common retention pattern.`);
+                }
+                return toolResult(lines.join('\n'));
+            }
             const effectiveLimit = output_mode === 'ids' ? Math.min(limit, 10000) : Math.min(limit, 500);
             const result = queryNodes(snapshot, isDetachedDOMNode, {
                 limit: effectiveLimit,
                 offset,
                 outputMode: output_mode,
             });
-            return textResult(formatQueryNodesResult(result, offset));
+            const output = formatQueryNodesResult(result, offset);
+            if (result.total_count > 0 && output_mode === 'full') {
+                return toolResult(output +
+                    '\n\n---\n\n' +
+                    '**Suggested action:** Check for missing `removeEventListener` calls, ' +
+                    'React component cleanup in `useEffect` return, or refs not cleared on unmount. ' +
+                    'Use `memlab_retainer_trace` on top entries to find the retention path. ' +
+                    'Use `group_by: "retainer"` to see which components are retaining the most detached DOM.');
+            }
+            return toolResult(output);
         }
         catch (err) {
             return errorResult(err);

package/dist/tools/detached-dom.js.map

@@ -1 +1 @@
-{"version":3,"file":"detached-dom.js","sourceRoot":"","sources":["../../src/tools/detached-dom.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAGH,OAAO,EAAC,CAAC,EAAC,MAAM,KAAK,CAAC;AACtB,OAAO,EAAC,WAAW,EAAC,MAAM,kBAAkB,CAAC;AAE7C,OAAO,EACL,UAAU,EACV,sBAAsB,EACtB,WAAW,EACX,UAAU,GACX,MAAM,aAAa,CAAC;AAGrB,SAAS,iBAAiB,CAAC,IAAe;IACxC,IAAI,IAAI,CAAC,EAAE,IAAI,CAAC;QAAE,OAAO,KAAK,CAAC;IAC/B,IAAI,IAAI,CAAC,WAAW;QAAE,OAAO,IAAI,CAAC;IAClC,OAAO,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC,WAAW,CAAC,CAAC;AAC3C,CAAC;AAED,MAAM,UAAU,mBAAmB,CAAC,MAAiB;IACnD,MAAM,CAAC,IAAI,CACT,qBAAqB,EACrB,4OAA4O,EAC5O;QACE,WAAW,EAAE,CAAC;aACX,IAAI,CAAC,CAAC,MAAM,EAAE,OAAO,EAAE,KAAK,CAAC,CAAC;aAC9B,QAAQ,EAAE;aACV,OAAO,CAAC,MAAM,CAAC;aACf,QAAQ,CACP,8HAA8H,CAC/H;QACH,MAAM,EAAE,CAAC;aACN,MAAM,EAAE;aACR,QAAQ,EAAE;aACV,OAAO,CAAC,CAAC,CAAC;aACV,QAAQ,CAAC,2CAA2C,CAAC;QACxD,KAAK,EAAE,CAAC;aACL,MAAM,EAAE;aACR,QAAQ,EAAE;aACV,OAAO,CAAC,EAAE,CAAC;aACX,QAAQ,CACP,kEAAkE,CACnE;KACJ,EACD,KAAK,EAAE,EAAC,WAAW,EAAE,MAAM,EAAE,KAAK,EAAC,EAAE,EAAE;QACrC,IAAI,CAAC;YACH,MAAM,QAAQ,GAAG,WAAW,EAAE,CAAC;YAC/B,MAAM,cAAc,GAClB,WAAW,KAAK,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC;YAExE,MAAM,MAAM,GAAG,UAAU,CAAC,QAAQ,EAAE,iBAAiB,EAAE;gBACrD,KAAK,EAAE,cAAc;gBACrB,MAAM;gBACN,UAAU,EAAE,WAAyB;aACtC,CAAC,CAAC;YAEH,OAAO,UAAU,CAAC,sBAAsB,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;QAC5D,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,OAAO,WAAW,CAAC,GAAG,CAAC,CAAC;QAC1B,CAAC;IACH,CAAC,CACF,CAAC;AACJ,CAAC"}
+{"version":3,"file":"detached-dom.js","sourceRoot":"","sources":["../../src/tools/detached-dom.ts"],"names":[],"mappings":"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"}

package/dist/tools/diff-snapshots.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ * @format
+ * @oncall memory_lab
+ */
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+export declare function registerDiffSnapshots(server: McpServer): void;
+//# sourceMappingURL=diff-snapshots.d.ts.map

package/dist/tools/diff-snapshots.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"diff-snapshots.d.ts","sourceRoot":"","sources":["../../src/tools/diff-snapshots.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,yCAAyC,CAAC;AAsCvE,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,SAAS,GAAG,IAAI,CAyP7D"}

package/dist/tools/diff-snapshots.js

@@ -0,0 +1,224 @@
+/**
+ * Copyright (c) Meta Platforms, Inc. and affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ * @format
+ * @oncall memory_lab
+ */
+import fs from 'fs';
+import path from 'path';
+import { z } from 'zod';
+import memlabHeapAnalysis from '@memlab/heap-analysis';
+const { getFullHeapFromFile } = memlabHeapAnalysis;
+import { setSnapshot } from '../heap-state.js';
+import { formatBytes, formatNumber, markdownTable, errorResult, toolResult, } from '../utils.js';
+function buildHistogram(snapshot) {
+    const map = new Map();
+    snapshot.nodes.forEach(node => {
+        if (node.id <= 3)
+            return;
+        const key = `${node.type}::${node.name}`;
+        const entry = map.get(key);
+        if (entry) {
+            entry.count++;
+            entry.self_size += node.self_size;
+        }
+        else {
+            map.set(key, { count: 1, self_size: node.self_size });
+        }
+    });
+    return map;
+}
+export function registerDiffSnapshots(server) {
+    server.tool('memlab_diff_snapshots', 'Compare two heap snapshots by class histogram. Shows classes that grew, shrunk, appeared, or disappeared between "before" and "after" snapshots. The "after" snapshot becomes the active snapshot for subsequent analysis.', {
+        before_path: z
+            .string()
+            .describe('Absolute path to the "before" .heapsnapshot file'),
+        after_path: z
+            .string()
+            .describe('Absolute path to the "after" .heapsnapshot file'),
+        limit: z
+            .number()
+            .optional()
+            .default(30)
+            .describe('Maximum rows per section (default 30)'),
+        min_count_delta: z
+            .number()
+            .optional()
+            .default(0)
+            .describe('Minimum absolute change in instance count to show (default 0). Use to filter noise.'),
+        min_size_delta: z
+            .number()
+            .optional()
+            .default(0)
+            .describe('Minimum absolute change in self size (bytes) to show (default 0).'),
+    }, async ({ before_path, after_path, limit, min_count_delta, min_size_delta, }) => {
+        try {
+            const resolvedBefore = path.resolve(before_path);
+            const resolvedAfter = path.resolve(after_path);
+            if (!fs.existsSync(resolvedBefore)) {
+                return errorResult(new Error(`Before file not found: ${resolvedBefore}`));
+            }
+            if (!fs.existsSync(resolvedAfter)) {
+                return errorResult(new Error(`After file not found: ${resolvedAfter}`));
+            }
+            const [beforeSnapshot, afterSnapshot] = await Promise.all([
+                getFullHeapFromFile(resolvedBefore),
+                getFullHeapFromFile(resolvedAfter),
+            ]);
+            const beforeHist = buildHistogram(beforeSnapshot);
+            const afterHist = buildHistogram(afterSnapshot);
+            // Make "after" the active snapshot
+            let afterNodeCount = 0;
+            let afterEdgeCount = 0;
+            let afterTotalSize = 0;
+            afterSnapshot.nodes.forEach(node => {
+                afterNodeCount++;
+                afterTotalSize += node.self_size;
+            });
+            afterSnapshot.edges.forEach(() => {
+                afterEdgeCount++;
+            });
+            let hasWindow = false;
+            let hasModule = false;
+            afterSnapshot.nodes.forEach(node => {
+                if (hasWindow)
+                    return;
+                if (node.name.startsWith('Window ') && node.type === 'object')
+                    hasWindow = true;
+                if (node.name === 'Module' && node.type === 'object' && !hasModule)
+                    hasModule = true;
+            });
+            const afterEnv = hasWindow ? 'browser' : hasModule ? 'node' : 'unknown';
+            setSnapshot(afterSnapshot, after_path, {
+                fileName: path.basename(after_path),
+                nodeCount: afterNodeCount,
+                edgeCount: afterEdgeCount,
+                totalSize: afterTotalSize,
+                env: afterEnv,
+            });
+            // Compute deltas
+            const allKeys = new Set([...beforeHist.keys(), ...afterHist.keys()]);
+            const diffs = [];
+            for (const key of allKeys) {
+                const before = beforeHist.get(key);
+                const after = afterHist.get(key);
+                const bc = before?.count ?? 0;
+                const ac = after?.count ?? 0;
+                const bs = before?.self_size ?? 0;
+                const as_ = after?.self_size ?? 0;
+                const countDelta = ac - bc;
+                const sizeDelta = as_ - bs;
+                if (Math.abs(countDelta) < min_count_delta ||
+                    Math.abs(sizeDelta) < min_size_delta) {
+                    continue;
+                }
+                const parts = key.split('::');
+                diffs.push({
+                    key,
+                    name: parts.slice(1).join('::'),
+                    type: parts[0],
+                    before_count: bc,
+                    after_count: ac,
+                    count_delta: countDelta,
+                    before_size: bs,
+                    after_size: as_,
+                    size_delta: sizeDelta,
+                });
+            }
+            const grew = diffs
+                .filter(d => d.count_delta > 0)
+                .sort((a, b) => b.count_delta - a.count_delta);
+            const shrunk = diffs
+                .filter(d => d.count_delta < 0)
+                .sort((a, b) => a.count_delta - b.count_delta);
+            const lines = [];
+            // Overall summary
+            let totalBeforeNodes = 0;
+            let totalBeforeSize = 0;
+            let totalAfterNodes = 0;
+            let totalAfterSize = 0;
+            beforeHist.forEach(v => {
+                totalBeforeNodes += v.count;
+                totalBeforeSize += v.self_size;
+            });
+            afterHist.forEach(v => {
+                totalAfterNodes += v.count;
+                totalAfterSize += v.self_size;
+            });
+            const nodeDelta = totalAfterNodes - totalBeforeNodes;
+            const sizeDelta = totalAfterSize - totalBeforeSize;
+            const sign = (n) => (n >= 0 ? '+' : '-');
+            lines.push('## Snapshot Comparison');
+            lines.push('');
+            lines.push(`| | Before | After | Delta |`);
+            lines.push(`|---|---:|---:|---:|`);
+            lines.push(`| Nodes | ${formatNumber(totalBeforeNodes)} | ${formatNumber(totalAfterNodes)} | ${sign(nodeDelta)}${formatNumber(Math.abs(nodeDelta))} |`);
+            lines.push(`| Self Size | ${formatBytes(totalBeforeSize)} | ${formatBytes(totalAfterSize)} | ${sign(sizeDelta)}${formatBytes(Math.abs(sizeDelta))} |`);
+            lines.push('');
+            // Grew section
+            if (grew.length > 0) {
+                const headers = [
+                    'Class',
+                    'Type',
+                    'Before',
+                    'After',
+                    'Δ Count',
+                    'Δ Size',
+                ];
+                const rightCols = new Set([2, 3, 4, 5]);
+                const rows = grew
+                    .slice(0, limit)
+                    .map(d => [
+                    d.name,
+                    d.type,
+                    formatNumber(d.before_count),
+                    formatNumber(d.after_count),
+                    `+${formatNumber(d.count_delta)}`,
+                    `${sign(d.size_delta)}${formatBytes(Math.abs(d.size_delta))}`,
+                ]);
+                lines.push(`### Classes that grew (${formatNumber(grew.length)} total, showing ${rows.length})`);
+                lines.push('');
+                lines.push(markdownTable(headers, rows, rightCols));
+                lines.push('');
+            }
+            // Shrunk section
+            if (shrunk.length > 0) {
+                const headers = [
+                    'Class',
+                    'Type',
+                    'Before',
+                    'After',
+                    'Δ Count',
+                    'Δ Size',
+                ];
+                const rightCols = new Set([2, 3, 4, 5]);
+                const rows = shrunk
+                    .slice(0, limit)
+                    .map(d => [
+                    d.name,
+                    d.type,
+                    formatNumber(d.before_count),
+                    formatNumber(d.after_count),
+                    formatNumber(d.count_delta),
+                    `${sign(d.size_delta)}${formatBytes(Math.abs(d.size_delta))}`,
+                ]);
+                lines.push(`### Classes that shrunk (${formatNumber(shrunk.length)} total, showing ${rows.length})`);
+                lines.push('');
+                lines.push(markdownTable(headers, rows, rightCols));
+                lines.push('');
+            }
+            if (grew.length === 0 && shrunk.length === 0) {
+                lines.push('No significant differences found between the two snapshots.');
+            }
+            lines.push(`\n*The "after" snapshot is now active for further analysis.*`);
+            return toolResult(lines.join('\n'));
+        }
+        catch (err) {
+            return errorResult(err);
+        }
+    });
+}
+//# sourceMappingURL=diff-snapshots.js.map

package/dist/tools/diff-snapshots.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"diff-snapshots.js","sourceRoot":"","sources":["../../src/tools/diff-snapshots.ts"],"names":[],"mappings":"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"}

package/dist/tools/dominator-subtree.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"dominator-subtree.d.ts","sourceRoot":"","sources":["../../src/tools/dominator-subtree.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,yCAAyC,CAAC;AAevE,wBAAgB,wBAAwB,CAAC,MAAM,EAAE,SAAS,GAAG,IAAI,CAuEhE"}
+{"version":3,"file":"dominator-subtree.d.ts","sourceRoot":"","sources":["../../src/tools/dominator-subtree.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,yCAAyC,CAAC;AAevE,wBAAgB,wBAAwB,CAAC,MAAM,EAAE,SAAS,GAAG,IAAI,CAsGhE"}

package/dist/tools/dominator-subtree.js

@@ -9,7 +9,7 @@
  */
 import { z } from 'zod';
 import { getSnapshot } from '../heap-state.js';
-import { serializeNodeSummary, isNodeWorthInspecting, formatNodeSummaryTable, formatNodeInline, errorResult, textResult, formatBytes, formatNumber, } from '../utils.js';
+import { serializeNodeSummary, isNodeWorthInspecting, formatNodeSummaryTable, formatNodeInline, errorResult, toolResult, formatBytes, formatNumber, } from '../utils.js';
 export function registerDominatorSubtree(server) {
     server.tool('memlab_dominator_subtree', 'Show the direct children in the dominator tree for a given node — i.e., objects whose retained size is exclusively attributed to this node. These are the objects that would be freed if this node were garbage collected. Useful for understanding what composes a large retained size.', {
         node_id: z.number().describe('The numeric ID of the heap node'),
@@ -56,18 +56,43 @@ export function registerDominatorSubtree(server) {
                     }
                 }
             });
-            const summaries = dominated.map(serializeNodeSummary);
+            let summaries = dominated.map(serializeNodeSummary);
+            if (summaries.length === 0 && totalDominated > 0 && !include_internal) {
+                const internalChildren = [];
+                snapshot.nodes.forEach(node => {
+                    if (node.dominatorNode?.id === node_id && node.id !== node_id) {
+                        const size = node.retainedSize;
+                        let inserted = false;
+                        for (let i = 0; i < internalChildren.length; i++) {
+                            if (size > internalChildren[i].retainedSize) {
+                                internalChildren.splice(i, 0, node);
+                                inserted = true;
+                                break;
+                            }
+                        }
+                        if (!inserted)
+                            internalChildren.push(node);
+                        if (internalChildren.length > limit)
+                            internalChildren.length = limit;
+                    }
+                });
+                summaries = internalChildren.map(serializeNodeSummary);
+            }
+            const autoIncluded = summaries.length > 0 && dominated.length === 0 && !include_internal;
             const lines = [
-                `**${formatNodeInline(targetNode.id, targetNode.name, targetNode.type)}** — retained ${formatBytes(targetNode.retainedSize)}, ${formatNumber(totalDominated)} dominated nodes (showing ${summaries.length})`,
+                `**${formatNodeInline(targetNode.id, targetNode.name, targetNode.type, targetNode.self_size)}** — retained ${formatBytes(targetNode.retainedSize)}, ${formatNumber(totalDominated)} dominated nodes (showing ${summaries.length})`,
                 '',
             ];
+            if (autoIncluded) {
+                lines.push(`_All ${formatNumber(totalDominated)} dominated children are internal/V8 nodes — showing them automatically (pass \`include_internal: true\` to always include)._`, '');
+            }
             if (summaries.length > 0) {
                 lines.push(formatNodeSummaryTable(summaries));
             }
             else {
                 lines.push('No dominated nodes found.');
             }
-            return textResult(lines.join('\n'));
+            return toolResult(lines.join('\n'));
         }
         catch (err) {
             return errorResult(err);

package/dist/tools/dominator-subtree.js.map

@@ -1 +1 @@
-{"version":3,"file":"dominator-subtree.js","sourceRoot":"","sources":["../../src/tools/dominator-subtree.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"dominator-subtree.js","sourceRoot":"","sources":["../../src/tools/dominator-subtree.ts"],"names":[],"mappings":"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"}

package/dist/tools/duplicated-strings.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"duplicated-strings.d.ts","sourceRoot":"","sources":["../../src/tools/duplicated-strings.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,yCAAyC,CAAC;AAKvE,wBAAgB,yBAAyB,CAAC,MAAM,EAAE,SAAS,GAAG,IAAI,CA4EjE"}
+{"version":3,"file":"duplicated-strings.d.ts","sourceRoot":"","sources":["../../src/tools/duplicated-strings.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,yCAAyC,CAAC;AAKvE,wBAAgB,yBAAyB,CAAC,MAAM,EAAE,SAAS,GAAG,IAAI,CA6IjE"}