xsbug-debugmachine.js

/*
 * Copyright (c) 2022-2026  Moddable Tech, Inc.
 *
 *   This file is part of the Moddable SDK Tools.
 *
 *   The Moddable SDK Tools is free software: you can redistribute it and/or modify
 *   it under the terms of the GNU General Public License as published by
 *   the Free Software Foundation, either version 3 of the License, or
 *   (at your option) any later version.
 *
 *   The Moddable SDK Tools is distributed in the hope that it will be useful,
 *   but WITHOUT ANY WARRANTY; without even the implied warranty of
 *   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 *   GNU General Public License for more details.
 *
 *   You should have received a copy of the GNU General Public License
 *   along with the Moddable SDK Tools.  If not, see <http://www.gnu.org/licenses/>.
 *
 */

/*
	Generated by Claude Code and Google Antigravity. Beware.
*/

const fs = require('node:fs');
const { Machine } = require('./xsbug-machine.js');
const { TestRunner } = require('./xsbug-test.js');

class DebugMachine extends Machine {
	// View data from the protocol
	view = {};

	// Log accumulation (from LogMachine)
	log = "";
	binaryOutput = null;

	// Debugger state
	broken = false;
	running = false;
	connected = false;

	// Current stop location
	currentPath = null;
	currentLine = null;

	// Known file paths (collected from frames)
	knownPaths = new Set();

	// Settings
	exceptionsMode = 'off';
	breakOnStart = false;

	// Timestamps on device traces: 'off', 'time', 'delta', 'elapsed', 'iso', 'epoch'
	timestamps = 'off';

	// Reference points for 'delta' and 'elapsed' (host arrival times, in ms). Shared by every
	// thread: traces from all threads interleave in one console, so the timeline must be one
	// timeline — a per-thread delta would hide the time for events to travel between threads.
	static sessionTime = null;
	static lastLogTime = null;

	// User breakpoints: array of { path, line }
	breakpoints = [];

	// Source file cache: path -> lines array
	sourceCache = {};

	// Last list position: { path, line } for "list" continuation
	listPosition = null;

	// Command history
	lastCommand = '';

	// Prompt state
	promptShown = false;

	// Pending callback for async toggle/view updates
	pendingViewCallback = null;
	pendingViewName = null;

	// command output format "text" or "JSON"
	outputFormat = 'text';

	completionsShown = false;

	completer(line, callback) {
		const finish = (result) => {
			let [completions, matched] = result;
			// Nothing to complete if only match is what's already typed
			if (completions.length === 1 && completions[0] === matched)
				completions = [];
			if (completions.length > 1) {
				if (!this.completionsShown)
					this._displayCompletions(completions);
				// The list is ours to show. Hand readline only a longer common prefix to insert, never the list:
				// on a second consecutive tab it would print its own table and redraw the prompt below it.
				let prefix = completions[0];
				for (const completion of completions) {
					let i = 0;
					while ((i < prefix.length) && (i < completion.length) && (prefix[i] === completion[i])) i++;
					prefix = prefix.slice(0, i);
				}
				completions = (prefix.length > matched.length) ? [prefix] : [];
			}
			callback(null, [completions, matched]);
		};
		if (this.broken) {
			const args = line.trimStart().split(/\s+/);
			const cmd = args[0];
			if (cmd === 'print' || cmd === 'p') {
				const expr = line.substring(line.indexOf(cmd) + cmd.length).trimLeft();
				if (expr && expr.includes('.')) {
					this._expandForCompletion(expr, () => {
						finish(this._syncCompleter(line));
					});
					return;
				}
				if (expr) {
					// Expand (..) in globals so built-ins are available for completion
					this._expandGlobalPrototype(() => {
						finish(this._syncCompleter(line));
					});
					return;
				}
			}
		}
		finish(this._syncCompleter(line));
	}

	_displayCompletions(completions) {
		const width = process.stdout.columns || 80;
		const maxLen = Math.max(...completions.map(c => c.length)) + 2;
		const cols = Math.max(1, Math.floor((width - 1) / maxLen));	// a row must stay short of the width, or the terminal wraps before our newline and the cursor math is off by one
		let out = '';
		for (let i = 0; i < completions.length; i++) {
			out += completions[i].padEnd(maxLen);
			if ((i + 1) % cols === 0) out += '\r\n';
		}
		if (completions.length % cols !== 0) out += '\r\n';
		// Count lines written (initial newline + completion rows)
		const linesDown = (out.match(/\n/g) || []).length + 1;
		// Write completions below, move cursor back up to prompt
		process.stdout.write(`\r\n${out}\x1b[${linesDown}A`);
		// Position cursor at end of current input
		const col = (this.rl._prompt || '').length + this.rl.line.length;
		process.stdout.write(`\r\x1b[${col}C`);
		this.completionsShown = true;
		// Clear completions on next non-TAB keypress
		const handler = (str, key) => {
			if (key && key.name === 'tab')
				return;
			const col = (this.rl._prompt || '').length + this.rl.line.length;
			process.stdout.write(`\r\n\x1b[J\x1b[A\r\x1b[${col}C`);
			this.completionsShown = false;
			process.stdin.removeListener('keypress', handler);
		};
		process.stdin.on('keypress', handler);
	}

	_expandGlobalPrototype(callback) {
		const globals = this.view.global || [];
		const dotdot = globals.find(i => i.name === '(..)');
		if (dotdot && this.isExpandable(dotdot) && !dotdot.children) {
			this.toggleOpen(dotdot, () => this._expandGlobalPrototype(callback));
			return;
		}
		callback();
	}

	_expandForCompletion(expr, callback) {
		const parts = [];
		const regex = /\["([^"]*)"?\]?|\['([^']*)'?\]?|\[`([^`]*)`?\]?|(\[[0-9]*\]?)|\.([^.\[]*)|^([^.\[]+)/g;
		let match;
		while ((match = regex.exec(expr)) !== null) {
			let val;
			if (match[1] !== undefined) val = match[1];
			else if (match[2] !== undefined) val = match[2];
			else if (match[3] !== undefined) val = match[3];
			else if (match[4] !== undefined) val = match[4];
			else if (match[5] !== undefined) val = match[5];
			else if (match[6] !== undefined) val = match[6];
			if (val !== undefined) parts.push(val);
		}
		if (parts.length < 2) {
			callback();
			return;
		}

		const locals = this.view.local || [];
		const globals = this.view.global || [];

		let items;
		let startIndex;
		if (parts[0] === 'globalThis' || parts[0] === 'global') {
			items = globals;
			startIndex = 1;
		} else {
			let root = locals.find(i => i.name === parts[0]);
			if (!root) root = globals.find(i => i.name === parts[0]);
			if (!root) {
				// Search globals as if globalThis — Date, Math, etc. live there
				items = globals;
				startIndex = 0;
			} else {
				if (this.isExpandable(root) && !root.children) {
					this.toggleOpen(root, () => this._expandForCompletion(expr, callback));
					return;
				}
				items = root.children;
				startIndex = 1;
			}
		}

