heaplens-cli 0.0.0-stage → 0.1.0

package/runtime/browser-ui/rpc.cjs

@@ -0,0 +1,115 @@
+'use strict';
+const { spawn } = require('node:child_process');
+const { EventEmitter } = require('node:events');
+// Preserve wide integers as decimal strings. Existing renderer actions reject
+// unsafe IDs rather than selecting an adjacent object after JSON rounding.
+function parseExact(text) {
+    let out = '', quoted = false, escaped = false;
+    for (let i = 0; i < text.length;) {
+        const c = text[i];
+        if (quoted) {
+            out += c;
+            i++;
+            if (escaped)
+                escaped = false;
+            else if (c === '\\')
+                escaped = true;
+            else if (c === '"')
+                quoted = false;
+            continue;
+        }
+        if (c === '"') {
+            quoted = true;
+            out += c;
+            i++;
+            continue;
+        }
+        if (c === '-' || /[0-9]/.test(c)) {
+            const match = text.slice(i).match(/^-?\d+(?:\.\d+)?(?:[eE][+-]?\d+)?/);
+            if (!match)
+                throw Error('Invalid JSON');
+            const n = match[0];
+            out += !/[.eE]/.test(n) && (BigInt(n) > 9007199254740991n || BigInt(n) < -9007199254740991n) ? JSON.stringify(n) : n;
+            i += n.length;
+        }
+        else {
+            out += c;
+            i++;
+        }
+    }
+    return JSON.parse(out);
+}
+class Rpc extends EventEmitter {
+    constructor(executable, legacy = false) {
+        super();
+        this.pending = new Map();
+        this.seq = 0;
+        this.buffer = '';
+        this.closed = false;
+        this.child = spawn(executable, legacy ? ['--legacy'] : [], { stdio: ['pipe', 'pipe', 'pipe'], windowsHide: true });
+        this.child.stderr.on('data', () => { }); // Never forward raw heap paths/parser bytes.
+        this.child.stdin.on('error', () => this.fail());
+        this.child.on('error', () => this.fail());
+        this.child.on('exit', () => this.fail());
+        this.child.stdout.setEncoding('utf8');
+        this.child.stdout.on('data', text => {
+            if (this.closed)
+                return;
+            this.buffer += text;
+            if (Buffer.byteLength(this.buffer) > 64 * 1024 * 1024)
+                return this.fail();
+            let end;
+            while ((end = this.buffer.indexOf('\n')) !== -1) {
+                const line = this.buffer.slice(0, end);
+                this.buffer = this.buffer.slice(end + 1);
+                try {
+                    const message = parseExact(line);
+                    if (message.id !== undefined) {
+                        const p = this.pending.get(message.id);
+                        if (!p)
+                            continue;
+                        this.pending.delete(message.id);
+                        clearTimeout(p.timer);
+                        message.error ? p.reject(Error('Engine request failed. Check syntax or retry.')) : p.resolve(message.result);
+                    }
+                    else if (message.method)
+                        this.emit('notification', message);
+                }
+                catch {
+                    return this.fail();
+                }
+            }
+        });
+    }
+    request(method, params, timeout = 30000) {
+        if (this.closed)
+            return Promise.reject(Error('Server unavailable. Retry.'));
+        const id = ++this.seq;
+        const promise = new Promise((resolve, reject) => {
+            const timer = setTimeout(() => { this.pending.delete(id); reject(Error('Engine request did not reply. Retry or simplify the query.')); }, timeout);
+            this.pending.set(id, { resolve, reject, timer });
+            this.child.stdin.write(serialize({ jsonrpc: '2.0', id, method, params }, method === 'compare_snapshots') + '\n');
+        });
+        return { id, promise };
+    }
+    call(method, params, timeout) { const r = this.request(method, params, timeout); return r.promise || r; }
+    fail() { if (this.closed)
+        return; this.closed = true; for (const p of this.pending.values()) {
+        clearTimeout(p.timer);
+        p.reject(Error('Server unavailable. Retry.'));
+    } this.pending.clear(); this.child.kill(); this.emit('unavailable'); }
+    close() { this.removeAllListeners(); this.fail(); }
+}
+// Only typed engine numeric fields are emitted as exact unquoted decimals.
+// Ordinary heap/user strings (including digits) remain JSON strings.
+const integerFields = new Set(['object_id', 'total_heap_size', 'reachable_heap_size', 'total_instances', 'total_classes', 'total_arrays', 'total_gc_roots', 'instance_count', 'shallow_size', 'retained_size', 'total_wasted_bytes', 'duplicate_string_wasted_bytes', 'empty_collection_wasted_bytes', 'over_allocated_wasted_bytes', 'boxed_primitive_wasted_bytes']);
+function serialize(value, exact = false, key = '') {
+    if (exact && integerFields.has(key) && typeof value === 'string' && /^(0|[1-9]\d*)$/.test(value) && BigInt(value) <= 18446744073709551615n)
+        return value;
+    if (Array.isArray(value))
+        return '[' + value.map(x => serialize(x, exact)).join(',') + ']';
+    if (value && typeof value === 'object')
+        return '{' + Object.entries(value).filter(([, v]) => v !== undefined).map(([k, v]) => JSON.stringify(k) + ':' + serialize(v, exact, k)).join(',') + '}';
+    return JSON.stringify(value);
+}
+module.exports = { Rpc, parseExact, serialize };

