take4-console 0.25.0 → 0.30.0

package/src/Screen/Window.mts

@@ -1,8 +1,9 @@
-import type { Cell, StyleId, BorderStyle, BorderChars, WindowBorder, WindowProperties, WriteTextOptions, WriteTextInput, WriteTextSegment, TerminalSize, LayoutMode, AlignItems, JustifyContent, Padding, PaddingSpec, DimSpec } from './types.mjs';
+import type { Cell, StyleId, BorderStyle, BorderChars, WindowBorder, WindowProperties, WriteTextOptions, WriteTextInput, WriteTextSegment, TerminalSize, LayoutMode, AlignItems, JustifyContent, Padding, PaddingSpec, Margin, MarginSpec, DimSpec } from './types.mjs';
 import { BUILTIN_TEXT, BUILTIN_TEXT_FOCUSED, BUILTIN_TEXT_DISABLED, BUILTIN_BORDER, BUILTIN_BORDER_FOCUSED, BUILTIN_BORDER_DISABLED } from './types.mjs';
 import { Region } from './Region.mjs';
 import { StyleRegistry } from './StyleRegistry.mjs';
 import { getRegistry } from './RegistryHolder.mjs';
+import { getErrorHandler } from './ErrorHolder.mjs';
 import { charWidth, stringWidth } from './textWidth.mjs';
 import type { Pos } from './Pos.mjs';
 import { Size } from './Size.mjs';
@@ -76,6 +77,23 @@ const resolvePadding = (spec: PaddingSpec | undefined): Padding => {
 	};
 };
 
