take4-console 0.25.0 → 0.30.0

package/src/Screen/controls/TextBox.mts

@@ -1,7 +1,8 @@
 import type { TextBoxProperties, WindowProperties, StyleId } from '../types.mjs';
-import { BUILTIN_TEXT_PLACEHOLDER, BUILTIN_CURSOR } from '../types.mjs';
+import { BUILTIN_TEXT_PLACEHOLDER, BUILTIN_CURSOR, BUILTIN_TEXT_SELECTION } from '../types.mjs';
 import { Window } from '../Window.mjs';
 import { getRegistry } from '../RegistryHolder.mjs';
+import { VirtualCursor } from '../VirtualCursor.mjs';
 
 /** A single-line text-input widget with scrolling, cursor display, and placeholder support.
  *  Wraps content area inside a single-line border (total height 3 by default).
@@ -9,10 +10,17 @@ import { getRegistry } from '../RegistryHolder.mjs';
 export class TextBox extends Window {
 	private value: string;
 	private cursor: number;
+	/** Anchor of the active selection, or null when no selection is active.
+	 *  Selection spans the half-open range [min(anchor, cursor), max(anchor, cursor)). */
+	private selectionAnchor: number | null;
 	private scrollOffset: number;
 	private placeholder: string;
 	private placeholderStyleId: StyleId;
 	private cursorStyleId: StyleId;
+	private selectionStyleId: StyleId;
+	/** Software-cursor model: blink state + glyph. Always present so the
+	 *  caller can reconfigure at runtime via `getVirtualCursor()`. */
+	private virtualCursor: VirtualCursor;
 
 	/** Invoked after every value change driven by handleKey. Not called by setValue. */
 	private onChange?: (value: string) => void;
