take4-console 0.25.0 → 0.31.0

package/src/Screen/Window.mts

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