@memlab/mcp-server 2.1.1 → 2.18.1

package/dist/tools/search-strings.js

@@ -0,0 +1,182 @@
+/**
+ * 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 { z } from 'zod';
+import { getSnapshot } from '../heap-state.js';
+import { formatBytes, formatNumber, markdownTable, errorResult, toolResult, } from '../utils.js';
+export function registerSearchStrings(server) {
+    server.tool('memlab_search_strings', 'Search the content (stringValue) of all string nodes in the heap snapshot. ' +
+        'Unlike memlab_search_nodes which searches by node name/class, this searches the ' +
+        'actual text content of strings. Essential for finding string constants (error messages, ' +
+        'event names, config keys, URLs) and tracing them back to their origin. ' +
+        'Supports exact substring match and regex patterns. ' +
+        "⚠ Full-heap scan over every string's content — slow on very large heaps (millions of nodes); use a specific pattern and a small limit.", {
+        pattern: z
+            .string()
+            .describe('The search pattern. Plain text for substring match, or prefix with "/" for regex ' +
+            '(e.g., "/change:ack.*directPath/i" for case-insensitive regex).'),
+        limit: z
+            .number()
+            .optional()
+            .default(20)
+            .describe('Maximum number of matching strings to return (default 20)'),
+        min_length: z
+            .number()
+            .optional()
+            .default(0)
+            .describe('Minimum string length to search (default 0). Use to skip short strings.'),
+        max_length: z
+            .number()
+            .optional()
+            .describe('Maximum string length to search. Use to skip very large strings for faster results.'),
+        show_referrers: z
+            .boolean()
+            .optional()
+            .default(true)
+            .describe('Show which objects reference each matching string (default true). Disable for faster results when you only need the string values.'),
+    }, async ({ pattern, limit, min_length, max_length, show_referrers }) => {
+        try {
+            const snapshot = getSnapshot();
+            let regex = null;
+            let substring = null;
+            if (pattern.startsWith('/') && pattern.lastIndexOf('/') > 0) {
+                const lastSlash = pattern.lastIndexOf('/');
+                const regexPattern = pattern.slice(1, lastSlash);
+                const flags = pattern.slice(lastSlash + 1);
+                regex = new RegExp(regexPattern, flags);
+            }
+            else {
+                substring = pattern;
+            }
+            const matches = [];
+            let scannedCount = 0;
+            let totalStringNodes = 0;
+            snapshot.nodes.forEach(node => {
+                if (node.id <= 3)
+                    return;
+                if (!node.isString)
+                    return;
+                totalStringNodes++;
+                const strNode = node.toStringNode();
+                if (!strNode)
+                    return;
+                const val = strNode.stringValue;
+                if (val.length < min_length)
+                    return;
+                if (max_length != null && val.length > max_length)
+                    return;
+                scannedCount++;
+                let isMatch = false;
+                if (regex) {
+                    isMatch = regex.test(val);
+                }
+                else if (substring) {
+                    isMatch = val.includes(substring);
+                }
+                if (!isMatch)
+                    return;
+                const size = node.retainedSize;
+                let inserted = false;
+                for (let i = 0; i < matches.length; i++) {
+                    if (size > matches[i].retainedSize) {
+                        matches.splice(i, 0, {
+                            nodeId: node.id,
+                            stringValue: val,
+                            selfSize: node.self_size,
+                            retainedSize: size,
+                            nodeType: node.type,
+                            nodeName: node.name,
+                        });
+                        inserted = true;
+                        break;
+                    }
+                }
+                if (!inserted)
+                    matches.push({
+                        nodeId: node.id,
+                        stringValue: val,
+                        selfSize: node.self_size,
+                        retainedSize: size,
+                        nodeType: node.type,
+                        nodeName: node.name,
+                    });
+                if (matches.length > limit)
+                    matches.length = limit;
+            });
+            const patternDesc = regex ? `regex ${pattern}` : `"${pattern}"`;
+            if (matches.length === 0) {
+                return toolResult(`No strings matching ${patternDesc} found.\n\n` +
+                    `Scanned ${formatNumber(scannedCount)} of ${formatNumber(totalStringNodes)} string nodes` +
+                    (min_length > 0 ? ` (filtered to length >= ${min_length})` : '') +
+                    '.\n\n' +
+                    '**Try:**\n' +
+                    '- Use a shorter or less specific pattern\n' +
+                    '- Use regex for flexible matching: `/partial.*match/i`\n' +
+                    '- Remove min_length/max_length filters\n' +
+                    '- Use `memlab_duplicated_strings` if looking for repeated strings');
+            }
+            const lines = [
+                `## String Content Search`,
+                `Found ${formatNumber(matches.length)} string(s) matching ${patternDesc} (scanned ${formatNumber(scannedCount)} of ${formatNumber(totalStringNodes)} string nodes)`,
+                '',
+            ];
+            const headers = ['ID', 'Preview', 'Length', 'Self Size', 'Retained'];
+            const rightCols = new Set([2, 3, 4]);
+            const rows = matches.map(m => {
+                const preview = m.stringValue.length > 80
+                    ? m.stringValue.slice(0, 77) + '...'
+                    : m.stringValue;
+                return [
+                    `@${m.nodeId}`,
+                    `"${preview.replace(/\n/g, '\\n').replace(/\|/g, '\\|')}"`,
+                    formatNumber(m.stringValue.length),
+                    formatBytes(m.selfSize),
+                    formatBytes(m.retainedSize),
+                ];
+            });
+            lines.push(markdownTable(headers, rows, rightCols));
+            if (show_referrers && matches.length > 0) {
+                lines.push('');
+                lines.push('**Referrer context for top matches:**');
+                for (const m of matches.slice(0, 5)) {
+                    const node = snapshot.getNodeById(m.nodeId);
+                    if (!node)
+                        continue;
+                    const referrers = [];
+                    let count = 0;
+                    for (const edge of node.referrers) {
+                        if (count >= 3)
+                            break;
+                        if (edge.fromNode.id <= 3)
+                            continue;
+                        referrers.push(`\`${String(edge.name_or_index)}\` on @${edge.fromNode.id} \`${edge.fromNode.name}\``);
+                        count++;
+                    }
+                    if (referrers.length > 0) {
+                        const preview = m.stringValue.length > 40
+                            ? m.stringValue.slice(0, 37) + '...'
+                            : m.stringValue;
+                        lines.push(`- @${m.nodeId} "${preview.replace(/\n/g, '\\n')}": ${referrers.join(', ')}`);
+                    }
+                }
+            }
+            lines.push('');
+            lines.push('**Suggested next steps:**');
+            const top = matches[0];
+            lines.push(`- Inspect string: \`memlab_get_string(${top.nodeId})\` for full value`);
+            lines.push(`- Trace retention: \`memlab_retainer_trace(${top.nodeId})\``);
+            lines.push(`- Find duplicates: \`memlab_retainer_summary\` with \`node_ids\` from matching strings`);
+            return toolResult(lines.join('\n'));
+        }
+        catch (err) {
+            return errorResult(err);
+        }
+    });
+}
+//# sourceMappingURL=search-strings.js.map

package/dist/tools/search-strings.js.map

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

package/dist/tools/sequence-analysis.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 registerSequenceAnalysis(server: McpServer): void;
+//# sourceMappingURL=sequence-analysis.d.ts.map

package/dist/tools/sequence-analysis.d.ts.map

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

package/dist/tools/sequence-analysis.js

@@ -0,0 +1,244 @@
+/**
+ * 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 { z } from 'zod';
+import memlabHeapAnalysis from '@memlab/heap-analysis';
+const { getFullHeapFromFile } = memlabHeapAnalysis;
+import { resolveSnapshotPath } from './load-snapshot.js';
+import { formatBytes, formatNumber, markdownTable, errorResult, toolResult, } from '../utils.js';
+// A class key is "<type>::<name>". Value-named string "classes" (literal
+// values used as the name, e.g. "554", "1780525701808.81", "o:10,add") are
+// noise across a sequence — drop them like diff_snapshots does (§10).
+function isNoiseClass(type, name) {
+    if (type !== 'string' && type !== 'concatenated string')
+        return false;
+    if (name.length < 8)
+        return true;
+    if (/^[\s\d.,:+-]*$/.test(name))
+        return true;
+    return false;
+}
+function buildHistogram(snapshot) {
+    const hist = new Map();
+    let nodeCount = 0;
+    let totalSize = 0;
+    snapshot.nodes.forEach(node => {
+        nodeCount++;
+        totalSize += node.self_size;
+        if (node.id <= 3)
+            return;
+        const key = `${node.type}::${node.name}`;
+        const e = hist.get(key);
+        if (e) {
+            e.count++;
+            e.selfSize += node.self_size;
+        }
+        else {
+            hist.set(key, { count: 1, selfSize: node.self_size });
+        }
+    });
+    return { hist, nodeCount, totalSize };
+}
+function classifyTrend(counts) {
+    let up = true;
+    let down = true;
+    for (let i = 1; i < counts.length; i++) {
+        if (counts[i] <= counts[i - 1])
+            up = false;
+        if (counts[i] >= counts[i - 1])
+            down = false;
+    }
+    const net = counts[counts.length - 1] - counts[0];
+    if (up && net > 0)
+        return 'monotonic-up';
+    if (down && net < 0)
+        return 'monotonic-down';
+    if (net > 0)
+        return 'grew-net';
+    return 'flat-or-mixed';
+}
+export function registerSequenceAnalysis(server) {
+    server.tool('memlab_sequence_analysis', 'Trend analysis across an ORDERED sequence of >=2 heap snapshots (the canonical "is anything growing unboundedly?" tool). Loads each snapshot transiently (does NOT change your active snapshot), builds per-class histograms, and reports each class\'s value at every step plus a growth verdict: "monotonic-up" (grew every step — strongest leak signal) vs "grew-net" (grew overall but not every step — often GC/navigation noise) vs flat/shrank. Also lists classes new since the baseline. Paths may be local, manifold:// URLs, or bare filenames.', {
+        paths: z
+            .array(z.string())
+            .min(2)
+            .describe('Ordered list of >=2 snapshot paths (oldest first). Each may be a local absolute path, a manifold:// URL, or a bare snapshot filename.'),
+        limit: z
+            .number()
+            .optional()
+            .default(25)
+            .describe('Maximum number of growing classes to report (default 25).'),
+        min_growth_count: z
+            .number()
+            .optional()
+            .default(50)
+            .describe('Only report classes whose net instance-count growth is at least this (default 50).'),
+        monotonic_only: z
+            .boolean()
+            .optional()
+            .default(false)
+            .describe('Report only classes that grew at EVERY step (default false: include grew-net too, flagged).'),
+        max_file_size_mb: z
+            .number()
+            .optional()
+            .default(900)
+            .describe('Per-file size ceiling (default 900) to avoid OOM.'),
+    }, async ({ paths, limit, min_growth_count, monotonic_only, max_file_size_mb, }) => {
+        try {
+            const steps = [];
+            for (const p of paths) {
+                let local;
+                let fetchedFrom = null;
+                try {
+                    const r = resolveSnapshotPath(p);
+                    local = r.localPath;
+                    fetchedFrom = r.fetchedFrom;
+                }
+                catch (e) {
+                    return errorResult(new Error(`Failed to resolve "${p}": ${e instanceof Error ? e.message : String(e)}`));
+                }
+                if (!fs.existsSync(local)) {
+                    return errorResult(new Error(`File not found: ${local}`));
+                }
+                const sizeMB = fs.statSync(local).size / (1024 * 1024);
+                if (sizeMB > max_file_size_mb) {
+                    return errorResult(new Error(`${p} is ${sizeMB.toFixed(0)} MB — exceeds max_file_size_mb (${max_file_size_mb}).`));
+                }
+                // Load sequentially and drop the graph before the next one so only
+                // one full graph is resident at a time (memory-safe for big heaps).
+                const snapshot = await getFullHeapFromFile(local);
+                const { hist, nodeCount, totalSize } = buildHistogram(snapshot);
+                steps.push({
+                    label: fetchedFrom ?? p.replace(/^.*\//, ''),
+                    hist,
+                    nodeCount,
+                    totalSize,
+                });
+            }
+            const n = steps.length;
+            const first = steps[0].hist;
+            const last = steps[n - 1].hist;
+            // Union of non-noise class keys.
+            const keys = new Set();
+            for (const s of steps) {
+                for (const k of s.hist.keys()) {
+                    const sep = k.indexOf('::');
+                    const type = k.slice(0, sep);
+                    const name = k.slice(sep + 2);
+                    if (!isNoiseClass(type, name))
+                        keys.add(k);
+                }
+            }
+            const rows = [];
+            for (const k of keys) {
+                const counts = steps.map(s => s.hist.get(k)?.count ?? 0);
+                const sizes = steps.map(s => s.hist.get(k)?.selfSize ?? 0);
+                const netCount = counts[n - 1] - counts[0];
+                const netSize = sizes[n - 1] - sizes[0];
+                if (netCount < min_growth_count)
+                    continue;
+                const trend = classifyTrend(counts);
+                if (monotonic_only && trend !== 'monotonic-up')
+                    continue;
+                if (trend !== 'monotonic-up' && trend !== 'grew-net')
+                    continue;
+                rows.push({ key: k, counts, netCount, netSize, trend });
+            }
+            // Monotonic growers first, then by net size delta.
+            rows.sort((a, b) => {
+                if (a.trend !== b.trend)
+                    return a.trend === 'monotonic-up' ? -1 : 1;
+                return b.netSize - a.netSize;
+            });
+            const top = rows.slice(0, limit);
+            const lines = [
+                `## Sequence / Trend Analysis (${n} snapshots)`,
+                '',
+            ];
+            // Per-step heap totals.
+            const totalHeaders = ['Step', 'Snapshot', 'Nodes', 'Heap (self)'];
+            const totalRows = steps.map((s, i) => [
+                String(i + 1),
+                s.label.length > 40 ? '…' + s.label.slice(-39) : s.label,
+                formatNumber(s.nodeCount),
+                formatBytes(s.totalSize),
+            ]);
+            lines.push(markdownTable(totalHeaders, totalRows, new Set([2, 3])));
+            const heapNet = steps[n - 1].totalSize - steps[0].totalSize;
+            lines.push('', `Overall heap self-size ${heapNet >= 0 ? 'grew' : 'shrank'} by ${formatBytes(Math.abs(heapNet))} across the sequence.`, '');
+            if (top.length === 0) {
+                lines.push(`No classes grew by >= ${formatNumber(min_growth_count)} instances across the sequence. Heap looks flat-to-shrinking — no unbounded-growth signal.`);
+                return toolResult(lines.join('\n'));
+            }
+            lines.push('### Growing classes', '');
+            const headers = [
+                'Class',
+                'Type',
+                ...steps.map((_, i) => `#${i + 1}`),
+                'Δ count',
+                'Δ size',
+                'Verdict',
+            ];
+            const rightCols = new Set();
+            for (let i = 2; i < headers.length - 1; i++)
+                rightCols.add(i);
+            const tableRows = top.map(r => {
+                const sep = r.key.indexOf('::');
+                const type = r.key.slice(0, sep);
+                const name = r.key.slice(sep + 2);
+                const verdict = r.trend === 'monotonic-up'
+                    ? '↑ every step (LEAK signal)'
+                    : 'grew net (noisy)';
+                return [
+                    name.length > 36 ? name.slice(0, 33) + '…' : name,
+                    type,
+                    ...r.counts.map(c => formatNumber(c)),
+                    `+${formatNumber(r.netCount)}`,
+                    `${r.netSize >= 0 ? '+' : ''}${formatBytes(r.netSize)}`,
+                    verdict,
+                ];
+            });
+            lines.push(markdownTable(headers, tableRows, rightCols));
+            // New-since-baseline classes (absent at step 1, present at step N).
+            const newClasses = [];
+            for (const k of keys) {
+                if (!first.has(k) && last.has(k)) {
+                    const c = last.get(k)?.count ?? 0;
+                    if (c >= min_growth_count) {
+                        const sep = k.indexOf('::');
+                        newClasses.push(`${k.slice(sep + 2)} (${formatNumber(c)})`);
+                    }
+                }
+            }
+            if (newClasses.length > 0) {
+                lines.push('', '### New since baseline', '', newClasses.slice(0, 20).join(', ') +
+                    (newClasses.length > 20
+                        ? `, … +${newClasses.length - 20} more`
+                        : ''));
+            }
+            // "heap number" is V8's node for a captured numeric value. It only
+            // appears when the snapshot was taken with numeric-value capture on
+            // (Chrome's captureNumericValue / the browser MCP's capture_numeric_value
+            // option). In that mode V8 emits one node per distinct number, which
+            // both ~3x inflates the graph and shows up here as a top "↑ every step"
+            // grower — a capture artifact, not a real leak. Flag it so it isn't
+            // mistaken for the leak signal.
+            if (top.some(r => r.key === 'number::heap number')) {
+                lines.push('', '> ⚠️ `heap number` is growing. This is almost always a **capture artifact** from taking snapshots with numeric-value capture enabled (one graph node per distinct number), not a real leak. Re-capture with numeric values OFF (browser MCP `capture_numeric_value: false`) for a ~3x smaller, faster, cleaner graph, and disregard `heap number` growth here.');
+            }
+            lines.push('', '_"↑ every step" is the strong unbounded-growth signal; "grew net (noisy)" often reflects GC timing or navigation and warrants a closer look before treating as a leak. Object-identity matching across snapshots is not available (node ids differ per capture) — to localize a specific growing collection, load the last snapshot and use `memlab_cache_analysis` / `memlab_event_listener_leaks` / `memlab_growth_signals`._');
+            return toolResult(lines.join('\n'));
+        }
+        catch (err) {
+            return errorResult(err);
+        }
+    });
+}
+//# sourceMappingURL=sequence-analysis.js.map

package/dist/tools/sequence-analysis.js.map

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

package/dist/tools/server-status.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 registerServerStatus(server: McpServer): void;
+//# sourceMappingURL=server-status.d.ts.map

package/dist/tools/server-status.d.ts.map

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

package/dist/tools/server-status.js

@@ -0,0 +1,41 @@
+/**
+ * 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 { listSnapshots, getCurrentHandle } from '../heap-state.js';
+import { formatBytes, formatNumber, errorResult, textResult } from '../utils.js';
+export function registerServerStatus(server) {
+    server.tool('memlab_server_status', 'Cheap liveness/health check: returns instantly with the server process RSS, uptime, and the resident snapshots. Use it to confirm the server is responsive (vs. stuck behind a heavy scan) and to watch RSS against the snapshot-size ceiling. Scan tools are time-budgeted (timeout_ms) so a heavy scan returns cleanly instead of wedging the server; if a call ever seems hung, this check should still answer immediately.', {}, async () => {
+        try {
+            const mem = process.memoryUsage();
+            const uptimeS = Math.round(process.uptime());
+            const all = listSnapshots();
+            const cur = getCurrentHandle();
+            const lines = [
+                '## memlab server status',
+                '',
+                `- Status: ready`,
+                `- Uptime: ${uptimeS}s`,
+                `- Process RSS: ${formatBytes(mem.rss)} (heapUsed ${formatBytes(mem.heapUsed)} / heapTotal ${formatBytes(mem.heapTotal)})`,
+                `- Resident snapshots: ${all.length}`,
+            ];
+            for (const m of all) {
+                lines.push(`  ${m.handle === cur ? '→' : ' '} ${m.handle} — ${m.fileName}, ${formatBytes(m.totalSize)}, ${formatNumber(m.nodeCount)} nodes`);
+            }
+            if (all.length === 0) {
+                lines.push('  (none loaded — use memlab_load_snapshot)');
+            }
+            lines.push('', '_Tip: full-heap scan tools (search_nodes, find_by_property, global_variables) accept timeout_ms and return partial results rather than hanging. If RSS approaches your --max-old-space-size, unload snapshots with memlab_snapshots(action:"unload")._', '_Recovery: if a prior long/interrupted call left the server unresponsive (even trivial calls hang), starting a FRESH server instance fully recovers it — restart the MCP server and reload the snapshot._');
+            return textResult(lines.join('\n'));
+        }
+        catch (err) {
+            return errorResult(err);
+        }
+    });
+}
+//# sourceMappingURL=server-status.js.map

package/dist/tools/server-status.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"server-status.js","sourceRoot":"","sources":["../../src/tools/server-status.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAGH,OAAO,EAAC,aAAa,EAAE,gBAAgB,EAAC,MAAM,kBAAkB,CAAC;AACjE,OAAO,EAAC,WAAW,EAAE,YAAY,EAAE,WAAW,EAAE,UAAU,EAAC,MAAM,aAAa,CAAC;AAE/E,MAAM,UAAU,oBAAoB,CAAC,MAAiB;IACpD,MAAM,CAAC,IAAI,CACT,sBAAsB,EACtB,gaAAga,EACha,EAAE,EACF,KAAK,IAAI,EAAE;QACT,IAAI,CAAC;YACH,MAAM,GAAG,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC;YAClC,MAAM,OAAO,GAAG,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;YAC7C,MAAM,GAAG,GAAG,aAAa,EAAE,CAAC;YAC5B,MAAM,GAAG,GAAG,gBAAgB,EAAE,CAAC;YAC/B,MAAM,KAAK,GAAG;gBACZ,yBAAyB;gBACzB,EAAE;gBACF,iBAAiB;gBACjB,aAAa,OAAO,GAAG;gBACvB,kBAAkB,WAAW,CAAC,GAAG,CAAC,GAAG,CAAC,cAAc,WAAW,CAAC,GAAG,CAAC,QAAQ,CAAC,gBAAgB,WAAW,CAAC,GAAG,CAAC,SAAS,CAAC,GAAG;gBAC1H,yBAAyB,GAAG,CAAC,MAAM,EAAE;aACtC,CAAC;YACF,KAAK,MAAM,CAAC,IAAI,GAAG,EAAE,CAAC;gBACpB,KAAK,CAAC,IAAI,CACR,KAAK,CAAC,CAAC,MAAM,KAAK,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC,MAAM,MAAM,CAAC,CAAC,QAAQ,KAAK,WAAW,CAAC,CAAC,CAAC,SAAS,CAAC,KAAK,YAAY,CAAC,CAAC,CAAC,SAAS,CAAC,QAAQ,CACjI,CAAC;YACJ,CAAC;YACD,IAAI,GAAG,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;gBACrB,KAAK,CAAC,IAAI,CAAC,4CAA4C,CAAC,CAAC;YAC3D,CAAC;YACD,KAAK,CAAC,IAAI,CACR,EAAE,EACF,wPAAwP,EACxP,2MAA2M,CAC5M,CAAC;YACF,OAAO,UAAU,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC;QACtC,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,OAAO,WAAW,CAAC,GAAG,CAAC,CAAC;QAC1B,CAAC;IACH,CAAC,CACF,CAAC;AACJ,CAAC"}

package/dist/tools/shape-histogram.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"shape-histogram.d.ts","sourceRoot":"","sources":["../../src/tools/shape-histogram.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,yCAAyC,CAAC;AA4BvE,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,SAAS,GAAG,IAAI,CA+H9D"}
+{"version":3,"file":"shape-histogram.d.ts","sourceRoot":"","sources":["../../src/tools/shape-histogram.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,yCAAyC,CAAC;AAmCvE,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,SAAS,GAAG,IAAI,CA2L9D"}