+/** Normalises a MarginSpec to a full Margin record (missing sides → 0).
+ *  Shares the PaddingSpec shape so the two helpers are interchangeable. */
+const resolveMargin = (spec: MarginSpec | undefined): Margin => {
+	if (spec === undefined) return { top: 0, right: 0, bottom: 0, left: 0 };
+	if (typeof spec === 'number') return { top: spec, right: spec, bottom: spec, left: spec };
+	if (Array.isArray(spec)) {
+		const [v = 0, h = 0] = spec;
+		return { top: v, right: h, bottom: v, left: h };
+	}
+	return {
+		top:    spec.top    ?? 0,
+		right:  spec.right  ?? 0,
+		bottom: spec.bottom ?? 0,
+		left:   spec.left   ?? 0,
+	};
+};
+
 export class Window {
 	public x: number;
 	public y: number;
@@ -119,12 +137,25 @@ export class Window {
 	/** Padding applied inside the border (in addition to the border inset).
 	 *  Influences `getInnerSize()` / `getInnerOffset()`. */
 	private padding: Padding;
+	/** Outer spacing reserved around this window inside its parent's layout.
+	 *  Consumed by the parent's layout engine (absolute/flex/grid); does not
+	 *  influence this window's inner area. */
+	private margin: Margin;
 	/** Number of columns for `layout: 'grid'`. */
 	private gridColumns: number;
 	/** Cross-axis alignment for row/column layouts. */
 	private alignItems: AlignItems;
 	/** Main-axis distribution of leftover space when no flex-grow child consumes it. */
 	private justifyContent: JustifyContent;
+	/** Optional identifier — copied from WindowProperties.id. Used by
+	 *  `WindowManager.focusById` and by diagnostic tooling. */
+	private id: string | undefined;
+	/** Stacking order among siblings (higher z renders on top). Default: 0. */
+	private zIndex: number;
+	/** Fires once when focused state flips from false to true. */
+	private onFocusHandler: (() => void) | undefined;
+	/** Fires once when focused state flips from true to false. */
+	private onBlurHandler: (() => void) | undefined;
 
 	/** Creates a window from the given properties.
 	 *  For percentage-based sizes, call addChild() before writing content to the window.
@@ -150,9 +181,14 @@ export class Window {
 		this.layoutMode     = wp.layout         ?? 'absolute';
 		this.gap            = wp.gap            ?? 0;
 		this.padding        = resolvePadding(wp.padding);
+		this.margin         = resolveMargin(wp.margin);
 		this.gridColumns    = Math.max(1, wp.gridColumns ?? 1);
 		this.alignItems     = wp.alignItems     ?? 'stretch';
 		this.justifyContent = wp.justifyContent ?? 'start';
+		this.id             = wp.id;
+		this.zIndex         = wp.zIndex ?? 0;
+		this.onFocusHandler = wp.onFocus;
+		this.onBlurHandler  = wp.onBlur;
 
 		const { w, h } = size.isAbsolute() ? size.resolve(0, 0) : { w: 1, h: 1 };
 		this.region  = new Region(w, h);
@@ -173,6 +209,12 @@ export class Window {
 		return this.region.getSize();
 	}
 
+	/** Returns a snapshot of the resolved per-side margin (in cells). The parent's
+	 *  layout engine reads this to reserve outer spacing around the child. */
+	public getMargin(): Readonly<Margin> {
+		return { ...this.margin };
+	}
+
 	/** Returns the number of cells consumed by decorations on each edge.
 	 *  The explicit 'none' border style is treated as no border (no insets). */
 	private borderInset(): { top: number; right: number; bottom: number; left: number } {
@@ -221,9 +263,58 @@ export class Window {
 		this.active = active;
 	}
 
-	/** Sets the focused state. Controls use this to change visual appearance on focus. */
+	/** Sets the focused state. Controls use this to change visual appearance on focus.
+	 *  Fires `onFocus` / `onBlur` (configured via `WindowProperties`) when the state
+	 *  actually changes; a no-op call with the current value does not re-fire them. */
 	public setFocused(focused: boolean): void {
+		if (this.focused === focused) return;
 		this.focused = focused;
+		if (focused) this.onFocusHandler?.();
+		else         this.onBlurHandler?.();
+	}
+
+	/** Registers (or replaces) the onFocus handler at runtime. Pass `undefined`
+	 *  to detach. Fires in `setFocused` on every false → true transition. */
+	public setOnFocus(handler: (() => void) | undefined): void {
+		this.onFocusHandler = handler;
+	}
+
+	/** Registers (or replaces) the onBlur handler at runtime. Pass `undefined`
+	 *  to detach. Fires in `setFocused` on every true → false transition. */
+	public setOnBlur(handler: (() => void) | undefined): void {
+		this.onBlurHandler = handler;
+	}
+
+	/** Returns the optional identifier set via WindowProperties.id. */
+	public getId(): string | undefined {
+		return this.id;
+	}
+
+	/** Sets (or clears with `undefined`) the window identifier used by
+	 *  `WindowManager.focusById` and diagnostic tooling. */
+	public setId(id: string | undefined): void {
+		this.id = id;
+	}
+
+	/** Returns the current stacking order. Higher values render on top of
+	 *  lower ones among siblings. Default: 0. */
+	public getZIndex(): number {
+		return this.zIndex;
+	}
+
+	/** Updates the stacking order. Siblings are re-sorted on the next render()
+	 *  call; call `screen.render()` (or the surrounding window) to see the
+	 *  change. Does not affect layout (flex/absolute coordinates are
+	 *  independent of z). */
+	public setZIndex(zIndex: number): void {
+		this.zIndex = zIndex;
+	}
+
+	/** Returns the direct children of this window in insertion order (a
+	 *  read-only view). WindowManager uses this to walk subtrees for
+	 *  `trapFocus` and `focusById` without exposing the internal array. */
+	public getChildren(): readonly Window[] {
+		return this.children;
 	}
 
 	/** Returns whether this window currently has keyboard focus. */
@@ -478,10 +569,53 @@ export class Window {
 		this.paintBackground();
 		this.blitContent();
 		this.paintBorder();
-		for (const child of this.children) {
+		for (const child of this.orderedByZ()) {
 			if (!child.visible) continue;
-			child.render();
+			try {
+				child.render();
+				this.blitChild(child);
+			} catch (err) {
+				this.paintErrorPlaceholder(child, err);
+				const handler = getErrorHandler();
+				if (handler) handler(err, child);
+				else         throw err;
+			}
+		}
+	}
+
+	/** Returns direct children sorted for rendering — stable by (zIndex asc,
+	 *  insertion order). Children with higher zIndex paint last, so they
+	 *  appear on top of lower-z siblings. Layout is NOT affected: flex and
+	 *  absolute positioning run off the insertion-ordered `children` list. */
+	private orderedByZ(): Window[] {
+		if (this.children.length < 2) return this.children;
+		const stable = this.children.map((child, idx) => ({ child, idx }));
+		stable.sort((a, b) => (a.child.zIndex - b.child.zIndex) || (a.idx - b.idx));
+		return stable.map(e => e.child);
+	}
+
+	/** Renders a single-line "⚠ render error" marker over the child's
+	 *  pre-allocated region so a broken subtree never blanks the rest of the
+	 *  frame. The child is still blitted onto this window so its geometry
+	 *  (borders, siblings) remains visible in the debug layout. */
+	private paintErrorPlaceholder(child: Window, err: unknown): void {
+		const { width, height } = child.getSize();
+		if (width === 0 || height === 0) return;
+		const styleId = this.registry.register({ foreground: 196, background: 52, bold: true });
+		try {
+			child.region = new Region(width, height);
+			child.region.fill(' ', styleId);
+			const message = err instanceof Error ? err.message : String(err);
+			const prefix = '⚠ render error: ';
+			const maxLen = Math.max(0, width - prefix.length);
+			const text = prefix + message.slice(0, maxLen);
+			const chars = [...text];
+			for (let i = 0; i < chars.length && i < width; i++) {
+				child.region.setCell(i, 0, chars[i]!, styleId);
+			}
 			this.blitChild(child);
+		} catch {
+			// Swallow — the placeholder itself must not throw further.
 		}
 	}
 
@@ -657,7 +791,10 @@ export class Window {
 	}
 
 	/** Absolute layout: each child independently resolves its Pos/Size against
-	 *  the parent's inner area — the pre-flex behaviour. */
+	 *  the parent's inner area — the pre-flex behaviour. A child's `margin`
+	 *  shifts the resolved position by `(marginLeft, marginTop)` without
+	 *  altering its size, so callers can push a window away from its declared
+	 *  anchor without recomputing coordinates by hand. */
 	private layoutAbsolute(pw: number, ph: number, ox: number, oy: number): void {
 		for (const child of this.children) {
 			if (!child.sizeSpec.isAbsolute()) {
@@ -666,8 +803,8 @@ export class Window {
 			}
 			const { width: cw, height: ch } = child.getSize();
 			const { x, y } = child.posSpec.resolve(pw, ph, cw, ch);
-			child.x = x + ox;
-			child.y = y + oy;
+			child.x = x + ox + child.margin.left;
+			child.y = y + oy + child.margin.top;
 		}
 	}
 
@@ -681,7 +818,13 @@ export class Window {
 	 *  distribution only when no child consumes slack via flex-grow. Invisible
 	 *  children are skipped so `setVisible(false)` effectively removes them
 	 *  from the stack. Children are ordered by `Pos.flex(order)` first, then
-	 *  by addChild insertion (stable). */
+	 *  by addChild insertion (stable).
+	 *
+	 *  Each child's `margin` reserves extra cells around it: the main axis
+	 *  loses `marginLeft+marginRight` (row) or `marginTop+marginBottom` (column)
+	 *  per child before distribution, and the cross axis loses `margin*` per
+	 *  child before alignment. Grow/shrink still apply to the inner size so the
+	 *  declared margin stays constant even when the child is flex-resized. */
 	private layoutFlex(mode: 'row' | 'column', pw: number, ph: number, ox: number, oy: number): void {
 		const ordered = this.orderedVisibleChildren();
 		if (ordered.length === 0) return;
@@ -690,7 +833,14 @@ export class Window {
 		const crossParent = isRow ? ph : pw;
 		const gap = this.gap;
 
-		// First pass: basis sizes per child.
+		// Per-child main/cross margin totals captured up-front so they stay
+		// constant across grow/shrink passes.
+		const mainMargin  = (c: Window): number => isRow ? c.margin.left + c.margin.right  : c.margin.top  + c.margin.bottom;
+		const crossMargin = (c: Window): number => isRow ? c.margin.top  + c.margin.bottom : c.margin.left + c.margin.right;
+
+		// First pass: basis sizes per child (inner, i.e. the child's own region
+		// without margin). Natural size is taken before margin so content-sized
+		// children keep their intrinsic footprint.
 		const items = ordered.map((c): FlexItem => {
 			const mainSpec  = isRow ? c.sizeSpec.getWidthSpec()  : c.sizeSpec.getHeightSpec();
 			const crossSpec = isRow ? c.sizeSpec.getHeightSpec() : c.sizeSpec.getWidthSpec();
@@ -703,10 +853,13 @@ export class Window {
 			};
 		});
 
-		// Distribute leftover main-axis space.
+		// Distribute leftover main-axis space. The parent sees each child's
+		// slot as `mainSize + mainMargin`, so margins are charged against the
+		// remaining space before grow/shrink.
 		const totalGap = Math.max(0, items.length - 1) * gap;
+		const totalMargin = items.reduce((s, it) => s + mainMargin(it.child), 0);
 		const totalMain = items.reduce((s, it) => s + it.mainSize, 0);
-		let remainder = mainParent - totalMain - totalGap;
+		let remainder = mainParent - totalMain - totalMargin - totalGap;
 		const totalGrow = items.reduce((s, it) => s + (it.mainSpec.mode === 'flex' ? it.mainSpec.grow : 0), 0);
 		if (remainder > 0 && totalGrow > 0) {
 			let distributed = 0;
@@ -733,17 +886,21 @@ export class Window {
 					it.mainSize = Math.max(0, it.mainSize - take);
 				}
 				const consumed = items.reduce((s, it) => s + it.mainSize, 0);
-				remainder = mainParent - consumed - totalGap;
+				remainder = mainParent - consumed - totalMargin - totalGap;
 			}
 		}
 
-		// Apply cross-axis stretch where allowed.
+		// Apply cross-axis stretch where allowed. Cross-axis margin is charged
+		// before stretch/clamp so a stretched child + its margin fits within
+		// crossParent.
 		for (const it of items) {
+			const cm = crossMargin(it.child);
+			const available = Math.max(0, crossParent - cm);
 			const mode = it.crossSpec.mode;
 			if (this.alignItems === 'stretch' && mode !== 'abs' && mode !== 'pct') {
-				it.crossSize = crossParent;
+				it.crossSize = available;
 			} else {
-				it.crossSize = Math.min(it.crossSize, crossParent);
+				it.crossSize = Math.min(it.crossSize, available);
 			}
 		}
 
@@ -767,7 +924,10 @@ export class Window {
 			}
 		}
 
-		// Write final sizes and positions.
+		// Write final sizes and positions. The child's main-axis starting
+		// coordinate is `cursor + marginLeading`; cursor then advances by
+		// `mainSize + mainMargin + itemSpacing` so the next slot is offset by
+		// this child's full footprint.
 		let cursor = mainStart;
 		for (const it of items) {
 			const mainSize  = Math.max(0, it.mainSize);
@@ -777,28 +937,34 @@ export class Window {
 			if (newW !== it.child.getSize().width || newH !== it.child.getSize().height) {
 				it.child.resizeRegions(newW, newH);
 			}
+			const m = it.child.margin;
+			const mainLead  = isRow ? m.left : m.top;
+			const mainTrail = isRow ? m.right : m.bottom;
+			const crossLead = isRow ? m.top  : m.left;
+			const cm = crossMargin(it.child);
 			let crossPos = 0;
 			if (this.alignItems !== 'stretch') {
-				const free = crossParent - crossSize;
+				const free = Math.max(0, crossParent - crossSize - cm);
 				if      (this.alignItems === 'center') crossPos = Math.floor(free / 2);
 				else if (this.alignItems === 'end')    crossPos = free;
 			}
 			if (isRow) {
-				it.child.x = ox + cursor;
-				it.child.y = oy + crossPos;
+				it.child.x = ox + cursor + mainLead;
+				it.child.y = oy + crossPos + crossLead;
 			} else {
-				it.child.x = ox + crossPos;
-				it.child.y = oy + cursor;
+				it.child.x = ox + crossPos + crossLead;
+				it.child.y = oy + cursor + mainLead;
 			}
-			cursor += mainSize + itemSpacing;
+			cursor += mainSize + mainLead + mainTrail + itemSpacing;
 		}
 	}
 
 	/** Grid layout: children are placed row-major into equally sized cells.
 	 *  Each cell's width is `(innerWidth - gap * (cols - 1)) / cols` (floored);
 	 *  heights use the same formula with the derived row count. Children are
-	 *  resized to the cell dimensions and positioned at the cell's top-left.
-	 *  Invisible children are skipped. */
+	 *  resized to the cell dimensions minus their own margin and positioned
+	 *  at the cell's top-left offset by `(marginLeft, marginTop)`. Invisible
+	 *  children are skipped. */
 	private layoutGrid(pw: number, ph: number, ox: number, oy: number): void {
 		const ordered = this.orderedVisibleChildren();
 		if (ordered.length === 0) return;
@@ -811,11 +977,14 @@ export class Window {
 			const child = ordered[i]!;
 			const c = i % cols;
 			const r = Math.floor(i / cols);
-			if (cellW !== child.getSize().width || cellH !== child.getSize().height) {
-				child.resizeRegions(cellW, cellH);
+			const m = child.margin;
+			const innerW = Math.max(0, cellW - m.left - m.right);
+			const innerH = Math.max(0, cellH - m.top  - m.bottom);
+			if (innerW !== child.getSize().width || innerH !== child.getSize().height) {
+				child.resizeRegions(innerW, innerH);
 			}
-			child.x = ox + c * (cellW + gap);
-			child.y = oy + r * (cellH + gap);
+			child.x = ox + c * (cellW + gap) + m.left;
+			child.y = oy + r * (cellH + gap) + m.top;
 		}
 	}
 

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,6 +618,9 @@ 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) {
 			this.renderFrame();
 		}
@@ -533,6 +633,56 @@ 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;
+			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 +810,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. */