take4-console 0.25.0 → 0.31.0

package/src/Screen/WindowManager.mts

@@ -7,6 +7,7 @@ import type {
 } from './types.mjs';
 import { Screen } from './Screen.mjs';
 import { Window } from './Window.mjs';
+import { setErrorHandler } from './ErrorHolder.mjs';
 
 // ── Internal types ────────────────────────────────────────────────────────────
 
@@ -182,6 +183,15 @@ export class WindowManager {
 	private onKey?: (key: string, ctx: KeyContext) => boolean | void;
 	private onMouse?: (event: TerminalMouseEvent) => void;
 	private mouseEnabled: boolean;
+	/** Optional sink for render-time exceptions thrown by descendant windows.
+	 *  Installed into the global ErrorHolder on construction (cleared on
+	 *  stop). When unset, `Window.render()` rethrows instead of swallowing. */
+	private onError?: (err: unknown, control: Window) => void;
+	/** When non-null, focus navigation (`focusNext/Prev/First/Last`, Tab cycle)
+	 *  is constrained to focusable controls whose absolute position falls
+	 *  inside a descendant of this window. Set by `trapFocus`; cleared by the
+	 *  release callback it returns. */
+	private focusTrap: Window | null = null;
 
 	/** Registered bindings mapped by raw key string.
 	 *  Multiple handlers for the same key fire in insertion order; the first
@@ -212,6 +222,12 @@ export class WindowManager {
 	/** Set by pause() when it showed a previously-hidden cursor — instructs
 	 *  resume() to hide it again. Cleared after resume() or stop() uses it. */
 	private pauseRestoreCursorHidden: boolean = false;
+	/** Active setInterval handle for cursor blink ticks, or null when
+	 *  cursor blinking is disabled (the default). */
+	private blinkTimer: ReturnType<typeof setInterval> | null = null;
+	/** Interval (ms) requested by the last `enableCursorBlink()` call.
+	 *  Kept so resume() can reinstall the timer with the same cadence. */
+	private blinkIntervalMs: number | null = null;
 
 	/** Creates a WindowManager for the given Screen.
 	 *  Does not start the input loop; call run() to begin. */
@@ -222,6 +238,11 @@ export class WindowManager {
 		this.onKey        = options?.onKey;
 		this.onMouse      = options?.onMouse;
 		this.mouseEnabled = options?.mouse ?? false;
+		this.onError      = options?.onError;
+
+		if (this.onError) {
+			setErrorHandler((err, control) => this.onError?.(err, control));
+		}
 
 		this.mainEntries   = [];
 		this.mainFocusIndex = -1;
@@ -263,18 +284,86 @@ export class WindowManager {
 	}
 
 	/** Moves focus to the given control if it belongs to the active context and is
-	 *  eligible (not disabled, not hidden via setVisible(false)). */
+	 *  eligible (not disabled, not hidden via setVisible(false)). When a focus
+	 *  trap is installed, the candidate must also be a descendant of the trap
+	 *  — otherwise the call is a no-op. */
 	public setFocus(control: Focusable & Window): void {
 		const entries = this.activeEntries();
 		const idx     = entries.findIndex(e => e.control === control);
 		if (idx === -1) return;
 		const candidate = entries[idx].control;
 		if (candidate.isDisabled() || !candidate.isVisible()) return;
+		if (this.focusTrap && !this.isWithinTrap(candidate)) return;
 		this.blurCurrent();
 		this.setActiveFocusIndex(idx);
 		control.setFocused(true);
 	}
 
+	/** Moves focus to the next eligible control (forward cycle), skipping
+	 *  disabled, hidden, and out-of-trap entries. Equivalent to the Tab key. */
+	public focusNext(): void {
+		this.moveFocus(1);
+	}
+
+	/** Moves focus to the previous eligible control (reverse cycle), skipping
+	 *  disabled, hidden, and out-of-trap entries. Equivalent to Shift-Tab. */
+	public focusPrev(): void {
+		this.moveFocus(-1);
+	}
+
+	/** Focuses the first eligible control in the active context. No-op when
+	 *  no control is eligible. */
+	public focusFirst(): void {
+		this.focusAtEdge('first');
+	}
+
+	/** Focuses the last eligible control in the active context. */
+	public focusLast(): void {
+		this.focusAtEdge('last');
+	}
+
+	/** Focuses the control registered with the given `id` (copied from
+	 *  `WindowProperties.id` / YAML `id:`). Searches the active focus context
+	 *  only; returns `true` on success, `false` when no matching control is
+	 *  registered or the match is ineligible. */
+	public focusById(id: string): boolean {
+		const entries = this.activeEntries();
+		for (const entry of entries) {
+			if (entry.control.getId() !== id) continue;
+			if (!this.isFocusable(entry.control))        return false;
+			if (this.focusTrap && !this.isWithinTrap(entry.control)) return false;
+			this.blurCurrent();
+			this.setActiveFocusIndex(entries.indexOf(entry));
+			entry.control.setFocused(true);
+			return true;
+		}
+		return false;
+	}
+
+	/** Constrains focus navigation to descendants of `within`. While active,
+	 *  `focusNext / focusPrev / focusFirst / focusLast / setFocus / focusById`
+	 *  skip any control that is not a descendant of `within`; Tab / Shift-Tab
+	 *  cycle within the trapped subtree only. Nested calls stack in LIFO
+	 *  order via the returned release function — calling the release restores
+	 *  the previous trap (or clears it when this was the outermost). The
+	 *  helper is independent of the modal dialog stack, so it can be used
+	 *  for composite controls that live inside the main context. */
+	public trapFocus(within: Window): () => void {
+		const previous = this.focusTrap;
+		this.focusTrap = within;
+		return () => {
+			if (this.focusTrap === within) {
+				this.focusTrap = previous;
+			}
+		};
+	}
+
+	/** Returns the Window that currently defines the focus trap, or null when
+	 *  no trap is active. Exposed primarily for tests and diagnostics. */
+	public getFocusTrap(): Window | null {
+		return this.focusTrap;
+	}
+
 	// ── Global key bindings (P0-4) ─────────────────────────────────────────────
 
 	/** Registers a global shortcut handler.
@@ -422,6 +511,8 @@ export class WindowManager {
 		this.running     = false;
 		this.paused      = false;
 
+		this.uninstallBlinkTimer();
+
 		if (wasRunning) {
 			if (!wasPaused) {
 				process.stdin.off('data', this.boundHandleInput);
@@ -448,6 +539,8 @@ export class WindowManager {
 			this.pauseRestoreCursorHidden = false;
 		}
 
+		if (this.onError) setErrorHandler(undefined);
+
 		this.onExit?.();
 	}
 
@@ -485,6 +578,10 @@ export class WindowManager {
 			this.screen.showHardwareCursor();
 		}
 
+		// Stop the blink timer so a spawned sub-process doesn't get its
+		// screen overwritten mid-frame. resume() reinstalls it.
+		this.uninstallBlinkTimer();
+
 		this.pauseRestoreAltScreen = false;
 		if (options?.leaveAltScreen && this.screen.isAltScreenActive()) {
 			this.screen.exitAltScreen();
@@ -521,7 +618,14 @@ export class WindowManager {
 		process.stdin.resume();
 		process.stdin.on('data', this.boundHandleInput);
 
+		// Restore the blink timer with its previously configured cadence.
+		this.installBlinkTimer();
+
 		if (options?.rerender !== false) {
+			// The paused interval may have reflowed via external writes
+			// (e.g. another process scribbled onto stdout), so schedule a
+			// full repaint instead of relying on cached dirty rects.
+			this.screen.invalidate();
 			this.renderFrame();
 		}
 	}
@@ -533,6 +637,63 @@ export class WindowManager {
 		return this.paused;
 	}
 
+	// ── Cursor blink ───────────────────────────────────────────────────────────
+
+	/** Starts a timer that periodically triggers a re-render so timed-blink
+	 *  `VirtualCursor` instances (used by focused `TextBox` / `TextArea`)
+	 *  actually animate in the terminal. Call once after `run()`; the timer
+	 *  automatically pauses during `pause()` and re-arms on `resume()`.
+	 *
+	 *  The `intervalMs` parameter sets how often the timer fires — smaller
+	 *  values are smoother but render more frames per second. Default:
+	 *  `80` ms (≈12 Hz), enough to capture the `fast` preset (250/250) and
+	 *  the short phases of `irregular` without flooding stdout.
+	 *
+	 *  Idempotent: calling again with a new interval replaces the existing
+	 *  timer. */
+	public enableCursorBlink(intervalMs: number = 80): void {
+		this.blinkIntervalMs = Math.max(16, intervalMs);
+		this.installBlinkTimer();
+	}
+
+	/** Stops the blink timer installed by `enableCursorBlink()`. Idempotent. */
+	public disableCursorBlink(): void {
+		this.blinkIntervalMs = null;
+		this.uninstallBlinkTimer();
+	}
+
+	/** (Re)creates the blink interval using the cached `blinkIntervalMs`. */
+	private installBlinkTimer(): void {
+		this.uninstallBlinkTimer();
+		if (this.blinkIntervalMs === null) return;
+		this.blinkTimer = setInterval(() => {
+			// Avoid drawing while paused — the stdin listener is detached
+			// and the terminal might be owned by a sub-process.
+			if (this.paused) return;
+			// A blink tick is a pure time-driven change: no user input
+			// modified any state, so damage tracking would otherwise skip
+			// the frame entirely and the cursor would never visually blink.
+			// Flag the focused control dirty (if any) so its render() path
+			// re-emits the TextBox / TextArea row with the new cursor
+			// phase; when nothing is focused the frame is still skipped.
+			this.getFocused()?.markDirty();
+			this.renderFrame();
+		}, this.blinkIntervalMs);
+		// Don't keep the Node event loop alive just for cursor blinks.
+		if (typeof this.blinkTimer === 'object' && this.blinkTimer !== null
+		    && 'unref' in this.blinkTimer && typeof this.blinkTimer.unref === 'function') {
+			this.blinkTimer.unref();
+		}
+	}
+
+	/** Clears the active blink interval, if any. */
+	private uninstallBlinkTimer(): void {
+		if (this.blinkTimer !== null) {
+			clearInterval(this.blinkTimer);
+			this.blinkTimer = null;
+		}
+	}
+
 	// ── Input handling ─────────────────────────────────────────────────────────
 
 	/** Processes a raw stdin Buffer. Exposed as public so tests can drive it directly
@@ -660,9 +821,48 @@ export class WindowManager {
 	}
 
 	/** Returns true when the control is eligible to receive focus in the current
-	 *  context — neither disabled nor hidden via `Window.setVisible(false)`. */
+	 *  context — neither disabled nor hidden via `Window.setVisible(false)`,
+	 *  and inside the active focus trap (if any). */
 	private isFocusable(control: Focusable & Window): boolean {
-		return !control.isDisabled() && control.isVisible();
+		if (control.isDisabled() || !control.isVisible()) return false;
+		if (this.focusTrap && !this.isWithinTrap(control)) return false;
+		return true;
+	}
+
+	/** Depth-first check: is `control` the trap window itself or one of its
+	 *  descendants? Used when `focusTrap` is installed to filter focus
+	 *  candidates. Cheaper than storing parent pointers because the subtree
+	 *  is usually small (the trap is a dialog or composite control). */
+	private isWithinTrap(control: Window): boolean {
+		if (!this.focusTrap) return true;
+		return this.isDescendant(control, this.focusTrap);
+	}
+
+	/** Returns true when `node` is `root` or is reachable by walking
+	 *  `root.getChildren()` recursively. */
+	private isDescendant(node: Window, root: Window): boolean {
+		if (node === root) return true;
+		for (const child of root.getChildren()) {
+			if (this.isDescendant(node, child)) return true;
+		}
+		return false;
+	}
+
+	/** Moves focus to the first or last eligible control in the active
+	 *  context. Shared implementation for `focusFirst` / `focusLast`. */
+	private focusAtEdge(edge: 'first' | 'last'): void {
+		const entries = this.activeEntries();
+		if (entries.length === 0) return;
+		const order = edge === 'first'
+			? entries.map((_, i) => i)
+			: entries.map((_, i) => entries.length - 1 - i);
+		for (const idx of order) {
+			if (!this.isFocusable(entries[idx]!.control)) continue;
+			this.blurCurrent();
+			this.setActiveFocusIndex(idx);
+			entries[idx]!.control.setFocused(true);
+			return;
+		}
 	}
 
 	/** Finds the first already-focused (or first eligible) control and focuses it. */

package/src/Screen/controls/BarChart.mts

@@ -34,6 +34,7 @@ export class BarChart extends Window {
 	/** Sets the data values. Call render() afterwards. */
 	public setData(data: number[]): void {
 		this.data = data;
+		this.markDirty();
 	}
 
 	/** Returns the current data values. */
@@ -44,6 +45,7 @@ export class BarChart extends Window {
 	/** Sets the bar labels. Call render() afterwards. */
 	public setLabels(labels: string[]): void {
 		this.labels = labels;
+		this.markDirty();
 	}
 
 	/** Returns the current bar labels. */
@@ -54,6 +56,7 @@ export class BarChart extends Window {
 	/** Sets the maximum Y value. Pass undefined to derive from data. Call render() afterwards. */
 	public setMax(max: number | undefined): void {
 		this.max = max;
+		this.markDirty();
 	}
 
 	/** Returns the configured maximum Y value, or undefined if derived from data. */

package/src/Screen/controls/Checkbox.mts

@@ -31,7 +31,9 @@ export class Checkbox extends Window {
 
 	/** Toggles or sets the checked state. */
 	public setChecked(checked: boolean): void {
+		if (this.checked === checked) return;
 		this.checked = checked;
+		this.markDirty();
 	}
 
 	/** Returns the current checked state. */
@@ -44,6 +46,7 @@ export class Checkbox extends Window {
 		if (this.disabled) return;
 		if (key === ' ' || key === 'space') {
 			this.checked = !this.checked;
+			this.markDirty();
 			this.onChange?.(this.checked);
 		}
 	}

package/src/Screen/controls/LineChart.mts

@@ -38,6 +38,7 @@ export class LineChart extends Window {
 	/** Sets the data series. Call render() afterwards. */
 	public setData(data: number[]): void {
 		this.data = data;
+		this.markDirty();
 	}
 
 	/** Returns the current data series. */
@@ -48,6 +49,7 @@ export class LineChart extends Window {
 	/** Sets the minimum Y value. Pass undefined to derive from data. Call render() afterwards. */
 	public setMin(min: number | undefined): void {
 		this.minValue = min;
+		this.markDirty();
 	}
 
 	/** Returns the configured minimum Y value, or undefined if derived from data. */
@@ -58,6 +60,7 @@ export class LineChart extends Window {
 	/** Sets the maximum Y value. Pass undefined to derive from data. Call render() afterwards. */
 	public setMax(max: number | undefined): void {
 		this.maxValue = max;
+		this.markDirty();
 	}
 
 	/** Returns the configured maximum Y value, or undefined if derived from data. */

package/src/Screen/controls/ListBox.mts

@@ -54,6 +54,7 @@ export class ListBox<T = string> extends Window {
 		this.items         = items;
 		this.selectedIndex = items.length > 0 ? 0 : -1;
 		this.scrollTop     = 0;
+		this.markDirty();
 	}
 
 	/** Returns the current list items. */
@@ -67,7 +68,9 @@ export class ListBox<T = string> extends Window {
 			this.selectedIndex = -1;
 			return;
 		}
+		const prev = this.selectedIndex;
 		this.selectedIndex = Math.max(0, Math.min(this.items.length - 1, index));
+		if (prev !== this.selectedIndex) this.markDirty();
 		this.ensureVisible();
 	}
 
@@ -85,6 +88,7 @@ export class ListBox<T = string> extends Window {
 	/** Replaces the per-row renderer after construction. Pass undefined to restore default behaviour. */
 	public setRenderItem(fn: ((item: T, ctx: ListBoxRenderContext) => ListBoxRowSegments) | undefined): void {
 		this.renderItem = fn;
+		this.markDirty();
 	}
 
 	/** Returns the configured row height in cells. */
@@ -129,7 +133,11 @@ export class ListBox<T = string> extends Window {
 				return;
 		}
 
+		const prevScroll = this.scrollTop;
 		this.ensureVisible();
+		if (this.selectedIndex !== prev || this.scrollTop !== prevScroll) {
+			this.markDirty();
+		}
 		if (this.selectedIndex !== prev) {
 			this.onChange?.(this.selectedIndex, this.items[this.selectedIndex]);
 		}

package/src/Screen/controls/ProgressBar.mts

@@ -37,6 +37,7 @@ export class ProgressBar extends Window {
 	/** Sets the current value (clamped to 0–max). Call render() afterwards. */
 	public setValue(value: number): void {
 		this.value = Math.max(0, Math.min(value, this.max));
+		this.markDirty();
 	}
 
 	/** Returns the current value. */
@@ -48,6 +49,7 @@ export class ProgressBar extends Window {
 	public setMax(max: number): void {
 		this.max   = Math.max(1, max);
 		this.value = Math.min(this.value, this.max);
+		this.markDirty();
 	}
 
 	/** Returns the maximum value. */

package/src/Screen/controls/ProgressBarV.mts

@@ -31,6 +31,7 @@ export class ProgressBarV extends Window {
 	/** Sets the current value (clamped to 0–max). Call render() afterwards. */
 	public setValue(value: number): void {
 		this.value = Math.max(0, Math.min(value, this.max));
+		this.markDirty();
 	}
 
 	/** Returns the current value. */
@@ -42,6 +43,7 @@ export class ProgressBarV extends Window {
 	public setMax(max: number): void {
 		this.max   = Math.max(1, max);
 		this.value = Math.min(this.value, this.max);
+		this.markDirty();
 	}
 
 	/** Returns the maximum value. */

package/src/Screen/controls/Radio.mts

@@ -31,7 +31,9 @@ export class Radio extends Window {
 
 	/** Sets the selected state. */
 	public setChecked(checked: boolean): void {
+		if (this.checked === checked) return;
 		this.checked = checked;
+		this.markDirty();
 	}
 
 	/** Returns the current selected state. */
@@ -43,7 +45,10 @@ export class Radio extends Window {
 	public handleKey(key: string): void {
 		if (this.disabled) return;
 		if (key === ' ' || key === 'space') {
-			this.checked = true;
+			if (!this.checked) {
+				this.checked = true;
+				this.markDirty();
+			}
 			this.onChange?.(true);
 		}
 	}

package/src/Screen/controls/Sparkline.mts

@@ -31,6 +31,7 @@ export class Sparkline extends Window {
 	/** Sets the data series. Call render() afterwards. */
 	public setData(data: number[]): void {
 		this.data = data;
+		this.markDirty();
 	}
 
 	/** Returns the current data series. */
@@ -41,6 +42,7 @@ export class Sparkline extends Window {
 	/** Sets the minimum value. Pass undefined to derive from data. Call render() afterwards. */
 	public setMin(min: number | undefined): void {
 		this.minValue = min;
+		this.markDirty();
 	}
 
 	/** Returns the configured minimum value, or undefined if derived from data. */
@@ -51,6 +53,7 @@ export class Sparkline extends Window {
 	/** Sets the maximum value. Pass undefined to derive from data. Call render() afterwards. */
 	public setMax(max: number | undefined): void {
 		this.maxValue = max;
+		this.markDirty();
 	}
 
 	/** Returns the configured maximum value, or undefined if derived from data. */

package/src/Screen/controls/Spinner.mts

@@ -52,12 +52,14 @@ export class Spinner extends Window {
 	public step(): void {
 		if (!this.running || this.frames.length === 0) return;
 		this.frame = (this.frame + 1) % this.frames.length;
+		this.markDirty();
 	}
 
 	/** Sets the current frame index directly. Wraps into the valid range. */
 	public setFrame(frame: number): void {
 		if (this.frames.length === 0) return;
 		this.frame = ((frame % this.frames.length) + this.frames.length) % this.frames.length;
+		this.markDirty();
 	}
 
 	/** Returns the current frame index. */
@@ -67,12 +69,16 @@ export class Spinner extends Window {
 
 	/** Starts or resumes the animation. step() will advance frames again. */
 	public start(): void {
+		if (this.running) return;
 		this.running = true;
+		this.markDirty();
 	}
 
 	/** Pauses the animation. step() becomes a no-op; the current frame stays visible. */
 	public stop(): void {
+		if (!this.running) return;
 		this.running = false;
+		this.markDirty();
 	}
 
 	/** Returns whether the spinner is currently animating. */

package/src/Screen/controls/StatusLED.mts

@@ -38,7 +38,9 @@ export class StatusLED extends Window {
 
 	/** Sets the current LED state. Call render() afterwards to update the display. */
 	public setState(state: 'ok' | 'warn' | 'error' | 'off'): void {
+		if (this.state === state) return;
 		this.state = state;
+		this.markDirty();
 	}
 
 	/** Returns the current LED state. */

package/src/Screen/controls/Tabs.mts

@@ -48,6 +48,7 @@ export class Tabs extends Window {
 	public setTitles(titles: string[]): void {
 		this.titles      = titles;
 		this.activeIndex = Math.max(0, Math.min(titles.length - 1, this.activeIndex));
+		this.markDirty();
 	}
 
 	/** Returns the current tab titles. */
@@ -64,6 +65,7 @@ export class Tabs extends Window {
 		const clamped = Math.max(0, Math.min(this.titles.length - 1, index));
 		if (clamped !== this.activeIndex) {
 			this.activeIndex = clamped;
+			this.markDirty();
 			this.onChange?.(clamped, this.titles[clamped]);
 		}
 	}