take4-console 0.30.0 → 0.31.0

package/src/Screen/controls/Sparkline.mts

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

package/src/Screen/controls/Spinner.mts

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

package/src/Screen/controls/StatusLED.mts

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

package/src/Screen/controls/Tabs.mts

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

package/src/Screen/controls/TextArea.mts

@@ -82,6 +82,7 @@ export class TextArea extends Window {
 		this.cursor.x = Math.min(this.cursor.x, this.lines[this.cursor.y].length);
 		this.selectionAnchor = null;
 		this.clampScroll();
+		this.markDirty();
 	}
 
 	/** Returns the normalized selection range `{ start, end }` in 2-D
@@ -120,6 +121,7 @@ export class TextArea extends Window {
 		this.selectionAnchor = (a.x === c.x && a.y === c.y) ? null : a;
 		this.cursor = c;
 		this.clampScroll();
+		this.markDirty();
 	}
 
 	/** Selects every character in the buffer. No-op when the buffer holds a
@@ -134,11 +136,14 @@ export class TextArea extends Window {
 		this.selectionAnchor = { x: 0, y: 0 };
 		this.cursor = { x: lastX, y: lastY };
 		this.clampScroll();
+		this.markDirty();
 	}
 
 	/** Drops any active selection without moving the cursor. */
 	public clearSelection(): void {
+		if (this.selectionAnchor === null) return;
 		this.selectionAnchor = null;
+		this.markDirty();
 	}
 
 	/** Clamps a 2-D position so both components land inside the buffer. */
@@ -182,6 +187,7 @@ export class TextArea extends Window {
 		this.cursor.x = Math.max(0, Math.min(pos.x, this.lines[this.cursor.y].length));
 		this.selectionAnchor = null;
 		this.clampScroll();
+		this.markDirty();
 	}
 
 	/** Returns a copy of the current cursor position. */