		this._expandPath(expr, items, parts, startIndex, callback);
	}

	_expandNextPrototype(items, expr, callback, visited = new Set()) {
		const dotdot = items.find(i => i.name === '(..)');
		if (!dotdot || !dotdot.value) return false;
		if (visited.has(dotdot.value)) return false;
		visited.add(dotdot.value);
		if (this.isExpandable(dotdot) && !dotdot.children) {
			this.toggleOpen(dotdot, () => this._expandForCompletion(expr, callback));
			return true;
		}
		if (dotdot.children)
			return this._expandNextPrototype(dotdot.children, expr, callback, visited);
		return false;
	}

	_expandPath(expr, items, parts, index, callback) {
		if (!items || index >= parts.length - 1) {
			if (items) {
				const needsExpand = items.find(c =>
					this.isPrivateContainer(c) && this.isExpandable(c) && !c.children
				);
				if (needsExpand) {
					this.toggleOpen(needsExpand, () => {
						this._expandForCompletion(expr, callback);
					});
					return;
				}
				if (this._expandNextPrototype(items, expr, callback))
					return;
			}
			callback();
			return;
		}

		const name = parts[index];

		// Expand unexpanded private containers before searching #fields
		if (name.startsWith('#')) {
			const unexpandedContainer = items.find(i =>
				this.isPrivateContainer(i) && this.isExpandable(i) && !i.children
			);
			if (unexpandedContainer) {
				this.toggleOpen(unexpandedContainer, () => this._expandForCompletion(expr, callback));
				return;
			}
		}

		// Expand (..) if it's needed but not yet expanded
		const dotdot = items.find(i => i.name === '(..)');
		if (dotdot && this.isExpandable(dotdot) && !dotdot.children) {
			// Only expand if the name isn't found directly
			if (!items.find(i => i.name === name)) {
				this.toggleOpen(dotdot, () => this._expandForCompletion(expr, callback));
				return;
			}
		}

		const item = this.findProperty(items, name);
		if (!item) {
			callback();
			return;
		}

		if (this.isExpandable(item) && !item.children) {
			this.toggleOpen(item, () => this._expandForCompletion(expr, callback));
			return;
		}

		this._expandPath(expr, item.children, parts, index + 1, callback);
	}

	_syncCompleter(line) {
		const commands = ['run', 'continue', 'next', 'step', 'finish', 'until', 'break', 'clear', 'delete', 'condition', 'trace', 'hitcount', 'eval', 'info', 'list', 'backtrace', 'where', 'frame', 'print', 'set', 'quit', 'help', 'thread', 'test'];
		const args = line.trimStart().split(/\s+/);
		
		if (args.length === 1 && !line.match(/\s$/)) {
			const hits = commands.filter(c => c.startsWith(args[0]));
			return [hits.length ? hits : commands, args[0]];
		}
		
		const cmd = args[0];
		// If line ends with space, the prefix being typed is empty
		const prefix = line.match(/\s$/) ? "" : args[args.length - 1];
		const argCount = line.match(/\s$/) ? args.filter(Boolean).length + 1 : args.length;	// a trailing space starts a new, empty argument
		
		if (cmd === 'info') {
			const subcmds = ['breakpoints', 'locals', 'globals', 'modules', 'module', 'instruments', 'exceptions', 'start', 'threads', 'tests', 'test262'];
			if (argCount === 2) {
				const hits = subcmds.filter(c => c.startsWith(prefix));
				return [hits.map(h => `${cmd} ${h}`), line];
			}
			if (argCount === 3 && (args[1] === 'module')) {
				if (this.view.modules) {
					const names = this.view.modules.map(m => m.name).filter(n => n !== '(map)' && n.startsWith(prefix));
					return [names.map(n => `${cmd} ${args[1]} ${n}`), line];
				}
			}
		}
		
		if (cmd === 'test') {
			if (argCount === 2) {
				const hits = ['stop'].filter(c => c.startsWith(prefix)).concat(this.tests?.complete(prefix) ?? []);
				return [hits.map(h => `${cmd} ${h}`), line];
			}
		}

		if (cmd === 'delete' || cmd === 'clear') {
			if (argCount === 2) {
				const hits = ['all'].filter(c => c.startsWith(prefix));
				return [hits.map(h => `${cmd} ${h}`), line];
			}
		}

		if (cmd === 'set') {
			if (argCount === 2) {
				const subcmds = ['exceptions', 'output', 'mcsim', 'start', 'timestamps', 'test262', 'test'];
				const hits = subcmds.filter(c => c.startsWith(prefix));
				return [hits.map(h => `${cmd} ${h}`), line];
			}
			if (argCount === 3) {
				let options = [];
				if (args[1] === 'exceptions') options = ['on', 'off', 'silent'];
				else if (args[1] === 'test') options = ['timeout'];
				else if (args[1] === 'output') options = ['json', 'text'];
				else if (args[1] === 'timestamps') options = ['on', 'off', 'time', 'delta', 'elapsed', 'iso', 'epoch'];
				else if (args[1] === 'mcsim' || args[1] === 'start') options = ['on', 'off'];
				else if (args[1] === 'test') options = ['timeout', 'log'];
				
				const hits = options.filter(c => c.startsWith(prefix));
				return [hits.map(h => `${cmd} ${args[1]} ${h}`), line];
			}
		}

		if (cmd === 'print' || cmd === 'p') {
			const locals = this.view.local || [];
			const globals = this.view.global || [];
			
			const expr = line.substring(cmd.length).trimLeft();
			if (!expr) {
				let options = [...new Set([...this.getCompletableNames(locals, ''), ...this.getCompletableNames(globals, '')])];
				options.sort((a, b) => a.localeCompare(b, undefined, { sensitivity: 'base' }));
				return [options, ''];
			}
			
			const parts = [];
			const regex = /\["([^"]*)"?\]?|\['([^']*)'?\]?|\[`([^`]*)`?\]?|(\[[0-9]*\]?)|\.([^.\[]*)|^([^.\[]+)/g;
			let match;
			while ((match = regex.exec(expr)) !== null) {
				let val;
				if (match[1] !== undefined) val = match[1];
				else if (match[2] !== undefined) val = match[2];
				else if (match[3] !== undefined) val = match[3];
				else if (match[4] !== undefined) val = match[4];
				else if (match[5] !== undefined) val = match[5];
				else if (match[6] !== undefined) val = match[6];
				
				if (val !== undefined) parts.push(val);
			}
			
			const resolveDotPathCompletion = (items, partsArr, partIndex) => {
				if (partIndex === partsArr.length - 1) {
					return this.getCompletableNames(items, partsArr[partIndex], true);
				}
				const item = this.findProperty(items, partsArr[partIndex]);
				if (item && item.children)
					return resolveDotPathCompletion(item.children, partsArr, partIndex + 1);
				return [];
			};

			let options = [];
			if (parts.length === 1) {
				const localNames = resolveDotPathCompletion(locals, parts, 0);
				const globalNames = resolveDotPathCompletion(globals, parts, 0);
				options = [...new Set([...localNames, ...globalNames])];
			} else {
				if (parts[0] === 'globalThis' || parts[0] === 'global') {
					options = resolveDotPathCompletion(globals, parts, 1);
				} else {
					options = resolveDotPathCompletion(locals, parts, 0);
					if (options.length === 0) {
						options = resolveDotPathCompletion(globals, parts, 0);
					}
				}
				options = [...new Set(options)];
			}

			options.sort((a, b) => a.localeCompare(b, undefined, { sensitivity: 'base' }));
			return [options, parts[parts.length - 1]];
		}

		return [[], line];
	}

	// --- Output helpers ---

	clearLine() {
		// Implemented dynamically via Router in xsbug-log.js
	}

	showPrompt() {
		if (!this.promptShown) {
			this.promptShown = true;
			this.rl.prompt(true);
		}
	}

	print(text, path, line, eventType = 'print', time) {
		const payload = { text };
		if (path !== undefined && path !== null) payload.path = path;
		if (line !== undefined && line !== null) payload.line = parseInt(line);
		// Only traces from the device are timestamped. The time is when the host received
		// the trace, so it trails the moment the device emitted it by the transport latency.
		let stamp = '';
		if (eventType === 'log') {
			payload.time = time ?? Date.now();
			stamp = this.formatTimestamp(payload.time);
		}
		this.report(eventType, payload, undefined, (data) => {
			this.clearLine();
			let out = data.text;
			if (data.path) out = `${data.path} (${data.line}) ${out}`;
			if (this.id !== undefined) out = `[Thread ${this.id}] ${out}`;
			if (stamp) out = `${stamp} ${out}`;
			console.log(out);
			this.showPrompt();
		});
	}

	// Returns the display prefix for a trace received at `time` (empty when timestamps are off).
	// Always advances the reference points, so switching modes mid-session gives a sane first value.
	formatTimestamp(time) {
		const previous = DebugMachine.lastLogTime;
		DebugMachine.lastLogTime = time;
		DebugMachine.sessionTime ??= time;

		switch (this.timestamps) {
			case 'time': {
				const d = new Date(time);
				const pad = (value, count = 2) => String(value).padStart(count, '0');
				return `${pad(d.getHours())}:${pad(d.getMinutes())}:${pad(d.getSeconds())}.${pad(d.getMilliseconds(), 3)}`;
			}
			case 'iso':
				return new Date(time).toISOString();
			case 'epoch':
				return String(time);
			case 'delta':
				return this.formatSeconds((previous === null) ? 0 : time - previous);
			case 'elapsed':
				return this.formatSeconds(time - DebugMachine.sessionTime);
			default:
				return '';
		}
	}

	formatSeconds(ms) {
		return `+${(ms / 1000).toFixed(3)}`.padStart(8);
	}

	commandError(message) {
		const cmd = this.currentCommand || 'error';
		this.report(cmd, undefined, (typeof message === 'string') ? { message } : message, (data, err) => {
			this.clearLine();
			console.log(err.message);
			this.showPrompt();
		});
	}

	report(event, data, error, formatter) {
		if (this.outputFormat === 'json') {
			this.clearLine();
			const output = { event };
			if (this.id !== undefined) output.thread = this.id;
			if (data !== undefined && data !== null) output.data = data;
			if (error !== undefined && error !== null) output.error = error;
			console.log(JSON.stringify(output, null, 2));
			this.showPrompt();
		} else if (formatter) {
			formatter(data, error);
		}
	}

	// --- Protocol event handlers ---

	onTitleChanged(title, tag) {
		this.tag = tag;
		this.title = title;
		this.connected = true;
		DebugMachine.sessionTime ??= Date.now();		// first connection anchors "set timestamps elapsed"
		this.interactive = (title !== "mcsim");
		this.once = true;

		this.onTitleReady?.();

		if (this.interactive && !this.tests?.running)		// the test app reconnects after every test
			this.print(`Connected to "${title}"`);
	}

	onParsed() {
		if (this.once) {
			this.once = false;

			// Send <go/> BEFORE <set-all-breakpoints> to precisely match the xsbug GUI protocol initialization sequence.
			// This addresses an unblocking state machine issue on certain targets (like ESP/Zephyr) when breakOnStart is active.
			this.doGo();
			this.doSetAllBreakpoint(this.breakpoints, this.breakOnStart, this.exceptionsMode === 'on');
			this.running = true;
		}
	}

	onViewChanged(name, items) {
		if (name === 'property') {
			if (items && items.length > 0) {
				const prop = items[0];
				if (prop && prop.value) {
					const hydrateNode = (nodes, visited = new Set()) => {
						if (!nodes) return;
						for (const node of nodes) {
							if (visited.has(node)) continue;
							visited.add(node);
							if (node.value === prop.value) {
								node.children = prop.children;
								node.flags = prop.flags;
							}
							if (node.children) {
								hydrateNode(node.children, visited);
							}
						}
					};
					hydrateNode(this.view.local);
					hydrateNode(this.view.global);
				}
			}
		}
		
		if (this.view[name] && name !== 'property') {
			const hydrateView = (oldItems, newItems, visited = new Set()) => {
				if (!oldItems || !newItems) return;
				for (const newItem of newItems) {
					if (visited.has(newItem.name)) continue;
					visited.add(newItem.name);
					const oldItem = oldItems.find(i => i.name === newItem.name);
					if (oldItem) {
						if (oldItem.children && (!newItem.children || newItem.children.length === 0)) {
							newItem.children = oldItem.children;
							// Also preserve the expanded flag if we hydrated children
							if (newItem.flags && newItem.flags.charAt(0) === '+') {
								newItem.flags = '-' + newItem.flags.slice(1);
							}
						} else if (oldItem.children && newItem.children) {
							hydrateView(oldItem.children, newItem.children, new Set());
						}
					}
				}
			};
			hydrateView(this.view[name], items);
		}
		if (name !== 'property') {
			this.view[name] = items;
		}
		if (name === 'frames') {
			for (const frame of items) {
				if (frame.path)
					this.knownPaths.add(frame.path);
			}
		}
		if (this.pendingViewCallback) {
			if (!this.pendingViewName || this.pendingViewName === name) {
				const pendingViewCallback = this.pendingViewCallback;
				this.pendingViewCallback = null;
				this.pendingViewName = null;
				pendingViewCallback(items, name);
			}
		}
	}

	onFileChanged(path, line) {
		this.currentPath = path;
		this.currentLine = line;
	}

	onFrameChanged(name, value) {
		this.currentFrameValue = value;
	}

	onResult(items, data) {
		let result;
		if (items.length === 0) {
			result = data;
		}
		else {
			const prop = items[0];
			if (!prop.children || prop.children.length === 0)
				result = prop.value;
			else {
				let parts = [];
				for (const child of prop.children) {
					if (child.name && child.name !== "(..)")
						parts.push(`${child.name}: ${child.value}`);
					if (parts.length > 20) {
						parts.push("…");
						break;
					}
				}
				result = "{ " + parts.join(", ") + " }";
			}
		}
		this.clearLine();
		console.log(result);
		this.showPrompt();
	}

	onBroken(path, line, text) {
		// Auto-continue for non-interactive connections (e.g., mcsim)
		if (!this.interactive) {
			this.doGo();
			return;
		}

		this.broken = true;
		this.running = false;

		if (path) {
			this.currentPath = path;
			this.knownPaths.add(path);
		}
		if (line)
			this.currentLine = line;

		// Handle temporary breakpoint (until command)
		if (this.temporaryBreakpoint) {
			const temporaryBreakpoint = this.temporaryBreakpoint;
			this.doClearBreakpoint(temporaryBreakpoint.path, temporaryBreakpoint.line);
			// Remove from user breakpoints if it was added there
			const i = this.breakpoints.findIndex(bp => bp.path === temporaryBreakpoint.path && bp.line === temporaryBreakpoint.line);
			if (i >= 0)
				this.breakpoints.splice(i, 1);
			delete this.temporaryBreakpoint;
		}

		this.clearLine();

		const msg = text ? text.replace(/\n$/, '') : '';
		if (this.onBreakpointHit) this.onBreakpointHit();

		this.report('stopped', { 
			path: this.currentPath ?? '', 
			line: this.currentLine ?? 0, 
			reason: msg 
		}, undefined, (data) => {
			this.printLocation(data.reason);
			this.showPrompt();
		});
	}

	onLogged(path, line, data) {
		this.log += data;
		// Stamp when the first fragment arrives: a trace may be delivered in several pieces.
		this.logTime ??= Date.now();
		if (!this.logPath && path) {
			this.logPath = path;
			this.logLine = line;
			this.knownPaths.add(path);
		}
		if (this.log.endsWith("\n")) {
			if (this.log.startsWith("|:") && this.log.endsWith(":|\n")) {
				const payload = this.log.slice(2, this.log.length - 3);
				if (payload.startsWith("@filename ")) {
					const parts = payload.split(" ");
					if (parts[1])
						this.binaryName = parts[1];
				}
				else if (payload.startsWith("@close")) {
					if (this.binaryOutput) {
						fs.closeSync(this.binaryOutput);
						this.print(`#xsbug-log capture: ${this.binaryPath}`);
					}
					delete this.binaryOutput;
					delete this.binaryName;
					delete this.binaryPath;
				}
				else if (payload.startsWith("@")) {
					// ignore unknown directives
				}
				else if (payload) {
					if (!this.binaryOutput) {
						this.binaryPath = process.env.MODDABLE + "/build/tmp/" + (this.binaryName ? this.binaryName : "log.bin");
						this.binaryOutput = fs.openSync(this.binaryPath, "w+");
					}
					fs.writeSync(this.binaryOutput, Buffer.from(payload, "base64"), 0);
				}
			}
			else if (this.log.startsWith("# Break: ")) {
				// Suppress — onBroken will display this with full context
			}
			else if (this.log.startsWith("# Exception: ")) {
				if (this.exceptionsMode !== 'silent') {
					// Show exception with file/line like xsbug does
					const msg = this.log.slice(0, this.log.length - 1);
					this.print(msg, this.logPath, this.logLine, 'log', this.logTime);
				}
			}
			else {
				this.print(this.log.slice(0, this.log.length - 1), this.logPath, this.logLine, 'log', this.logTime);
			}
			this.log = "";
			this.logPath = null;
			this.logLine = null;
			this.logTime = null;
		}
	}

	// Bubbles carry a conversation name. The test apps use "test262" to talk to the test runner.
	onBubbled(path, line, id, flags, message) {
		if (id === 'test262') {
			this.tests?.onMessage(this, message);
			return;
		}
		if (this.isHidden?.())		// mcsim's own traces, unless "set mcsim on"
			return;
		this.report('bubble', { name: id ?? '', flags: parseInt(flags) || 0, text: message, path, line: parseInt(line) || 0 }, undefined, (data) => {
			this.clearLine();
			console.log(data.name ? `${data.name}: ${data.text}` : data.text);
			this.showPrompt();
		});
	}

	// The engine is waiting for the source of a module the debugger was asked to import (test fixtures).
	onImport(path) {
		TestRunner.answerImport(this, path);
	}

	onInstrumentValues(values) {
		super.onInstrumentValues(values);
		this.instrumentHistory ??= [];
		
		this.instrumentHistory.push({
			time: Date.now(),
			readings: this.instruments.map(i => ({ name: i.name, value: i.value, unit: i.unit }))
		});
		// Assuming ~1 second intervals per VM, retain 5 minutes of logs
		if (this.instrumentHistory.length > 300)
			this.instrumentHistory.shift();
	}

	// --- Display helpers ---

	printLocation(reason) {
		// Reset list position on each stop
		this.listPosition = null;

		let frameLocation = {};

		if (this.view.frames && this.view.frames.length > 0) {
			const frame = this.view.frames[0];
			frameLocation = { name: frame.name, path: frame.path, line: frame.line, shortPath: this.shortPath(frame.path) };
		}
		else if (this.currentPath) {
			frameLocation = { path: this.currentPath, line: this.currentLine, shortPath: this.shortPath(this.currentPath) };
		}

		this.report('location', { ...frameLocation, reason }, undefined, (data) => {
			let loc = '';
			if (data.name) {
				loc = `${data.name}()`;
				if (data.path)
					loc += ` at ${data.shortPath}:${data.line}`;
			} else if (data.path) {
				loc = `at ${data.shortPath}:${data.line}`;
			}

			if (data.reason === '# Break: breakpoint!') {
				const bpIndex = this.breakpoints.findIndex(b => {
					if (b.line == 0)
						return b.path === data.name;
					return b.path === data.path && b.line == data.line;
				});
				const bpNum = bpIndex >= 0 ? this.breakpoints[bpIndex].id : '?';
				console.log(`Breakpoint ${bpNum}, ${loc}`);
			} else if (data.reason === '# Break: step!') {
				console.log(`Step, ${loc}`);
			} else if (data.reason === '# Break: debugger!') {
				console.log(`Debugger, ${loc}`);
			} else if (data.reason && data.reason.startsWith('# Break: ')) {
				let txt = data.reason.replace('# Break: ', '');
				if (txt.startsWith('Error: '))
					txt = 'Exception: ' + txt.slice(7);
				console.log(`${txt}, ${loc}`);
			} else if (data.reason) {
				console.log(`${data.reason}, ${loc}`);
			} else {
				console.log(loc);
			}
		});

		// Show the current source line
		if (this.currentPath && this.currentLine)
			this.printSourceLine(this.currentPath, this.currentLine);
	}

	shortPath(path) {
		// Show just the filename for readability
		if (!path)
			return path;
		const slash = path.lastIndexOf('/');
		if (slash >= 0)
			return path.slice(slash + 1);
		return path;
	}

	isExpandable(item) {
		return item && item.flags && item.flags.charAt(0) === '+';
	}

	findItem(items, name) {
		if (!items)
			return null;
		return items.find(item => item.name === name) || null;
	}

	// Shared property resolution: find a named property in items,
	// handling prototype→(..), #private containers, and (..) chain.
	// Returns the found item or null.
	findProperty(items, name) {
		if (!items)
			return null;

		// Direct lookup
		let found = items.find(i => i.name === name);
		if (found)
			return found;

		// Map 'prototype' to (..)
		if (name === 'prototype')
			return items.find(i => i.name === '(..)') || null;

		// Synthetic 'length' from (array) node value "N items"
		if (name === 'length') {
			const arr = items.find(i => i.name === '(array)');
			if (arr && arr.value) {
				const m = arr.value.match(/^(\d+)\s+item/);
				if (m)
					return { name: 'length', value: m[1], flags: ' ' };
			}
		}

		// Accessor properties: "get X" matches lookup for "X"
		found = items.find(i => i.name === 'get ' + name);
		if (found)
			return found;

		// Search #private in (ClassName) containers
		if (name.startsWith('#')) {
			for (const c of items) {
				if (this.isPrivateContainer(c) && c.children) {
					found = c.children.find(i => i.name === name);
					if (found)
						return found;
				}
			}
			return null;
		}

		// Walk (..) prototype chain
		const dotdot = items.find(i => i.name === '(..)');
		if (dotdot && dotdot.children)
			return this.findProperty(dotdot.children, name);

		return null;
	}

	// Shared completion: collect all visible property names matching a prefix.
	// Traverses own properties, private containers, (..) chain, and adds synthetic 'prototype'.
	getCompletableNames(items, prefix, followPrototype = true) {
		if (!items)
			return [];

		let names = [];

		// Own non-internal properties
		for (const item of items) {
			if (!item.name || item.name.startsWith('('))
				continue;
			if (item.name.startsWith(prefix))
				names.push(item.name);
			// Accessor "get X" / "set X" → expose "X"
			if (item.name.startsWith('get ')) {
				const stripped = item.name.slice(4);
				if (stripped.startsWith(prefix))
					names.push(stripped);
			}
		}

		// Synthetic 'length' from (array) node
		if ('length'.startsWith(prefix)) {
			const arr = items.find(i => i.name === '(array)');
			if (arr && arr.value && /^\d+\s+item/.test(arr.value))
				names.push('length');
		}

		// Private fields from (ClassName) containers
		for (const item of items) {
			if (this.isPrivateContainer(item) && item.children) {
				for (const child of item.children) {
					if (child.name && child.name.startsWith(prefix))
						names.push(child.name);
				}
			}
		}

		// Synthetic 'prototype' when (..) exists and no real 'prototype' property
		const dotdot = items.find(i => i.name === '(..)');
		if (dotdot && 'prototype'.startsWith(prefix) && !items.find(i => i.name === 'prototype'))
			names.push('prototype');

		// Recurse into (..) chain only when requested (top-level variable completion)
		if (followPrototype && dotdot && dotdot.children)
			names = names.concat(this.getCompletableNames(dotdot.children, prefix, true));

		return names;
	}

	// Toggle an item open (expand it). After the view updates, fires callback.
	// viewName optionally specifies which view to wait for (e.g. 'modules').
	toggleOpen(item, callback, viewName) {
		if (!this.isExpandable(item) || !item.value) {
			callback();
			return;
		}
		this.pendingViewName = viewName || 'global';
		this.pendingViewCallback = (items, name) => {
			if (name === 'property' && items) {
				item.children = items;
				item.flags = '-' + item.flags.slice(1);
			}
			callback();
		};
		this.doToggle(item.value);
	}

	// Format a value for display in compact WebKit-style format.
	// depth 0 = expand one level of properties; depth 1+ = abbreviate.
	formatValue(item, depth = 0) {
		if (!item)
			return 'undefined';

		const val = item.value;

		// Leaf node — no children, not expandable
		if (!item.children && !this.isExpandable(item)) {
			if (val === undefined)
				return '(uninitialized)';
			return this.formatLeafValue(val);
		}

		// Has children (expanded object) — format inline
		if (item.children)
			return this.formatObject(item, depth);

		// Expandable but not yet expanded — format from value hint
		if (val === undefined)
			return '{...}';
		return this.formatLeafValue(val);
	}

	formatLeafValue(val) {
		if (val === undefined)
			return '';
		// Function types
		if (val === '(C code)' || val === '(host function)')
			return '[native]';
		// XS code function — value is a file path
		if (typeof val === 'string' && val.startsWith('/') && !val.startsWith("'"))
			return 'function';
		// Hex addresses for unexpanded objects
		if (typeof val === 'string' && val.startsWith('@'))
			return '{...}';
		return val;
	}

	getClassName(children) {
		if (!children)
			return null;
		let promiseState = null;
		// Look for (ClassName) private containers and promises
		for (const child of children) {
			if (child.name === '(promise)')
				promiseState = child.value;

			if (child.name.startsWith('(') && child.name.endsWith(')')
				&& child.name !== '(..)' && child.name !== '(array)') {
				const inner = child.name.slice(1, -1);
				// Skip internal names like (function), (closures), (home), and iterator numbers like (0.0)
				if (!/^[a-z]/.test(inner) && !/^[0-9]/.test(inner))
					return inner;
			}
		}
		if (promiseState)
			return `Promise <${promiseState}>`;
		return null;
	}

	// Collect user-visible properties from an object's children.
	// Returns array of {name, item} pairs.
	collectProperties(children) {
		const props = [];
		if (!children)
			return props;

		for (const child of children) {
			const name = child.name;
			// Skip internal properties
			if (name.startsWith('(') && name.endsWith(')')) {
				if (name === '(value)' || name === '(reason)') {
					const displayName = name === '(reason)' ? '[[PromiseReason]]' : '[[PromiseResult]]';
					props.push({ name: displayName, item: child });
				}
				// But extract private fields from (ClassName) containers
				else if (name !== '(..)' && name !== '(array)' && child.children) {
					const inner = name.slice(1, -1);
					if (!/^[a-z]/.test(inner) && !/^[0-9]/.test(inner)) {
						// This is a private container — include its children as #field
						for (const priv of child.children)
							props.push({ name: priv.name, item: priv });
					}
				}
				continue;
			}
			props.push({ name, item: child });
		}
		props.sort((a, b) => a.name.toLowerCase().localeCompare(b.name.toLowerCase()));
		return props;
	}

	// Check if an expanded item is a function/class
	isFunction(children) {
		return children && children.some(c => c.name === '(function)');
	}

	formatObject(item, depth) {
		const children = item.children;
		if (!children || children.length === 0)
			return '{}';

		let isFunc = false;
		let funcLabel = '';
		if (this.isFunction(children)) {
			isFunc = true;
			funcLabel = 'function';
			const funcChild = this.findItem(children, '(function)');
			if (funcChild) {
				const v = funcChild.value;
				if (v === '(C code)' || v === '(host function)')
					funcLabel = '[native]';
			}
		}

		// Arrays and TypedArrays: format concisely like WebKit if dense
		const arrayNode = children.find(c => c.name === '(array)' || (c.name.startsWith('(') && c.name.endsWith('Array)')));
		if (arrayNode && arrayNode.value) {
			const match = arrayNode.value.match(/^(\d+) items?$/);
			if (match) {
				const length = parseInt(match[1], 10);
				const isTyped = arrayNode.name !== '(array)';
				const prefixStr = isTyped ? `${arrayNode.name.slice(1, -1)} ` : '';

				const props = this.collectProperties(children);
				let isDense = true;
				const elements = [];
				if (props.length === length) {
					for (let i = 0; i < length; i++) {
						const p = props.find(pr => pr.name === `[${i}]`);
						if (!p) {
							isDense = false;
							break;
						}
						elements.push(this.formatValue(p.item, depth + 1));
					}
				} else {
					isDense = false;
				}

				if (isDense) {
					return `${prefixStr}[${elements.join(', ')}] (${length})`;
				}
			}
		}

		// Map special parsing
		const hasMapKeys = children.some(c => c.name === '(0.0)');
		if (hasMapKeys) {
			let count = 0;
			while (children.some(c => c.name === `(${count}.0)`)) count++;
			const elements = [];
			for (let i = 0; i < count; i++) {
				const k = children.find(c => c.name === `(${i}.0)`);
				const v = children.find(c => c.name === `(${i}.1)`);
				if (k && v) elements.push(`${this.formatValue(k, depth + 1)} => ${this.formatValue(v, depth + 1)}`);
			}
			return `Map {${elements.join(', ')}} (${count})`;
		}

		// Set special parsing
		const hasSetKeys = children.some(c => c.name === '(0)');
		if (hasSetKeys) {
			let count = 0;
			while (children.some(c => c.name === `(${count})`)) count++;
			const elements = [];
			for (let i = 0; i < count; i++) {
				const v = children.find(c => c.name === `(${i})`);
				if (v) elements.push(this.formatValue(v, depth + 1));
			}
			return `Set {${elements.join(', ')}} (${count})`;
		}

		// Date special parsing
		const dateNode = children.find(c => c.name === '(date)');
		if (dateNode && dateNode.value) {
			const ms = parseInt(dateNode.value, 10);
			if (!isNaN(ms)) {
				return new Date(ms).toString();
			}
		}

		const className = this.getClassName(children);
		const props = this.collectProperties(children);
		
		let prefix = '';
		if (isFunc) {
			prefix = funcLabel + (props.length > 0 ? ' ' : '');
		} else if (className) {
			prefix = `${className} `;
		}

		const protoNode = children.find(c => c.name === '(..)');

		if (props.length === 0) {
			if (depth === 0 && protoNode && !isFunc) return `${prefix}{prototype: (..)}`;
			if (isFunc) return funcLabel;
			return `${prefix}{}`;
		}

		if (depth > 0) {
			if (isFunc) return funcLabel;
			return `${prefix}{...}`;
		}

		const parts = props.map(p => {
			const val = this.formatValue(p.item, depth + 1);
			return `${p.name}: ${val}`;
		});
		
		if (protoNode && !props.find(p => p.name === 'prototype')) {
			parts.push(`prototype: (..)`);
		}
		
		return `${prefix}{${parts.join(', ')}}`;
	}

	// Check if an expanded item has any private containers that need expanding.
	isPrivateContainer(child) {
		if (!child.name.startsWith('(') || !child.name.endsWith(')'))
			return false;
		if (child.name === '(..)' || child.name === '(array)')
			return false;
		const inner = child.name.slice(1, -1);
		return !/^[a-z]/.test(inner);
	}

	// Check if an expanded item has collapsed private containers.
	hasCollapsedPrivateContainers(item) {
		if (!item.children)
			return false;
		return item.children.some(c =>
			this.isPrivateContainer(c) && this.isExpandable(c) && !c.children
		);
	}

	// Expand any collapsed private containers in an item's children,
	// then call callback. getItem is a function that returns a fresh
	// item reference after each view rebuild (since toggleOpen rebuilds
	// the entire view, staling previous references).
	expandPrivateContainers(getItem, callback) {
		const item = getItem();
		if (!item || !item.children) {
			callback();
			return;
		}
		for (const child of item.children) {
			if (this.isPrivateContainer(child) && this.isExpandable(child) && !child.children) {
				this.toggleOpen(child, () => {
					// View rebuilt — re-resolve item and re-check for more containers
					this.expandPrivateContainers(getItem, callback);
				});
				return;
			}
		}
		// All private containers expanded (or none found)
		callback();
	}

	printVariable(item, depth) {
		const indent = '  '.repeat(depth + 1);
		const val = this.formatValue(item, 0);
		if (val)
			console.log(`${indent}${item.name} = ${val}`);
		else
			console.log(`${indent}${item.name}`);
	}

	printVariables(items, depth) {
		if (!items)
			return;
		for (const item of items) {
			this.printVariable(item, depth);
		}
	}

	resolveFilePath(input, isSet = true) {
		const allPaths = this.knownPaths;

		// Exact match
		if (allPaths.has(input))
			return input;

		let matches = [];
		// Suffix match against known paths
		if (allPaths.size > 0) {
			matches = [...allPaths].filter(p =>
				p.endsWith('/' + input) || p.endsWith('\\' + input) ||
				p.endsWith('/' + input + '.js') || p.endsWith('\\' + input + '.js') ||
				p.endsWith('/' + input + '.ts') || p.endsWith('\\' + input + '.ts')
			);
			if (matches.length === 1)
				return matches[0];
			if (matches.length > 1) {
				const ambiguousMsg = `Ambiguous file name "${input}". Matches:\n` + matches.map(p => `  ${p}`).join('\n');
				this.commandError(ambiguousMsg);
				return null;
			}
		}

		// Try resolving relative to current file's directory
		if (this.currentPath && !input.startsWith('/')) {
			const dir = this.currentPath.substring(0, this.currentPath.lastIndexOf('/'));
			const candidates = [
				dir + '/' + input,
				dir + '/' + input + '.js',
				dir + '/' + input + '.ts'
			];
			for (const candidate of candidates) {
				try {
					fs.accessSync(candidate, fs.constants.R_OK);
					return candidate;
				}
				catch (e) {
					// not found in current directory
				}
			}
		}

		// Check if the file exists directly (absolute or relative to CWD)
		const candidates = [
			input,
			input + '.js',
			input + '.ts'
		];
		for (const candidate of candidates) {
			try {
				fs.accessSync(candidate, fs.constants.R_OK);
				// Resolve to absolute path so it matches XS engine's internal path
				const abs = require('path').resolve(candidate);
				this.knownPaths.add(abs);
				return abs;
			}
			catch (e) {
				// does not exist
			}
		}

		// Try resolving relative to directories of all known paths
		if (!input.startsWith('/') && allPaths.size > 0) {
			const dirs = new Set();
			for (const p of allPaths) {
				const lastSlash = p.lastIndexOf('/');
				if (lastSlash > 0) dirs.add(p.substring(0, lastSlash));
			}
			const suffixes = [input, input + '.js', input + '.ts'];
			for (const dir of dirs) {
				for (const suffix of suffixes) {
					const candidate = dir + '/' + suffix;
					try {
						fs.accessSync(candidate, fs.constants.R_OK);
						this.knownPaths.add(candidate);
						return candidate;
					} catch (e) {}
				}
			}
		}

		// Search for the file under $XSBUG_PROJECT first, then $MODDABLE
		if (!input.startsWith('/')) {
			const slashIdx = input.lastIndexOf('/');
			const baseName = slashIdx >= 0 ? input.substring(slashIdx + 1) : input;
			const searchDirs = [];
			if (process.env.XSBUG_PROJECT) searchDirs.push(process.env.XSBUG_PROJECT);
			if (process.env.MODDABLE) searchDirs.push(process.env.MODDABLE);
			for (const searchDir of searchDirs) {
				let found = this.searchForFile(searchDir, baseName);
				if (slashIdx >= 0 && found.length > 0)
					found = found.filter(p => p.endsWith('/' + input) || p.endsWith('\\' + input));
				if (found.length === 1) {
					this.knownPaths.add(found[0]);
					return found[0];
				}
				if (found.length > 1) {
					this.commandError(`Ambiguous file name "${input}". Matches:\n` + found.map(p => `  ${p}`).join('\n'));
					return null;
				}
			}
		}

		// If no file found, attempt to resolve relative to working tree so engine absolute paths match
		if (matches.length === 0) {
			try {
				const p = require('path');
				const abs = p.resolve(input);
				if (fs.existsSync(abs)) {
					if (isSet) this.print(`Note: File "${input}" not yet loaded. Pending breakpoint mapped to ${abs}`);
					return abs;
				}
			} catch (e) {}

			if (isSet) {
				this.print(`Note: File "${input}" not yet loaded. Breakpoint makes it pending.`);
				return input;
			}
		}

		this.commandError(`File "${input}" not found. Try using the full path.`);
		return null;
	}

	searchForFile(baseDir, fileName, maxDepth = 6) {
		const results = [];
		const names = [fileName];
		if (!fileName.includes('.')) {
			names.push(fileName + '.js');
			names.push(fileName + '.ts');
		}
		const skip = new Set(['.git', 'node_modules', 'build']);
		const search = (dir, depth) => {
			if (depth <= 0 || results.length >= 4) return;
			try {
				const entries = fs.readdirSync(dir, { withFileTypes: true });
				for (const entry of entries) {
					if (entry.isFile() && names.includes(entry.name))
						results.push(dir + '/' + entry.name);
				}
				for (const entry of entries) {
					if (entry.isDirectory() && !entry.name.startsWith('.') && !skip.has(entry.name))
						search(dir + '/' + entry.name, depth - 1);
				}
			} catch (e) {}
		};
		search(baseDir, maxDepth);
		return results;
	}

	// --- State helpers ---

	resume() {
		this.broken = false;
		this.running = true;
		this.promptShown = false;
		setTimeout(() => this.showPrompt(), 0);
	}

	requireBroken() {
		if (!this.broken) {
			this.commandError('  The program is not stopped.');
			return false;
		}
		return true;
	}

	// --- Command dispatch ---

	handleCommand(line) {
		if (!line) {
			// Empty line: repeat last command (GDB convention)
			line = this.lastCommand || '';
		}
		if (!line) {
			this.showPrompt();
			return;
		}
		this.lastCommand = line;

		const parts = line.split(/\s+/);
		const cmd = parts[0];
		const args = parts.slice(1);
		this.currentCommand = cmd;

		switch (cmd) {
			case 'continue': case 'c':
				this.cmdContinue();
				break;
			case 'next': case 'n':
				this.cmdNext();
				break;
			case 'step': case 's':
				this.cmdStep();
				break;
			case 'finish':
				this.cmdFinish();
				break;
			case 'until':
				this.cmdUntil(args);
				break;
			case 'break': case 'b':
				this.cmdBreak(args);
				break;
			case 'delete': case 'd':
				this.cmdDelete(args);
				break;
			case 'clear':
				this.cmdClear(args);
				break;
			case 'condition':
				this.cmdCondition(args);
				break;
			case 'trace':
				this.cmdTrace(args);
				break;
			case 'hitcount':
				this.cmdHitcount(args);
				break;
			case 'list': case 'l':
				this.cmdList(args);
				break;
			case 'backtrace': case 'bt': case 'where':
				this.cmdBacktrace();
				break;
			case 'frame': case 'f':
				this.cmdFrame(args);
				break;
			case 'print': case 'p':
				this.cmdPrint(args);
				break;
			case 'eval':
				this.cmdEval(line.slice(line.indexOf('eval') + 5));
				break;
			case 'info':
				this.cmdInfo(args);
				break;
			case 'set':
				this.cmdSet(args);
				break;
			case 'help': case 'h':
				this.cmdHelp();
				break;
			case 'quit': case 'q':
				this.cmdQuit();
				break;
			case 'run': case 'r':
				this.cmdRun();
				break;
			case 'test':
				this.cmdTest(args);
				break;
			default:
				this.currentCommand = cmd;
				this.commandError(`Unknown command: "${cmd}". Type "help" for help.`);
				break;
		}
	}

	// --- Command implementations ---

	cmdContinue() {
		if (!this.requireBroken()) {
			this.showPrompt();
			return;
		}
		console.log('Continuing.');
		this.resume();
		this.doGo();
		// doStep() from ^C sets breakOnStartFlag on the device when there's no JS frame.
		// doGo() doesn't clear it, so explicitly clear the stale flag if breakOnStart is off.
		if (!this.breakOnStart)
			this.doClearBreakpoint("start", "0");
	}

	cmdNext() {
		if (!this.requireBroken()) {
			this.showPrompt();
			return;
		}
		this.resume();
		this.doStep();
	}

	cmdStep() {
		if (!this.requireBroken()) {
			this.showPrompt();
			return;
		}
		this.resume();
		this.doStepIn();
	}

	cmdFinish() {
		if (!this.requireBroken()) {
			this.showPrompt();
			return;
		}
		this.resume();
		this.doStepOut();
	}

	readSourceLines(path) {
		if (this.sourceCache[path])
			return this.sourceCache[path];
		try {
			const content = fs.readFileSync(path, 'utf8');
			const lines = content.split('\n');
			this.sourceCache[path] = lines;
			return lines;
		}
		catch (e) {
			return null;
		}
	}

	printSourceLine(path, lineNum) {
		const lines = this.readSourceLines(path);
		if (!lines)
			return;
		const idx = parseInt(lineNum) - 1;
		if (idx < 0 || idx >= lines.length)
			return;
		this.report('print_source_line', { path, line: lineNum, text: lines[idx] }, undefined, (data) => {
			const lStr = String(data.line).padStart(4);
			console.log(`${lStr}\t${data.text}`);
		});
	}

	cmdList(args) {

		let path, centerLine, startLine, endLine;

		if (args.length > 0) {
			const spec = args[0];
			if (spec.includes(':')) {
				const lastColon = spec.lastIndexOf(':');
				path = spec.substring(0, lastColon);
				
				const lineSpec = spec.substring(lastColon + 1);
				if (lineSpec.includes(',')) {
					const parts = lineSpec.split(',');
					startLine = parseInt(parts[0]);
					endLine = parseInt(parts[1]);
				} else {
					centerLine = parseInt(lineSpec);
				}
				
				const resolved = this.resolveFilePath(path, false);
				if (resolved === null)
					return;
				path = resolved;
			}
			else {
				if (spec.includes(',')) {
					const parts = spec.split(',');
					startLine = parseInt(parts[0]);
					endLine = parseInt(parts[1]);
				} else {
					centerLine = parseInt(spec);
				}
				path = this.currentPath;
			}
		}
		else if (this.listPosition) {
			// Continue listing from where we left off
			path = this.listPosition.path;
			centerLine = this.listPosition.line;
		}
		else {
			path = this.currentPath;
			centerLine = parseInt(this.currentLine);
		}

		if (!path) {
			this.commandError('No current file.');
			return;
		}

		const lines = this.readSourceLines(path);
		if (!lines) {
			this.commandError(`Cannot read file: ${path}`);
			return;
		}

		let start, end;
		if (this.listWindowSize === undefined) this.listWindowSize = 10;

		if (startLine !== undefined && endLine !== undefined) {
			if (isNaN(startLine) || isNaN(endLine)) {
				this.commandError('Invalid line range.');
				return;
			}
			start = Math.max(0, startLine - 1);
			end = Math.min(lines.length, endLine);
			this.listWindowSize = end - start;
			this.listPosition = { path, line: endLine + 1 + Math.floor(this.listWindowSize / 2) };
		} else {
			if (isNaN(centerLine)) {
				this.commandError('Invalid line number.');
				return;
			}
			start = Math.max(0, centerLine - 1 - Math.floor(this.listWindowSize / 2));
			end = Math.min(lines.length, start + this.listWindowSize);
			this.listPosition = { path, line: end + Math.floor(this.listWindowSize / 2) };
		}

		const currentLineNum = (path === this.currentPath) ? parseInt(this.currentLine) : -1;

		const listData = [];
		for (let i = start; i < end; i++) {
			listData.push({
				line: i + 1,
				text: lines[i],
				isCurrent: (i + 1 === currentLineNum)
			});
		}

		this.report('list_source', { path, lines: listData }, undefined, (data) => {
			for (const l of data.lines) {
				const marker = l.isCurrent ? '>' : ' ';
				const lineStr = String(l.line).padStart(4);
				console.log(`${marker}${lineStr}\t${l.text}`);
			}
			this.showPrompt();
		});

	}

	cmdUntil(args) {
		if (!this.requireBroken()) {
			this.showPrompt();
			return;
		}
		if (args.length < 1) {
			this.commandError('Syntax: until <line> | until <function>');
			return;
		}

		const spec = args[0];
		let path = this.currentPath;
		let line;

		if (!isNaN(parseInt(spec))) {
			line = parseInt(spec);
			if (!path) {
				this.commandError('No current file.');
				return;
			}
		}
		else {
			// Function until
			path = spec;
			line = 0;
		}

		// Clear any previous temporary breakpoint
		if (this.temporaryBreakpoint) {
			this.doClearBreakpoint(this.temporaryBreakpoint.path, this.temporaryBreakpoint.line);
		}

		this.temporaryBreakpoint = { path, line };
		this.doSetBreakpoint(path, line);

		this.resume();
		this.doGo();
	}


	// Build protocol options {condition, hitCount, trace} from a breakpoint's stored expressions.
	buildBreakpointOptions(bp) {
		const options = {};
		if (bp.conditionExpr) {
			try {
				options.condition = Machine.compileExpression(bp.conditionExpr);
			}
			catch (e) {
				this.commandError(e.message);
				return null;
			}
		}
		if (bp.hitCountExpr)
			options.hitCount = bp.hitCountExpr;
		if (bp.traceExpr) {
			try {
				options.trace = Machine.compileExpression(bp.traceExpr);
			}
			catch (e) {
				this.commandError(e.message);
				return null;
			}
		}
		if (options.condition || options.hitCount || options.trace)
			return options;
		return undefined;
	}

	// Re-send a breakpoint to the target (clear + set with current options).
	resendBreakpoint(bp) {
		this.doClearBreakpoint(bp.path, bp.line);
		const options = this.buildBreakpointOptions(bp);
		if (options === null) return; // compile error
		this.doSetBreakpoint(bp.path, bp.line, options);
	}

	cmdBreak(args) {
		if (args.length < 1) {
			// No args: list breakpoints
			this.cmdInfoBreakpoints();
			return;
		}

		// Parse "if <expr>" suffix from args
		let conditionExpr = null;
		const ifIndex = args.indexOf('if');
		if (ifIndex > 0) {
			conditionExpr = args.slice(ifIndex + 1).join(' ');
			args = args.slice(0, ifIndex);
			if (!conditionExpr) {
				this.commandError('Missing expression after "if".');
				return;
			}
		}

		let path, line;
		const spec = args[0];

		if (spec.includes(':')) {
			const lastColon = spec.lastIndexOf(':');
			path = spec.substring(0, lastColon);
			const lineStr = spec.substring(lastColon + 1);
			if (isNaN(parseInt(lineStr))) {
				this.commandError('Invalid line number.');
				return;
			}
			line = parseInt(lineStr);

			// Resolve short filenames against known files
			const resolved = this.resolveFilePath(path, true);
			if (resolved === null) {
				this.showPrompt();
				return;
			}
			path = resolved;
		}
		else if (!isNaN(parseInt(spec))) {
			// Just a line number: use current file
			path = this.currentPath;
			if (!path) {
				this.commandError('No current file. Use "break file:line" or "break function".');
				return;
			}
			if (spec.startsWith('+') || spec.startsWith('-')) {
				if (!this.currentLine) {
					this.commandError('No current line known for relative breakpoint.');
					return;
				}
				line = parseInt(this.currentLine) + parseInt(spec);
			}
			else {
				line = parseInt(spec);
			}
		}
		else {
			// Function breakpoint
			path = spec;
			line = 0;
		}

		let bpId;
		// Track the breakpoint
		const existing = this.breakpoints.find(bp => bp.path === path && bp.line === line);
		if (!existing) {
			bpId = this.getNextBreakpointId ? this.getNextBreakpointId() : 1;
			const bp = { id: bpId, path, line };
			if (conditionExpr)
				bp.conditionExpr = conditionExpr;
			this.breakpoints.push(bp);
		} else {
			bpId = existing.id;
			if (conditionExpr)
				existing.conditionExpr = conditionExpr;
		}

		const bp = this.breakpoints.find(b => b.id === bpId);
		const options = this.buildBreakpointOptions(bp);
		if (options === null) return; // compile error already reported

		this.doSetBreakpoint(path, line, options);
		this.report('break', { id: bpId, path, line, shortPath: this.shortPath(path), conditionExpr: bp.conditionExpr }, undefined, (data) => {
			this.clearLine();
			if (data.line === 0)
				console.log(`Breakpoint ${data.id} set on function ${data.path}`);
			else
				console.log(`Breakpoint ${data.id} set at ${data.shortPath}:${data.line}`);
			if (data.conditionExpr)
				console.log(`  stop only if ${data.conditionExpr}`);
			this.showPrompt();
		});
	}

	cmdCondition(args) {
		if (args.length < 1) {
			this.commandError('Syntax: condition <id> [expr]');
			return;
		}
		const id = parseInt(args[0]);
		const bp = this.breakpoints.find(b => b.id === id);
		if (!bp) {
			this.commandError(`No breakpoint number ${id}.`);
			return;
		}
		if (args.length < 2) {
			// Clear condition
			delete bp.conditionExpr;
			this.resendBreakpoint(bp);
			console.log(`Breakpoint ${id} condition cleared.`);
			this.showPrompt();
		}
		else {
			const expr = args.slice(1).join(' ');
			// Verify it compiles
			try {
				Machine.compileExpression(expr);
			}
			catch (e) {
				this.commandError(e.message);
				return;
			}
			bp.conditionExpr = expr;
			this.resendBreakpoint(bp);
			console.log(`Breakpoint ${id}: stop only if ${expr}`);
			this.showPrompt();
		}
	}

	cmdTrace(args) {
		if (args.length < 1) {
			this.commandError('Syntax: trace <id> [expr]');
			return;
		}
		const id = parseInt(args[0]);
		const bp = this.breakpoints.find(b => b.id === id);
		if (!bp) {
			this.commandError(`No breakpoint number ${id}.`);
			return;
		}
		if (args.length < 2) {
			delete bp.traceExpr;
			this.resendBreakpoint(bp);
			console.log(`Breakpoint ${id} trace cleared.`);
			this.showPrompt();
		}
		else {
			const expr = args.slice(1).join(' ');
			try {
				Machine.compileExpression(expr);
			}
			catch (e) {
				this.commandError(e.message);
				return;
			}
			bp.traceExpr = expr;
			this.resendBreakpoint(bp);
			console.log(`Breakpoint ${id}: trace ${expr}`);
			this.showPrompt();
		}
	}

	cmdHitcount(args) {
		if (args.length < 1) {
			this.commandError('Syntax: hitcount <id> [op count]  (op: = < <= > >= %)');
			return;
		}
		const id = parseInt(args[0]);
		const bp = this.breakpoints.find(b => b.id === id);
		if (!bp) {
			this.commandError(`No breakpoint number ${id}.`);
			return;
		}
		if (args.length < 2) {
			delete bp.hitCountExpr;
			this.resendBreakpoint(bp);
			console.log(`Breakpoint ${id} hit count cleared.`);
			this.showPrompt();
		}
		else {
			// Accept ">=5" or ">= 5" or "> 5"
			const expr = args.slice(1).join('');
			if (!/^[%<>=]+\d+$/.test(expr)) {
				this.commandError('Invalid hit count. Use: = < <= > >= % followed by a number (e.g. ">=5", "%10").');
				return;
			}
			bp.hitCountExpr = expr;
			this.resendBreakpoint(bp);
			console.log(`Breakpoint ${id}: hit count ${expr}`);
			this.showPrompt();
		}
	}

	cmdEval(source) {
		source = source.trim();
		if (!source) {
			this.commandError('Syntax: eval <expression>');
			return;
		}
		if (!this.requireBroken()) {
			this.showPrompt();
			return;
		}
		if (!this.currentFrameValue) {
			this.commandError('No frame selected.');
			return;
		}
		let compiled;
		try {
			compiled = Machine.compileExpression(source);
		}
		catch (e) {
			this.commandError(e.message);
			return;
		}
		this.doEval(this.currentFrameValue, compiled);
	}

	cmdDelete(args) {
		if (args.length < 1) {
			this.commandError('Syntax: delete <id...> | delete all');
			return;
		}

		if (args[0] === 'all') {
			this.breakpoints.length = 0;
			this.doClearAllBreakpoints();
			// Restore exception breakpoint if enabled
			if (this.exceptionsMode === 'on')
				this.doSetBreakpoint("exceptions", "0");
			if (this.breakOnStart)
				this.doSetBreakpoint("start", "0");
			this.report('delete', { all: true }, undefined, () => {
				console.log('All breakpoints cleared.');
				this.showPrompt();
			});
			return;
		}

		const ids = [];
		for (const arg of args) {
			const id = parseInt(arg);
			if (isNaN(id) || id <= 0) {
				this.commandError(`Invalid breakpoint number ${arg}.`);
				return;
			}
			const bpIndex = this.breakpoints.findIndex(b => b.id === id);
			if (bpIndex < 0) {
				this.commandError(`No breakpoint number ${arg}.`);
				return;
			}
			ids.push(id);
		}

		const deletedList = [];
		for (const id of ids) {
			const idx = this.breakpoints.findIndex(b => b.id === id);
			if (idx >= 0) {
				const bp = this.breakpoints[idx];
				this.breakpoints.splice(idx, 1);
				this.doClearBreakpoint(bp.path, bp.line);
				deletedList.push({ path: bp.path, line: bp.line, shortPath: this.shortPath(bp.path) });
			}
		}

		this.report('delete', { deleted: deletedList }, undefined, (data) => {
			this.clearLine();
			for (const bp of data.deleted) {
				if (bp.line === 0)
					console.log(`Breakpoint deleted on function ${bp.path}`);
				else
					console.log(`Breakpoint deleted at ${bp.shortPath}:${bp.line}`);
			}
			this.showPrompt();
		});
	}

	cmdClear(args) {
		if (args.length < 1) {
			this.commandError('Syntax: clear <file:line> | clear <line> | clear <function> | clear all');
			return;
		}

		if (args[0] === 'all') {
			this.breakpoints.length = 0;
			this.doClearAllBreakpoints();
			// Restore exception breakpoint if enabled
			if (this.exceptionsMode === 'on')
				this.doSetBreakpoint("exceptions", "0");
			if (this.breakOnStart)
				this.doSetBreakpoint("start", "0");
			this.report('clear', { all: true }, undefined, () => {
				console.log('All breakpoints cleared.');
				this.showPrompt();
			});
			return;
		}

		let path, line;
		const spec = args[0];

		if (spec.includes(':')) {
			const lastColon = spec.lastIndexOf(':');
			path = spec.substring(0, lastColon);
			const lineStr = spec.substring(lastColon + 1);
			if (isNaN(parseInt(lineStr))) {
				this.commandError('Invalid line number.');
				return;
			}
			line = parseInt(lineStr);

			const resolved = this.resolveFilePath(path, false);
			if (resolved === null)
				return;
			path = resolved;
		}
		else if (!isNaN(parseInt(spec))) {
			path = this.currentPath;
			if (!path) {
				this.commandError('No current file. Use "clear file:line" or "clear function".');
				return;
			}
			if (spec.startsWith('+') || spec.startsWith('-')) {
				if (!this.currentLine) {
					this.commandError('No current line known for relative command.');
					return;
				}
				line = parseInt(this.currentLine) + parseInt(spec);
			}
			else {
				line = parseInt(spec);
			}
		}
		else {
			// Function breakpoint
			path = spec;
			line = 0;
		}

		const idx = this.breakpoints.findIndex(bp => bp.path === path && bp.line === line);
		let deleted = false;
		if (idx >= 0) {
			this.breakpoints.splice(idx, 1);
			this.doClearBreakpoint(path, line);
			deleted = true;
		}
		
		this.report('clear', { path, line, shortPath: this.shortPath(path), deleted }, undefined, (data) => {
			if (data.deleted) {
				if (data.line === 0)
					console.log(`Breakpoint cleared on function ${data.path}`);
				else
					console.log(`Breakpoint cleared at ${data.shortPath}:${data.line}`);
			} else {
				if (data.line === 0)
					console.log(`No breakpoint found on function ${data.path}`);
				else
					console.log(`No breakpoint found at ${data.shortPath}:${data.line}`);
			}
			this.showPrompt();
		});
	}

	cmdBacktrace() {
		if (!this.requireBroken()) {
			this.showPrompt();
			return;
		}
		if (!this.view.frames || this.view.frames.length === 0) {
			this.commandError('No stack frames available.');
			return;
		}
		this.report('info_backtrace', { frames: this.view.frames }, undefined, (data) => {
			data.frames.forEach((frame, index) => {
				let line = `  #${index}: ${frame.name}`;
				if (frame.path)
					line += ` at ${this.shortPath(frame.path)}:${frame.line}`;
				console.log(line);
			});
			this.showPrompt();
		});
	}

	cmdFrame(args) {
		if (!this.requireBroken()) {
			this.showPrompt();
			return;
		}
		if (args.length === 0 || !this.view.frames) {
			this.commandError('Syntax: frame <number>');
			return;
		}
		const idx = parseInt(args[0]);
		if (isNaN(idx) || idx < 0 || idx >= this.view.frames.length) {
			this.commandError(`Frame index out of range (0-${this.view.frames.length - 1})`);
			return;
		}
		const frame = this.view.frames[idx];
		this.doSelect(frame.value);
		this.currentPath = frame.path || null;
		this.currentLine = frame.line || null;
		this.listPosition = null;
		this.report('frame', { index: idx, frame: { name: frame.name, path: frame.path, line: frame.line, shortPath: this.shortPath(frame.path) } }, undefined, (data) => {
			console.log(`Selected frame #${data.index}: ${data.frame.name}`);
			if (data.frame.path)
				console.log(`  ${data.frame.shortPath}:${data.frame.line}`);
			this.showPrompt();
		});
		// doSelect triggers onViewChanged for local/global, prompt will be reshown
	}

	cmdPrint(args) {
		if (!this.requireBroken()) {
			this.showPrompt();
			return;
		}
		if (args.length === 0) {
			if (!this.view.local || this.view.local.length === 0) {
				this.commandError('No local variables.');
				return;
			}
			
			this.gatherAllLocals(0, [], (collected) => {
				collected.sort((a, b) => a.name.toLowerCase().localeCompare(b.name.toLowerCase()));
				this.report('info_locals', { locals: collected }, undefined, (data) => {
					for (const c of data.locals) {
						this.printVariable(c, 0);
					}
					this.showPrompt();
				});
			});
		}
		else {
			const expr = args.join(' ');

			// "import.meta" is a language expression, not a debug view variable
			if (expr === 'import.meta' || expr.startsWith('import.meta.')) {
				this.commandError('"import.meta" is not available as a debug variable. Assign it to a local first: let meta = import.meta');
				return;
			}

			const parts = [];
			const regex = /\["([^"]+)"\]|\['([^']+)'\]|\[`([^`]+)`\]|(\[[0-9]+\])|\.([^.\[]+)|^([^.\[]+)/g;
			let match;
			while ((match = regex.exec(expr)) !== null) {
				parts.push(match[1] || match[2] || match[3] || match[4] || match[5] || match[6]);
			}

			// "p globalThis.name" or "p global.name" — search global hierarchy
			if ((parts[0] === 'globalThis' || parts[0] === 'global') && parts.length > 1) {
				if (!this.view.global || this.view.global.length === 0) {
					this.commandError('No global variables available.');
					return;
				}
				this.resolveGlobalPath(parts.slice(1));
			}
			else {
				// Search locals first, fall back to globals
				this.resolveDotPath(this.view.local || [], parts, 0, true);
			}
		}
	}

	// Skip internal/frame items when listing all locals
	isInternalLocal(item) {
		const name = item.name;
		if (name.startsWith('(') && name.endsWith(')'))
			return true;
		// "this = undefined" in non-method calls is noise
		if (name === 'this' && item.value === 'undefined')
			return true;
		// "new.target = undefined" in non-constructor calls is noise
		if (name === 'new.target' && item.value === 'undefined')
			return true;
		return false;
	}

	gatherAllLocals(index, collected, callback) {
		const locals = this.view.local;
		if (index >= locals.length) {
			callback(collected);
			return;
		}
		const item = locals[index];
		// Skip internal frame slots
		if (this.isInternalLocal(item)) {
			this.gatherAllLocals(index + 1, collected, callback);
			return;
		}
		if (this.isExpandable(item) && !item.children) {
			this.toggleOpen(item, () => {
				// Re-read from updated view
				const getItem = () => this.view.local[index];
				// Expand private containers before printing
				this.expandPrivateContainers(getItem, () => {
					const final = getItem();
					collected.push(final);
					this.gatherAllLocals(index + 1, collected, callback);
				});
			});
		}
		else if (this.hasCollapsedPrivateContainers(item)) {
			const getItem = () => this.view.local[index];
			this.expandPrivateContainers(getItem, () => {
				const updated = getItem();
				collected.push(updated);
				this.gatherAllLocals(index + 1, collected, callback);
			});
		}
		else {
			collected.push(item);
			this.gatherAllLocals(index + 1, collected, callback);
		}
	}

	findExpandedAlias(value, items, path = "") {
		if (!items) return null;
		for (const item of items) {
			if (item.value === value && item.children) {
				return path ? (path + "." + item.name) : item.name;
			}
			if (item.children) {
				const nested = this.findExpandedAlias(value, item.children, path ? (path + "." + item.name) : item.name);
				if (nested) return nested;
			}
		}
		return null;
	}

	findItemByValue(items, value) {
		if (!items) return null;
		for (const item of items) {
			if (item.value === value && item.children) return item;
			if (item.children) {
				const nested = this.findItemByValue(item.children, value);
				if (nested) return nested;
			}
		}
		return null;
	}

	resolveDotPath(items, parts, partIndex, fallbackToGlobals, toggledIds = new Set()) {
		const name = parts[partIndex];

		// Use findProperty for unified lookup (direct, prototype→(..), #private, (..) chain)
		let found = this.findProperty(items, name);

		// Handle compound names like "new.target", "import.meta" — if not
		// found, try joining with subsequent parts to match XS internal names
		if (!found && partIndex === 0) {
			for (let end = partIndex + 2; end <= parts.length; end++) {
				const compound = parts.slice(partIndex, end).join('.');
				found = this.findItem(items, compound);
				if (found) {
					// Adjust partIndex to skip the joined parts
					partIndex = end - 1;
					break;
				}
			}
		}

		// Contextual compound names — check before global fallback
		if (!found && partIndex === 0) {
			if (name === 'new.target') {
				this.commandError(`"new.target" is only available inside a constructor.`);
				return;
			}
		}

		// Fall back to globals if not found in locals
		if (!found && fallbackToGlobals && partIndex === 0 && this.view.global) {
			this.resolveGlobalPath(parts);
			return;
		}

		if (!found) {
			// findProperty already walked the (..) chain, but those nodes may need expanding
			const proto = this.findItem(items, '(..)');
			if (proto) {
				if (this.isExpandable(proto) && !proto.children) {
					const alias = this.findExpandedAlias(proto.value, this.view.global) || this.findExpandedAlias(proto.value, this.view.local);
					if (alias) {
						const actualProto = this.findItemByValue(this.view.global, proto.value) || this.findItemByValue(this.view.local, proto.value);
						if (actualProto && actualProto.children) {
							if (toggledIds.has(proto.value)) {
								if (partIndex === 0) this.commandError(`No variable "${name}" in current scope.`);
								else this.commandError(`No property "${name}" on "${parts.slice(0, partIndex).join('.')}".`);
								return;
							}
							toggledIds.add(proto.value);
							this.resolveDotPath(actualProto.children, parts, partIndex, false, toggledIds);
							return;
						}
					}
					this.toggleOpen(proto, () => {
						this.cmdPrint([parts.join('.')]);
					});
					return;
				} else if (proto.children) {
					if (toggledIds.has(proto.value)) {
						if (partIndex === 0) this.commandError(`No variable "${name}" in current scope.`);
						else this.commandError(`No property "${name}" on "${parts.slice(0, partIndex).join('.')}".`);
						return;
					}
					toggledIds.add(proto.value);
					this.resolveDotPath(proto.children, parts, partIndex, false, toggledIds);
					return;
				}
			}

			// Check if #private containers need expanding
			if (name.startsWith('#')) {
				const unexpanded = items?.filter(i =>
					this.isPrivateContainer(i) && this.isExpandable(i) && !i.children
				);
				if (unexpanded && unexpanded.length > 0) {
					this.searchPrivateField(items, parts, partIndex, toggledIds);
					return;
				}
			}

			if (partIndex === 0)
				this.commandError(`No variable "${name}" in current scope.`);
			else
				this.commandError(`No property "${name}" on "${parts.slice(0, partIndex).join('.')}".`);
			return;
		}

		const isLast = (partIndex === parts.length - 1);

		if (isLast) {
			// Final part — display it, expanding if needed
			if (this.isExpandable(found) && !found.children) {
				const alias = this.findExpandedAlias(found.value, this.view.global) || this.findExpandedAlias(found.value, this.view.local);
				if (alias) {
					this.print(`${'  '.repeat(0)}${found.name} = ${alias}`);
					this.showPrompt();
					return;
				}
				this.toggleOpen(found, () => {
					// View rebuilt after toggle — re-run the print command
					this.cmdPrint([parts.join('.')]);
				});
			}
			else if (this.hasCollapsedPrivateContainers(found)) {
				// Expand first collapsed private container, then re-run
				// cmdPrint will re-resolve from fresh view and expand more if needed
				const container = found.children.find(c =>
					this.isPrivateContainer(c) && this.isExpandable(c) && !c.children
				);
				const alias = this.findExpandedAlias(container.value, this.view.global) || this.findExpandedAlias(container.value, this.view.local);
				if (alias) {
					this.report('eval_print', { variable: found }, undefined, (data) => {
						this.printVariable(data.variable, 0);
						this.showPrompt();
					});
					return;
				}
				this.toggleOpen(container, () => {
					this.cmdPrint([parts.join('.')]);
				});
			}
			else {
				this.report('eval_print', { variable: found }, undefined, (data) => {
					this.printVariable(data.variable, 0);
					this.showPrompt();
				});
			}
		}
		else {
			// Need to descend into children
			if (this.isExpandable(found) && !found.children) {
				const alias = this.findExpandedAlias(found.value, this.view.global) || this.findExpandedAlias(found.value, this.view.local);
				if (alias) {
					if (this.currentCommand === 'print' || this.currentCommand === 'p') {
						this.commandError(`"${parts.slice(0, partIndex + 1).join('.')}" refers to ${alias} which is inherently cyclic.`);
					}
					return;
				}
				this.toggleOpen(found, () => {
					// View rebuilt after toggle — re-run the print command
					this.cmdPrint([parts.join('.')]);
				});
			}
			else if (found.children) {
				this.resolveDotPath(found.children, parts, partIndex + 1, false, toggledIds);
			}
			else {
				this.commandError(`"${parts.slice(0, partIndex + 1).join('.')}" has no properties.`);
			}
		}
	}

	// Search parenthesized private-field containers for a #name
	searchPrivateField(items, parts, partIndex, toggledIds) {
		const name = parts[partIndex];
		// Collect (ClassName) containers — names like "(Foo)"
		const containers = items ? items.filter(i =>
			i.name.startsWith('(') && i.name.endsWith(')') && i.name !== '(..)'
		) : [];
		this.searchPrivateContainers(containers, 0, items, parts, partIndex, name, toggledIds);
	}

	searchPrivateContainers(containers, idx, items, parts, partIndex, name, toggledIds) {
		if (idx >= containers.length) {
			this.commandError(`No private field "${name}" on "${parts.slice(0, partIndex).join('.')}".`);
			return;
		}
		const container = containers[idx];
		const expandAndSearch = (c) => {
			if (!c || !c.children) {
				// Empty container, try next
				this.searchPrivateContainers(containers, idx + 1, items, parts, partIndex, name, toggledIds);
				return;
			}
			const found = this.findItem(c.children, name);
			if (found) {
				// Found the private field — continue resolving remaining parts
				const isLast = (partIndex === parts.length - 1);
				if (isLast && this.isExpandable(found) && !found.children) {
					this.toggleOpen(found, () => {
						this.cmdPrint([parts.join('.')]);
					});
				}
				else if (isLast) {
					this.report('eval_print', { variable: found }, undefined, (data) => {
						this.printVariable(data.variable, 0);
						this.showPrompt();
					});
				}
				else if (this.isExpandable(found) && !found.children) {
					this.toggleOpen(found, () => {
						this.cmdPrint([parts.join('.')]);
					});
				}
				else if (found.children) {
					this.resolveDotPath(found.children, parts, partIndex + 1, false, toggledIds);
				}
				else {
					this.commandError(`"${parts.slice(0, partIndex + 1).join('.')}" has no properties.`);
				}
			}
			else {
				this.searchPrivateContainers(containers, idx + 1, items, parts, partIndex, name, toggledIds);
			}
		};
		if (this.isExpandable(container) && !container.children) {
			const alias = this.findExpandedAlias(container.value, this.view.global) || this.findExpandedAlias(container.value, this.view.local);
			if (alias) {
				this.commandError(`"${parts.join('.')}" private fields refers to ${alias} which is already expanded.`);
				return;
			}
			this.toggleOpen(container, () => {
				// View rebuilt after toggle — re-run from scratch
				this.cmdPrint([parts.join('.')]);
			});
		}
		else {
			expandAndSearch(container);
		}
	}

	resolveGlobalPath(parts) {
		this.searchGlobalItems(this.view.global, parts);
	}

	// Walk the global hierarchy using findProperty for unified lookup.
	// If a property is found (directly, via prototype→(..), #private, or (..) chain),
	// delegates to resolveDotPath. Otherwise expands (..) and retries.
	searchGlobalItems(items, parts) {
		if (!items || items.length === 0) {
			this.commandError(`No variable "${parts[0]}" in current scope.`);
			return;
		}
		const name = parts[0];

		// Use findProperty for unified lookup
		const found = this.findProperty(items, name);
		if (found) {
			// Find which items list contains the result so resolveDotPath starts correctly
			// If found directly or via prototype mapping, use items directly
			if (items.find(i => i.name === name) || (name === 'prototype' && items.find(i => i.name === '(..)'))) {
				this.resolveDotPath(items, parts, 0, false);
			} else {
				// Found in (..) chain — walk to the level that contains it
				const walkToLevel = (searchItems) => {
					if (searchItems.find(i => i.name === name) || (name === 'prototype' && searchItems.find(i => i.name === '(..)'))) {
						this.resolveDotPath(searchItems, parts, 0, false);
						return;
					}
					if (name.startsWith('#')) {
						for (const c of searchItems) {
							if (this.isPrivateContainer(c) && c.children && c.children.find(i => i.name === name)) {
								this.resolveDotPath(searchItems, parts, 0, false);
								return;
							}
						}
					}
					const dd = searchItems.find(i => i.name === '(..)');
					if (dd && dd.children)
						walkToLevel(dd.children);
					else
						this.resolveDotPath(items, parts, 0, false);
				};
				walkToLevel(items);
			}
			return;
		}

		// Not found — (..) may need expanding
		const dotdot = this.findItem(items, '(..)');
		if (!dotdot) {
			this.commandError(`No variable "${name}" in current scope.`);
			return;
		}
		if (this.isExpandable(dotdot) && !dotdot.children) {
			const alias = this.findExpandedAlias(dotdot.value, this.view.global) || this.findExpandedAlias(dotdot.value, this.view.local);
			if (alias) {
				this.commandError(`"${parts.join('.')}" refers to ${alias} which is inherently cyclic.`);
				return;
			}
			this.toggleOpen(dotdot, () => {
				this.resolveGlobalPath(parts);
			});
		}
		else {
			this.commandError(`No variable "${name}" in current scope.`);
		}
	}

	cmdInfo(args) {
		this.currentCommand = 'info';
		let subcmd = args[0] || 'breakpoints';

		// Handle dotted module paths: "info module.Resource.default"
		if (subcmd.startsWith('module.')) {
			const dotIndex = subcmd.indexOf('.');
			const dotPath = subcmd.substring(dotIndex + 1).split('.');
			this.cmdInfoModules(dotPath, false);
			return;
		}

		switch (subcmd) {
			case 'breakpoints':
			case 'break':
			case 'b':
				this.cmdInfoBreakpoints();
				break;
			case 'instruments':
			case 'instrument':
				this.cmdInfoInstruments();
				break;
			case 'locals':
			case 'local':
				this.cmdPrint([]);
				break;
			case 'globals':
			case 'global':
				this.cmdInfoGlobals();
				break;
			case 'modules':
				this.cmdInfoModules(args.slice(1), true);
				break;
			case 'module':
				this.cmdInfoModules(args.slice(1), false);
				break;
			case 'exceptions':
				this.print(`Break on exceptions: ${this.exceptionsMode}`);
				this.showPrompt();
				break;
			case 'start':
				this.print(`Break on start: ${this.breakOnStart ? 'on' : 'off'}`);
				this.showPrompt();
				break;
			case 'timestamps':
			case 'timestamp':
				this.print(`Trace timestamps: ${this.timestamps}`);
				this.showPrompt();
				break;
			case 'test262':
				if (this.tests)
					this.tests.infoTest262();
				else
					this.commandError('No test runner.');
				this.showPrompt();
				break;
			case 'tests':
			case 'test':
				if (this.tests)
					this.tests.info();
				else
					this.print('No test runner.');
				this.showPrompt();
				break;
			default:
				this.commandError('Syntax: info breakpoints | locals | globals | modules[.name.path] | exceptions | start | timestamps | tests | test262');
				break;
		}
	}

	cmdInfoBreakpoints() {
		const bpData = this.breakpoints.map(bp => ({
			id: bp.id,
			path: bp.path,
			line: bp.line,
			shortPath: this.shortPath(bp.path),
			conditionExpr: bp.conditionExpr,
			hitCountExpr: bp.hitCountExpr,
			traceExpr: bp.traceExpr
		}));

		this.report('info_breakpoints', { breakpoints: bpData, exceptionsMode: this.exceptionsMode }, undefined, (data) => {
			if (data.breakpoints.length === 0) {
				this.print('No breakpoints.');
			}
			else {
				data.breakpoints.forEach((bp) => {
					if (bp.line === 0)
						console.log(`  ${bp.id}: function ${bp.path}`);
					else
						console.log(`  ${bp.id}: ${bp.shortPath}:${bp.line}`);
					if (bp.conditionExpr)
						console.log(`       stop only if ${bp.conditionExpr}`);
					if (bp.hitCountExpr)
						console.log(`       hit count ${bp.hitCountExpr}`);
					if (bp.traceExpr)
						console.log(`       trace ${bp.traceExpr}`);
				});
			}
			if (data.exceptionsMode === 'on')
				this.print('Break on exceptions: on');
			else if (data.exceptionsMode === 'silent')
				this.print('Break on exceptions: silent (logs suppressed)');
			this.showPrompt();
		});
	}

	cmdInfoInstruments() {
		if (!this.instruments || this.instruments.length === 0) {
			this.commandError('No instrument snapshots yet.');
			return;
		}
		
		this.report('info_instruments', { 
			historyCount: this.instrumentHistory ? this.instrumentHistory.length : 0,
			instruments: this.instruments 
		}, undefined, (data) => {
			let length = data.instruments.length;
			for (let index = 0; index < length; index++) {
				let instrument = data.instruments[index];
				let result = instrument.name;
				result = result.padEnd(24);
				result += instrument.value;
				result += instrument.unit;
				if (instrument.unit == " / " && index + 1 < length) {
					index++;
					instrument = data.instruments[index];
					result += instrument.value;
					result += instrument.unit;
				}
				console.log(`  ${result}`);
			}
			console.log(`  (Captured ${data.historyCount} snapshots)`);
			this.showPrompt();
		});
	}

	cmdInfoGlobals() {
		if (!this.requireBroken()) {
			this.showPrompt();
			return;
		}
		
		const globalsRaw = this.view.global || [];
		if (globalsRaw.length === 0) {
			this.report('info_globals', { globals: [] }, undefined, () => {
				this.commandError('No global variables available.');
			});
			return;
		}

		// Flatten the prototype chain (..) and sort alphabetically
		const map = new Map();
		const traverse = (nodes) => {
			if (!nodes) return;
			for (const node of nodes) {
				if (node.name === '(..)') {
					if (node.children) traverse(node.children);
				} else {
					map.set(node.name, node);
				}
			}
		};
		traverse(globalsRaw);
		const flattened = Array.from(map.values()).sort((a, b) => a.name.toLowerCase().localeCompare(b.name.toLowerCase()));
		
		this.report('info_globals', { globals: flattened }, undefined, (data) => {
			this.printVariables(data.globals, 0);
			this.showPrompt();
		});
	}

	cmdInfoModules(args, isPlural = false) {
		if (!this.requireBroken()) {
			this.showPrompt();
			return;
		}
		
		const modsRaw = this.view.modules || [];
		if (modsRaw.length === 0) {
			this.report('info_modules', { list: true, modules: [] }, undefined, () => {
				this.commandError('No modules loaded.');
			});
			return;
		}
		
		if (isPlural) {
			if (args.length > 0) {
				this.commandError('Syntax: info modules');
				return;
			}
			
			const sortedModules = [...modsRaw].sort((a, b) => a.name.toLowerCase().localeCompare(b.name.toLowerCase()));
			const listed = sortedModules.filter(m => m.name !== '(map)').map(m => m.name);
			
			this.report('info_modules', { list: true, modules: listed }, undefined, (data) => {
				for (const name of data.modules) {
					console.log(`  ${name}`);
				}
				this.showPrompt();
			});
		}
		else {
			if (args.length === 0) {
				this.commandError('Syntax: info module <name>');
				return;
			}
			// Find the module by name (first arg)
			let name = args[0];
			let mod = this.view.modules.find(m => m.name === name);
			
			// If not found, try splitting the first arg by dots (e.g. 'timer.default')
			let pathArgs = args;
			if (!mod && name.includes('.')) {
				const parts = name.split('.');
				name = parts[0];
				mod = this.view.modules.find(m => m.name === name);
				if (mod) {
					// Found the base module! Reconstruct args array.
					// e.g. ['timer.default', 'foo'] -> ['timer', 'default', 'foo']
					pathArgs = [...parts, ...args.slice(1)];
				}
			}

			if (!mod) {
				this.commandError(`No module "${args[0]}". Use "info modules" to list.`);
				return;
			}
			if (this.isExpandable(mod) && !mod.children) {
				this.toggleOpen(mod, () => {
					// View rebuilt — find it again in the fresh view
					this.cmdInfoModules(pathArgs, false);
				}, 'modules');
			}
			else if (pathArgs.length === 1) {
				// Just the module name — show its exports
				this.report('info_module', { variable: mod }, undefined, (data) => {
					this.printVariable(data.variable, 0);
					this.showPrompt();
				});
			}
			else {
				// Dot-path into module exports: navigate children
				this.resolveModulePath(mod.children, pathArgs, 1);
			}
		}
	}

	// Navigate into a module's exports tree using dot-path parts.
	// items: the current children list to search
	// parts: full path array (e.g. ['Resource', 'default', 'name'])
	// partIndex: current index into parts
	resolveModulePath(items, parts, partIndex) {
		if (!items || items.length === 0) {
			if (this.currentCommand === 'print' || this.currentCommand === 'p') {
				this.commandError(`"${parts.slice(0, partIndex).join('.')}" has no properties.`);
			}
			return;
		}
		const name = parts[partIndex];
		const found = this.findItem(items, name);
		if (!found) {
			this.commandError(`No property "${name}" on "${parts.slice(0, partIndex).join('.')}".`);
			return;
		}
		const isLast = (partIndex === parts.length - 1);
		if (this.isExpandable(found) && !found.children) {
			this.toggleOpen(found, () => {
				// View rebuilt — re-run from scratch
				this.cmdInfoModules(parts, false);
			}, 'modules');
		}
		else if (isLast) {
			this.report('info_module', { variable: found }, undefined, (data) => {
				this.printVariable(data.variable, 0);
				this.showPrompt();
			});
		}
		else if (found.children) {
			this.resolveModulePath(found.children, parts, partIndex + 1);
		}
		else {
			if (this.currentCommand === 'print' || this.currentCommand === 'p') {
				this.commandError(`"${parts.slice(0, partIndex + 1).join('.')}" has no properties.`);
			}
		}
	}

	cmdSet(args) {
		if (args.length === 2 && args[0] === 'output') {
			if (args[1] === 'json' || args[1] === 'text') {
				this.outputFormat = args[1];
				this.report('set', { outputFormat: this.outputFormat }, undefined, () => {
					console.log(`Output format set to ${this.outputFormat}.`);
					this.showPrompt();
				});
				return;
			}
			this.commandError('Syntax: set output [json|text]');
			return;
		}

		if (args[0] === 'exceptions') {
			const value = args[1];
			if (value === 'on') {
				this.exceptionsMode = 'on';
				this.doSetBreakpoint("exceptions", "0");
				this.report('set', { exceptionsMode: 'on' }, undefined, () => {
					console.log('Break on exceptions: on');
					this.showPrompt();
				});
			}
			else if (value === 'off' || value === 'silent') {
				this.exceptionsMode = value;
				this.doClearBreakpoint("exceptions", "0");
				this.report('set', { exceptionsMode: value }, undefined, () => {
					console.log(`Break on exceptions: ${value}`);
					this.showPrompt();
				});
			}
			else {
				this.commandError('Syntax: set exceptions on|off|silent');
			}
		}
		else if (args[0] === 'timestamps' || args[0] === 'timestamp') {
			const value = (args[1] === 'on') ? 'time' : args[1];
			if (['off', 'time', 'delta', 'elapsed', 'iso', 'epoch'].includes(value)) {
				this.timestamps = value;
				if (value !== 'off')
					DebugMachine.sessionTime ??= Date.now();
				this.report('set', { timestamps: value }, undefined, () => {
					console.log(`Trace timestamps: ${value}`);
					this.showPrompt();
				});
			}
			else {
				this.commandError('Syntax: set timestamps on|off|time|delta|elapsed|iso|epoch');
			}
		}
		else if (args[0] === 'start') {
			const value = args[1];
			if (value === 'on') {
				this.breakOnStart = true;
				this.doSetBreakpoint("start", "0");
				this.report('set', { breakOnStart: true }, undefined, () => {
					console.log('Break on start: on');
					this.showPrompt();
				});
			}
			else if (value === 'off') {
				this.breakOnStart = false;
				this.doClearBreakpoint("start", "0");
				this.report('set', { breakOnStart: false }, undefined, () => {
					console.log('Break on start: off');
					this.showPrompt();
				});
			}
			else {
				this.commandError('Syntax: set start on|off');
			}
		}
		else if (args[0] === 'test262') {
			const value = args.slice(1).join(' ');
			if (!this.tests)
				this.commandError('No test runner.');
			else if (!value || value === 'off') {
				this.tests.test262 = null;
				this.report('set', { test262: null }, undefined, () => {
					console.log('test262 repository: not set');
					this.showPrompt();
				});
			}
			else {
				const root = require('node:path').resolve(require('./xsbug-test.js').expandHome(value));
				if (!fs.existsSync(require('node:path').join(root, 'harness')) || !fs.existsSync(require('node:path').join(root, 'test'))) {
					this.commandError(`Not a test262 repository (no test and harness directories): ${root}`);
					return;
				}
				this.tests.test262 = root;
				this.report('set', { test262: root }, undefined, () => {
					console.log(`test262 repository: ${root}`);
					this.showPrompt();
				});
			}
		}
		else if (args[0] === 'test') {
			if (!this.tests)
				this.commandError('No test runner.');
			else if (args[1] === 'timeout') {
				const seconds = Number(args[2]);
				if (!(seconds >= 0)) {
					this.commandError('Syntax: set test timeout <seconds> (0 disables)');
					return;
				}
				this.tests.timeout = seconds;
				this.report('set', { testTimeout: seconds }, undefined, () => {
					console.log(`Test timeout: ${seconds ? seconds + ' seconds' : 'off'}`);
					this.showPrompt();
				});
			}
			else if (args[1] === 'log') {
				const value = require('./xsbug-test.js').expandHome(args.slice(2).join(' '));
				if (!value || value === 'off') {
					this.tests.logDirectory = null;
					this.report('set', { testLog: null }, undefined, () => {
						console.log('Test reports: off');
						this.showPrompt();
					});
				}
				else {
					const directory = require('node:path').resolve(value);
					if (!fs.existsSync(directory) || !fs.statSync(directory).isDirectory()) {
						this.commandError(`Not a directory: ${directory}`);
						return;
					}
					this.tests.logDirectory = directory;
					this.report('set', { testLog: directory }, undefined, () => {
						console.log(`Test reports: ${directory}`);
						this.showPrompt();
					});
				}
			}
			else
				this.commandError('Syntax: set test timeout <seconds> | set test log <directory>|off');
		}
		else {
			this.commandError('Syntax: set output [json|text] | set exceptions on|off|silent | set start on|off | set mcsim on|off | set timestamps on|off|time|delta|elapsed|iso|epoch | set test262 <path>|off | set test timeout <seconds> | set test log <directory>|off');
		}
	}

	// test <path>: run the tests in a file or directory using the test262 or testmc app. test stop: end the run.
	cmdTest(args) {
		if (!this.tests) {
			this.commandError('No test runner.');
			return;
		}
		const what = args.join(' ').trim();
		if (!what) {
			this.commandError('Syntax: test <path> | test stop');
			return;
		}
		if (what === 'stop') {
			if (!this.tests.stop("stopped"))
				this.commandError('No tests running.');
			this.showPrompt();
			return;
		}
		this.tests.start(what);
		this.showPrompt();
	}

	cmdHelp() {
		const helpData = {
			sections: [
				{
					title: "Commands",
					items: [
						{ keys: "run, r", desc: "Restart the target execution" },
						{ keys: "continue, c", desc: "Resume execution" },
						{ keys: "next, n", desc: "Step over" },
						{ keys: "step, s", desc: "Step into" },
						{ keys: "finish", desc: "Step out (return from current function)" },
						{ keys: "until <line>|<fn>", desc: "Run to specified line or JS function" }
					]
				},
				{
					title: "Breakpoints",
					items: [
						{ keys: "break [file:]<l>|<fn> [if expr]", desc: "Set breakpoint with optional condition" },
						{ keys: "condition <id> [expr]", desc: "Set/clear condition on breakpoint" },
						{ keys: "hitcount <id> [op count]", desc: "Set/clear hit count (op: = < <= > >= %)" },
						{ keys: "trace <id> [expr]", desc: "Set/clear trace expression (logs without stopping)" },
						{ keys: "delete [id1 id2...]", desc: "Delete breakpoint(s) by ID" },
						{ keys: "delete all", desc: "Clear all breakpoints" },
						{ keys: "clear [file:]<l>|<fn>|+l|-l", desc: "Clear breakpoint by location" },
						{ keys: "clear all", desc: "Clear all breakpoints by location" },
						{ keys: "info breakpoints", desc: "List breakpoints" }
					]
				},
				{
					title: "Inspection & Navigation",
					items: [
						{ keys: "list, l [file:]<line>", desc: "Show source around line (default: current)" },
						{ keys: "backtrace, bt, where", desc: "Print call stack" },
						{ keys: "frame <n>, f <n>", desc: "Select stack frame" },
						{ keys: "print, p [expr]", desc: "Print variable (examples below)" },
						{ keys: "info locals", desc: "Print local variables" },
						{ keys: "info globals", desc: "Print global variables" },
						{ keys: "eval <expr>", desc: "Evaluate JavaScript expression in current frame" },
						{ keys: "info modules", desc: "List loaded modules" },
						{ keys: "info module name", desc: "Show exports" },
						{ keys: "info modules.name.path", desc: "Navigate into module exports" },
						{ keys: "info instruments", desc: "Print instrument snapshots" }
					]
				},
				{
					title: "Testing (with the test262 or testmc app)",
					items: [
						{ keys: "test <path>", desc: "Run the tests in a file or directory (relative to $MODDABLE/tests or the test262 repository)" },
						{ keys: "test stop", desc: "Stop the test run" },
						{ keys: "info tests", desc: "Show test results, failures, and settings" },
						{ keys: "info test262", desc: "Show the test262 repository in use" },
						{ keys: "set test262 <path>|off", desc: "test262 repository to use for tests and harness includes" },
						{ keys: "set test timeout <sec>", desc: "Fail a test that does not complete in time (default 60, 0 disables)" },
						{ keys: "set test log <dir>|off", desc: "Where to write the report file of each run (default: the project directory)" }
					]
				},
				{
					title: "Settings",
					items: [
						{ keys: "set exceptions on|off|silent", desc: "Break on exceptions (off shows logs, silent hides them)" },
						{ keys: "info exceptions", desc: "Show break-on-exceptions setting" },
						{ keys: "set start on|off", desc: "Toggle break-on-start" },
						{ keys: "info start", desc: "Show break-on-start setting" },
						{ keys: "set timestamps <mode>", desc: "Timestamp device traces (off|on|time|delta|elapsed|iso|epoch)" },
						{ keys: "info timestamps", desc: "Show trace timestamp setting" },
						{ keys: "set output json|text", desc: "Switch output format to JSON or text" },
						{ keys: "set mcsim on|off", desc: "Show/hide mcsim thread (hidden by default)" }
					]
				},
				{
					title: "Control",
					items: [
						{ keys: "quit, q", desc: "Abort target and exit" },
						{ keys: "help, h", desc: "Show this help" }
					]
				},
				{
					title: "Print examples",
					items: [
						{ keys: "p", desc: "All locals" },
						{ keys: "p name", desc: "Variable (local or global)" },
						{ keys: "p obj.prop", desc: "Property of object" },
						{ keys: "p globalThis.name", desc: "Global variable" },
						{ keys: "p global.name", desc: "Global variable (alias)" },
						{ keys: "p obj.#field", desc: "Private field" },
						{ keys: "p new.target", desc: "new.target" }
					]
				}
			],
			notes: [
				"Press Enter to repeat last command.",
				"Ctrl+C when running to break into target.",
				"Ctrl+D to exit."
			]
		};

		this.report('help', helpData, undefined, (data) => {
			for (const section of data.sections) {
				console.log(section.title === "Commands" ? "Commands:" : `\n${section.title === "Print examples" ? "Print examples" : section.title}:`);
				for (const item of section.items) {
					console.log(`  ${item.keys.padEnd(22)} ${item.desc}`);
				}
			}
			console.log("");
			for (const note of data.notes) {
				console.log(note);
			}
			this.showPrompt();
		});
	}
	cmdRun() {
		if (this.connected) {
			this.promptShown = true;
			this.rl.question('The program being debugged has been started already.\nStart it from the beginning? (y or n) ', (answer) => {
				answer = answer.trim().toLowerCase();
				if (answer === 'y' || answer === 'yes') {
					console.log('Starting program...');
					this.doAbort();
				} else {
					console.log('Not confirmed.');
					this.promptShown = false;
					this.showPrompt();
				}
			});
		} else {
			console.log('No active program to restart.');
			this.showPrompt();
		}
	}

	cmdQuit() {
		if (this.connected)
			this.doAbort();
		process.exit(0);
	}
}

exports.LogMachine = DebugMachine;