take4-console 0.25.0 → 0.31.0

package/src/Screen/Screen.mts

@@ -1,10 +1,11 @@
 import { EventEmitter } from 'node:events';
-import type { CellAttributes, ScreenFrameStats, ScreenOptions, StyleId, TerminalSize } from './types.mjs';
+import type { CellAttributes, DirtyRect, ScreenFrameStats, ScreenOptions, StyleId, TerminalSize, ToastOptions, ToastPosition } from './types.mjs';
 import { StyleRegistry } from './StyleRegistry.mjs';
 import { getRegistry, setRegistry } from './RegistryHolder.mjs';
 import { Window } from './Window.mjs';
 import { Pos } from './Pos.mjs';
 import { Size } from './Size.mjs';
+import { Toast } from './controls/Toast.mjs';
 
 /** ANSI control sequences for the terminal lifecycle features owned by Screen. */
 const ENTER_ALT_SCREEN = '\x1b[?1049h';
@@ -30,6 +31,30 @@ export class Screen extends Window {
 	private signalsInstalled: boolean;
 	/** Whether dispose() has already restored terminal state. */
 	private disposed: boolean;
+	/** Active toast overlays grouped by anchor position. Within each group the
+	 *  toasts are stored in the order they were created so re-layout can stack
+	 *  them outward from the anchor edge. A toast is removed from its group by
+	 *  `dismissToast` (auto-dismiss timer) or by `Toast.dismiss()`. */
+	private activeToasts: Map<ToastPosition, Toast[]>;
+	/** Per-toast auto-dismiss timers. `dismissToast` consults this map so
+	 *  manual dismissals cancel the pending timer and leaking timers are
+	 *  impossible when the caller drops their reference to the toast. */
+	private toastTimers: Map<Toast, ReturnType<typeof setTimeout>>;
+	/** Per-toast dismiss callbacks (from `ToastOptions.onDismiss`). Kept out of
+	 *  the `Toast` instance so the control stays free of bookkeeping code. */
+	private toastDismissHandlers: Map<Toast, () => void>;
+	/** When true, `render()` computes the union of every dirty rect propagated
+	 *  bottom-up from the window tree and emits ANSI sequences only for those
+	 *  cells. When false, every frame re-emits the full buffer (pre-0.31
+	 *  behaviour), which is useful for debugging or for terminals that
+	 *  mis-handle partial cursor jumps. Configured via `ScreenOptions.damageTracking`. */
+	private damageTracking: boolean;
+	/** Forces the next `render()` onto the full-repaint path regardless of the
+	 *  dirty state. Set on the first frame, after `resize()`, and bubbled up
+	 *  from descendants via `markFullInvalidation()` when they change
+	 *  geometry, visibility, or tree topology in ways that would leave
+	 *  stale cells on stdout. Cleared after every full-repaint emit. */
+	private fullInvalidate: boolean;
 
 	/** Initializes the root window sized to the current terminal dimensions.
 	 *  Creates a fresh StyleRegistry (with built-in styles pre-registered)
@@ -52,6 +77,11 @@ export class Screen extends Window {
 		this.boundExit        = (): void => { this.restoreTerminalState(); };
 		this.signalsInstalled = false;
 		this.disposed         = false;
+		this.activeToasts        = new Map();
+		this.toastTimers         = new Map();
+		this.toastDismissHandlers = new Map();
+		this.damageTracking      = options?.damageTracking ?? true;
+		this.fullInvalidate      = true;
 
 		if (options?.altScreen)  this.enterAltScreen();
 		if (options?.hideCursor) this.hideHardwareCursor();
@@ -79,6 +109,146 @@ export class Screen extends Window {
 		return this.targetFps;
 	}
 
+	// ── Toast overlays (P1-27) ────────────────────────────────────────────────
+
+	/** Shows a non-modal toast overlay with the given text. Returns the
+	 *  underlying `Toast` window so callers can inspect it, swap its message,
+	 *  or dismiss it manually via `toast.dismiss()`.
+	 *
+	 *  Toasts are stacked by anchor: every call at the same `position` adds
+	 *  to the visible column, and a dismissal shifts the remainder back
+	 *  towards the anchor edge. Auto-dismissal is driven by a `setTimeout`
+	 *  whose handle is tracked per-toast so manual dismissals cancel the
+	 *  timer. A duration of `0` disables the timer entirely (sticky toast).
+	 *
+	 *  The method calls `render()` once so the overlay appears immediately,
+	 *  and again after every dismissal for the same reason. Consumers
+	 *  driving their own render loop can call `screen.render()` themselves —
+	 *  the extra render here is idempotent against the `'frame'` event. */
+	public toast(text: string, options?: ToastOptions): Toast {
+		const position = options?.position ?? 'top-right';
+		const duration = options?.duration ?? 2000;
+		const zIndex   = options?.zIndex   ?? 10_000;
+		const border   = options?.border   ?? { top: true, right: true, bottom: true, left: true, style: 'rounded' };
+		const style    = options?.style    ?? Toast.resolveDefaultStyle();
+		const width    = options?.width;
+
+		const toast = new Toast(text, { position, style, border, zIndex, width });
+		toast.attachDismiss(() => this.dismissToast(toast));
+
+		const list = this.activeToasts.get(position) ?? [];
+		list.push(toast);
+		this.activeToasts.set(position, list);
+
+		this.addChild(toast);
+		this.relayoutToasts(position);
+
+		if (duration > 0) {
+			const timer = setTimeout(() => this.dismissToast(toast), duration);
+			if (typeof timer === 'object' && timer !== null && 'unref' in timer && typeof timer.unref === 'function') {
+				timer.unref();
+			}
+			this.toastTimers.set(toast, timer);
+		}
+
+		if (options?.onDismiss) this.toastDismissHandlers.set(toast, options.onDismiss);
+
+		this.render();
+		return toast;
+	}
+
+	/** Removes a toast from the Screen, cancels its auto-dismiss timer (if
+	 *  any), reflows the remaining toasts anchored to the same corner, and
+	 *  fires the `onDismiss` callback the caller registered at creation
+	 *  time. Safe to call twice — the second call is a no-op. */
+	public dismissToast(toast: Toast): void {
+		const position = toast.getToastPosition();
+		const list = this.activeToasts.get(position);
+		if (!list) return;
+		const idx = list.indexOf(toast);
+		if (idx === -1) return;
+		list.splice(idx, 1);
+
+		const timer = this.toastTimers.get(toast);
+		if (timer !== undefined) {
+			clearTimeout(timer);
+			this.toastTimers.delete(toast);
+		}
+
+		this.removeChild(toast);
+		this.relayoutToasts(position);
+
+		const handler = this.toastDismissHandlers.get(toast);
+		if (handler) {
+			this.toastDismissHandlers.delete(toast);
+			handler();
+		}
+
+		this.render();
+	}
+
+	/** Returns a snapshot of the currently active toasts for the given anchor
+	 *  position (or every anchor when `position` is omitted). Exposed for
+	 *  tests and diagnostics — consumers generally keep the instance returned
+	 *  by `toast()` rather than walking this list. */
+	public getActiveToasts(position?: ToastPosition): readonly Toast[] {
+		if (position !== undefined) {
+			return [...(this.activeToasts.get(position) ?? [])];
+		}
+		const all: Toast[] = [];
+		for (const list of this.activeToasts.values()) all.push(...list);
+		return all;
+	}
+
+	/** Computes each toast's absolute position inside the Screen for the
+	 *  given anchor group and writes it to the toast's `x` / `y`. Called
+	 *  after every `addChild` / `removeChild` toast mutation and whenever
+	 *  the Screen is resized so the stack stays anchored. Mutates `x` / `y`
+	 *  directly — the Toast's `Pos.topLeft()` is only a placeholder consumed
+	 *  by the absolute layout pass that ran during `addChild`. */
+	private relayoutToasts(position: ToastPosition): void {
+		const list = this.activeToasts.get(position);
+		if (!list || list.length === 0) return;
+		const { width: screenW, height: screenH } = this.getSize();
+
+		const horizontalAnchor: 'left' | 'center' | 'right' =
+			position.endsWith('left')   ? 'left'   :
+			position.endsWith('right')  ? 'right'  :
+			                              'center';
+		const verticalAnchor: 'top' | 'bottom' =
+			position.startsWith('top') ? 'top' : 'bottom';
+
+		let offset = 0;
+		for (const toast of list) {
+			const { width: tw, height: th } = toast.getSize();
+
+			let x: number;
+			if (horizontalAnchor === 'left')       x = 0;
+			else if (horizontalAnchor === 'right') x = Math.max(0, screenW - tw);
+			else                                   x = Math.max(0, Math.floor((screenW - tw) / 2));
+
+			let y: number;
+			if (verticalAnchor === 'top') {
+				y = offset;
+			} else {
+				y = Math.max(0, screenH - offset - th);
+			}
+			offset += th;
+
+			toast.x = x;
+			toast.y = y;
+		}
+	}
+
+	/** Re-runs `relayoutToasts` for every non-empty anchor group. Invoked
+	 *  from `resize()` so terminal resizes keep the overlays pinned to their
+	 *  corners. */
+	private relayoutAllToasts(): void {
+		for (const position of this.activeToasts.keys()) {
+			this.relayoutToasts(position);
+		}
+	}
+
 	// ── Terminal lifecycle helpers ────────────────────────────────────────────
 
 	/** Switches the terminal into the alternate screen buffer. Idempotent. */
@@ -127,6 +297,12 @@ export class Screen extends Window {
 	 *  call from both deliberate teardown and a process 'exit' handler. */
 	public dispose(): void {
 		if (this.disposed) return;
+		// Cancel every pending auto-dismiss timer so a disposed Screen does
+		// not hold the Node event loop open via a detached setTimeout.
+		for (const timer of this.toastTimers.values()) clearTimeout(timer);
+		this.toastTimers.clear();
+		this.toastDismissHandlers.clear();
+		this.activeToasts.clear();
 		this.restoreTerminalState();
 		this.uninstallSignalHandlers();
 		this.disposed = true;
@@ -143,6 +319,9 @@ export class Screen extends Window {
 		const w = width  ?? process.stdout.columns ?? 80;
 		const h = height ?? process.stdout.rows    ?? 24;
 		this.setSize(w, h);
+		// Re-anchor every active toast overlay so corner-positioned stacks
+		// follow the new terminal geometry rather than drifting out of view.
+		this.relayoutAllToasts();
 		const size: TerminalSize = { width: w, height: h };
 		this.events.emit('resize', size);
 		return size;
@@ -175,12 +354,49 @@ export class Screen extends Window {
 	 */
 	public override render(): void {
 		const start = Date.now();
+
+		// Fast path: damage tracking is on, nothing is dirty, no full
+		// invalidation pending — skip composition AND emit entirely. The
+		// terminal already shows the correct pixels from the previous frame.
+		if (this.damageTracking && !this.fullInvalidate) {
+			const rects: DirtyRect[] = [];
+			this.collectDirtyRects(0, 0, rects);
+			if (rects.length === 0) {
+				this.events.emit('frame', { ms: Date.now() - start, cellsEmitted: 0 });
+				return;
+			}
+			// Compose first so `this.region` reflects the latest content; the
+			// emit below reads from it. We keep `rects` for the emit phase
+			// instead of re-collecting, because `super.render()` does not
+			// mutate dirty flags (render-depth guard suppresses markDirty
+			// inside render overrides).
+			super.render();
+			const stats = this.emitDirty(rects);
+			this.clearDirtyRecursive();
+			this.events.emit('frame', { ms: Date.now() - start, cellsEmitted: stats, fullRepaint: false });
+			return;
+		}
+
+		// Slow / fallback path: full repaint. Always used for the first
+		// frame, after `resize()`, after `markFullInvalidation()`, and when
+		// damage tracking has been disabled by the caller.
 		super.render();
+		const cellsEmitted = this.emitFull();
+		this.fullInvalidate = false;
+		this.clearDirtyRecursive();
+		this.events.emit('frame', { ms: Date.now() - start, cellsEmitted, fullRepaint: true });
+	}
 
+	/** Emits every visible cell in `this.region` as one ANSI write, starting
+	 *  with `\x1b[H` (cursor home) and ending with `\x1b[0m`. Returns the
+	 *  number of cells whose character was actually written (skips wide-char
+	 *  continuation sentinels). Used by the full-repaint path. */
+	private emitFull(): number {
 		const reg      = getRegistry();
 		const chars    = this.region.getChars();
 		const styleIds = this.region.getStyleIds();
 		let output = '\x1b[H';
+		let count  = 0;
 		for (let i = 0; i < chars.length; i++) {
 			const ch = chars[i];
 			// Empty-string sentinel = continuation cell of a wide character;
@@ -188,10 +404,105 @@ export class Screen extends Window {
 			if (ch === '') continue;
 			output += this.buildAnsiSequence(reg.get(styleIds[i]));
 			output += ch;
+			count++;
 		}
 		output += '\x1b[0m';
 		process.stdout.write(output);
-		this.events.emit('frame', { ms: Date.now() - start });
+		return count;
+	}
+
+	/** Coalesces the collected dirty rects into per-row horizontal intervals
+	 *  and emits only those cells, using `\x1b[row;colH` cursor jumps between
+	 *  rows. Returns the number of cells emitted so consumers of the 'frame'
+	 *  event can see how much work each frame did. */
+	private emitDirty(rects: DirtyRect[]): number {
+		const { width: sw, height: sh } = this.getSize();
+		if (sw === 0 || sh === 0) { process.stdout.write(''); return 0; }
+
+		// Collapse rects into per-row min/max columns. A Map keyed by row is
+		// sparse enough for the common case (few small dirty regions) and
+		// avoids allocating a dense sh-sized array when only a couple of
+		// rows are touched.
+		const rowSpans = new Map<number, { minX: number; maxX: number }>();
+		for (const r of rects) {
+			const y0 = Math.max(0, r.y);
+			const y1 = Math.min(sh - 1, r.y + r.h - 1);
+			const x0 = Math.max(0, r.x);
+			const x1 = Math.min(sw - 1, r.x + r.w - 1);
+			if (y1 < y0 || x1 < x0) continue;
+			for (let y = y0; y <= y1; y++) {
+				const existing = rowSpans.get(y);
+				if (existing) {
+					if (x0 < existing.minX) existing.minX = x0;
+					if (x1 > existing.maxX) existing.maxX = x1;
+				} else {
+					rowSpans.set(y, { minX: x0, maxX: x1 });
+				}
+			}
+		}
+		if (rowSpans.size === 0) return 0;
+
+		// Emit rows in ascending order so the terminal cursor advances
+		// forward — random access is fine (we always send an explicit cursor
+		// move) but ordered output compresses a bit better and is easier to
+		// reason about in transcripts / tests.
+		const rows = [...rowSpans.keys()].sort((a, b) => a - b);
+		const reg      = getRegistry();
+		const chars    = this.region.getChars();
+		const styleIds = this.region.getStyleIds();
+		let output = '';
+		let count  = 0;
+		for (const y of rows) {
+			const span = rowSpans.get(y)!;
+			// ANSI cursor addressing is 1-based.
+			output += `\x1b[${y + 1};${span.minX + 1}H`;
+			for (let x = span.minX; x <= span.maxX; x++) {
+				const i  = y * sw + x;
+				const ch = chars[i];
+				if (ch === '') continue;
+				output += this.buildAnsiSequence(reg.get(styleIds[i]));
+				output += ch;
+				count++;
+			}
+		}
+		output += '\x1b[0m';
+		process.stdout.write(output);
+		return count;
+	}
+
+	/** Overrides the parent hook so bubbled full-invalidation signals land
+	 *  on this Screen's own `fullInvalidate` flag instead of walking further
+	 *  up a non-existent parent chain. Public so WindowManager can also
+	 *  request a full repaint after pause/resume or alt-screen toggling. */
+	public override markFullInvalidation(): void {
+		this.fullInvalidate = true;
+	}
+
+	/** Public alias of `markFullInvalidation()` — schedules a full repaint on
+	 *  the next `render()` call. Use this when external state (terminal
+	 *  re-init, post-OS dialog, SSH reconnect, …) may have corrupted the
+	 *  on-screen buffer and the stored dirty rects are no longer sufficient. */
+	public invalidate(): void {
+		this.markFullInvalidation();
+	}
+
+	/** Returns whether damage tracking is currently enabled. Useful for demo
+	 *  code and tests that want to assert or toggle the mode at runtime. */
+	public isDamageTrackingEnabled(): boolean {
+		return this.damageTracking;
+	}
+
+	/** Enables or disables damage tracking at runtime. Disabling forces every
+	 *  subsequent frame onto the full-repaint path; re-enabling resumes the
+	 *  dirty-rect emit on the next frame (after one final full repaint, so
+	 *  the terminal state matches the tree-derived baseline). */
+	public setDamageTracking(enabled: boolean): void {
+		if (this.damageTracking === enabled) return;
+		this.damageTracking = enabled;
+		// Always do one full repaint on transition so the terminal buffer
+		// matches what the window tree would produce from scratch — useful
+		// when flipping back and forth for debugging.
+		this.fullInvalidate = true;
 	}
 
 	// ── Private helpers ───────────────────────────────────────────────────────

package/src/Screen/StyleRegistry.mts

@@ -10,6 +10,8 @@ import {
 	BUILTIN_TEXT_PLACEHOLDER,
 	BUILTIN_TEXT_CHECKED,
 	BUILTIN_CURSOR,
+	BUILTIN_TEXT_SELECTION,
+	BUILTIN_TOAST,
 } from './types.mjs';
 
 /** Central registry that maps integer style IDs to CellAttributes objects.
@@ -34,6 +36,8 @@ export class StyleRegistry {
 		this.registerNamed(BUILTIN_TEXT_PLACEHOLDER, { foreground: 242, italic: true });
 		this.registerNamed(BUILTIN_TEXT_CHECKED,     { foreground: 76, bold: true });
 		this.registerNamed(BUILTIN_CURSOR,           { inverse: true });
+		this.registerNamed(BUILTIN_TEXT_SELECTION,   { background: 24, foreground: 231 });
+		this.registerNamed(BUILTIN_TOAST,            { background: 24, foreground: 231, bold: true });
 	}
 
 	/** Registers a CellAttributes object and returns its stable ID.

package/src/Screen/VirtualCursor.mts

@@ -0,0 +1,175 @@
+import type { CursorBlink, VirtualCursorOptions } from './types.mjs';
+
+/** Default on/off durations (ms) for the named blink modes. */
+const BLINK_PRESETS = {
+	slow:    { onMs:  600, offMs:  600 },
+	fast:    { onMs:  250, offMs:  250 },
+} as const;
+
+/** Bounds (ms) for the irregular blink mode — each phase picks a random
+ *  duration from its range so the cursor feels "alive" rather than metronomic. */
+const IRREGULAR_ON_MIN  = 180;
+const IRREGULAR_ON_MAX  = 520;
+const IRREGULAR_OFF_MIN =  90;
+const IRREGULAR_OFF_MAX = 240;
+
+/** Default glyph used when the consumer does not supply one — a vertical
+ *  bar that reads as a text insertion caret on most monospace fonts. */
+export const DEFAULT_CURSOR_SYMBOL = '▎';
+
+/** Internal schedule entry used to walk the blink timeline. */
+interface Phase {
+	/** Absolute timestamp (ms since epoch) when this phase started. */
+	startedAt: number;
+	/** True when the cursor is currently showing, false when hidden. */
+	visible: boolean;
+	/** Duration of this phase in ms. */
+	duration: number;
+}
+
+/** Software cursor model — owns the glyph rendered on screen and the
+ *  on/off blink state. Stateless when `blink.mode === 'off'` or `'steady'`;
+ *  for timed modes the class samples `Date.now()` on every `isVisible()`
+ *  call and advances internal phase state as needed. A caller (typically
+ *  `WindowManager`) is responsible for triggering re-renders on a timer so
+ *  the visual state actually reaches the terminal. */
+export class VirtualCursor {
+	/** Glyph rendered for the cursor when visible. `undefined` means "use
+	 *  the legacy inverse-block highlight over the underlying character". */
+	private symbol: string | undefined;
+	/** Blink configuration — mode and custom timings. */
+	private blink: CursorBlink;
+	/** Current phase in the blink timeline. Lazily initialised on first
+	 *  `isVisible()` call so construction stays free of side effects. */
+	private phase: Phase | null;
+
+	/** Creates a new cursor with the provided symbol and blink settings.
+	 *  Defaults: symbol = `undefined` (inverse-block), blink = `{ mode: 'steady' }`. */
+	public constructor(options?: VirtualCursorOptions) {
+		this.symbol = options?.symbol;
+		this.blink  = options?.blink  ?? { mode: 'steady' };
+		this.phase  = null;
+	}
+
+	/** Returns the caller-supplied glyph, or `DEFAULT_CURSOR_SYMBOL` when
+	 *  none was set. Use `hasCustomSymbol()` to distinguish the two cases. */
+	public getSymbol(): string {
+		return this.symbol ?? DEFAULT_CURSOR_SYMBOL;
+	}
+
+	/** Returns true when a custom glyph was provided; false means the
+	 *  caller wants the legacy inverse-block highlight behaviour. */
+	public hasCustomSymbol(): boolean {
+		return this.symbol !== undefined;
+	}
+
+	/** Replaces the cursor glyph. Pass `undefined` to revert to inverse-block. */
+	public setSymbol(symbol: string | undefined): void {
+		this.symbol = symbol;
+	}
+
+	/** Returns the active blink configuration (for inspection / cloning). */
+	public getBlink(): CursorBlink {
+		return this.blink;
+	}
+
+	/** Replaces the blink configuration and resets the phase timer so the
+	 *  new mode starts in its "on" phase immediately. */
+	public setBlink(blink: CursorBlink): void {
+		this.blink = blink;
+		this.phase = null;
+	}
+
+	/** Returns the fastest cadence (in ms) a re-render would need to show
+	 *  this cursor's blink faithfully, or `null` when the cursor is static
+	 *  (modes `'off'` and `'steady'`). Used by `WindowManager` to pick a
+	 *  timer interval. For `irregular` we return the minimum possible
+	 *  off-phase duration so quick flicks are not missed. */
+	public getTickHintMs(): number | null {
+		switch (this.blink.mode) {
+			case 'off':
+			case 'steady':
+				return null;
+			case 'slow':
+				return BLINK_PRESETS.slow.onMs;
+			case 'fast':
+				return BLINK_PRESETS.fast.onMs;
+			case 'irregular':
+				return IRREGULAR_OFF_MIN;
+			case 'custom':
+				return Math.min(this.blink.onMs, this.blink.offMs);
+			default:
+				return null;
+		}
+	}
+
+	/** Returns whether the cursor should be drawn at the given moment.
+	 *  `now` is accepted for deterministic testing; defaults to `Date.now()`. */
+	public isVisible(now: number = Date.now()): boolean {
+		if (this.blink.mode === 'off')    return false;
+		if (this.blink.mode === 'steady') return true;
+
+		if (this.phase === null) {
+			this.phase = { startedAt: now, visible: true, duration: this.firstOnDuration() };
+		}
+
+		// Walk forward through phases until we land on the one that covers `now`.
+		// Doing this iteratively (vs. a single modulo) is important for
+		// `irregular` mode, where every phase has an independently sampled
+		// duration.
+		while (now - this.phase.startedAt >= this.phase.duration) {
+			const current: Phase      = this.phase;
+			const nextStart: number   = current.startedAt + current.duration;
+			const nextVisible: boolean = !current.visible;
+			this.phase = {
+				startedAt: nextStart,
+				visible:   nextVisible,
+				duration:  this.phaseDuration(nextVisible),
+			};
+		}
+
+		return this.phase.visible;
+	}
+
+	/** Forces the next `isVisible()` sample to begin a fresh "on" phase at
+	 *  `now`. Useful for keeping the cursor steady while the user types — a
+	 *  blink that vanishes mid-keystroke is jarring. */
+	public resetPhase(now: number = Date.now()): void {
+		this.phase = { startedAt: now, visible: true, duration: this.firstOnDuration() };
+	}
+
+	/** Picks the first "on" phase duration for the current blink mode.
+	 *  Split out so tests can assert the expected preset values. */
+	private firstOnDuration(): number {
+		return this.phaseDuration(true);
+	}
+
+	/** Returns the duration of the upcoming phase given its visibility flag.
+	 *  Implements both the named presets and the `custom` / `irregular`
+	 *  semantics in one place. */
+	private phaseDuration(visible: boolean): number {
+		switch (this.blink.mode) {
+			case 'off':
+			case 'steady':
+				return Number.POSITIVE_INFINITY;
+			case 'slow':
+				return visible ? BLINK_PRESETS.slow.onMs : BLINK_PRESETS.slow.offMs;
+			case 'fast':
+				return visible ? BLINK_PRESETS.fast.onMs : BLINK_PRESETS.fast.offMs;
+			case 'custom':
+				return visible ? this.blink.onMs : this.blink.offMs;
+			case 'irregular':
+				return visible
+					? randomBetween(IRREGULAR_ON_MIN,  IRREGULAR_ON_MAX)
+					: randomBetween(IRREGULAR_OFF_MIN, IRREGULAR_OFF_MAX);
+			default:
+				return Number.POSITIVE_INFINITY;
+		}
+	}
+}
+
+/** Returns a uniformly distributed integer in the closed range [min, max].
+ *  Kept as a module-private helper so `VirtualCursor` stays compact. */
+function randomBetween(min: number, max: number): number {
+	return min + Math.floor(Math.random() * (max - min + 1));
+}