@houwert/conductor 0.13.1 → 0.14.0

package/dist/commands/memory.js

@@ -1,9 +1,28 @@
 "use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.HELP = void 0;
 exports.memory = memory;
-exports.HELP = `  memory [<appId>]                    Show device + app memory usage and object counts`;
+exports.HELP = `  memory [<appId>]                    Show device + app memory usage
+    --objects                           Include per-class object counts (iOS: heap; slower)
+    --leaks                             Run leak detection (iOS only; slow, can pause the app)
+    --all                               Shorthand for --objects --leaks
+    --top <n>                           Limit object/region tables (default 20)
+    --save <name>                       Save the report as a snapshot
+    --diff <name>                       Diff snapshot <name> vs current
+    --diff <name> --vs <other>          Diff two saved snapshots
+    --snapshots                         List saved snapshots
+    --no-gc                             Skip the pre-measurement GC (web only)
+    --filter <regex>                    Filter object/class tables by name (regex)
+    --growth-only                       In diff output, only show positive deltas (leak-hunting)
+    --json                              Emit JSON instead of formatted text`;
+const node_fs_1 = require("node:fs");
+const node_path_1 = __importDefault(require("node:path"));
+const node_os_1 = __importDefault(require("node:os"));
 const runner_js_1 = require("../runner.js");
+const sdk_js_1 = require("../android/sdk.js");
 const session_js_1 = require("../session.js");
 const foreground_app_js_1 = require("./foreground-app.js");
 const output_js_1 = require("../output.js");
@@ -11,6 +30,7 @@ const bootstrap_js_1 = require("../drivers/bootstrap.js");
 const ios_js_1 = require("../drivers/ios.js");
 const android_js_1 = require("../drivers/android.js");
 const web_js_1 = require("../drivers/web.js");