package/runtime/browser-ui/server.cjs

@@ -0,0 +1,209 @@
+'use strict';
+const http = require('node:http'), fs = require('node:fs/promises'), sync = require('node:fs'), path = require('node:path'), crypto = require('node:crypto');
+const { spawn } = require('node:child_process');
+const { Sources } = require('./sources.cjs'), { Session } = require('./session.cjs');
+const {Telemetry}=require('../telemetry/node.cjs');
+const {platform,architecture}=require('../telemetry/contract.cjs');
+class BrowserHost {
+    constructor(options) {
+        this.server = options.server;
+        this.telemetry=new Telemetry({context:{host:'browser',version:require('../package.json').version,os:platform(process.platform),arch:architecture(process.arch)},
+            level:options.telemetry??'all',disabled:!!process.env.CI || process.env.DO_NOT_TRACK==='1',...(options.telemetrySend?{send:options.telemetrySend}:{})});
+        this.legacy = options.legacy;
+        this.quickScan = !!options.quickScan;
+        this.sourceRoots = options.roots || [];
+        this.sources = new Sources(this.sourceRoots);
+        this.sessions = new Map();
+        this.queue = Promise.resolve();
+        this.token = crypto.randomBytes(32).toString('base64url');
+        this.stopped = false;
+        this.lastSeen = Date.now();
+        this.seen = false;
+        const assets = options.assets || path.join(__dirname, 'build');
+        this.html = sync.readFileSync(path.join(assets, 'index.html'), 'utf8');
+        this.providers = JSON.parse(sync.readFileSync(path.join(assets, 'providers.json'), 'utf8'));
+        this.prompts = require(path.join(assets, 'prompts.cjs'));
+        options.files.forEach(file => { const session = new Session(this, file); this.sessions.set(session.id, session); });
+    }
+    available() { return [...this.sessions.values()].filter(s => s.state === 'ready' && s.snapshot); }
+    changed() { for (const s of this.sessions.values())
+        if (s.state !== 'closed')
+            s.emit('snapshotsChanged'); }
+    slot(work) { const result = this.queue.then(() => this.stopped ? undefined : work()); this.queue = result.catch(() => { }); return result; }
+    async listen(port = 0) {
+        this.http = http.createServer((req, res) => this.handle(req, res));
+        this.http.requestTimeout = 15000;
+        this.http.headersTimeout = 10000;
+        this.http.maxHeadersCount = 32;
+        await new Promise((resolve, reject) => { this.http.once('error', reject); this.http.listen(port, '127.0.0.1', resolve); });
+        this.port = this.http.address().port;
+        this.origin = 'http://127.0.0.1:' + this.port;
+        this.idle = setInterval(() => { if (Date.now() - this.lastSeen > (this.seen ? 90000 : 300000))
+            this.shutdown(); }, 5000);
+        this.idle.unref();
+        return this;
+    }
+    url(id = [...this.sessions.keys()][0]) { return this.origin + '/dump/' + id + '#token=' + this.token; }
+    headers(res) { res.setHeader('Cache-Control', 'no-store'); res.setHeader('Referrer-Policy', 'no-referrer'); res.setHeader('X-Content-Type-Options', 'nosniff'); res.setHeader('X-Frame-Options', 'DENY'); res.setHeader('Cross-Origin-Resource-Policy', 'same-origin'); res.setHeader('Content-Security-Policy', "frame-ancestors 'none'; base-uri 'none'; form-action 'none'"); }
+    reply(res, status, data) { if (res.destroyed || res.writableEnded)
+        return; this.headers(res); res.writeHead(status, { 'Content-Type': 'application/json; charset=utf-8' }); res.end(JSON.stringify(data)); }
+    authenticated(req) { const raw = req.headers['x-heaplens-token']; if (typeof raw !== 'string' || raw.length !== this.token.length)
+        return false; return crypto.timingSafeEqual(Buffer.from(raw), Buffer.from(this.token)); }
+    async handle(req, res) {
+        try {
+            if (req.headers.host !== '127.0.0.1:' + this.port)
+                return this.reply(res, 403, { error: 'Invalid host' });
+            const url = new URL(req.url, this.origin);
+            if (url.origin !== this.origin || url.searchParams.has('token'))
+                return this.reply(res, 403, { error: 'Invalid request' });
+            if (req.method === 'GET' && /^\/dump\/[a-f0-9-]{36}$/.test(url.pathname) && this.sessions.get(url.pathname.split('/').at(-1))?.state !== 'closed' && this.sessions.has(url.pathname.split('/').at(-1))) {
+                const nonce = crypto.randomBytes(24).toString('base64');
+                this.headers(res);
+                res.writeHead(200, { 'Content-Type': 'text/html; charset=utf-8' });
+                res.end(this.html.replaceAll('__NONCE__', nonce));
+                return;
+            }
+            if (!url.pathname.startsWith('/api/') || !this.authenticated(req) || req.headers.origin && req.headers.origin !== this.origin || req.headers['sec-fetch-site'] && req.headers['sec-fetch-site'] !== 'same-origin' && req.headers['sec-fetch-site'] !== 'none' || req.method === 'POST' && req.headers.origin !== this.origin)
+                return this.reply(res, 403, { error: 'Unauthorized local request' });
+            this.lastSeen = Date.now();
+            this.seen = true;
+            if (req.method === 'GET' && url.pathname === '/api/catalog')
+                return this.reply(res, 200, { dumps: [...this.sessions.values()].filter(s => s.state !== 'closed').map(s => ({ id: s.id, label: s.file.label })) });
+            if (req.method === 'GET' && url.pathname === '/api/events') {
+                const session = this.sessions.get(url.searchParams.get('session')), after = Number(url.searchParams.get('after'));
+                if (!session || session.view !== req.headers['x-heaplens-view'] || !Number.isSafeInteger(after) || after < 0 || after > session.seq)
+                    return this.reply(res, 400, { error: 'Invalid event cursor or retired page' });
+                while (session.events.length && session.events[0].seq <= after)
+                    session.eventBytes -= session.events.shift().bytes;
+                const reset = after > 0 && session.events.length && after < session.events[0].seq - 1;
+                return this.reply(res, 200, { reset: !!reset, cursor: session.seq, events: reset ? [] : session.events.map(e => ({ seq: e.seq, message: e.message })) });
+            }
+            if (req.method === 'POST' && url.pathname === '/api/command') {
+                const body = await this.body(req);
+                const session = this.sessions.get(body.session);
+                if (!session || !body.message || !session.commands.has(body.message.command))
+                    return this.reply(res, 400, { error: 'Unsupported action' });
+                // Do not keep an HTTP request open for an analysis, approval or stream.
+                if (body.message.command === 'ready')
+                    session.attach(req.headers['x-heaplens-view']);
+                else if (session.view !== req.headers['x-heaplens-view'])
+                    return this.reply(res, 403, { error: 'Retired page' });
+                const generation = session.generation, view = session.view;
+                // Acknowledge before running a side effect: shutdown must not
+                // destroy its own HTTP response or strand the launcher's client.
+                res.once('finish', () => setImmediate(() => {
+                    if (this.stopped || session.view !== view)
+                        return;
+                    session.dispatch(body.message).catch(() => {
+                        if (session.state !== 'closed' && session.generation === generation && session.view === view)
+                            session.emit('localActionStatus', { message: 'Action rejected or failed. Check limits and analysis status.' });
+                    });
+                }));
+                this.reply(res, 202, { accepted: true });
+                return;
+            }
+            this.reply(res, 404, { error: 'Not found' });
+        }
+        catch {
+            this.reply(res, 400, { error: 'Invalid local request' });
+        }
+    }
+    async body(req) { if (req.headers['content-type'] !== 'application/json')
+        throw Error('Expected JSON'); let bytes = 0; const chunks = []; for await (const chunk of req) {
+        bytes += chunk.length;
+        if (bytes > 9 * 1024 * 1024)
+            throw Error('Request exceeds limit');
+        chunks.push(chunk);
+    } return JSON.parse(Buffer.concat(chunks).toString('utf8')); }
+    async shutdown() {
+        if (this.stopped)
+            return;
+        this.stopped = true;
+        this.telemetry.dispose();
+        clearInterval(this.idle);
+        for (const session of this.sessions.values()) {
+            session.emit('browserStopped');
+            session.close();
+        }
+        await new Promise(resolve => { if (!this.http?.listening)
+            return resolve(); this.http.close(resolve); this.http.closeAllConnections(); });
+    }
+}
+function options(argv) {
+    const out = { roots: [], files: [], legacy: false, port: 0, browser: true, telemetry:'all' };
+    for (let i = 0; i < argv.length; i++) {
+        const flag = argv[i];
+        if (flag === '--legacy')
+            out.legacy = true;
+        else if (flag === '--quick-scan')
+            out.quickScan = true;
+        else if (flag === '--no-browser')
+            out.browser = false;
+        else if (['--server', '--source-root', '--port', '--dump', '--telemetry'].includes(flag)) {
+            const value = argv[++i];
+            if (!value)
+                throw Error('Missing argument');
+            if(flag==='--telemetry') {
+                if(!['off','error','all'].includes(value))throw Error('Invalid telemetry choice');
+                out.telemetry=value;
+            } else if (flag === '--server')
+                out.server = value;
+            else if (flag === '--source-root')
+                out.roots.push(value);
+            else if (flag === '--port')
+                out.port = Number(value);
+            else
+                out.files.push(value);
+        }
+        else
+            throw Error('Unknown argument');
+    }
+    if (!out.server || out.files.length < 1 || out.files.length > 8 || out.roots.length > 16 || !Number.isInteger(out.port) || out.port < 0 || out.port > 65535)
+        throw Error('Invalid arguments');
+    return out;
+}
+async function main(argv) {
+    let host;
+    try {
+        const args = options(argv), files = [];
+        for (const input of args.files) {
+            const file = await fs.realpath(input), stat = await fs.stat(file);
+            if (!stat.isFile() || !stat.size || files.some(f => f.path === file))
+                throw Error('Invalid input');
+            files.push({ path: file, label: path.basename(file), size: stat.size, mtime: stat.mtimeMs });
+        }
+        args.server = await fs.realpath(args.server);
+        if (!(await fs.stat(args.server)).isFile())
+            throw Error('Invalid server');
+        args.roots = await Promise.all(args.roots.map(async (root) => { const real = await fs.realpath(root); if (!(await fs.stat(real)).isDirectory())
+            throw Error('Invalid source root'); return real; }));
+        host = await new BrowserHost({ ...args, files }).listen(args.port);
+        const launch = host.url();
+        process.stdout.write('HeapLens local browser (keep this terminal running):\n' + launch + '\nThis launch URL is a private session capability. Do not share it. Ctrl+C stops owned servers.\n');
+        if (args.browser) {
+            const launcher = process.platform === 'darwin' ? ['open', [launch]] : process.platform === 'win32' ? ['rundll32', ['url.dll,FileProtocolHandler', launch]] : ['xdg-open', [launch]];
+            const browser = spawn(launcher[0], launcher[1], { stdio: 'ignore', windowsHide: true });
+            browser.on('error', () => process.stderr.write('Could not open a browser. Paste the private launch URL above.\n'));
+        }
+        for (const signal of ['SIGINT', 'SIGTERM'])
+            process.once(signal, () => host.shutdown());
+        // Retire the service if its foreground CLI parent exits unexpectedly.
+        const parent = process.ppid;
+        const check = setInterval(() => { try {
+            process.kill(parent, 0);
+        }
+        catch {
+            clearInterval(check);
+            host.shutdown();
+        } }, 3000);
+        check.unref();
+    }
+    catch {
+        await host?.shutdown();
+        process.stderr.write('Cannot start local browser. Check Node runtime, built browser assets, server binary, dump/source paths and port.\n');
+        process.exitCode = 3;
+    }
+}
+if (require.main === module)
+    main(process.argv.slice(2));
+module.exports = { BrowserHost, options, main };

