take4-console 0.30.0 → 0.31.0

package/src/Screen/Screen.mts

@@ -1,5 +1,5 @@
 import { EventEmitter } from 'node:events';
-import type { CellAttributes, ScreenFrameStats, ScreenOptions, StyleId, TerminalSize, ToastOptions, ToastPosition } 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';
@@ -43,6 +43,18 @@ export class Screen extends Window {
 	/** 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)
@@ -68,6 +80,8 @@ export class Screen extends Window {
 		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();
@@ -340,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;
@@ -353,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/Window.mts

@@ -1,4 +1,4 @@
-import type { Cell, StyleId, BorderStyle, BorderChars, WindowBorder, WindowProperties, WriteTextOptions, WriteTextInput, WriteTextSegment, TerminalSize, LayoutMode, AlignItems, JustifyContent, Padding, PaddingSpec, Margin, MarginSpec, DimSpec } from './types.mjs';
+import type { Cell, StyleId, BorderStyle, BorderChars, WindowBorder, WindowProperties, WriteTextOptions, WriteTextInput, WriteTextSegment, TerminalSize, LayoutMode, AlignItems, JustifyContent, Padding, PaddingSpec, Margin, MarginSpec, DimSpec, DirtyRect } 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';
@@ -156,6 +156,25 @@ export class Window {
 	private onFocusHandler: (() => void) | undefined;
 	/** Fires once when focused state flips from true to false. */
 	private onBlurHandler: (() => void) | undefined;
+	/** Parent window (set by `addChild`, cleared by `removeChild`). Damage
+	 *  tracking walks up this chain to notify the root `Screen` of geometry
+	 *  or topology changes that need a full repaint. */
+	protected parent: Window | null = null;
+	/** Accumulated dirty region in this window's local coordinates.
+	 *  - `null`  — nothing changed since the last emit.
+	 *  - `'all'` — the whole window area needs to be re-emitted.
+	 *  - `DirtyRect` — bounding box of localised writes; `markDirty()` eagerly
+	 *    unions new rects so we only ever carry one rect per window.
+	 *  Windows start as `'all'` so the very first frame re-emits every cell. */
+	protected dirtyRect: DirtyRect | 'all' | null = 'all';
+	/** Depth of nested `Window.render()` calls currently executing. Increments
+	 *  at the top of every `render()` and decrements in a `finally`, so
+	 *  controls whose `render()` override re-writes content via `this.clear()`
+	 *  / `this.writeText(...)` do not re-mark themselves dirty every frame —
+	 *  render-time writes deterministically rebuild the display buffer from
+	 *  existing state, so marking them as "user-driven dirty" would defeat the
+	 *  "skip frame when nothing changed" optimisation. */
+	protected static renderingDepth: number = 0;
 
 	/** Creates a window from the given properties.
 	 *  For percentage-based sizes, call addChild() before writing content to the window.
@@ -209,6 +228,88 @@ export class Window {
 		return this.region.getSize();
 	}
 
+	// ── Damage tracking ─────────────────────────────────────────────────────
+
+	/** Marks this window (or a sub-rectangle in its local coordinates) as
+	 *  dirty. Subsequent `Screen.render()` calls emit ANSI only for cells
+	 *  inside the collected dirty rects, skipping untouched regions. When
+	 *  `rect` is omitted, the entire window is flagged. Render-time writes
+	 *  are ignored so controls' `render()` overrides do not re-mark
+	 *  themselves every frame. Safe to call many times between renders —
+	 *  new rects are unioned into the existing bounding box. */
+	public markDirty(rect?: DirtyRect): void {
+		if (Window.renderingDepth > 0) return;
+		if (this.dirtyRect === 'all') return;
+		if (rect === undefined) { this.dirtyRect = 'all'; return; }
+		if (rect.w <= 0 || rect.h <= 0) return;
+		if (this.dirtyRect === null) {
+			this.dirtyRect = { x: rect.x, y: rect.y, w: rect.w, h: rect.h };
+			return;
+		}
+		const ax0 = this.dirtyRect.x;
+		const ay0 = this.dirtyRect.y;
+		const ax1 = ax0 + this.dirtyRect.w;
+		const ay1 = ay0 + this.dirtyRect.h;
+		const bx0 = rect.x;
+		const by0 = rect.y;
+		const bx1 = bx0 + rect.w;
+		const by1 = by0 + rect.h;
+		const nx0 = Math.min(ax0, bx0);
+		const ny0 = Math.min(ay0, by0);
+		const nx1 = Math.max(ax1, bx1);
+		const ny1 = Math.max(ay1, by1);
+		this.dirtyRect = { x: nx0, y: ny0, w: nx1 - nx0, h: ny1 - ny0 };
+	}
+
+	/** Convenience alias — flags the entire window as dirty. Equivalent to
+	 *  calling `markDirty()` with no argument; kept as a named entry point
+	 *  so custom controls can invalidate themselves without depending on
+	 *  the default-argument behaviour. */
+	public invalidate(): void {
+		this.markDirty();
+	}
+
+	/** Walks the parent chain up to the root window. Damage tracking uses
+	 *  this to bubble a full-invalidation signal to the root `Screen` when
+	 *  geometry or tree topology changes, because the cells previously
+	 *  occupied by a now-moved / resized / hidden window need to be repainted
+	 *  from the content underneath them. `Screen` overrides it to toggle its
+	 *  internal full-repaint flag; plain `Window`s forward the call up. */
+	protected markFullInvalidation(): void {
+		this.parent?.markFullInvalidation();
+	}
+
+	/** Appends this window's dirty rect (translated into screen coordinates
+	 *  via the running offset) and every descendant's dirty rects to `acc`.
+	 *  Hidden subtrees are skipped — invisible windows don't contribute to
+	 *  the emit phase, and any state change that flips visibility already
+	 *  escalated to a full invalidation so the vacated area repaints. */
+	protected collectDirtyRects(offsetX: number, offsetY: number, acc: DirtyRect[]): void {
+		if (!this.visible) return;
+		if (this.dirtyRect === 'all') {
+			const { width, height } = this.getSize();
+			acc.push({ x: offsetX, y: offsetY, w: width, h: height });
+		} else if (this.dirtyRect !== null) {
+			acc.push({
+				x: offsetX + this.dirtyRect.x,
+				y: offsetY + this.dirtyRect.y,
+				w: this.dirtyRect.w,
+				h: this.dirtyRect.h,
+			});
+		}
+		for (const child of this.children) {
+			child.collectDirtyRects(offsetX + child.x, offsetY + child.y, acc);
+		}
+	}
+
+	/** Clears the dirty flag on this window and every descendant. Called by
+	 *  `Screen.render()` after the emit phase so the next frame starts from
+	 *  a clean slate. */
+	protected clearDirtyRecursive(): void {
+		this.dirtyRect = null;
+		for (const child of this.children) child.clearDirtyRecursive();
+	}
+
 	/** 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> {
@@ -260,7 +361,9 @@ export class Window {
 
 	/** Sets the active state. Affects border and background appearance on next render(). */
 	public setActive(active: boolean): void {
+		if (this.active === active) return;
 		this.active = active;
+		this.markDirty();
 	}
 
 	/** Sets the focused state. Controls use this to change visual appearance on focus.
@@ -269,6 +372,7 @@ export class Window {
 	public setFocused(focused: boolean): void {
 		if (this.focused === focused) return;
 		this.focused = focused;
+		this.markDirty();
 		if (focused) this.onFocusHandler?.();
 		else         this.onBlurHandler?.();
 	}
@@ -307,7 +411,13 @@ export class Window {
 	 *  change. Does not affect layout (flex/absolute coordinates are
 	 *  independent of z). */
 	public setZIndex(zIndex: number): void {
+		if (this.zIndex === zIndex) return;
 		this.zIndex = zIndex;
+		// Re-stacking can expose or occlude any cell inside the parent's
+		// bounds — escalate to a full repaint so the neighbour(s) underneath
+		// get re-emitted along with this window.
+		this.markFullInvalidation();
+		this.markDirty();
 	}
 
 	/** Returns the direct children of this window in insertion order (a
@@ -324,6 +434,7 @@ export class Window {
 
 	/** Sets the disabled state and deactivates the window when disabled. */
 	public setDisabled(disabled: boolean): void {
+		if (this.disabled !== disabled) this.markDirty();
 		this.disabled = disabled;
 		this.setActive(!disabled);
 	}
@@ -339,7 +450,14 @@ export class Window {
 	 *  the content buffer — previously written cells reappear verbatim on the
 	 *  next render after the window is shown again. */
 	public setVisible(visible: boolean): void {
+		if (this.visible === visible) return;
 		this.visible = visible;
+		// Showing / hiding a window changes what the root Screen emits in this
+		// window's old bounds (the parent below may need to repaint, or the
+		// new reveal needs its first emit). Full invalidation is the
+		// conservative, always-correct choice.
+		this.markFullInvalidation();
+		this.markDirty();
 	}
 
 	/** Returns whether this window is currently visible. Default: true. */
@@ -349,7 +467,9 @@ export class Window {
 
 	/** Sets the label text displayed by the control. */
 	public setLabel(label: string): void {
+		if (this.label === label) return;
 		this.label = label;
+		this.markDirty();
 	}
 
 	/** Returns the current label text. */
@@ -361,6 +481,7 @@ export class Window {
 	 *  Intended for use by subclasses that need dynamic decoration (e.g. focus-state colour). */
 	protected updateBorder(border: WindowBorder | boolean | undefined): void {
 		this.border = resolveBorder(border);
+		this.markDirty();
 	}
 
 	/** Recomputes the border color from the current focused/disabled state.
@@ -383,7 +504,13 @@ export class Window {
 	 *  geometry consistent when more children join the stack. */
 	public addChild(child: Window): void {
 		this.children.push(child);
+		child.parent = this;
 		this.runLayout();
+		// Newly attached subtrees may overlap existing cells, and their own
+		// `dirtyRect` already defaults to `'all'` — but the parent region that
+		// may be exposed by later removal needs a correct baseline on the root
+		// Screen side, so we bubble a full invalidation for the first frame.
+		this.markFullInvalidation();
 	}
 
 	/** Returns a resolved Cell (char + CellAttributes) at (x, y) from the display buffer.
@@ -404,12 +531,14 @@ export class Window {
 	public setChar(x: number, y: number, char: string): void {
 		this.content.setChar(x, y, char);
 		this.region.setChar(x, y, char);
+		this.markDirty({ x, y, w: 1, h: 1 });
 	}
 
 	/** Sets the character and style ID at (x, y). Throws RangeError if out of bounds. */
 	public setCell(x: number, y: number, char: string, styleId: StyleId = 0): void {
 		this.content.setCell(x, y, char, styleId);
 		this.region.setCell(x, y, char, styleId);
+		this.markDirty({ x, y, w: 1, h: 1 });
 	}
 
 	/** Merges the given style ID onto the existing style at (x, y) without changing the character.
@@ -419,18 +548,21 @@ export class Window {
 		const mergedRegion  = this.registry.merge(this.region.getStyleId(x, y),  styleId);
 		this.content.setStyleId(x, y, mergedContent);
 		this.region.setStyleId(x, y,  mergedRegion);
+		this.markDirty({ x, y, w: 1, h: 1 });
 	}
 
 	/** Resets every cell to a blank space with style ID 0. */
 	public clear(): void {
 		this.content.clear();
 		this.region.clear();
+		this.markDirty();
 	}
 
 	/** Fills every cell with the given character and style ID. */
 	public fill(char: string, styleId: StyleId = 0): void {
 		this.content.fill(char, styleId);
 		this.region.fill(char, styleId);
+		this.markDirty();
 	}
 
 	/** Writes text into the window's content area starting at (x, y) (default 0, 0).
@@ -565,21 +697,26 @@ export class Window {
 	 */
 	public render(): void {
 		if (!this.visible) return;
-		this.syncBorderColor();
-		this.paintBackground();
-		this.blitContent();
-		this.paintBorder();
-		for (const child of this.orderedByZ()) {
-			if (!child.visible) continue;
-			try {
-				child.render();
-				this.blitChild(child);
-			} catch (err) {
-				this.paintErrorPlaceholder(child, err);
-				const handler = getErrorHandler();
-				if (handler) handler(err, child);
-				else         throw err;
+		Window.renderingDepth++;
+		try {
+			this.syncBorderColor();
+			this.paintBackground();
+			this.blitContent();
+			this.paintBorder();
+			for (const child of this.orderedByZ()) {
+				if (!child.visible) continue;
+				try {
+					child.render();
+					this.blitChild(child);
+				} catch (err) {
+					this.paintErrorPlaceholder(child, err);
+					const handler = getErrorHandler();
+					if (handler) handler(err, child);
+					else         throw err;
+				}
 			}
+		} finally {
+			Window.renderingDepth--;
 		}
 	}
 
@@ -748,7 +885,13 @@ export class Window {
 	/** Removes a previously added child window. No-op if the child is not found. */
 	public removeChild(child: Window): void {
 		const idx = this.children.indexOf(child);
-		if (idx !== -1) this.children.splice(idx, 1);
+		if (idx !== -1) {
+			this.children.splice(idx, 1);
+			child.parent = null;
+			// The vacated rectangle has to be re-emitted from the content
+			// underneath — escalate so the root Screen repaints everything.
+			this.markFullInvalidation();
+		}
 	}
 
 	/** Replaces both internal regions with new ones of the given dimensions,
@@ -756,6 +899,12 @@ export class Window {
 	protected resizeRegions(w: number, h: number): void {
 		this.region  = new Region(w, h);
 		this.content = new Region(w, h);
+		// A new region invalidates any per-cell dirty bookkeeping from the
+		// previous size — escalate to a full-window repaint and ask the
+		// Screen to emit from scratch because the old footprint on stdout
+		// may include cells that are no longer part of this window.
+		this.dirtyRect = 'all';
+		this.markFullInvalidation();
 		this.reflowChildren();
 	}
 

package/src/Screen/WindowManager.mts

@@ -622,6 +622,10 @@ export class WindowManager {
 		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();
 		}
 	}
@@ -666,6 +670,13 @@ export class WindowManager {
 			// 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.

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);
 		}
 	}