@@ -35,6 +43,7 @@ export class TextBox extends Window {
 		this.cursor      = cp?.cursor !== undefined
 			? Math.max(0, Math.min(cp.cursor, this.value.length))
 			: this.value.length;
+		this.selectionAnchor = null;
 
 		this.onChange  = cp?.onChange;
 		this.onSubmit  = cp?.onSubmit;
@@ -43,17 +52,75 @@ export class TextBox extends Window {
 		const reg = getRegistry();
 		this.placeholderStyleId = reg.getNamed(BUILTIN_TEXT_PLACEHOLDER)!;
 		this.cursorStyleId      = reg.getNamed(BUILTIN_CURSOR)!;
+		this.selectionStyleId   = reg.getNamed(BUILTIN_TEXT_SELECTION)!;
+
+		this.virtualCursor = new VirtualCursor({
+			symbol: cp?.cursorSymbol,
+			blink:  cp?.cursorBlink,
+		});
 
 		this.clampScroll();
 	}
 
-	/** Replaces the current value; clamps cursor and scroll to fit. Does NOT fire onChange. */
+	/** Returns the VirtualCursor model so callers can tweak symbol/blink at runtime. */
+	public getVirtualCursor(): VirtualCursor {
+		return this.virtualCursor;
+	}
+
+	/** Replaces the current value; clamps cursor and scroll to fit. Does NOT fire onChange.
+	 *  Any active selection is cleared because the old anchor no longer maps
+	 *  onto the new string. */
 	public setValue(value: string): void {
 		this.value  = value;
 		this.cursor = Math.min(this.cursor, value.length);
+		this.selectionAnchor = null;
+		this.clampScroll();
+	}
+
+	/** Returns the normalized selection range `{ start, end }` (half-open)
+	 *  when a selection is active and non-empty, otherwise `null`. */
+	public getSelection(): { start: number; end: number } | null {
+		if (this.selectionAnchor === null) return null;
+		const a = this.selectionAnchor;
+		const b = this.cursor;
+		if (a === b) return null;
+		return a < b ? { start: a, end: b } : { start: b, end: a };
+	}
+
+	/** Returns the currently selected substring, or '' when no selection. */
+	public getSelectedText(): string {
+		const sel = this.getSelection();
+		return sel === null ? '' : this.value.slice(sel.start, sel.end);
+	}
+
+	/** Replaces the current selection: sets anchor and cursor, clamping both
+	 *  to the current value length. Passing identical indices clears the
+	 *  selection; callers that want an empty anchor should use `clearSelection()`. */
+	public setSelection(anchor: number, cursor: number): void {
+		const len = this.value.length;
+		const a = Math.max(0, Math.min(anchor, len));
+		const c = Math.max(0, Math.min(cursor, len));
+		this.selectionAnchor = a === c ? null : a;
+		this.cursor = c;
 		this.clampScroll();
 	}
 
+	/** Selects every character in the current value. No-op when the value is empty. */
+	public selectAll(): void {
+		if (this.value.length === 0) {
+			this.selectionAnchor = null;
+			return;
+		}
+		this.selectionAnchor = 0;
+		this.cursor = this.value.length;
+		this.clampScroll();
+	}
+
+	/** Drops any active selection without moving the cursor. */
+	public clearSelection(): void {
+		this.selectionAnchor = null;
+	}
+
 	/** Replaces the onChange callback (passing undefined clears it). */
 	public setOnChange(fn?: (value: string) => void): void {
 		this.onChange = fn;
@@ -74,9 +141,12 @@ export class TextBox extends Window {
 		return this.value;
 	}
 
-	/** Sets the cursor to the given character index (clamped to valid range). */
+	/** Sets the cursor to the given character index (clamped to valid range).
+	 *  Any active selection is dropped — callers that want to adjust the
+	 *  cursor while keeping the selection must use `setSelection()`. */
 	public setCursor(pos: number): void {
 		this.cursor = Math.max(0, Math.min(pos, this.value.length));
+		this.selectionAnchor = null;
 		this.clampScroll();
 	}
 
@@ -87,9 +157,13 @@ export class TextBox extends Window {
 
 	/** Processes a key string from the terminal input loop and updates value/cursor.
 	 *  Supported special keys: backspace (\x7f), delete (\x1b[3~), left (\x1b[D),
-	 *  right (\x1b[C), home (\x1b[H), end (\x1b[F).
-	 *  Human-readable aliases: 'backspace', 'delete', 'left', 'right', 'home', 'end'.
-	 *  Any single printable character is inserted at the cursor position. */
+	 *  right (\x1b[C), home (\x1b[H), end (\x1b[F), plus their shift-modified
+	 *  CSI variants (`\x1b[1;2D` etc.) which extend the selection, and
+	 *  Ctrl+A (`\x01`) which selects the entire value.
+	 *  Human-readable aliases: 'backspace', 'delete', 'left', 'right', 'home',
+	 *  'end', 'shift+left', 'shift+right', 'shift+home', 'shift+end', 'ctrl+a'.
+	 *  Any single printable character is inserted at the cursor position and
+	 *  replaces the active selection (if any). */
 	public handleKey(key: string): void {
 		if (this.disabled) return;
 
@@ -100,44 +174,119 @@ export class TextBox extends Window {
 		}
 
 		const before = this.value;
+
+		// ── Selection-extending motion (shift + arrow / home / end) ─────────
+		if (key === '\x1b[1;2D' || key === 'shift+left') {
+			this.ensureAnchor();
+			if (this.cursor > 0) this.cursor--;
+			this.finishKey(before);
+			return;
+		}
+		if (key === '\x1b[1;2C' || key === 'shift+right') {
+			this.ensureAnchor();
+			if (this.cursor < this.value.length) this.cursor++;
+			this.finishKey(before);
+			return;
+		}
+		if (key === '\x1b[1;2H' || key === 'shift+home') {
+			this.ensureAnchor();
+			this.cursor = 0;
+			this.finishKey(before);
+			return;
+		}
+		if (key === '\x1b[1;2F' || key === 'shift+end') {
+			this.ensureAnchor();
+			this.cursor = this.value.length;
+			this.finishKey(before);
+			return;
+		}
+		if (key === '\x01' || key === 'ctrl+a') {
+			this.selectAll();
+			this.finishKey(before);
+			return;
+		}
+
 		switch (key) {
 			case '\r': case '\n': case 'enter':
 				this.onSubmit?.(this.value);
 				this.clampScroll();
 				return; // Enter never mutates value by itself in TextBox.
 			case '\x7f': case '\b': case 'backspace':
+				if (this.deleteSelection()) break;
 				if (this.cursor > 0) {
 					this.value = this.value.slice(0, this.cursor - 1) + this.value.slice(this.cursor);
 					this.cursor--;
 				}
 				break;
 			case '\x1b[3~': case 'delete':
+				if (this.deleteSelection()) break;
 				if (this.cursor < this.value.length) {
 					this.value = this.value.slice(0, this.cursor) + this.value.slice(this.cursor + 1);
 				}
 				break;
 			case '\x1b[D': case 'left':
+				// Non-shift left collapses an active selection to its start.
+				if (this.collapseSelection('start')) break;
 				if (this.cursor > 0) this.cursor--;
 				break;
 			case '\x1b[C': case 'right':
+				if (this.collapseSelection('end')) break;
 				if (this.cursor < this.value.length) this.cursor++;
 				break;
 			case '\x1b[H': case 'home':
+				this.selectionAnchor = null;
 				this.cursor = 0;
 				break;
 			case '\x1b[F': case 'end':
+				this.selectionAnchor = null;
 				this.cursor = this.value.length;
 				break;
 			default:
 				if (key.length === 1 && key >= ' ') {
+					this.deleteSelection();
 					this.value = this.value.slice(0, this.cursor) + key + this.value.slice(this.cursor);
 					this.cursor++;
 				}
 		}
+		this.finishKey(before);
+	}
+
+	/** Shared post-key housekeeping: clamp scroll, reset blink phase, fire
+	 *  onChange when the value actually changed. */
+	private finishKey(before: string): void {
 		this.clampScroll();
+		this.virtualCursor.resetPhase();
 		if (this.value !== before) this.onChange?.(this.value);
 	}
 
+	/** Starts a selection at the current cursor if none is active, so that a
+	 *  subsequent cursor move extends the selection. */
+	private ensureAnchor(): void {
+		if (this.selectionAnchor === null) this.selectionAnchor = this.cursor;
+	}
+
+	/** Removes the selected text when a selection is active; cursor is placed
+	 *  at the start of the deleted range. Returns true when a deletion
+	 *  happened, false otherwise. */
+	private deleteSelection(): boolean {
+		const sel = this.getSelection();
+		if (sel === null) return false;
+		this.value = this.value.slice(0, sel.start) + this.value.slice(sel.end);
+		this.cursor = sel.start;
+		this.selectionAnchor = null;
+		return true;
+	}
+
+	/** Drops an active selection, moving the cursor to the selection's
+	 *  `start` or `end` edge. Returns true when it did so. */
+	private collapseSelection(edge: 'start' | 'end'): boolean {
+		const sel = this.getSelection();
+		if (sel === null) return false;
+		this.cursor = edge === 'start' ? sel.start : sel.end;
+		this.selectionAnchor = null;
+		return true;
+	}
+
 	/** Rebuilds the TextBox: renders text or placeholder, draws cursor. */
 	public override render(): void {
 		this.clear();
@@ -153,12 +302,34 @@ export class TextBox extends Window {
 			this.writeText(visible, { style: this.disabled ? undefined : this.normalStyleId });
 		}
 
-		// Draw cursor when focused.
-		if (this.focused && !this.disabled) {
+		// Paint the selection highlight over any cells that fall inside the
+		// active selection range — run before the cursor so the caret still
+		// shows on top of the highlight.
+		const sel = this.focused && !this.disabled ? this.getSelection() : null;
+		if (sel !== null) {
+			const base = this.normalStyleId;
+			for (let i = sel.start; i < sel.end; i++) {
+				const col = i - this.scrollOffset;
+				if (col < 0 || col >= width) continue;
+				const merged = this.registry.merge(base, this.selectionStyleId);
+				const ch = this.value[i] ?? ' ';
+				this.writeText(ch, { x: col, y: 0, style: merged });
+			}
+		}
+
+		// Draw cursor when focused and the virtual-cursor blink says "on".
+		if (this.focused && !this.disabled && this.virtualCursor.isVisible()) {
 			const cursorX = this.cursor - this.scrollOffset;
 			if (cursorX >= 0 && cursorX < width) {
-				const cursorChar  = this.value[this.cursor] ?? ' ';
-				const cursorStyle = this.registry.merge(this.normalStyleId, this.cursorStyleId);
+				const useSymbol   = this.virtualCursor.hasCustomSymbol();
+				// With a custom glyph we draw the glyph itself (styled with the
+				// normal text style so the symbol's colours stay predictable);
+				// without one we fall back to the legacy inverse-block highlight
+				// painted over the character under the caret.
+				const cursorChar  = useSymbol ? this.virtualCursor.getSymbol() : (this.value[this.cursor] ?? ' ');
+				const cursorStyle = useSymbol
+					? this.normalStyleId
+					: this.registry.merge(this.normalStyleId, this.cursorStyleId);
 				this.writeText(cursorChar, { x: cursorX, y: 0, style: cursorStyle });
 			}
 		}

package/src/Screen/controls/Toast.mts

@@ -0,0 +1,138 @@
+import type { StyleId, ToastPosition, WindowBorder } from '../types.mjs';
+import { BUILTIN_TOAST } from '../types.mjs';
+import { Window } from '../Window.mjs';
+import { Pos } from '../Pos.mjs';
+import { Size } from '../Size.mjs';
+import { getRegistry } from '../RegistryHolder.mjs';
+import { stringWidth } from '../textWidth.mjs';
+
+/** Resolved option bag consumed by the `Toast` constructor. `Screen.toast()`
+ *  fills every field so the control itself never has to re-apply defaults. */
+export interface ToastConstructorOptions {
+  /** Anchor corner (or top/bottom centre). Stored on the instance so the
+   *  enclosing Screen can group toasts by anchor for stacking / re-layout. */
+  position: ToastPosition;
+  /** Pre-registered style used both as the window background and as the
+   *  base style for the toast text. */
+  style: StyleId;
+  /** Border configuration. `false` yields a borderless toast. */
+  border: WindowBorder | boolean;
+  /** Stacking order relative to regular Screen children. */
+  zIndex: number;
+  /** Optional width override for the text row (inner area, without border).
+   *  When undefined the toast auto-sizes to the measured string width. */
+  width: number | undefined;
+}
+
+/** Converts a border option (`true` / `false` / `WindowBorder`) into the
+ *  normalised `{ top, right, bottom, left }` record we need to compute the
+ *  toast's final width and height at construction time. */
+const resolveBorderSides = (border: WindowBorder | boolean): { top: boolean; right: boolean; bottom: boolean; left: boolean } => {
+  if (border === false) return { top: false, right: false, bottom: false, left: false };
+  if (border === true)  return { top: true,  right: true,  bottom: true,  left: true  };
+  const style = border.style;
+  if (style === 'none') return { top: false, right: false, bottom: false, left: false };
+  return {
+    top:    border.top    ?? false,
+    right:  border.right  ?? false,
+    bottom: border.bottom ?? false,
+    left:   border.left   ?? false,
+  };
+};
+
+/** A transient overlay window produced by `Screen.toast()`. Holds the
+ *  message text and the anchor position so the Screen can stack, re-flow,
+ *  and dismiss toasts without leaking that bookkeeping into every caller.
+ *
+ *  The toast is auto-sized: the inner text row is `max(stringWidth(text), 1)`
+ *  cells wide (or `options.width` when explicitly provided), plus one cell
+ *  of horizontal padding on each side and the border insets. Height is
+ *  always one text row plus the vertical border insets — toasts do not
+ *  wrap or stack text vertically. */
+export class Toast extends Window {
+  /** Message rendered inside the toast body. Stored so `setMessage` can
+   *  redraw without re-asking the caller for the original text. */
+  private message: string;
+  /** Anchor corner (or top/bottom centre). Read by `Screen` when re-flowing
+   *  the active-toast stack after a dismissal or terminal resize. */
+  private toastPosition: ToastPosition;
+  /** Style shared between the background fill and the text row. Kept so
+   *  `setMessage` uses the same colour combination the toast launched with. */
+  private toastStyle: StyleId;
+  /** Screen-supplied dismissal hook. Registered after construction via
+   *  `attachDismiss()` so `Toast` does not need a circular import on
+   *  `Screen` to invoke `screen.dismissToast(this)`. */
+  private dismissHandler: (() => void) | undefined;
+
+  /** Builds a Toast with a final size derived from the supplied text and
+   *  option bag. The caller (`Screen.toast()`) is responsible for placing
+   *  the toast inside the Screen via `addChild` and setting the final x/y. */
+  public constructor(text: string, options: ToastConstructorOptions) {
+    const sides       = resolveBorderSides(options.border);
+    const borderW     = (sides.left ? 1 : 0) + (sides.right  ? 1 : 0);
+    const borderH     = (sides.top  ? 1 : 0) + (sides.bottom ? 1 : 0);
+    const innerWidth  = Math.max(1, options.width ?? stringWidth(text));
+    const width       = innerWidth + 2 + borderW; // 1-cell horizontal padding each side.
+    const height      = 1 + borderH;
+
+    super({
+      pos:        Pos.topLeft(),
+      size:       new Size(width, height),
+      background: options.style,
+      border:     options.border,
+      zIndex:     options.zIndex,
+      padding:    { left: 1, right: 1, top: 0, bottom: 0 },
+    });
+
+    this.message       = text;
+    this.toastPosition = options.position;
+    this.toastStyle    = options.style;
+
+    this.writeText(text, { x: 0, y: 0, style: options.style });
+  }
+
+  /** Returns the currently displayed message. */
+  public getMessage(): string {
+    return this.message;
+  }
+
+  /** Returns the resolved style id used for both the background fill and
+   *  the text row. Exposed so tests can verify the toast's paint without
+   *  re-resolving BUILTIN_TOAST by hand. */
+  public getToastStyle(): StyleId {
+    return this.toastStyle;
+  }
+
+  /** Returns the anchor corner the toast was created with. `Screen` uses
+   *  this to group sibling toasts when re-flowing the active stack. */
+  public getToastPosition(): ToastPosition {
+    return this.toastPosition;
+  }
+
+  /** Registers the dismiss callback wired up by `Screen.toast()`. Called
+   *  once immediately after construction so `toast.dismiss()` can trigger
+   *  the full Screen-side teardown (timer cancel, re-flow, onDismiss
+   *  callback) without the Toast needing a direct Screen reference. */
+  public attachDismiss(handler: () => void): void {
+    this.dismissHandler = handler;
+  }
+
+  /** Removes the toast from the Screen it was shown on. Equivalent to
+   *  calling `screen.dismissToast(this)` — the overload exists so callers
+   *  that only kept the Toast reference do not need to remember the owning
+   *  Screen. Safe to call before `attachDismiss()` (no-op) or twice
+   *  (subsequent calls are no-ops because the Screen guards re-dismissal). */
+  public dismiss(): void {
+    this.dismissHandler?.();
+  }
+
+  /** Builds a fallback toast style when the registry did not already have
+   *  `BUILTIN_TOAST` mapped. Extracted as a static helper so `Screen.toast`
+   *  can resolve the style before it knows whether construction will fail. */
+  public static resolveDefaultStyle(): StyleId {
+    const reg = getRegistry();
+    const existing = reg.getNamed(BUILTIN_TOAST);
+    if (existing !== undefined) return existing;
+    return reg.registerNamed(BUILTIN_TOAST, { background: 24, foreground: 231, bold: true });
+  }
+}

package/src/Screen/types.mts

@@ -28,6 +28,41 @@ export const BUILTIN_TEXT_PLACEHOLDER   = 'builtin:text-placeholder';
 export const BUILTIN_TEXT_CHECKED       = 'builtin:text-checked';
 /** Name of the cursor highlight style (inverse) used by text input controls. */
 export const BUILTIN_CURSOR             = 'builtin:cursor';
+/** Name of the selection highlight style merged over selected cells in
+ *  `TextBox` / `TextArea` (backlog P1-20). */
+export const BUILTIN_TEXT_SELECTION     = 'builtin:text-selection';
+/** Name of the default background + text style used by `Screen.toast()`
+ *  overlay windows (backlog P1-27). Consumers can override it via
+ *  `Screen.setBuiltinStyle(BUILTIN_TOAST, …)` to recolour every toast at
+ *  once without threading a per-call `style` option. */
+export const BUILTIN_TOAST              = 'builtin:toast';
+
+// ── Virtual cursor ────────────────────────────────────────────────────────────
+
+/** Blink configuration for a `VirtualCursor`.
+ *  - `off`       — cursor is never drawn (hide software cursor entirely).
+ *  - `steady`    — cursor is always drawn (no blink).
+ *  - `slow`      — 600 ms on / 600 ms off.
+ *  - `fast`      — 250 ms on / 250 ms off.
+ *  - `irregular` — each on/off phase picks a randomised duration so the
+ *                  cursor pulses in a non-metronomic "alive" rhythm.
+ *  - `custom`    — caller-supplied on / off durations in milliseconds. */
+export type CursorBlink =
+  | { mode: 'off' }
+  | { mode: 'steady' }
+  | { mode: 'slow' }
+  | { mode: 'fast' }
+  | { mode: 'irregular' }
+  | { mode: 'custom'; onMs: number; offMs: number };
+
+/** Construction options for `VirtualCursor`. Both fields are optional;
+ *  defaults: `symbol = '▎'`, `blink = { mode: 'steady' }`. */
+export interface VirtualCursorOptions {
+  /** Glyph rendered for the cursor when visible. Default: `'▎'`. */
+  symbol?: string;
+  /** Blink schedule. Default: `{ mode: 'steady' }` (no blink). */
+  blink?: CursorBlink;
+}
 
 /** Integer handle returned by StyleRegistry.register(). ID 0 always means no style (empty {}). */
 export type StyleId = number;
@@ -167,6 +202,16 @@ export interface WindowProperties {
    *  padded inner area, and `getInnerSize()` / `getInnerOffset()` reflect the
    *  padding as well as the border. Default: 0 on every side. */
   padding?: PaddingSpec;
+  /** Outer spacing reserved around the window inside its parent's layout.
+   *  - In `row` / `column` flex layouts margin stacks with `gap`: each child
+   *    claims `intrinsic + marginMain` cells on the main axis, and its cross
+   *    extent is reduced by the cross margin.
+   *  - In `grid` layout the child fits inside `cell − margin` and is offset by
+   *    `marginTop` / `marginLeft` within the cell.
+   *  - In `absolute` layout margin shifts the child's resolved position by
+   *    `(marginLeft, marginTop)` without changing its size.
+   *  Default: 0 on every side. */
+  margin?: MarginSpec;
   /** Number of columns for `layout: 'grid'`. Children are placed row-major,
    *  so `gridColumns` implicitly determines the number of rows from the child
    *  count. Default: 1. */
@@ -177,6 +222,21 @@ export interface WindowProperties {
   /** Main-axis distribution of leftover space for `layout: 'row'` / `'column'`
    *  when no child consumes it via flex-grow. Default: 'start'. */
   justifyContent?: JustifyContent;
+  /** Optional string identifier used by `WindowManager.focusById` and for
+   *  diagnostics. InterfaceBuilder copies the YAML `id:` into this field so
+   *  the runtime can cross-reference programmatic focus with the builder map. */
+  id?: string;
+  /** Stacking order among siblings — windows with a higher `zIndex` render
+   *  on top of windows with a lower value. Ties are broken by `addChild`
+   *  insertion order, so the pre-0.26 behaviour (everything at `zIndex: 0`)
+   *  is preserved for callers that don't opt in. Default: 0. */
+  zIndex?: number;
+  /** Fires once when this window transitions from unfocused to focused, via
+   *  any code path (WindowManager, explicit `setFocused(true)`, focus
+   *  inheritance on dialog open). Not fired when the state does not change. */
+  onFocus?: () => void;
+  /** Fires once when this window transitions from focused to unfocused. */
+  onBlur?: () => void;
 }
 
 /** Internal per-axis position spec used by Pos.
@@ -240,6 +300,20 @@ export interface Padding {
  *  a partial per-side record (missing sides default to 0). */
 export type PaddingSpec = number | [number, number] | Partial<Padding>;
 
+/** Resolved per-side margin values (in cells). Margin is the outer counterpart
+ *  of padding — it pushes the window away from its parent's inner edges /
+ *  siblings without reserving space inside the window itself. */
+export interface Margin {
+  top:    number;
+  right:  number;
+  bottom: number;
+  left:   number;
+}
+
+/** User-supplied margin: a uniform number, a [vertical, horizontal] tuple, or
+ *  a partial per-side record (missing sides default to 0). Mirrors `PaddingSpec`. */
+export type MarginSpec = number | [number, number] | Partial<Margin>;
+
 /** Options for Window.writeText() – position defaults to (0, 0). */
 export interface WriteTextOptions {
   /** Column to start writing at. Default: 0. */
@@ -298,6 +372,15 @@ export interface TextBoxProperties {
    *  `true` to mark the key as handled — the default behaviour (inserting,
    *  moving cursor, deleting, …) is then skipped. */
   onKeyDown?: (key: string) => boolean | void;
+  /** Virtual-cursor glyph. Overrides the default inverse-block look. When
+   *  set, the character under the cursor is replaced by this symbol (unless
+   *  the symbol is a zero-width string, in which case the underlying
+   *  character stays). Default: undefined (inverse block). */
+  cursorSymbol?: string;
+  /** Blink schedule for the virtual cursor. Default: `{ mode: 'steady' }`
+   *  (no blink). Requires `WindowManager.enableCursorBlink()` for timed
+   *  modes to actually animate. */
+  cursorBlink?: CursorBlink;
 }
 
 /** Control-specific properties for the TextArea control. */
@@ -324,6 +407,10 @@ export interface TextAreaProperties {
   /** When true, Ctrl+D deletes the character to the right of the cursor
    *  (or joins with the next line at end of line). Default: false. */
   ctrlDDeletesForward?: boolean;
+  /** Virtual-cursor glyph. Overrides the default inverse-block look. */
+  cursorSymbol?: string;
+  /** Blink schedule for the virtual cursor. Default: `{ mode: 'steady' }`. */
+  cursorBlink?: CursorBlink;
 }
 
 /** Control-specific properties for the Checkbox control. */
@@ -465,6 +552,43 @@ export interface SpinnerProperties {
   color?: number;
 }
 
+/** Corner (or top/bottom centre) where `Screen.toast()` anchors its overlay
+ *  windows. Toasts launched at the same position stack vertically in the
+ *  order they were created; a dismissal shifts the remaining stack towards
+ *  the anchor edge so the UI stays compact. */
+export type ToastPosition =
+  | 'top-left'    | 'top-center'    | 'top-right'
+  | 'bottom-left' | 'bottom-center' | 'bottom-right';
+
+/** Options accepted by `Screen.toast()`. All fields are optional; sensible
+ *  defaults make `screen.toast('Saved!')` a single-call notification. */
+export interface ToastOptions {
+  /** Auto-dismiss delay in milliseconds. Pass `0` to keep the toast sticky
+   *  until `toast.dismiss()` is called manually. Default: `2000`. */
+  duration?: number;
+  /** Pre-registered style ID used as both the window background and the
+   *  text style. Default: `BUILTIN_TOAST` (falls back to a high-contrast
+   *  style registered on first use). */
+  style?: StyleId;
+  /** Corner (or top/bottom centre) the toast anchors to. Default:
+   *  `'top-right'`. */
+  position?: ToastPosition;
+  /** Border configuration. Pass `false` for a borderless toast. Default:
+   *  a rounded single-line border on all four sides. */
+  border?: WindowBorder | boolean;
+  /** Stacking order among Screen children. Default: `10_000` so toasts
+   *  draw on top of every regular window without callers having to raise
+   *  other `zIndex` values by hand. */
+  zIndex?: number;
+  /** Override the automatic text-based width (in cells, not counting the
+   *  border). When the text is wider than this value it overflows
+   *  normally — toasts never wrap. Default: `undefined` (auto-size). */
+  width?: number;
+  /** Fires once after the toast has been removed from the Screen
+   *  (auto-dismiss or manual). */
+  onDismiss?: () => void;
+}
+
 /** Control-specific properties for the BarChart control. */
 export interface BarChartProperties {
   /** Data values for each bar. Default: []. */
@@ -575,6 +699,10 @@ export interface YamlWindowDef {
   insertTabAsSpaces?: number;
   /** TextArea: when true, Ctrl+D deletes the character to the right of the cursor. */
   ctrlDDeletesForward?: boolean;
+  /** TextBox / TextArea: virtual-cursor glyph (overrides inverse-block look). */
+  cursorSymbol?: string;
+  /** TextBox / TextArea: virtual-cursor blink schedule. */
+  cursorBlink?: CursorBlink;
   /** LED state ('ok' | 'warn' | 'error' | 'off') — used by statusled. */
   state?: 'ok' | 'warn' | 'error' | 'off';
   /** Whether to show a percentage label over a progress bar. Default: true. */
@@ -620,6 +748,9 @@ export interface YamlWindowDef {
   /** Padding inside the border: uniform number, [vertical, horizontal] tuple,
    *  or a partial per-side record. */
   padding?: number | [number, number] | { top?: number; right?: number; bottom?: number; left?: number };
+  /** Outer spacing reserved around this window inside its parent's layout.
+   *  Same shape as `padding`. */
+  margin?: number | [number, number] | { top?: number; right?: number; bottom?: number; left?: number };
   /** Number of columns for `layout: grid`. */
   gridColumns?: number;
   /** Cross-axis alignment for `layout: row|column`. */
@@ -629,6 +760,9 @@ export interface YamlWindowDef {
   /** Free-form property bag for user-registered custom types. Built-in types
    *  ignore this field; custom factories read it via `node.props`. */
   props?: Record<string, unknown>;
+  /** Stacking order among siblings. Higher values render on top; ties keep
+   *  YAML declaration order. Default: 0. */
+  zIndex?: number;
 }
 
 /** Context passed to factories registered via `InterfaceBuilder.registerType`.
@@ -718,4 +852,10 @@ export interface WindowManagerOptions {
   onMouse?: (event: TerminalMouseEvent) => void;
   /** Enable mouse click tracking (SGR protocol). Default: false. */
   mouse?: boolean;
+  /** Fires when a descendant Window throws during its `render()` call (or its
+   *  blit onto the parent). The offending subtree is replaced in-place with a
+   *  single-line error placeholder so the rest of the frame still paints;
+   *  the handler is invoked once per error with the thrown value and the
+   *  Window that produced it. Default: no-op. */
+  onError?: (err: unknown, control: Window) => void;
 }