package/runtime/browser-ui/session.cjs

@@ -0,0 +1,184 @@
+'use strict';
+const crypto = require('node:crypto');
+const { AsyncLocalStorage } = require('node:async_hooks');
+const { Rpc } = require('./rpc.cjs');
+const { requestId, objectId } = require('./guards.cjs');
+const capabilities = ["object-actions", "consent-actions", "source-actions", "ai-actions", "snapshot-actions", "export-actions", "monitor-actions", "telemetry-actions", "progressive-actions", "waste-actions"].map(name => require('./' + name + '.cjs'));
+const rename = { summary: 'summary', top_objects: 'topObjects', top_layers: 'topLayers', class_histogram: 'classHistogram', leak_suspects: 'leakSuspects', object_leak_suspects: 'objectLeakSuspects', waste_analysis: 'wasteAnalysis', storage: 'storage' };
+// Immutable compact snapshots, not a second heap graph or comparator.
+function snapshot(raw) {
+    const summary = Object.fromEntries(['total_heap_size', 'reachable_heap_size', 'total_instances', 'total_classes', 'total_arrays', 'total_gc_roots'].map(k => [k, raw.summary[k]]));
+    const waste = raw.waste_analysis ? Object.fromEntries(['total_wasted_bytes', 'waste_percentage', 'duplicate_string_wasted_bytes', 'empty_collection_wasted_bytes', 'over_allocated_wasted_bytes', 'boxed_primitive_wasted_bytes'].map(k => [k, raw.waste_analysis[k]])) : null;
+    const value = { summary, class_histogram: raw.class_histogram, leak_suspects: raw.leak_suspects, waste_analysis: waste };
+    if (Buffer.byteLength(JSON.stringify(value)) > 8 * 1024 * 1024)
+        throw Error('Comparison metadata exceeds 8 MiB');
+    return value;
+}
+class Session {
+    constructor(host, file) {
+        this.host = host;
+        this.file = file;
+        this.id = crypto.randomUUID();
+        this.generation = 0;
+        this.events = [];
+        this.seq = 0;
+        this.eventBytes = 0;
+        this.state = 'idle';
+        this.raw = null;
+        this.mode = host.quickScan ? 'shallow' : 'full';
+        this.history = [];
+        this.config = null;
+        this.chatGrant = null;
+        this.pendingConsent = null;
+        this.activeAi = null;
+        this.actionContext = new AsyncLocalStorage();
+        // New host capabilities extend this registry instead of changing analysis classes.
+        this.commands = new Map(Object.entries({ ready: m => this.ready(), retryAnalysis: m => this.analyze(), cancelAnalysis: m => this.cancel(), closeDump: m => this.close(), shutdown: m => this.host.shutdown() }));
+        for (const capability of capabilities)
+            capability.install(this);
+    }
+    purge() { this.events = []; this.eventBytes = 0; }
+    attach(view) { if (typeof view !== 'string' || !/^[a-f0-9-]{36}$/.test(view))
+        throw Error('Invalid page session'); if (this.view !== view) {
+        this.view = view;
+        this.stopAi();
+        this.monitor?.close();
+        this.monitor = null;
+        this.chatGrant = null;
+        this.purge();
+    } }
+    emit(command, data = {}) {
+        const action = this.actionContext.getStore();
+        if (action && (action.view !== this.view || action.generation !== this.generation))
+            return;
+        const message = { command, ...data };
+        try { require('./telemetry-actions.cjs').observe(this,command,data); } catch { /* Diagnostics cannot fail UI delivery. */ }
+        const bytes = Buffer.byteLength(JSON.stringify(message));
+        if (bytes > 64 * 1024 * 1024)
+            throw Error('UI response exceeds 64 MiB');
+        this.events.push({ seq: ++this.seq, message, bytes });
+        this.eventBytes += bytes;
+        while (this.events.length > 256 || this.eventBytes > 64 * 1024 * 1024) {
+            this.eventBytes -= this.events.shift().bytes;
+        }
+    }
+    async dispatch(m) {
+        if (!m || typeof m !== 'object' || Array.isArray(m) || !this.commands.has(m.command) || this.state === 'closed' && !['ready', 'shutdown'].includes(m.command))
+            throw Error('Unsupported action');
+        const action = this.commands.get(m.command);
+        if (['ready', 'retryAnalysis', 'quickScan', 'analyzeRetained', 'cancelAnalysis', 'closeDump', 'shutdown'].includes(m.command))
+            await this.actionContext.run(undefined, () => action(m));
+        else
+            await this.actionContext.run({ view: this.view, generation: this.generation }, () => action(m));
+    }
+    status(message) { this.emit('browserStatus', { message }); }
+    ready() {
+        if (this.raw) {
+            if(this.mode === 'shallow') this.emit('shallowScanComplete', {summary:this.raw.summary,classHistogram:this.raw.class_histogram,readiness:this.raw.readiness});
+            else this.emit('analysisComplete', { ...Object.fromEntries(Object.entries(rename).map(([a, b]) => [b, this.raw[a]])), displayName: this.file.label });
+            this.status('READY | server PID ' + this.rpc?.child.pid);
+            this.emit('aiHistory', { messages: this.history });
+        }
+        else if (this.state === 'idle')
+            this.analyze();
+        else
+            this.status(this.state === 'closed' ? 'Dump closed. Start a new CLI session to reopen.' : this.state.toUpperCase() + ' | server PID ' + (this.rpc?.child.pid || 'pending'));
+    }
+    async analyze(mode = this.mode) {
+        if (['loading', 'queued'].includes(this.state))
+            return;
+        const generation = ++this.generation;
+        this.mode = mode;
+        const shallow = mode === 'shallow';
+        this.stopAi();
+        this.chatGrant = null;
+        this.history = [];
+        this.monitor?.close();
+        this.raw = null;
+        this.snapshot = null;
+        this.rpc?.close();
+        this.purge();
+        this.state = 'queued';
+        this.host.changed();
+        this.emit('analysisStarting',{analysisScope:mode});
+        this.emit('analysisProgress', { stage: 'loading', phase: 1, totalPhases: 4, fileMetadata: { file_size: this.file.size } });
+        this.status('Waiting for analysis slot. Other dumps remain available.');
+        await this.host.slot(async () => {
+            if (generation !== this.generation || this.state === 'closed')
+                return;
+            this.state = 'loading';
+            this.rpc = new Rpc(this.host.server, this.host.legacy);
+            const rpc = this.rpc;
+            this.status('ANALYZING | server PID ' + rpc.child.pid);
+            rpc.on('unavailable', () => { if (generation !== this.generation)
+                return; this.state = 'failed'; this.raw = null; this.snapshot = null; this.stopAi(); this.host.changed(); this.emit('serverCrashed', { message: 'Analysis server unavailable. Retry starts a new server.' }); this.status('SERVER UNAVAILABLE | Retry'); this.finishAnalysis?.(); });
+            let finish;
+            const completed = new Promise(resolve => { finish = resolve; });
+            this.finishAnalysis = finish;
+            rpc.on('notification', message => {
+                if (generation !== this.generation || this.state !== 'loading' || message.params?.request_id !== this.analysisId)
+                    return;
+                const p = message.params;
+                if (message.method === (shallow ? 'heap_scan_progress' : 'heap_analysis_progress'))
+                    this.emit('analysisProgress', { stage: p.stage, phase: p.phase, totalPhases: p.total_phases, summary: p.summary, snapshot: p.snapshot, fileMetadata: p.file_metadata });
+                if (message.method === (shallow ? 'heap_scan_complete' : 'heap_analysis_complete')) {
+                    if (p.status === 'completed') {
+                        this.raw = p;
+                        this.state = shallow ? 'shallow-ready' : 'ready';
+                        try {
+                            this.snapshot = shallow ? null : snapshot(p);
+                        }
+                        catch {
+                            this.snapshot = null;
+                            this.status('READY. Comparison metadata exceeds its limit.');
+                        }
+                        this.ready();
+                        this.host.changed();
+                    }
+                    else {
+                        this.state = p.status === 'cancelled' ? 'cancelled' : 'failed';
+                        this.raw = null;
+                        this.snapshot = null;
+                        this.emit(p.status === 'cancelled' ? 'analysisCancelled' : 'serverCrashed', { message: 'Analysis failed or was cancelled. Retry.' });
+                        this.status(this.state.toUpperCase() + ' | Retry');
+                    }
+                    finish();
+                }
+            });
+            try {
+                const started = rpc.request(shallow ? 'scan_heap' : 'analyze_heap', { path: this.file.path }, 30000);
+                this.analysisId = started.id;
+                await started.promise;
+                await completed;
+            }
+            catch {
+                if (generation === this.generation) {
+                    this.state = 'failed';
+                    this.emit('serverCrashed', { message: 'Server did not acknowledge analysis. Retry.' });
+                    rpc.close();
+                }
+                finish();
+            }
+            finally {
+                if (this.finishAnalysis === finish)
+                    this.finishAnalysis = null;
+            }
+        });
+    }
+    async cancel() {
+        if (this.state === 'queued') {
+            this.generation++;
+            this.state = 'cancelled';
+            this.emit('analysisCancelled');
+            this.status('CANCELLED | Retry');
+            return;
+        }
+        if (this.state === 'loading')
+            await this.rpc.call('cancel_analysis', { path: this.file.path, analysis_request_id: this.analysisId }).catch(() => { });
+    }
+    async engine(method, params) { if (this.state !== 'ready' || !this.rpc)
+        throw Error('Wait for analysis or Retry.'); const gen = this.generation; const result = await this.rpc.call(method, { ...params, path: this.file.path }); if (gen !== this.generation || this.state !== 'ready')
+        throw Error('Analysis changed. Repeat the action.'); return result; }
+    close() { this.generation++; this.state = 'closed'; this.stopAi(); this.config = null; this.history = []; this.raw = null; this.snapshot = null; this.rpc?.close(); this.monitor?.close(); this.finishAnalysis?.(); this.purge(); this.host.changed(); this.emit('analysisCancelled'); this.status('Dump closed; server stopped. Other dumps are unaffected.'); }
+}
+module.exports = { Session, snapshot, requestId, objectId };

