take4-console 0.15.0 → 0.25.0

package/src/Screen/InterfaceBuilder.mts

@@ -5,16 +5,20 @@ import type {
   YamlWindowDef,
   YamlPosSpec,
   YamlSizeSpec,
+  YamlDimValue,
   YamlAxisValue,
   StyleId,
   Focusable,
   WindowProperties,
+  CustomTypeFactory,
+  CustomTypeContext,
 } from './types.mjs';
 import { Window } from './Window.mjs';
 import { Screen } from './Screen.mjs';
 import { WindowManager } from './WindowManager.mjs';
 import { Pos, Pct, pct } from './Pos.mjs';
-import { Size } from './Size.mjs';
+import { Size, flex, content } from './Size.mjs';
+import type { DimValue } from './Size.mjs';
 import { getRegistry } from './RegistryHolder.mjs';
 import { Button }       from './controls/Button.mjs';
 import { TextBox }      from './controls/TextBox.mjs';
@@ -33,6 +37,22 @@ import { Spinner }      from './controls/Spinner.mjs';
 
 // ── Internal helpers ──────────────────────────────────────────────────────────
 
+/** Reserved `type:` tags owned by the built-in widget switch — custom factories
+ *  cannot override these. */
+/** Structural check: returns true when the window opts into keyboard input by
+ *  exposing `handleKey` (on top of the focus helpers inherited from Window).
+ *  Used to auto-register custom-type controls with WindowManager. */
+function isFocusable(win: Window): win is Focusable & Window {
+  const w = win as Partial<Focusable>;
+  return typeof w.handleKey === 'function';
+}
+
+const BUILTIN_TYPE_NAMES = new Set<string>([
+  'window', 'button', 'textbox', 'textarea', 'checkbox', 'radio',
+  'statusled', 'progressbar', 'progressbarv', 'linechart', 'barchart',
+  'listbox', 'tabs', 'sparkline', 'spinner',
+]);
+
 /** A focusable control with its resolved parent chain, queued for WM registration. */
 interface PendingRegistration {
   control: Focusable & Window;
@@ -57,6 +77,7 @@ function parsePos(spec: YamlPosSpec | undefined): Pos {
   if (spec === 'topRight')    return Pos.topRight();
   if (spec === 'bottomLeft')  return Pos.bottomLeft();
   if (spec === 'bottomRight') return Pos.bottomRight();
+  if (spec === 'flex')        return Pos.flex();
   if (typeof spec === 'object') {
     if ('preset' in spec) {
       const off = spec.offset !== undefined ? parseAxisValue(spec.offset) : 0;
@@ -67,6 +88,9 @@ function parsePos(spec: YamlPosSpec | undefined): Pos {
         case 'bottom': return Pos.bottom(off);
       }
     }
+    if ('flex' in spec) {
+      return Pos.flex(spec.flex ?? 0);
+    }
     if ('x' in spec && 'y' in spec) {
       return new Pos(parseAxisValue(spec.x), parseAxisValue(spec.y));
     }
@@ -74,14 +98,36 @@ function parsePos(spec: YamlPosSpec | undefined): Pos {
   throw new Error(`Invalid pos spec: ${JSON.stringify(spec)}`);
 }
 
+/** Converts a single axis value within a Size spec — extends the plain-axis
+ *  parser with the 'flex' / 'content' shorthands and the `{ flex: {...} }` /
+ *  `{ content: true }` objects so each axis can be chosen independently. */
+function parseDimValue(v: YamlDimValue): DimValue {
+  if (v === 'flex')    return flex();
+  if (v === 'content') return content();
+  if (typeof v === 'object' && v !== null) {
+    if ('flex' in v) {
+      const basis = v.flex.basis !== undefined ? parseAxisValue(v.flex.basis) : 0;
+      return flex(v.flex.grow ?? 1, v.flex.shrink ?? 1, basis);
+    }
+    if ('content' in v && v.content === true) return content();
+  }
+  return parseAxisValue(v as YamlAxisValue);
+}
+
 /** Converts a YamlSizeSpec to a Size instance. */
 function parseSize(spec: YamlSizeSpec): Size {
-  if (spec === 'fill') return Size.fill();
+  if (spec === 'fill')    return Size.fill();
+  if (spec === 'flex')    return Size.flex();
+  if (spec === 'content') return Size.content();
   if (typeof spec === 'object') {
     if ('fillWidth'  in spec) return Size.fillWidth(parseAxisValue(spec.fillWidth));
     if ('fillHeight' in spec) return Size.fillHeight(parseAxisValue(spec.fillHeight));
+    if ('flex' in spec) {
+      const basis = spec.flex.basis !== undefined ? parseAxisValue(spec.flex.basis) : 0;
+      return Size.flex(spec.flex.grow ?? 1, spec.flex.shrink ?? 1, basis);
+    }
     if ('width' in spec && 'height' in spec) {
-      return new Size(parseAxisValue(spec.width), parseAxisValue(spec.height));
+      return new Size(parseDimValue(spec.width), parseDimValue(spec.height));
     }
   }
   throw new Error(`Invalid size spec: ${JSON.stringify(spec)}`);
@@ -102,9 +148,11 @@ function resolveBackground(bg: string | number | undefined): StyleId | undefined
  *
  * Usage:
  *   1. Create an InterfaceBuilder and call registerCallback() for any onPress/onChange IDs.
- *   2. Call build(yamlText, screen) or buildFromFile(path, screen).
- *   3. Optionally pass a WindowManager to automatically register all focusable controls.
- *   4. The returned Map<string, Window> gives access to windows by their YAML id.
+ *   2. Optionally call registerType(name, factory) to teach the builder about
+ *      user-defined controls addressable via `type: <name>` in YAML.
+ *   3. Call build(yamlText, screen) or buildFromFile(path, screen).
+ *   4. Optionally pass a WindowManager to automatically register all focusable controls.
+ *   5. The returned Map<string, Window> gives access to windows by their YAML id.
  *
  * YAML schema:
  *   windows:
@@ -118,11 +166,13 @@ function resolveBackground(bg: string | number | undefined): StyleId | undefined
  *         - ...
  */
 export class InterfaceBuilder {
-  private callbacks: Map<string, (...args: unknown[]) => void>;
+  private callbacks:   Map<string, (...args: unknown[]) => void>;
+  private customTypes: Map<string, CustomTypeFactory>;
 
-  /** Creates an InterfaceBuilder with an empty callback registry. */
+  /** Creates an InterfaceBuilder with empty callback and custom-type registries. */
   public constructor() {
-    this.callbacks = new Map();
+    this.callbacks   = new Map();
+    this.customTypes = new Map();
   }
 
   /** Registers a named callback for use with onPress or onChange in YAML definitions. */
@@ -130,6 +180,19 @@ export class InterfaceBuilder {
     this.callbacks.set(id, fn);
   }
 
+  /** Registers a custom control factory addressable by `type: <name>` in YAML.
+   *  The factory receives the raw YAML node plus a context with pre-resolved
+   *  `wp` (WindowProperties), the style registry, and a callback resolver.
+   *  Custom names cannot override a built-in type tag. If the returned window
+   *  implements Focusable, it is auto-registered with WindowManager (when one
+   *  is supplied to `build()`). */
+  public registerType(name: string, factory: CustomTypeFactory): void {
+    if (BUILTIN_TYPE_NAMES.has(name)) {
+      throw new Error(`Cannot register custom type "${name}": name is reserved by a built-in type.`);
+    }
+    this.customTypes.set(name, factory);
+  }
+
   /** Builds the UI from a YAML string, adds all top-level windows to Screen,
    *  and registers focusable controls with WindowManager if provided.
    *  Styles defined in the `styles:` section are registered before any windows are built.
@@ -193,13 +256,19 @@ export class InterfaceBuilder {
     /** Common window properties shared by all control types. */
     const wp: WindowProperties = {
       pos,
-      size:       def.size ? parseSize(def.size) : undefined,
-      background: bgId,
-      border:     def.border,
-      active:     def.active,
-      focused:    def.focused,
-      disabled:   def.disabled,
-      label:      def.label,
+      size:           def.size ? parseSize(def.size) : undefined,
+      background:     bgId,
+      border:         def.border,
+      active:         def.active,
+      focused:        def.focused,
+      disabled:       def.disabled,
+      label:          def.label,
+      layout:         def.layout,
+      gap:            def.gap,
+      padding:        def.padding,
+      gridColumns:    def.gridColumns,
+      alignItems:     def.alignItems,
+      justifyContent: def.justifyContent,
     };
 
     let win: Window;
@@ -218,9 +287,15 @@ export class InterfaceBuilder {
 
       case 'textbox': {
         wp.size = wp.size ?? this.requireSize(def);
+        const tbChange    = def.onChange  ? this.callbacks.get(def.onChange)  : undefined;
+        const tbSubmit    = def.onSubmit  ? this.callbacks.get(def.onSubmit)  : undefined;
+        const tbKeyDown   = def.onKeyDown ? this.callbacks.get(def.onKeyDown) : undefined;
         const tb = new TextBox(wp, {
           value:       def.value,
           placeholder: def.placeholder,
+          onChange:    tbChange  as ((value: string) => void)                 | undefined,
+          onSubmit:    tbSubmit  as ((value: string) => void)                 | undefined,
+          onKeyDown:   tbKeyDown as ((key: string) => boolean | void)         | undefined,
         });
         pending.push({ control: tb, parents: [...parentChain] });
         win = tb;
@@ -229,9 +304,17 @@ export class InterfaceBuilder {
 
       case 'textarea': {
         wp.size = wp.size ?? this.requireSize(def);
+        const taChange    = def.onChange  ? this.callbacks.get(def.onChange)  : undefined;
+        const taSubmit    = def.onSubmit  ? this.callbacks.get(def.onSubmit)  : undefined;
+        const taKeyDown   = def.onKeyDown ? this.callbacks.get(def.onKeyDown) : undefined;
         const ta = new TextArea(wp, {
-          value:       def.value,
-          placeholder: def.placeholder,
+          value:               def.value,
+          placeholder:         def.placeholder,
+          onChange:            taChange  as ((value: string) => void)         | undefined,
+          onSubmit:            taSubmit  as ((value: string) => void)         | undefined,
+          onKeyDown:           taKeyDown as ((key: string) => boolean | void) | undefined,
+          insertTabAsSpaces:   def.insertTabAsSpaces,
+          ctrlDDeletesForward: def.ctrlDDeletesForward,
         });
         pending.push({ control: ta, parents: [...parentChain] });
         win = ta;
@@ -368,8 +451,21 @@ export class InterfaceBuilder {
       }
 
       default: {
-        wp.size = wp.size ?? this.requireSize(def);
-        win = new Window(wp);
+        const customFactory = def.type ? this.customTypes.get(def.type) : undefined;
+        if (customFactory) {
+          const ctx: CustomTypeContext = {
+            wp,
+            registry:        getRegistry(),
+            resolveCallback: (id) => (id ? this.callbacks.get(id) : undefined),
+          };
+          win = customFactory(def, ctx);
+          if (isFocusable(win)) {
+            pending.push({ control: win as Focusable & Window, parents: [...parentChain] });
+          }
+        } else {
+          wp.size = wp.size ?? this.requireSize(def);
+          win = new Window(wp);
+        }
         break;
       }
     }

package/src/Screen/Pos.mts

@@ -17,13 +17,17 @@ function toAxisSpec(v: number | Pct): AxisSpec {
 	return { mode: 'start', value: v };
 }
 
-/** Resolves a single axis spec to a pixel offset. */
+/** Resolves a single axis spec to a pixel offset. The 'flex' mode has no
+ *  meaningful absolute resolution — the parent's layout engine overwrites
+ *  child.x / child.y before blit, so this returns 0 as a safe fallback that
+ *  keeps the value inside the region until the layout pass fires. */
 function resolveAxis(spec: AxisSpec, parentSize: number, ownSize: number): number {
 	switch (spec.mode) {
 		case 'start':  return spec.value;
 		case 'end':    return parentSize - ownSize - spec.value;
 		case 'pct':    return Math.floor(parentSize * spec.value / 100);
 		case 'center': return Math.floor((parentSize - ownSize) / 2);
+		case 'flex':   return 0;
 	}
 }
 
@@ -95,6 +99,25 @@ export class Pos {
 		return Pos.fromSpecs(toAxisSpec(x), { mode: 'end', value: 0 });
 	}
 
+	/** Marks the window as a flex-layout slot on both axes — the parent's layout
+	 *  engine (row / column / grid) decides the final position. The optional
+	 *  `order` controls the relative placement within the flex stack: children
+	 *  with a lower `order` appear earlier, ties broken by addChild insertion.
+	 *  Children without `Pos.flex()` in a flex parent are treated as order 0
+	 *  and fall back to insertion order, so authors can mix ordered and
+	 *  unordered children freely. Default `order`: 0. */
+	public static flex(order: number = 0): Pos {
+		return Pos.fromSpecs({ mode: 'flex', order }, { mode: 'flex', order });
+	}
+
+	/** Returns the flex order when this Pos was produced via `Pos.flex(order)`,
+	 *  or `undefined` for every other position mode. Used by the layout engine
+	 *  to sort children. */
+	public getFlexOrder(): number | undefined {
+		if (this.xSpec.mode === 'flex') return (this.xSpec as { mode: 'flex'; order: number }).order;
+		return undefined;
+	}
+
 	/** Returns true when both axes are absolute-from-start values (no parent/own-size needed). */
 	public isAbsolute(): boolean {
 		return this.xSpec.mode === 'start' && this.ySpec.mode === 'start';

package/src/Screen/Screen.mts

@@ -1,20 +1,61 @@
-import type { CellAttributes, StyleId } from './types.mjs';
+import { EventEmitter } from 'node:events';
+import type { CellAttributes, ScreenFrameStats, ScreenOptions, StyleId, TerminalSize } from './types.mjs';
 import { StyleRegistry } from './StyleRegistry.mjs';
 import { getRegistry, setRegistry } from './RegistryHolder.mjs';
 import { Window } from './Window.mjs';
 import { Pos } from './Pos.mjs';
 import { Size } from './Size.mjs';
 
+/** ANSI control sequences for the terminal lifecycle features owned by Screen. */
+const ENTER_ALT_SCREEN = '\x1b[?1049h';
+const EXIT_ALT_SCREEN  = '\x1b[?1049l';
+const HIDE_CURSOR      = '\x1b[?25l';
+const SHOW_CURSOR      = '\x1b[?25h';
+
 export class Screen extends Window {
+	/** Internal event bus for 'resize' and 'frame' notifications. Composed
+	 *  rather than inherited so the Window class hierarchy stays plain. */
+	private events: EventEmitter;
+	/** True while the alternate screen buffer is currently active. */
+	private altScreenActive: boolean;
+	/** True while the hardware cursor is currently hidden. */
+	private cursorHidden: boolean;
+	/** Soft FPS cap stored for inspection by consumers; full enforcement is P2-47. */
+	private targetFps: number | undefined;
+	/** Bound SIGWINCH listener (kept so we can detach it on dispose()). */
+	private boundSigwinch: () => void;
+	/** Bound 'exit' listener that runs synchronous terminal cleanup. */
+	private boundExit: () => void;
+	/** Whether the SIGWINCH + 'exit' listeners are currently attached. */
+	private signalsInstalled: boolean;
+	/** Whether dispose() has already restored terminal state. */
+	private disposed: boolean;
+
 	/** Initializes the root window sized to the current terminal dimensions.
 	 *  Creates a fresh StyleRegistry (with built-in styles pre-registered)
-	 *  and installs it as the global singleton. */
-	public constructor() {
+	 *  and installs it as the global singleton. The optional ScreenOptions
+	 *  control whether the alternate screen buffer is entered and the cursor
+	 *  hidden up-front; both are off by default so existing code that relies
+	 *  on WindowManager.run/stop for those toggles keeps working unchanged. */
+	public constructor(options?: ScreenOptions) {
 		const width    = process.stdout.columns ?? 80;
 		const height   = process.stdout.rows    ?? 24;
 		const registry = new StyleRegistry();
 		setRegistry(registry);
 		super({ pos: Pos.topLeft(), size: new Size(width, height), background: 0 });
+
+		this.events           = new EventEmitter();
+		this.altScreenActive  = false;
+		this.cursorHidden     = false;
+		this.targetFps        = options?.targetFps;
+		this.boundSigwinch    = (): void => { this.handleSigwinch(); };
+		this.boundExit        = (): void => { this.restoreTerminalState(); };
+		this.signalsInstalled = false;
+		this.disposed         = false;
+
+		if (options?.altScreen)  this.enterAltScreen();
+		if (options?.hideCursor) this.hideHardwareCursor();
+		this.installSignalHandlers();
 	}
 
 	/** Registers a CellAttributes object in the global style registry and returns its stable ID. */
@@ -33,10 +74,107 @@ export class Screen extends Window {
 		return getRegistry().registerNamed(name, attrs);
 	}
 
+	/** Returns the soft FPS cap configured via ScreenOptions, or undefined when uncapped. */
+	public getTargetFps(): number | undefined {
+		return this.targetFps;
+	}
+
+	// ── Terminal lifecycle helpers ────────────────────────────────────────────
+
+	/** Switches the terminal into the alternate screen buffer. Idempotent. */
+	public enterAltScreen(): void {
+		if (this.altScreenActive) return;
+		process.stdout.write(ENTER_ALT_SCREEN);
+		this.altScreenActive = true;
+	}
+
+	/** Restores the primary screen buffer if Screen previously entered the
+	 *  alternate one. Idempotent. */
+	public exitAltScreen(): void {
+		if (!this.altScreenActive) return;
+		process.stdout.write(EXIT_ALT_SCREEN);
+		this.altScreenActive = false;
+	}
+
+	/** Returns true while the alternate screen buffer is active. WindowManager
+	 *  uses this to avoid double-toggling when the consumer constructed the
+	 *  Screen with `altScreen: true`. */
+	public isAltScreenActive(): boolean {
+		return this.altScreenActive;
+	}
+
+	/** Hides the hardware cursor. Idempotent. */
+	public hideHardwareCursor(): void {
+		if (this.cursorHidden) return;
+		process.stdout.write(HIDE_CURSOR);
+		this.cursorHidden = true;
+	}
+
+	/** Restores the hardware cursor if Screen previously hid it. Idempotent. */
+	public showHardwareCursor(): void {
+		if (!this.cursorHidden) return;
+		process.stdout.write(SHOW_CURSOR);
+		this.cursorHidden = false;
+	}
+
+	/** Returns true while the hardware cursor is hidden by this Screen. */
+	public isCursorHidden(): boolean {
+		return this.cursorHidden;
+	}
+
+	/** Restores any terminal state that was modified by ScreenOptions /
+	 *  enter/hide helpers and detaches signal listeners. Idempotent — safe to
+	 *  call from both deliberate teardown and a process 'exit' handler. */
+	public dispose(): void {
+		if (this.disposed) return;
+		this.restoreTerminalState();
+		this.uninstallSignalHandlers();
+		this.disposed = true;
+	}
+
+	// ── Resize handling ───────────────────────────────────────────────────────
+
+	/** Recomputes the Screen dimensions from the live `process.stdout` size
+	 *  (or from the explicit overrides), reallocates the internal buffers,
+	 *  reflows all percentage-sized children, and emits a 'resize' event.
+	 *  Called automatically on SIGWINCH; also exposed for tests and consumers
+	 *  that drive resize manually (e.g. when running outside a TTY). */
+	public resize(width?: number, height?: number): TerminalSize {
+		const w = width  ?? process.stdout.columns ?? 80;
+		const h = height ?? process.stdout.rows    ?? 24;
+		this.setSize(w, h);
+		const size: TerminalSize = { width: w, height: h };
+		this.events.emit('resize', size);
+		return size;
+	}
+
+	// ── EventEmitter delegation ───────────────────────────────────────────────
+
+	/** Subscribes to a Screen lifecycle event.
+	 *  - 'resize' fires after SIGWINCH (or manual resize()) once the buffers
+	 *    have been re-allocated; the listener receives the new TerminalSize.
+	 *  - 'frame'  fires at the end of every render() with timing stats. */
+	public on(event: 'resize', listener: (size: TerminalSize) => void): this;
+	public on(event: 'frame',  listener: (stats: ScreenFrameStats) => void): this;
+	public on(event: string, listener: (...args: never[]) => void): this {
+		this.events.on(event, listener as (...args: unknown[]) => void);
+		return this;
+	}
+
+	/** Removes a previously registered listener. */
+	public off(event: 'resize', listener: (size: TerminalSize) => void): this;
+	public off(event: 'frame',  listener: (stats: ScreenFrameStats) => void): this;
+	public off(event: string, listener: (...args: never[]) => void): this {
+		this.events.off(event, listener as (...args: unknown[]) => void);
+		return this;
+	}
+
 	/**
 	 * Composites the full window tree, then writes the result to stdout as a single ANSI string.
+	 * Emits a 'frame' event with the wall-clock duration of the render after stdout has been written.
 	 */
 	public override render(): void {
+		const start = Date.now();
 		super.render();
 
 		const reg      = getRegistry();
@@ -44,11 +182,61 @@ export class Screen extends Window {
 		const styleIds = this.region.getStyleIds();
 		let output = '\x1b[H';
 		for (let i = 0; i < chars.length; i++) {
+			const ch = chars[i];
+			// Empty-string sentinel = continuation cell of a wide character;
+			// terminal cursor was already advanced by 2 when its left half was emitted.
+			if (ch === '') continue;
 			output += this.buildAnsiSequence(reg.get(styleIds[i]));
-			output += chars[i];
+			output += ch;
 		}
 		output += '\x1b[0m';
 		process.stdout.write(output);
+		this.events.emit('frame', { ms: Date.now() - start });
+	}
+
+	// ── Private helpers ───────────────────────────────────────────────────────
+
+	/** Synchronous teardown of any terminal state we own. Used by both dispose()
+	 *  and the 'exit' listener, where async work would be discarded. */
+	private restoreTerminalState(): void {
+		// Cursor first so it reappears in the primary buffer rather than blink
+		// on the (about-to-be-restored) alt buffer for one frame.
+		this.showHardwareCursor();
+		this.exitAltScreen();
+	}
+
+	/** Number of distinct process listeners each Screen installs (SIGWINCH + exit).
+	 *  Used to bump process.setMaxListeners() proportionally so test suites that
+	 *  spin up many Screens don't trip Node's default leak warning. */
+	private static readonly LISTENERS_PER_INSTANCE = 2;
+	/** Live count of Screens that have installed signal listeners but not yet
+	 *  disposed. Drives the dynamic process listener cap. */
+	private static liveInstances = 0;
+
+	/** Attaches the SIGWINCH listener (for autoresize) and an 'exit' listener
+	 *  (for last-chance terminal cleanup). Idempotent. */
+	private installSignalHandlers(): void {
+		if (this.signalsInstalled) return;
+		Screen.liveInstances++;
+		const wanted = 10 + Screen.liveInstances * Screen.LISTENERS_PER_INSTANCE;
+		if (process.getMaxListeners() < wanted) process.setMaxListeners(wanted);
+		process.on('SIGWINCH', this.boundSigwinch);
+		process.on('exit',     this.boundExit);
+		this.signalsInstalled = true;
+	}
+
+	/** Detaches the listeners installed by installSignalHandlers(). Idempotent. */
+	private uninstallSignalHandlers(): void {
+		if (!this.signalsInstalled) return;
+		process.off('SIGWINCH', this.boundSigwinch);
+		process.off('exit',     this.boundExit);
+		Screen.liveInstances = Math.max(0, Screen.liveInstances - 1);
+		this.signalsInstalled = false;
+	}
+
+	/** SIGWINCH handler: pulls the new size from process.stdout and triggers a resize. */
+	private handleSigwinch(): void {
+		this.resize();
 	}
 
 	/** Converts cell attributes into an ANSI escape sequence (always resets first). */

package/src/Screen/Size.mts

@@ -1,26 +1,85 @@
-import type { DimSpec } from './types.mjs';
+import type { DimSpec, FlexBasis } from './types.mjs';
 import { Pct } from './Pos.mjs';
 
+/** Value object describing a flex dimension — `grow` shares positive leftover
+ *  space between siblings, `shrink` soaks up negative leftover, `basis` is the
+ *  starting main-axis size before distribution. Produced via the `flex()`
+ *  factory and accepted anywhere a `Size` constructor expects a dimension. */
+export class FlexDim {
+	public readonly grow:   number;
+	public readonly shrink: number;
+	public readonly basis:  number | Pct;
+
+	public constructor(grow: number = 1, shrink: number = 1, basis: number | Pct = 0) {
+		this.grow   = grow;
+		this.shrink = shrink;
+		this.basis  = basis;
+	}
+}
+
+/** Singleton marker for content-sized dimensions. Produced via the `content()`
+ *  factory; the layout engine measures the child's natural size (current
+ *  Region dimensions) at layout time. */
+export class ContentDim {
+	public static readonly INSTANCE: ContentDim = new ContentDim();
+	private constructor() {}
+}
+
+/** Factory for a flex dimension — shorthand for `new FlexDim(grow, shrink, basis)`. */
+export function flex(grow: number = 1, shrink: number = 1, basis: number | Pct = 0): FlexDim {
+	return new FlexDim(grow, shrink, basis);
+}
+
+/** Factory for a content-sized dimension. Always returns the singleton. */
+export function content(): ContentDim {
+	return ContentDim.INSTANCE;
+}
+
+/** Accepted user-supplied values for a single Size dimension. */
+export type DimValue = number | Pct | FlexDim | ContentDim;
+
+/** Converts a basis literal to the internal FlexBasis representation. */
+function toFlexBasis(v: number | Pct): FlexBasis {
+	if (v instanceof Pct) return { kind: 'pct', value: v.value };
+	return { kind: 'abs', value: v };
+}
+
 /** Converts a user-supplied dimension value to an internal DimSpec. */
-function toDimSpec(v: number | Pct): DimSpec {
-	if (v instanceof Pct) return { mode: 'pct', value: v.value };
+function toDimSpec(v: DimValue): DimSpec {
+	if (v instanceof Pct)        return { mode: 'pct', value: v.value };
+	if (v instanceof FlexDim)    return { mode: 'flex', grow: v.grow, shrink: v.shrink, basis: toFlexBasis(v.basis) };
+	if (v instanceof ContentDim) return { mode: 'content' };
 	return { mode: 'abs', value: v };
 }
 
-/** Resolves a single dimension spec to a pixel value. */
+/** Resolves a single dimension spec to a pixel value. For modes whose final
+ *  size is determined by the parent's layout engine (`flex`, `content`) this
+ *  returns a safe fallback that keeps the region non-empty until the layout
+ *  pass overwrites it — `flex` falls back to its basis, `content` to 1. */
 function resolveDim(spec: DimSpec, parentSize: number): number {
-	if (spec.mode === 'pct') return Math.floor(parentSize * spec.value / 100);
-	return spec.value;
+	switch (spec.mode) {
+		case 'abs':     return spec.value;
+		case 'pct':     return Math.floor(parentSize * spec.value / 100);
+		case 'flex':    return spec.basis.kind === 'pct'
+			? Math.floor(parentSize * spec.basis.value / 100)
+			: spec.basis.value;
+		case 'content': return 1;
+	}
 }
 
-/** Encodes window dimensions. Supports absolute pixel values and percentage of parent size. */
+/** Encodes window dimensions. Supports absolute pixel values, percentages of
+ *  the parent, flex slots (`flex(grow, shrink, basis)`), and content-sized
+ *  dimensions (`content()`). Flex and content modes only take effect inside a
+ *  flex-layout parent (`WindowProperties.layout` set to 'row', 'column', or
+ *  'grid'); in 'absolute' layout they degrade to the fallback resolution. */
 export class Size {
 	private wSpec: DimSpec;
 	private hSpec: DimSpec;
 
 	/** Creates a size from width and height values.
-	 *  Pass a plain number for absolute pixels, or a Pct instance for a percentage of the parent. */
-	public constructor(w: number | Pct, h: number | Pct) {
+	 *  Accepts plain numbers (absolute pixels), `Pct` (percentage of parent),
+	 *  `FlexDim` (via `flex()` factory), or `ContentDim` (via `content()`). */
+	public constructor(w: DimValue, h: DimValue) {
 		this.wSpec = toDimSpec(w);
 		this.hSpec = toDimSpec(h);
 	}
@@ -31,25 +90,51 @@ export class Size {
 	}
 
 	/** Creates a size that fills 100% of the parent's width; height is absolute or percentage. */
-	public static fillWidth(h: number | Pct): Size {
+	public static fillWidth(h: DimValue): Size {
 		return new Size(new Pct(100), h);
 	}
 
 	/** Creates a size that fills 100% of the parent's height; width is absolute or percentage. */
-	public static fillHeight(w: number | Pct): Size {
+	public static fillHeight(w: DimValue): Size {
 		return new Size(w, new Pct(100));
 	}
 
+	/** Creates a size that flexes on both axes — shorthand for
+	 *  `new Size(flex(grow, shrink, basis), flex(grow, shrink, basis))`. The
+	 *  parent's layout engine decides which axis is main vs cross. */
+	public static flex(grow: number = 1, shrink: number = 1, basis: number | Pct = 0): Size {
+		return new Size(flex(grow, shrink, basis), flex(grow, shrink, basis));
+	}
+
+	/** Creates a size where both axes are content-sized. The layout engine
+	 *  measures the child's current Region dimensions and uses those. */
+	public static content(): Size {
+		return new Size(content(), content());
+	}
+
 	/** Returns true when both dimensions are absolute pixel values (no parent size needed). */
 	public isAbsolute(): boolean {
 		return this.wSpec.mode === 'abs' && this.hSpec.mode === 'abs';
 	}
 
-	/** Resolves this size to pixel dimensions given the parent's dimensions. */
+	/** Resolves this size to pixel dimensions given the parent's dimensions.
+	 *  Flex/content modes fall back to safe defaults; the layout engine takes
+	 *  over when the parent uses a non-'absolute' `layout`. */
 	public resolve(parentW: number, parentH: number): { w: number; h: number } {
 		return {
 			w: resolveDim(this.wSpec, parentW),
 			h: resolveDim(this.hSpec, parentH),
 		};
 	}
+
+	/** Returns the raw width spec so the layout engine can inspect the mode
+	 *  (abs/pct/flex/content) and route each child accordingly. */
+	public getWidthSpec(): DimSpec {
+		return this.wSpec;
+	}
+
+	/** Returns the raw height spec — companion to getWidthSpec(). */
+	public getHeightSpec(): DimSpec {
+		return this.hSpec;
+	}
 }