@@ -363,6 +369,10 @@ export class TextArea extends Window {
 	private finishKey(before: string): void {
 		this.clampScroll();
 		this.virtualCursor.resetPhase();
+		// Every key dispatch may have moved the cursor, changed the
+		// selection, or edited the buffer — flag the window dirty so the
+		// next Screen.render() re-emits the composed state.
+		this.markDirty();
 		if (this.getValue() !== before) this.onChange?.(this.getValue());
 	}
 

package/src/Screen/controls/TextBox.mts

@@ -75,6 +75,7 @@ export class TextBox extends Window {
 		this.cursor = Math.min(this.cursor, value.length);
 		this.selectionAnchor = null;
 		this.clampScroll();
+		this.markDirty();
 	}
 
 	/** Returns the normalized selection range `{ start, end }` (half-open)
@@ -103,6 +104,7 @@ export class TextBox extends Window {
 		this.selectionAnchor = a === c ? null : a;
 		this.cursor = c;
 		this.clampScroll();
+		this.markDirty();
 	}
 
 	/** Selects every character in the current value. No-op when the value is empty. */
@@ -114,11 +116,14 @@ export class TextBox extends Window {
 		this.selectionAnchor = 0;
 		this.cursor = this.value.length;
 		this.clampScroll();
+		this.markDirty();
 	}
 
 	/** Drops any active selection without moving the cursor. */
 	public clearSelection(): void {
+		if (this.selectionAnchor === null) return;
 		this.selectionAnchor = null;
+		this.markDirty();
 	}
 
 	/** Replaces the onChange callback (passing undefined clears it). */
@@ -148,6 +153,7 @@ export class TextBox extends Window {
 		this.cursor = Math.max(0, Math.min(pos, this.value.length));
 		this.selectionAnchor = null;
 		this.clampScroll();
+		this.markDirty();
 	}
 
 	/** Returns the current cursor character index. */
@@ -256,6 +262,12 @@ export class TextBox extends Window {
 	private finishKey(before: string): void {
 		this.clampScroll();
 		this.virtualCursor.resetPhase();
+		// Every key dispatch is a potential content / selection / cursor
+		// change — flag the window dirty unconditionally so the next
+		// Screen.render() re-emits it. The per-key equality checks in
+		// individual branches are not worth the code; the bounding box is
+		// cheap and we're going to emit at most the whole window.
+		this.markDirty();
 		if (this.value !== before) this.onChange?.(this.value);
 	}
 

package/src/Screen/types.mts

@@ -110,12 +110,39 @@ export interface ScreenOptions {
    *  for inspection; full enforcement (frame coalescing) lands with backlog
    *  item P2-47. Default: undefined (uncapped). */
   targetFps?: number;
+  /** Enables damage-region tracking: `Screen.render()` collects dirty rects
+   *  propagated bottom-up from each mutated window and emits ANSI sequences
+   *  only for the changed cells. A frame with no dirty rects is skipped
+   *  entirely (no stdout traffic). The first frame and every frame after
+   *  `resize()` / `invalidate()` fall back to a full repaint. Default:
+   *  `true`. Set to `false` for the pre-0.31 behaviour (always emit the
+   *  full buffer), useful for debugging or terminals that mis-handle
+   *  partial cursor jumps. */
+  damageTracking?: boolean;
 }
 
 /** Statistics emitted by the Screen 'frame' event after each render() call. */
 export interface ScreenFrameStats {
   /** Wall-clock duration of the render() call in milliseconds. */
   ms: number;
+  /** Number of cells emitted to stdout during this frame (0 when the frame
+   *  was skipped because nothing was dirty). Populated only when damage
+   *  tracking is enabled; undefined otherwise. */
+  cellsEmitted?: number;
+  /** True when the emit path was a full-screen repaint (first frame,
+   *  post-resize, or damage tracking disabled); false when only dirty runs
+   *  were emitted. Undefined when the frame was skipped entirely. */
+  fullRepaint?: boolean;
+}
+
+/** Rectangle expressed in the owning Window's local coordinate space (for
+ *  dirty regions on a Window) or in Screen coordinates (when collected by
+ *  `Screen.render()` during damage tracking). */
+export interface DirtyRect {
+  x: number;
+  y: number;
+  w: number;
+  h: number;
 }
 
 /** Box-drawing character style for window borders.

package/src/demo.mts

@@ -15,6 +15,8 @@ import { ListBox }      from './Screen/controls/ListBox.mjs';
 import { Tabs }         from './Screen/controls/Tabs.mjs';
 import { TextBox }      from './Screen/controls/TextBox.mjs';
 import { Window } from './Screen/Window.mjs';
+import { Pos } from './Screen/Pos.mjs';
+import { Size } from './Screen/Size.mjs';
 import type { ListBoxRowSegments, WindowProperties, StyleId } from './Screen/types.mjs';
 
 /** Custom Window subclass registered with InterfaceBuilder via
@@ -439,6 +441,22 @@ const main = async (): Promise<void> => {
 		return true;
 	});
 
+	// P2-59 demo: Ctrl+D toggles damage tracking at runtime and posts a
+	// sticky toast with the new state so the effect is visible. When
+	// tracking is on, the 'frame' event reports only the dirty cells each
+	// frame (watch the toast subtitle); when it's off, every frame is a
+	// full repaint as before.
+	wm.bindKey('ctrl+d', () => {
+		const next = !screen.isDamageTrackingEnabled();
+		screen.setDamageTracking(next);
+		screen.toast(
+			next ? ' Damage tracking ON — only dirty cells are emitted '
+			     : ' Damage tracking OFF — every frame is a full repaint ',
+			{ position: 'top-center', duration: 2500 },
+		);
+		return true;
+	});
+
 	// Virtual cursor: animated caret in TextBox/TextArea. The `tbEmail`
 	// TextBox opts into slow blink via layout.yaml; here we flip the
 	// `tbUsername` TextBox into the `irregular` mode so the two
@@ -457,6 +475,39 @@ const main = async (): Promise<void> => {
 	}
 	wm.enableCursorBlink(80);
 
+	// P2-59 showcase: five independent spinners with different styles,
+	// cadences, and positions, each driven by its own `setInterval`.
+	// With damage tracking ON, every tick emits only that spinner's 1–2
+	// cells (check the 'frame' event `cellsEmitted`); with tracking OFF
+	// (Ctrl+D) each tick repaints the whole screen. Placed along the
+	// bottom edge so they don't overlap existing widgets.
+	const spinnerStyles: Array<'braille' | 'dots' | 'line' | 'circle' | 'arrow'> =
+		['braille', 'dots', 'line', 'circle', 'arrow'];
+	const spinnerCadences = [120, 180, 240, 320, 420];
+	const spinnerTimers: NodeJS.Timeout[] = [];
+	const { width: screenW, height: screenH } = screen.getSize();
+	for (let i = 0; i < spinnerStyles.length; i++) {
+		const sp = new Spinner(
+			{ pos: new Pos(screenW - 12 - i * 3, screenH - 2), size: new Size(2, 1) },
+			{ style: spinnerStyles[i], color: 75 + i * 10 },
+		);
+		screen.addChild(sp);
+		const timer = setInterval(() => {
+			sp.step();
+			screen.render();
+		}, spinnerCadences[i]!);
+		if (typeof timer === 'object' && timer !== null && 'unref' in timer
+		    && typeof timer.unref === 'function') timer.unref();
+		spinnerTimers.push(timer);
+	}
+	// Ensure the spinner timers are torn down alongside the main demo
+	// timer when the user quits (the existing onExit handler already
+	// clears `demoTimer`, so extend it with ours).
+	const originalOnExit = () => {
+		for (const t of spinnerTimers) clearInterval(t);
+	};
+	process.once('exit', originalOnExit);
+
 	wm.run();
 };
 

package/src/index.mts

@@ -74,6 +74,7 @@ export type {
 	TerminalSize,
 	ScreenOptions,
 	ScreenFrameStats,
+	DirtyRect,
 	AxisSpec,
 	DimSpec,
 	FlexBasis,