package/runtime/browser-ui/snapshot-actions.cjs

@@ -0,0 +1,38 @@
+'use strict';
+const { requestId } = require('./guards.cjs');
+const actions = {
+    list(all) { const rows = this.host.available().filter(s => all || s !== this); this.emit(all ? 'allAnalyzedFiles' : 'analyzedFiles', { files: rows.map(s => s.id), labels: Object.fromEntries(rows.map(s => [s.id, s.file.label])) }); },
+    async compare(m) {
+        const id = requestId(m);
+        try {
+            const baseline = this.host.sessions.get(m.baselinePath);
+            if (!baseline?.snapshot || !this.snapshot || baseline === this)
+                throw Error();
+            const a = baseline.snapshot, b = this.snapshot;
+            const result = await this.engine('compare_snapshots', { baseline: a, current: b, baseline_label: baseline.file.label, current_label: this.file.label });
+            if (a !== baseline.snapshot || b !== this.snapshot)
+                throw Error();
+            this.emit('compareResult', { requestId: id, result, sizeModelsDiffer: JSON.stringify(baseline.raw.summary.size_model) !== JSON.stringify(this.raw.summary.size_model) });
+        }
+        catch {
+            this.emit('compareError', { requestId: id, error: 'Choose two currently analyzed dumps with comparison metadata below 8 MiB.' });
+        }
+    },
+    timeline(m) {
+        const id = requestId(m);
+        try {
+            if (!Array.isArray(m.paths) || m.paths.length < 2 || m.paths.length > 8 || new Set(m.paths).size !== m.paths.length)
+                throw Error();
+            const selected = m.paths.map(id => { const s = this.host.sessions.get(id); if (!s?.snapshot)
+                throw Error(); return s; }).sort((a, b) => a.file.mtime - b.file.mtime);
+            const tracked = new Set(selected.flatMap(s => s.snapshot.class_histogram.slice(0, 10).map(x => x.class_name)));
+            this.emit('timelineDataResponse', { requestId: id, sizeModelsDiffer: new Set(selected.map(s => JSON.stringify(s.raw.summary.size_model))).size > 1, result: { snapshots: selected.map(s => ({ path: s.file.label, timestamp: s.file.mtime / 1000, summary: s.snapshot.summary, size_model: s.raw.summary.size_model, top_classes: s.snapshot.class_histogram.filter(x => tracked.has(x.class_name)) })) } });
+        }
+        catch {
+            this.emit('timelineError', { requestId: id, error: 'Select 2–8 analyzed dumps. Time order is file modification time, not necessarily capture time.' });
+        }
+    }
+};
+module.exports.install = session => { for (const [name, action] of Object.entries(actions))
+    session[name] = action.bind(session); for (const [command, handler] of Object.entries({ listAnalyzedFiles: m => session.list(false), listAllAnalyzedFiles: m => session.list(true), compareHeaps: m => session.compare(m), getTimelineData: m => session.timeline(m) }))
+    session.commands.set(command, handler); };