+const hprof_js_1 = require("./hprof.js");
 async function resolveDeviceId(sessionName) {
     if (sessionName !== 'default')
         return sessionName;
@@ -60,7 +80,6 @@ function parseAndroidDumpsysMeminfo(out) {
     const pidMatch = out.match(/\*\* MEMINFO in pid (\d+)/);
     const pid = pidMatch ? Number(pidMatch[1]) : undefined;
     // App Summary block — most useful, single-line entries with KB values.
-    // e.g. "       Java Heap:    12345"
     const summary = out.match(/App Summary[\s\S]*?(?:\n\s*\n|TOTAL:)/);
     if (summary) {
         const block = summary[0];
@@ -85,25 +104,14 @@ function parseAndroidDumpsysMeminfo(out) {
         if (totalSwap)
             app['totalSwapBytes'] = Number(totalSwap[1]) * 1024;
     }
-    // Fallback: TOTAL line in the main table — "TOTAL  12345  ..."
     if (app.totalPssBytes === undefined) {
         const total = out.match(/^\s*TOTAL\s+(\d+)/m);
         if (total)
             app.totalPssBytes = Number(total[1]) * 1024;
     }
-    // Objects block:
-    //  Objects
-    //         Views:        3   ViewRootImpl:        1
-    //     AppContexts:        2     Activities:        1
-    //          Assets:        7  AssetManagers:        0
-    //   Local Binders:        5  Proxy Binders:       17
-    //   Parcel memory:        1     Parcel count:        4
-    //    Death Recipients:    0   OpenSSL Sockets:    0
-    //            WebViews:    0
     const objSection = out.match(/Objects[\s\S]*?(?:\n\s*\n|SQL\s|DATABASES|$)/);
     if (objSection) {
         const text = objSection[0];
-        // Capture every "Label: number" pair (labels may have spaces).
         const re = /([A-Za-z][A-Za-z _]*?):\s+(\d+)/g;
         let m;
         while ((m = re.exec(text)) !== null) {
@@ -115,9 +123,57 @@ function parseAndroidDumpsysMeminfo(out) {
     }
     return { app, objects, pid };
 }
-async function collectAndroid(deviceId, appId) {
+function parseAndroidUnreachable(out) {
+    // dumpsys meminfo --unreachable <pid> output:
+    //   Unreachable memory:
+    //     1234 bytes in 5 unreachable allocations
+    //     ABI: 'arm64'
+    //
+    //     192 bytes unreachable at 12abcdef
+    //      first 32 bytes of contents:
+    //      ...
+    //      #00 pc 000... /system/lib64/libc.so (malloc+24)
+    //      #01 pc 000... /data/app/.../lib/libfoo.so (foo_init+32)
+    const summary = out.match(/(\d+)\s+bytes?\s+in\s+(\d+)\s+unreachable\s+allocations?/i);
+    const totalBytes = summary ? Number(summary[1]) : 0;
+    const totalCount = summary ? Number(summary[2]) : 0;
+    // Aggregate by the most-specific (last user) library frame in each backtrace.
+    // System libs (libc, liblog, libart) are usually the immediate allocator —
+    // the user library a frame or two up tells us what's actually leaking.
+    const byClass = new Map();
+    const blocks = out.split(/(?=^\s*\d+\s+bytes?\s+unreachable\s+at)/m);
+    for (const block of blocks) {
+        const head = block.match(/^\s*(\d+)\s+bytes?\s+unreachable\s+at/m);
+        if (!head)
+            continue;
+        const size = Number(head[1]);
+        // Find first non-libc/-liblog/-libart frame in the backtrace.
+        const frames = [...block.matchAll(/#\d+\s+pc\s+\S+\s+(\/\S+?\.so)\s+\(([^)+]+)/g)];
+        let owner = '<unknown>';
+        for (const f of frames) {
+            const lib = f[1];
+            const sym = f[2];
+            if (/lib(c|m|art|log|dl|cutils)\.so$/.test(lib))
+                continue;
+            owner = `${sym}  [${lib.split('/').pop()}]`;
+            break;
+        }
+        if (owner === '<unknown>' && frames[0]) {
+            owner = `${frames[0][2]}  [${frames[0][1].split('/').pop()}]`;
+        }
+        const prev = byClass.get(owner) ?? { count: 0, bytes: 0 };
+        prev.count += 1;
+        prev.bytes += size;
+        byClass.set(owner, prev);
+    }
+    const classes = [...byClass.entries()]
+        .map(([cls, v]) => ({ class: cls, count: v.count, bytes: v.bytes }))
+        .sort((a, b) => b.bytes - a.bytes);
+    return { totalCount, totalBytes, classes };
+}
+async function collectAndroid(deviceId, appId, opts) {
     const report = { platform: 'android', deviceId, appId, notes: [] };
-    const meminfo = await (0, runner_js_1.spawnCommand)('adb', ['-s', deviceId, 'shell', 'cat', '/proc/meminfo']);
+    const meminfo = await (0, runner_js_1.spawnCommand)((0, sdk_js_1.resolveAndroidTool)('adb'), ['-s', deviceId, 'shell', 'cat', '/proc/meminfo'], { env: (0, sdk_js_1.androidSpawnEnv)() });
     if (meminfo.success) {
         const sys = parseAndroidMeminfo(meminfo.stdout);
         report.system = {
@@ -131,7 +187,7 @@ async function collectAndroid(deviceId, appId) {
         report.notes.push(`/proc/meminfo unavailable: ${meminfo.stderr.trim()}`);
     }
     if (appId) {
-        const dump = await (0, runner_js_1.spawnCommand)('adb', ['-s', deviceId, 'shell', 'dumpsys', 'meminfo', appId]);
+        const dump = await (0, runner_js_1.spawnCommand)((0, sdk_js_1.resolveAndroidTool)('adb'), ['-s', deviceId, 'shell', 'dumpsys', 'meminfo', appId], { env: (0, sdk_js_1.androidSpawnEnv)() });
         if (dump.success && !dump.stdout.includes('No process found')) {
             const { app, objects, pid } = parseAndroidDumpsysMeminfo(dump.stdout);
             report.app = app;
@@ -141,6 +197,80 @@ async function collectAndroid(deviceId, appId) {
         else {
             report.notes.push(`dumpsys meminfo ${appId} returned no data — app may not be running`);
         }
+        // --leaks → dumpsys meminfo --unreachable <pid>. Requires root on stock
+        // images; on user builds it returns "Unreachable memory check not supported".
+        if (opts.leaks && report.pid) {
+            const unreach = await (0, runner_js_1.spawnCommand)('adb', [
+                '-s',
+                deviceId,
+                'shell',
+                'dumpsys',
+                'meminfo',
+                '--unreachable',
+                String(report.pid),
+            ]);
+            if (unreach.success && unreach.stdout.includes('Unreachable memory:')) {
+                report.leaks = parseAndroidUnreachable(unreach.stdout);
+            }
+            else if (unreach.stdout.includes('not supported')) {
+                report.notes.push('dumpsys --unreachable not supported on this build (needs userdebug/root).');
+            }
+            else {
+                report.notes.push(`--unreachable unavailable: ${unreach.stderr.trim() || 'no output'}`);
+            }
+        }
+        // --objects → trigger `am dumpheap` and pull the .hprof. We don't parse
+        // HPROF binary; the file is meant to be opened in Android Studio's Memory
+        // Profiler. The path is recorded so it shows up in the report notes.
+        if (opts.objects && report.pid) {
+            const ts = new Date().toISOString().replace(/[:.]/g, '-');
+            const remote = `/data/local/tmp/conductor-${appId}-${ts}.hprof`;
+            const dumpRes = await (0, runner_js_1.spawnCommand)('adb', [
+                '-s',
+                deviceId,
+                'shell',
+                'am',
+                'dumpheap',
+                String(report.pid),
+                remote,
+            ]);
+            if (dumpRes.success) {
+                await new Promise((r) => setTimeout(r, 1500)); // dumpheap is async; wait for flush
+                const localDir = node_path_1.default.join(node_os_1.default.homedir(), '.conductor', 'heap-dumps');
+                await node_fs_1.promises.mkdir(localDir, { recursive: true });
+                const localFile = node_path_1.default.join(localDir, node_path_1.default.basename(remote));
+                const pull = await (0, runner_js_1.spawnCommand)('adb', ['-s', deviceId, 'pull', remote, localFile]);
+                if (pull.success) {
+                    await (0, runner_js_1.spawnCommand)('adb', ['-s', deviceId, 'shell', 'rm', remote]);
+                    // Parse the HPROF binary for per-class instance counts/bytes — same
+                    // shape as iOS `heap` and Web V8 snapshot output, so it slots into
+                    // the existing snapshot/diff workflow.
+                    try {
+                        const buf = await node_fs_1.promises.readFile(localFile);
+                        const { classes, totals, heaps } = (0, hprof_js_1.parseHprof)(buf);
+                        if (classes.length > 0)
+                            report.objectClasses = classes;
+                        report.heapTotals = totals;
+                        const heapsNote = heaps
+                            ? '  ' +
+                                Object.entries(heaps)
+                                    .map(([h, v]) => `${h}: ${v.count.toLocaleString()} obj / ${(v.bytes / 1048576).toFixed(1)} MB`)
+                                    .join(', ')
+                            : '';
+                        report.notes.push(`Heap dump saved → ${localFile}${heapsNote}  (also openable in Android Studio: Profiler → Memory → Import Heap Dump)`);
+                    }
+                    catch (err) {
+                        report.notes.push(`Heap dump saved → ${localFile} but parse failed: ${err instanceof Error ? err.message : String(err)}`);
+                    }
+                }
+                else {
+                    report.notes.push(`adb pull heap dump failed: ${pull.stderr.trim()}`);
+                }
+            }
+            else {
+                report.notes.push(`am dumpheap failed: ${dumpRes.stderr.trim()}`);
+            }
+        }
     }
     if (report.notes.length === 0)
         delete report.notes;
@@ -148,7 +278,6 @@ async function collectAndroid(deviceId, appId) {
 }
 // ── iOS / tvOS ────────────────────────────────────────────────────────────────
 function parseVmStat(out) {
-    // vm_stat output uses "page size of 16384 bytes" and counts in pages.
     const pageMatch = out.match(/page size of (\d+)/);
     const pageSize = pageMatch ? Number(pageMatch[1]) : 4096;
     const grab = (label) => {
@@ -188,23 +317,40 @@ async function findIOSPid(deviceId, appId) {
     }
     return undefined;
 }
+function parseFootprint(out) {
+    // Header: "Plex [15843]: 64-bit    Footprint: 801 MB (16384 bytes per page)"
+    // Values can be "B", "KB", "MB", "GB" with a space between number and unit.
+    const numUnit = '([\\d.]+\\s*[KMGT]?B)';
+    const header = out.match(new RegExp(`Footprint:\\s+${numUnit}`));
+    const footprintBytes = header ? humanToBytes(header[1].replace(/\s+/g, '')) : undefined;
+    // TOTAL line: " 801 MB    70 MB    4960 KB    5577    TOTAL"
+    // Columns: Dirty | Clean | Reclaimable | Regions | "TOTAL"
+    const total = out.match(new RegExp(`^\\s*${numUnit}\\s+${numUnit}\\s+${numUnit}\\s+\\d+\\s+TOTAL\\s*$`, 'm'));
+    const dirtyBytes = total ? humanToBytes(total[1].replace(/\s+/g, '')) : undefined;
+    return { footprintBytes, dirtyBytes };
+}
 function parseVmmapSummary(out) {
     const regions = {};
     const app = {};
-    // Lines look like: "MALLOC                          1.2G       234.5M  ..."
-    // We want the "RESIDENT" column (2nd numeric). The columns are whitespace-delimited.
-    // Easier: parse the per-region rows under "REGION TYPE" header.
+    // Find the per-region body. Layout:
+    //                                 VIRTUAL RESIDENT  DIRTY ...
+    //   REGION TYPE                      SIZE     SIZE   SIZE ...
+    //   ===========                   ======= ========  ===== ...
+    //   Accelerate framework             128K     128K   128K ...
+    //   ...
+    //   TOTAL                           5.2G     1.4G   950M ...
     const headerIdx = out.indexOf('REGION TYPE');
     if (headerIdx === -1)
         return { app, regions };
-    const body = out.slice(headerIdx);
-    const lines = body.split('\n').slice(1);
-    for (const raw of lines) {
-        const line = raw.trimEnd();
-        if (!line.trim())
+    const lines = out.slice(headerIdx).split('\n');
+    // Skip the REGION TYPE header line and the ====== separator that follows.
+    for (let i = 1; i < lines.length; i++) {
+        const line = lines[i].trimEnd();
+        const trimmed = line.trim();
+        if (!trimmed)
             continue;
-        if (line.startsWith('='))
-            break;
+        if (trimmed.startsWith('='))
+            continue; // separator row
         if (line.startsWith('TOTAL')) {
             // "TOTAL                          5.2G       1.4G       950M  ..."
             const m = line.match(/TOTAL\s+\S+\s+(\S+)/);
@@ -221,13 +367,12 @@ function parseVmmapSummary(out) {
         if (resident !== undefined)
             regions[name] = resident;
     }
-    // Roll up a few well-known regions into the canonical fields.
     app.nativeHeapBytes = regions['MALLOC'] ?? regions['MALLOC_NANO'];
     app.stackBytes = regions['Stack'];
     return { app, regions };
 }
 function humanToBytes(s) {
-    // Matches "1.2G", "234.5M", "950K", "1024", "1.2GB" etc.
+    // Matches "1.2G", "234.5M", "950K", "1024", "1.2GB", "0K" etc.
     const m = s.match(/^([\d.]+)\s*([KMGT]?)B?$/i);
     if (!m)
         return undefined;
@@ -243,10 +388,104 @@ function humanToBytes(s) {
     };
     return Math.round(n * (mult[m[2].toUpperCase()] ?? 1));
 }
-async function collectIOS(deviceId, platform, appId) {
+// ── iOS heap (per-class object counts) ────────────────────────────────────────
+function parseHeap(out) {
+    const classes = [];
+    let totals;
+    // Locate the "All zones: N nodes (B bytes)" totals line.
+    const totalsMatch = out.match(/All zones:\s+(\d+)\s+nodes\s+\((\d+)\s+bytes\)/);
+    if (totalsMatch) {
+        totals = { count: Number(totalsMatch[1]), bytes: Number(totalsMatch[2]) };
+    }
+    // Find the table header row. Heap prints:
+    //    COUNT      BYTES       AVG   CLASS_NAME ...    TYPE    BINARY
+    //    =====      =====       ===   ========== ...    ====    ======
+    //   549284  450043193     819.3   non-object
+    //   33305    1813840      54.5    CFString          ObjC    CoreFoundation
+    const headerIdx = out.search(/^\s*COUNT\s+BYTES\s+AVG\s+CLASS_NAME/m);
+    if (headerIdx === -1)
+        return { classes, totals };
+    const body = out.slice(headerIdx).split('\n').slice(2); // skip header + ===
+    for (const raw of body) {
+        const line = raw.trimEnd();
+        const trimmed = line.trim();
+        if (!trimmed)
+            break; // blank line ends the table
+        if (trimmed.startsWith('='))
+            continue;
+        // Match: leading count, bytes, avg, then the rest. CLASS_NAME / TYPE / BINARY
+        // are space-separated but the class name itself can contain spaces and angle
+        // brackets, so split off the trailing TYPE+BINARY columns from the right.
+        const m = line.match(/^\s*(\d+)\s+(\d+)\s+([\d.]+)\s+(.*)$/);
+        if (!m)
+            continue;
+        const count = Number(m[1]);
+        const bytes = Number(m[2]);
+        const rest = m[4];
+        // Trailing two whitespace-separated tokens are TYPE and BINARY (BINARY may
+        // be missing for "non-object" entries). Detect by looking at the last 1-2
+        // tokens; if the last token looks like a known TYPE, BINARY is absent.
+        const KNOWN_TYPES = new Set(['ObjC', 'Swift', 'C', 'C++', 'CFType']);
+        let className = rest;
+        let type;
+        let binary;
+        // Try: "<class>   TYPE   BINARY"
+        const trail2 = rest.match(/^(.*?)\s{2,}(\S+)\s+(\S+)\s*$/);
+        if (trail2 && KNOWN_TYPES.has(trail2[2])) {
+            className = trail2[1].trim();
+            type = trail2[2];
+            binary = trail2[3];
+        }
+        else {
+            // Try: "<class>   TYPE" (no binary)
+            const trail1 = rest.match(/^(.*?)\s{2,}(\S+)\s*$/);
+            if (trail1 && KNOWN_TYPES.has(trail1[2])) {
+                className = trail1[1].trim();
+                type = trail1[2];
+            }
+            else {
+                className = rest.trim();
+            }
+        }
+        if (!className)
+            continue;
+        classes.push({ class: className, count, bytes, type, binary });
+    }
+    classes.sort((a, b) => b.bytes - a.bytes);
+    return { classes, totals };
+}
+// ── iOS leaks ─────────────────────────────────────────────────────────────────
+function parseLeaks(out) {
+    // `leaks` prints e.g.:
+    //   Process 12345: 42 leaks for 16384 total leaked bytes.
+    // Followed by per-leak detail lines:
+    //   Leak: 0x12345  size=128  zone: ...  Class: NSConcreteData
+    // We aggregate by class.
+    const summary = out.match(/(\d+)\s+leaks?\s+for\s+(\d+)\s+total\s+leaked\s+bytes/i);
+    const totalCount = summary ? Number(summary[1]) : 0;
+    const totalBytes = summary ? Number(summary[2]) : 0;
+    const byClass = new Map();
+    const re = /Leak:\s*0x[0-9a-f]+\s+size=(\d+)[^\n]*?(?:\s(?:Class|Type):\s*(\S+))?/gi;
+    let m;
+    while ((m = re.exec(out)) !== null) {
+        const size = Number(m[1]);
+        const cls = m[2] ?? '<unknown>';
+        const prev = byClass.get(cls) ?? { count: 0, bytes: 0 };
+        prev.count += 1;
+        prev.bytes += size;
+        byClass.set(cls, prev);
+    }
+    const classes = [...byClass.entries()]
+        .map(([cls, v]) => ({ class: cls, count: v.count, bytes: v.bytes }))
+        .sort((a, b) => b.bytes - a.bytes);
+    return { totalCount, totalBytes, classes };
+}
+async function collectIOS(deviceId, platform, appId, opts) {
     const report = { platform, deviceId, appId, notes: [] };
-    // System-wide memory: vm_stat from inside the simulator (== host RAM).
-    const vm = await (0, runner_js_1.spawnCommand)('xcrun', ['simctl', 'spawn', deviceId, 'vm_stat']);
+    // System-wide memory: vm_stat from the host. Simulators share host RAM, and
+    // `vm_stat` is a host macOS binary — it isn't present inside the simulator
+    // runtime, so `xcrun simctl spawn <id> vm_stat` fails with ENOENT.
+    const vm = await (0, runner_js_1.spawnCommand)('vm_stat', []);
     if (vm.success) {
         const sys = parseVmStat(vm.stdout);
         report.system = {
@@ -286,7 +525,19 @@ async function collectIOS(deviceId, platform, appId) {
             };
         }
     }
-    // vmmap -summary for region breakdown — slower but provides categories.
+    // footprint — phys footprint + dirty memory totals. This is the actionable
+    // OOM number on iOS (jetsam compares this against the per-app limit), so
+    // surface it before vmmap region detail.
+    const fp = await (0, runner_js_1.spawnCommand)('footprint', [String(pid)]);
+    if (fp.success) {
+        const { footprintBytes, dirtyBytes } = parseFootprint(fp.stdout);
+        report.app = {
+            ...(report.app ?? {}),
+            ...(footprintBytes !== undefined ? { footprintBytes } : {}),
+            ...(dirtyBytes !== undefined ? { dirtyBytes } : {}),
+        };
+    }
+    // vmmap -summary for region breakdown.
     const vmmap = await (0, runner_js_1.spawnCommand)('vmmap', ['-summary', String(pid)]);
     if (vmmap.success) {
         const { app, regions } = parseVmmapSummary(vmmap.stdout);
@@ -297,14 +548,91 @@ async function collectIOS(deviceId, platform, appId) {
         };
     }
     else {
-        report.notes.push('vmmap unavailable — run `sudo DevToolsSecurity --enable` if it errors.');
+        report.notes.push(`vmmap unavailable: ${vmmap.stderr.trim() || 'unknown error'}`);
+    }
+    // heap for per-class object counts/bytes.
+    if (opts.objects) {
+        const h = await (0, runner_js_1.spawnCommand)('heap', [String(pid)]);
+        if (h.success) {
+            const { classes, totals } = parseHeap(h.stdout);
+            if (classes.length > 0)
+                report.objectClasses = classes;
+            if (totals)
+                report.heapTotals = totals;
+        }
+        else {
+            report.notes.push(`heap unavailable: ${h.stderr.trim() || 'unknown error'}`);
+        }
+    }
+    // leaks for leak detection.
+    if (opts.leaks) {
+        const l = await (0, runner_js_1.spawnCommand)('leaks', [String(pid)]);
+        // `leaks` exits non-zero when leaks are found; treat any output as success.
+        if (l.stdout && l.stdout.includes('leaks for')) {
+            report.leaks = parseLeaks(l.stdout);
+        }
+        else if (l.success) {
+            report.leaks = { totalCount: 0, totalBytes: 0, classes: [] };
+        }
+        else {
+            report.notes.push(`leaks unavailable: ${l.stderr.trim() || 'unknown error'}`);
+        }
     }
     if (report.notes.length === 0)
         delete report.notes;
     return report;
 }
-// ── Web (Playwright via CDP) ──────────────────────────────────────────────────
-async function collectWeb(deviceId, sessionName) {
+function parseV8HeapSnapshot(snap) {
+    const meta = snap.snapshot.meta;
+    const nf = meta.node_fields;
+    const stride = nf.length;
+    const typeIdx = nf.indexOf('type');
+    const nameIdx = nf.indexOf('name');
+    const sizeIdx = nf.indexOf('self_size');
+    const typeNames = meta.node_types[0]; // e.g. ["hidden","array","string","object","code","closure","regexp","number","native","synthetic","concatenated string","sliced string","symbol","bigint"]
+    const nodes = snap.nodes;
+    const strings = snap.strings;
+    // For "object", "closure", "native" → name is the constructor / function /
+    // C++ class name. For other types, group under "<type>".
+    const namedTypes = new Set(['object', 'closure', 'native']);
+    const namedTypeIds = new Set();
+    typeNames.forEach((t, i) => {
+        if (namedTypes.has(t))
+            namedTypeIds.add(i);
+    });
+    const byClass = new Map();
+    let totalCount = 0;
+    let totalBytes = 0;
+    for (let i = 0; i < nodes.length; i += stride) {
+        const t = nodes[i + typeIdx];
+        const size = nodes[i + sizeIdx];
+        const nameId = nodes[i + nameIdx];
+        totalCount++;
+        totalBytes += size;
+        let label;
+        if (namedTypeIds.has(t)) {
+            const tName = typeNames[t];
+            const ctor = strings[nameId] || '<anonymous>';
+            label = tName === 'object' ? ctor : `${ctor}  [${tName}]`;
+        }
+        else {
+            label = `<${typeNames[t] ?? 'unknown'}>`;
+        }
+        const prev = byClass.get(label);
+        if (prev) {
+            prev.count++;
+            prev.bytes += size;
+        }
+        else {
+            byClass.set(label, { count: 1, bytes: size });
+        }
+    }
+    const classes = [...byClass.entries()]
+        .map(([cls, v]) => ({ class: cls, count: v.count, bytes: v.bytes }))
+        .sort((a, b) => b.bytes - a.bytes);
+    return { classes, totals: { count: totalCount, bytes: totalBytes } };
+}
+async function collectWeb(deviceId, sessionName, opts) {
     const report = { platform: 'web', deviceId, notes: [] };
     let driver;
     try {
@@ -332,11 +660,8 @@ async function collectWeb(deviceId, sessionName) {
     const m = data.metrics;
     const pm = data.pageMemory;
     report.app = {
-        // Heap totals — prefer page-context performance.memory (Chromium) over
-        // CDP's JSHeapUsedSize (which can lag). Both are JS heap only.
         nativeHeapBytes: pm?.usedJSHeapSize ?? m['JSHeapUsedSize'],
         codeBytes: m['JSHeapTotalSize'] ? m['JSHeapTotalSize'] - (m['JSHeapUsedSize'] ?? 0) : undefined,
-        // Roll the raw CDP metrics into `regions` so they're inspectable verbatim.
         regions: { ...m },
     };
     if (pm) {
@@ -347,7 +672,6 @@ async function collectWeb(deviceId, sessionName) {
             'JS Heap Limit': pm.jsHeapSizeLimit,
         };
     }
-    // Object counts — direct CDP equivalents of Android's "Views/Activities/Binders".
     const objectKeys = [
         'Nodes',
         'Documents',
@@ -363,31 +687,228 @@ async function collectWeb(deviceId, sessionName) {
     }
     if (Object.keys(objects).length > 0)
         report.objects = objects;
+    // --objects → take a real V8 heap snapshot, parse class counts/bytes, and
+    // save the .heapsnapshot file so it can be opened in Chrome DevTools.
+    if (opts.objects) {
+        try {
+            const snapText = await driver.heapSnapshot({ gc: opts.gc !== false });
+            const snap = JSON.parse(snapText);
+            const { classes, totals } = parseV8HeapSnapshot(snap);
+            if (classes.length > 0)
+                report.objectClasses = classes;
+            report.heapTotals = totals;
+            const dumpsDir = node_path_1.default.join(node_os_1.default.homedir(), '.conductor', 'heap-dumps');
+            await node_fs_1.promises.mkdir(dumpsDir, { recursive: true });
+            const safeUrl = (data.url || 'page').replace(/[^\w.-]+/g, '_').slice(0, 60);
+            const ts = new Date().toISOString().replace(/[:.]/g, '-');
+            const file = node_path_1.default.join(dumpsDir, `${safeUrl}-${ts}.heapsnapshot`);
+            await node_fs_1.promises.writeFile(file, snapText);
+            report.notes.push(`Heap snapshot saved → ${file}  (open in Chrome DevTools: Memory → Load profile)`);
+        }
+        catch (err) {
+            report.notes.push(`Heap snapshot failed: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
     report.notes.push('Web memory is per-page (Performance.getMetrics + performance.memory). Run-wide RSS for the browser process is not exposed via CDP.');
     if (report.notes.length === 0)
         delete report.notes;
     return report;
 }
+// ── Snapshot save / load / diff ───────────────────────────────────────────────
+function snapshotsDir() {
+    return node_path_1.default.join(node_os_1.default.homedir(), '.conductor', 'memory-snapshots');
+}
+function snapshotPath(name) {
+    // Allow callers to pass either a bare name or a filename / path.
+    if (name.endsWith('.json') || name.includes('/'))
+        return name;
+    return node_path_1.default.join(snapshotsDir(), `${name}.json`);
+}
+async function saveSnapshot(name, report) {
+    const dir = snapshotsDir();
+    await node_fs_1.promises.mkdir(dir, { recursive: true });
+    const file = snapshotPath(name);
+    await node_fs_1.promises.writeFile(file, JSON.stringify(report, null, 2));
+    return file;
+}
+async function loadSnapshot(name) {
+    const file = snapshotPath(name);
+    const raw = await node_fs_1.promises.readFile(file, 'utf8');
+    return JSON.parse(raw);
+}
+async function listSnapshots() {
+    const dir = snapshotsDir();
+    let files;
+    try {
+        files = await node_fs_1.promises.readdir(dir);
+    }
+    catch {
+        return [];
+    }
+    const out = [];
+    for (const f of files) {
+        if (!f.endsWith('.json'))
+            continue;
+        const file = node_path_1.default.join(dir, f);
+        try {
+            const stat = await node_fs_1.promises.stat(file);
+            const r = JSON.parse(await node_fs_1.promises.readFile(file, 'utf8'));
+            out.push({
+                name: f.replace(/\.json$/, ''),
+                capturedAt: r.capturedAt,
+                appId: r.appId,
+                platform: r.platform,
+                size: stat.size,
+            });
+        }
+        catch {
+            /* skip malformed */
+        }
+    }
+    out.sort((a, b) => (a.capturedAt ?? '').localeCompare(b.capturedAt ?? ''));
+    return out;
+}
+function diffNumberMap(a, b) {
+    const keys = new Set([...Object.keys(a ?? {}), ...Object.keys(b ?? {})]);
+    const out = [];
+    for (const k of keys) {
+        const before = a?.[k] ?? 0;
+        const after = b?.[k] ?? 0;
+        if (before === after)
+            continue;
+        out.push({ key: k, before, after, delta: after - before });
+    }
+    out.sort((x, y) => Math.abs(y.delta) - Math.abs(x.delta));
+    return out;
+}
+function diffClasses(a, b) {
+    const idx = (arr) => {
+        const m = new Map();
+        for (const c of arr ?? [])
+            m.set(c.class, c);
+        return m;
+    };
+    const A = idx(a);
+    const B = idx(b);
+    const keys = new Set([...A.keys(), ...B.keys()]);
+    const out = [];
+    for (const k of keys) {
+        const x = A.get(k);
+        const y = B.get(k);
+        const beforeCount = x?.count ?? 0;
+        const afterCount = y?.count ?? 0;
+        const beforeBytes = x?.bytes ?? 0;
+        const afterBytes = y?.bytes ?? 0;
+        if (beforeCount === afterCount && beforeBytes === afterBytes)
+            continue;
+        out.push({
+            class: k,
+            beforeCount,
+            afterCount,
+            beforeBytes,
+            afterBytes,
+            deltaCount: afterCount - beforeCount,
+            deltaBytes: afterBytes - beforeBytes,
+        });
+    }
+    out.sort((x, y) => Math.abs(y.deltaBytes) - Math.abs(x.deltaBytes));
+    return out;
+}
+function buildDiff(a, b, aLabel, bLabel) {
+    const numericApp = (r) => {
+        const out = {};
+        for (const [k, v] of Object.entries(r.app ?? {})) {
+            if (typeof v === 'number')
+                out[k] = v;
+        }
+        return out;
+    };
+    return {
+        before: { name: aLabel, capturedAt: a.capturedAt },
+        after: { name: bLabel, capturedAt: b.capturedAt },
+        app: diffNumberMap(numericApp(a), numericApp(b)),
+        regions: diffNumberMap(a.app?.regions, b.app?.regions),
+        objects: diffNumberMap(a.objects, b.objects),
+        objectClasses: diffClasses(a.objectClasses, b.objectClasses),
+        leaksDelta: a.leaks || b.leaks
+            ? {
+                count: (b.leaks?.totalCount ?? 0) - (a.leaks?.totalCount ?? 0),
+                bytes: (b.leaks?.totalBytes ?? 0) - (a.leaks?.totalBytes ?? 0),
+            }
+            : undefined,
+    };
+}
 // ── Formatting ────────────────────────────────────────────────────────────────
 function fmtBytes(n) {
     if (n === undefined)
         return '—';
-    if (n < 1024)
-        return `${n} B`;
+    const sign = n < 0 ? '-' : '';
+    const abs = Math.abs(n);
+    if (abs < 1024)
+        return `${sign}${abs} B`;
     const units = ['KB', 'MB', 'GB', 'TB'];
-    let v = n / 1024;
+    let v = abs / 1024;
     let i = 0;
     while (v >= 1024 && i < units.length - 1) {
         v /= 1024;
         i++;
     }
-    return `${v.toFixed(v >= 100 ? 0 : v >= 10 ? 1 : 2)} ${units[i]}`;
+    return `${sign}${v.toFixed(v >= 100 ? 0 : v >= 10 ? 1 : 2)} ${units[i]}`;
+}
+function fmtSignedBytes(n) {
+    if (n === 0)
+        return '±0';
+    return (n > 0 ? '+' : '') + fmtBytes(n);
+}
+function fmtSignedInt(n) {
+    if (n === 0)
+        return '±0';
+    return (n > 0 ? '+' : '') + String(n);
+}
+function makeFilter(pattern) {
+    if (!pattern)
+        return undefined;
+    try {
+        const re = new RegExp(pattern, 'i');
+        return (s) => re.test(s);
+    }
+    catch {
+        // Invalid regex → no filter (safer than throwing mid-render).
+        return undefined;
+    }
+}
+function filterClasses(arr, pattern) {
+    const f = makeFilter(pattern);
+    return f ? arr.filter((c) => f(c.class)) : arr;
 }
-function formatReport(r) {
+function filterEntries(arr, pattern, growthOnly) {
+    const f = makeFilter(pattern);
+    return arr.filter((e) => {
+        if (growthOnly && e.delta <= 0)
+            return false;
+        if (f && !f(e.key))
+            return false;
+        return true;
+    });
+}
+function filterClassDiffs(arr, pattern, growthOnly) {
+    const f = makeFilter(pattern);
+    return arr.filter((c) => {
+        if (growthOnly && c.deltaBytes <= 0)
+            return false;
+        if (f && !f(c.class))
+            return false;
+        return true;
+    });
+}
+function formatReport(r, opts = {}) {
+    const top = opts.top ?? 20;
     const lines = [];
     lines.push(`Device:    ${r.deviceId} (${r.platform})`);
     if (r.appId)
         lines.push(`App:       ${r.appId}${r.pid ? ` (pid ${r.pid})` : ''}`);
+    if (r.capturedAt)
+        lines.push(`Captured:  ${r.capturedAt}`);
     if (r.system) {
         lines.push('');
         lines.push('System memory:');
@@ -409,6 +930,10 @@ function formatReport(r) {
         lines.push('');
         lines.push('App memory:');
         const a = r.app;
+        if (a.footprintBytes !== undefined)
+            lines.push(`  Footprint:  ${fmtBytes(a.footprintBytes)}    (jetsam target on iOS)`);
+        if (a.dirtyBytes !== undefined)
+            lines.push(`  Dirty:      ${fmtBytes(a.dirtyBytes)}`);
         if (a.totalPssBytes !== undefined)
             lines.push(`  PSS total:  ${fmtBytes(a.totalPssBytes)}`);
         if (a.totalRssBytes !== undefined)
@@ -433,24 +958,46 @@ function formatReport(r) {
             lines.push(`  System:     ${fmtBytes(a.systemBytes)}`);
         if (a.regions && Object.keys(a.regions).length > 0) {
             lines.push('');
-            lines.push('Top memory regions (resident):');
+            lines.push(`Top memory regions (resident, top ${top}):`);
             const entries = Object.entries(a.regions)
                 .filter(([, v]) => v > 0)
-                .sort((a, b) => b[1] - a[1])
-                .slice(0, 12);
+                .sort((x, y) => y[1] - x[1])
+                .slice(0, top);
             for (const [name, bytes] of entries) {
-                lines.push(`  ${name.padEnd(28)} ${fmtBytes(bytes)}`);
+                lines.push(`  ${name.padEnd(30)} ${fmtBytes(bytes)}`);
             }
         }
     }
+    if (r.objectClasses && r.objectClasses.length > 0) {
+        const filtered = filterClasses(r.objectClasses, opts.filter);
+        lines.push('');
+        if (r.heapTotals) {
+            lines.push(`Heap objects (${r.heapTotals.count.toLocaleString()} nodes, ${fmtBytes(r.heapTotals.bytes)} total) — top ${top} by bytes${opts.filter ? ` (filter: /${opts.filter}/)` : ''}:`);
+        }
+        else {
+            lines.push(`Heap objects (top ${top} by bytes${opts.filter ? ` (filter: /${opts.filter}/)` : ''}):`);
+        }
+        lines.push(`  ${'COUNT'.padStart(8)}  ${'BYTES'.padStart(10)}  CLASS`);
+        for (const c of filtered.slice(0, top)) {
+            const name = c.binary ? `${c.class}  [${c.binary}]` : c.class;
+            lines.push(`  ${String(c.count).padStart(8)}  ${fmtBytes(c.bytes).padStart(10)}  ${name}`);
+        }
+    }
     if (r.objects && Object.keys(r.objects).length > 0) {
         lines.push('');
         lines.push('Object counts:');
-        const entries = Object.entries(r.objects).sort((a, b) => b[1] - a[1]);
+        const entries = Object.entries(r.objects).sort((x, y) => y[1] - x[1]);
         for (const [name, count] of entries) {
             lines.push(`  ${name.padEnd(20)} ${count}`);
         }
     }
+    if (r.leaks) {
+        lines.push('');
+        lines.push(`Leaks: ${r.leaks.totalCount} leak${r.leaks.totalCount === 1 ? '' : 's'} (${fmtBytes(r.leaks.totalBytes)})`);
+        for (const l of r.leaks.classes.slice(0, top)) {
+            lines.push(`  ${String(l.count).padStart(6)}  ${fmtBytes(l.bytes).padStart(10)}  ${l.class}`);
+        }
+    }
     if (r.notes && r.notes.length > 0) {
         lines.push('');
         for (const n of r.notes)
@@ -458,8 +1005,94 @@ function formatReport(r) {
     }
     return lines.join('\n');
 }
+function formatDiff(d, opts = {}) {
+    const top = opts.top ?? 20;
+    const lines = [];
+    const tag = [];
+    if (opts.growthOnly)
+        tag.push('growth-only');
+    if (opts.filter)
+        tag.push(`filter: /${opts.filter}/`);
+    const tagStr = tag.length > 0 ? `  [${tag.join(', ')}]` : '';
+    lines.push(`Diff: ${d.before.name} → ${d.after.name}${tagStr}`);
+    if (d.before.capturedAt || d.after.capturedAt) {
+        lines.push(`      ${d.before.capturedAt ?? '?'} → ${d.after.capturedAt ?? '?'}`);
+    }
+    // App memory deltas — only filtered by growth-only (key is e.g. "totalRssBytes",
+    // not user-meaningful for regex filtering).
+    const appRows = opts.growthOnly ? d.app.filter((e) => e.delta > 0) : d.app;
+    if (appRows.length > 0) {
+        lines.push('');
+        lines.push('App memory deltas:');
+        for (const e of appRows.slice(0, top)) {
+            lines.push(`  ${e.key.padEnd(20)} ${fmtBytes(e.before).padStart(10)} → ${fmtBytes(e.after).padStart(10)}  (${fmtSignedBytes(e.delta)})`);
+        }
+    }
+    const regionRows = filterEntries(d.regions, opts.filter, opts.growthOnly);
+    if (regionRows.length > 0) {
+        lines.push('');
+        lines.push(`Region deltas (top ${top} by |Δ|):`);
+        for (const e of regionRows.slice(0, top)) {
+            lines.push(`  ${e.key.padEnd(30)} ${fmtBytes(e.before).padStart(10)} → ${fmtBytes(e.after).padStart(10)}  (${fmtSignedBytes(e.delta)})`);
+        }
+    }
+    const classRows = filterClassDiffs(d.objectClasses, opts.filter, opts.growthOnly);
+    if (classRows.length > 0) {
+        lines.push('');
+        lines.push(`Class deltas (top ${top} by |Δ bytes|):`);
+        lines.push(`  ${'Δ COUNT'.padStart(8)}  ${'Δ BYTES'.padStart(10)}  ${'AFTER COUNT'.padStart(11)}  ${'AFTER BYTES'.padStart(11)}  CLASS`);
+        for (const c of classRows.slice(0, top)) {
+            lines.push(`  ${fmtSignedInt(c.deltaCount).padStart(8)}  ${fmtSignedBytes(c.deltaBytes).padStart(10)}  ${String(c.afterCount).padStart(11)}  ${fmtBytes(c.afterBytes).padStart(11)}  ${c.class}`);
+        }
+    }
+    const objRows = filterEntries(d.objects, opts.filter, opts.growthOnly);
+    if (objRows.length > 0) {
+        lines.push('');
+        lines.push('Object count deltas:');
+        for (const e of objRows.slice(0, top)) {
+            lines.push(`  ${e.key.padEnd(20)} ${String(e.before).padStart(8)} → ${String(e.after).padStart(8)}  (${fmtSignedInt(e.delta)})`);
+        }
+    }
+    if (d.leaksDelta && (d.leaksDelta.count !== 0 || d.leaksDelta.bytes !== 0)) {
+        if (!opts.growthOnly || d.leaksDelta.bytes > 0) {
+            lines.push('');
+            lines.push(`Leaks delta: ${fmtSignedInt(d.leaksDelta.count)} leak(s), ${fmtSignedBytes(d.leaksDelta.bytes)}`);
+        }
+    }
+    if (lines.length <= 2)
+        lines.push('', 'No differences detected.');
+    return lines.join('\n');
+}
 // ── Entry point ───────────────────────────────────────────────────────────────
-async function memory(appIdArg, opts = {}, sessionName = 'default', _memOpts = {}) {
+async function memory(appIdArg, opts = {}, sessionName = 'default', memOpts = {}) {
+    // List snapshots — no device required.
+    if (memOpts.listSnapshots) {
+        const list = await listSnapshots();
+        if (opts.json) {
+            (0, output_js_1.printData)({ status: 'ok', snapshots: list }, opts);
+        }
+        else if (list.length === 0) {
+            console.log(`No snapshots saved. Try: conductor memory --save baseline`);
+        }
+        else {
+            console.log(`Snapshots in ${snapshotsDir()}:`);
+            for (const s of list) {
+                console.log(`  ${s.name.padEnd(24)} ${(s.platform ?? '?').padEnd(8)} ${s.appId ?? ''}  ${s.capturedAt ?? ''}`);
+            }
+        }
+        return 0;
+    }
+    // Diff between two saved snapshots.
+    if (memOpts.diff && memOpts.diffOther) {
+        const a = await loadSnapshot(memOpts.diff);
+        const b = await loadSnapshot(memOpts.diffOther);
+        const d = buildDiff(a, b, memOpts.diff, memOpts.diffOther);
+        if (opts.json)
+            (0, output_js_1.printData)({ status: 'ok', diff: d }, opts);
+        else
+            console.log(formatDiff(d, memOpts));
+        return 0;
+    }
     const deviceId = await resolveDeviceId(sessionName);
     if (!deviceId) {
         (0, output_js_1.printError)('No device found. Connect a device or start a simulator first.', opts);
@@ -468,22 +1101,40 @@ async function memory(appIdArg, opts = {}, sessionName = 'default', _memOpts = {
     const platform = await (0, bootstrap_js_1.detectPlatform)(deviceId);
     let report;
     if (platform === 'web') {
-        report = await collectWeb(deviceId, sessionName);
+        report = await collectWeb(deviceId, sessionName, memOpts);
     }
     else {
         const appId = await resolveAppId(appIdArg, sessionName, deviceId);
         if (platform === 'android') {
-            report = await collectAndroid(deviceId, appId);
+            report = await collectAndroid(deviceId, appId, memOpts);
         }
         else {
-            report = await collectIOS(deviceId, platform, appId);
+            report = await collectIOS(deviceId, platform, appId, memOpts);
         }
     }
+    report.capturedAt = new Date().toISOString();
+    // Diff current report against a saved snapshot.
+    if (memOpts.diff) {
+        const a = await loadSnapshot(memOpts.diff);
+        const d = buildDiff(a, report, memOpts.diff, 'current');
+        if (memOpts.save)
+            await saveSnapshot(memOpts.save, report);
+        if (opts.json)
+            (0, output_js_1.printData)({ status: 'ok', diff: d, current: report }, opts);
+        else
+            console.log(formatDiff(d, memOpts));
+        return 0;
+    }
+    if (memOpts.save) {
+        const file = await saveSnapshot(memOpts.save, report);
+        if (!opts.json)
+            console.error(`Saved snapshot → ${file}`);
+    }
     if (opts.json) {
         (0, output_js_1.printData)({ status: 'ok', ...report }, opts);
     }
     else {
-        console.log(formatReport(report));
+        console.log(formatReport(report, memOpts));
     }
     return 0;
 }