package/runtime/browser-ui/source-actions.cjs

@@ -0,0 +1,38 @@
+'use strict';
+const { requestId } = require('./guards.cjs');
+const actions = {
+    async selectSource(name, signal) {
+        const matches = await this.host.sources.find(name);
+        if (!matches.length)
+            throw Error('No matching Java file under --source-root. Add the source folder when launching.');
+        if (matches.length === 1)
+            return matches[0];
+        const selected = await this.consent('Choose source', 'Several files match. Select a local file; no network request is made.', matches.map((f, i) => [f.label + ' (root ' + f.rootIndex + ')', String(i)]).concat([['Cancel', null]]), signal);
+        return selected === null ? null : matches[Number(selected)];
+    },
+    async source(m) {
+        const id = requestId(m), gen = this.generation;
+        try {
+            if (this.state !== 'ready')
+                throw Error();
+            const file = await this.selectSource(m.className);
+            if (gen !== this.generation)
+                return;
+            if (!file) {
+                this.emit('sourceNavigationResult', { requestId: id, className: m.className, status: 'cancelled' });
+                return;
+            }
+            const text = await this.host.sources.read(file);
+            if (gen !== this.generation)
+                return;
+            this.emit('browserSource', { label: file.label, text });
+            this.emit('sourceNavigationResult', { requestId: id, className: m.className, status: 'opened' });
+        }
+        catch {
+            this.emit('sourceNavigationResult', { requestId: id, className: m.className, status: 'not-found' });
+            this.emit('localActionStatus', { message: 'Source unavailable. Supply --source-root. Dependency-JAR lookup/decompilation is not bundled.' });
+        }
+    }
+};
+module.exports.install = session => { for (const [name, action] of Object.entries(actions))
+    session[name] = action.bind(session); session.commands.set('openProjectSource', m => session.source(m)); };