@effect-tui/react 0.15.2 → 0.16.0

package/src/hooks/use-scroll.ts

@@ -2,7 +2,7 @@
 
 import type { KeyMsg } from "@effect-tui/core"
 import { useCallback, useLayoutEffect, useMemo, useReducer, useRef } from "react"
-import type { ScrollProps } from "../hosts/scroll.js"
+import type { ScrollAlign, ScrollAxis, ScrollLayoutChange, ScrollProps } from "../hosts/scroll.js"
 import { useTerminalSize } from "../renderer.js"
 import { useKeyboard } from "./use-keyboard.js"
 
@@ -86,21 +86,21 @@ class MacOSScrollAccel implements ScrollAcceleration {
 // ============================================================================
 
 export interface ScrollState {
-	/** Current scroll offset (pixels from start) for the primary axis */
-	offset: number
-	/** Maximum scroll offset for the primary axis */
-	maxOffset: number
-	/** Viewport size for the primary axis */
-	viewportSize: number
-	/** Whether viewport size has been measured by the host (primary axis) */
-	viewportMeasured: boolean
-	/** Total content size for the primary axis */
-	contentSize: number
-	/** Whether we're at the start edge (primary axis) */
-	atStart: boolean
-	/** Whether we're at the end edge (primary axis) */
-	atEnd: boolean
-	/** Current horizontal offset (pixels from start) */
+	/** Current vertical offset (pixels from top) */
+	offsetY: number
+	/** Maximum vertical offset */
+	maxOffsetY: number
+	/** Vertical viewport size */
+	viewportSizeY: number
+	/** Whether vertical viewport size has been measured by the host */
+	viewportMeasuredY: boolean
+	/** Total vertical content size */
+	contentSizeY: number
+	/** Whether we're at the top edge */
+	atStartY: boolean
+	/** Whether we're at the bottom edge */
+	atEndY: boolean
+	/** Current horizontal offset (pixels from left) */
 	offsetX: number
 	/** Maximum horizontal offset */
 	maxOffsetX: number
@@ -118,31 +118,25 @@ export interface ScrollState {
 
 export interface UseScrollOptions {
 	/** Scroll axis: "vertical" (default), "horizontal", or "both" */
-	axis?: "vertical" | "horizontal" | "both"
-	/** Controlled content size for the primary axis (skips host measurement when provided) */
-	contentSize?: number
+	axis?: ScrollAxis
 	/** Controlled content width (skips host measurement when provided) */
 	contentWidth?: number
 	/** Controlled content height (skips host measurement when provided) */
 	contentHeight?: number
-	/** @internal Initial viewport size override (useful for tests) */
-	initialViewportSize?: number
 	/** @internal Initial viewport width override (useful for tests) */
 	initialViewportWidth?: number
 	/** @internal Initial viewport height override (useful for tests) */
 	initialViewportHeight?: number
-	/** @internal Initial content size override (useful for tests) */
-	initialContentSize?: number
 	/** @internal Initial content width override (useful for tests) */
 	initialContentWidth?: number
 	/** @internal Initial content height override (useful for tests) */
 	initialContentHeight?: number
-	/** Initial scroll offset for the primary axis */
-	initialOffset?: number
+	/** Initial vertical scroll offset */
+	initialOffsetY?: number
 	/** Initial horizontal scroll offset */
 	initialOffsetX?: number
 	/** Alignment when content is smaller than viewport */
-	align?: "start" | "end"
+	align?: ScrollAlign
 	/** Whether to show scrollbars */
 	showScrollbar?: boolean
 	/** Enable keyboard navigation (default: true) */
@@ -157,23 +151,25 @@ export interface UseScrollOptions {
 	arrowSpeed?: number
 	/** Scroll speed for page up/down (fraction of viewport, default: 0.5) */
 	pageSpeed?: number
+	/** Optional layout callback (content/viewport/offset/rect). */
+	onScrollLayoutChange?: (event: ScrollLayoutChange) => void
 }
 
 export interface UseScrollReturn {
 	/** Current scroll state */
 	state: ScrollState
-	/** Set scroll offset directly (primary axis) */
-	setOffset: (offset: number) => void
+	/** Set vertical scroll offset directly */
+	setOffsetY: (offsetY: number) => void
 	/** Set horizontal scroll offset directly */
 	setOffsetX: (offsetX: number) => void
-	/** Scroll by delta pixels (primary axis) */
-	scrollBy: (delta: number) => void
+	/** Scroll by delta pixels vertically */
+	scrollByY: (delta: number) => void
 	/** Scroll by delta pixels horizontally */
 	scrollByX: (delta: number) => void
-	/** Scroll to start (primary axis) */
-	scrollToStart: () => void
-	/** Scroll to end (primary axis) */
-	scrollToEnd: () => void
+	/** Scroll to top */
+	scrollToStartY: () => void
+	/** Scroll to bottom */
+	scrollToEndY: () => void
 	/** Scroll to horizontal start */
 	scrollToStartX: () => void
 	/** Scroll to horizontal end */
@@ -187,7 +183,7 @@ export interface UseScrollReturn {
 	 * @param totalSize - Optional known total content size (avoids stale state issues)
 	 * @param axis - Axis to scroll (defaults to vertical)
 	 */
-	scrollToVisible: (
+	scrollIntoView: (
 		position: number,
 		itemSize?: number,
 		padding?: number,
@@ -287,18 +283,15 @@ const reduceScroll = (state: ScrollInternalState, action: ScrollAction): ScrollI
 export function useScroll(options: UseScrollOptions = {}): UseScrollReturn {
 	const {
 		axis = "vertical",
-		contentSize,
 		contentWidth,
 		contentHeight,
-		initialViewportSize,
 		initialViewportWidth,
 		initialViewportHeight,
-		initialContentSize,
 		initialContentWidth,
 		initialContentHeight,
-		initialOffset = 0,
+		initialOffsetY = 0,
 		initialOffsetX = 0,
-		align = "start",
+		align,
 		showScrollbar = true,
 		enableKeyboard = true,
 		enableMouseWheel = true,
@@ -306,31 +299,30 @@ export function useScroll(options: UseScrollOptions = {}): UseScrollReturn {
 		sticky = false,
 		arrowSpeed = 1,
 		pageSpeed = 0.5,
+		onScrollLayoutChange,
 	} = options
 
 	const { width: termWidth, height: termHeight } = useTerminalSize()
 	const enableY = axis === "vertical" || axis === "both"
 	const enableX = axis === "horizontal" || axis === "both"
-	const primaryAxis: "vertical" | "horizontal" = axis === "horizontal" ? "horizontal" : "vertical"
+	const useHorizontalPrimary = axis === "horizontal"
 
-	const controlledContentHeight = contentHeight ?? (axis !== "horizontal" ? contentSize : undefined)
-	const controlledContentWidth = contentWidth ?? (axis === "horizontal" ? contentSize : undefined)
+	const controlledContentHeight = contentHeight
+	const controlledContentWidth = contentWidth
 
-	const baseViewportHeight =
-		initialViewportHeight ?? (axis !== "horizontal" ? initialViewportSize : undefined) ?? termHeight
-	const baseViewportWidth =
-		initialViewportWidth ?? (axis === "horizontal" ? initialViewportSize : undefined) ?? termWidth
+	const baseViewportHeight = initialViewportHeight ?? termHeight
+	const baseViewportWidth = initialViewportWidth ?? termWidth
 
 	const baseContentHeight =
-		controlledContentHeight ?? initialContentHeight ?? (axis !== "horizontal" ? initialContentSize : undefined) ?? 0
+		controlledContentHeight ?? initialContentHeight ?? 0
 	const baseContentWidth =
-		controlledContentWidth ?? initialContentWidth ?? (axis === "horizontal" ? initialContentSize : undefined) ?? 0
+		controlledContentWidth ?? initialContentWidth ?? 0
 
-	const initialOffsetY = axis === "horizontal" ? 0 : initialOffset
-	const initialOffsetXResolved = axis === "horizontal" ? initialOffset : initialOffsetX
+	const initialOffsetYResolved = axis === "horizontal" ? 0 : initialOffsetY
+	const initialOffsetXResolved = axis === "vertical" ? 0 : initialOffsetX
 
 	const [internalY, dispatchY] = useReducer(reduceScroll, {
-		offset: clampOffset(initialOffsetY, baseContentHeight, baseViewportHeight),
+		offset: clampOffset(initialOffsetYResolved, baseContentHeight, baseViewportHeight),
 		contentSize: baseContentHeight,
 		viewportSize: baseViewportHeight,
 		viewportMeasured: false,
@@ -398,17 +390,6 @@ export function useScroll(options: UseScrollOptions = {}): UseScrollReturn {
 		[dispatchX, enableX],
 	)
 
-	const scrollBy = useCallback(
-		(delta: number) => {
-			if (primaryAxis === "horizontal") {
-				scrollByX(delta)
-			} else {
-				scrollByY(delta)
-			}
-		},
-		[primaryAxis, scrollByX, scrollByY],
-	)
-
 	const scrollToStartY = useCallback(() => {
 		dispatchY({ type: "set-offset", offset: 0 })
 		accumulatorYRef.current = 0
@@ -421,14 +402,6 @@ export function useScroll(options: UseScrollOptions = {}): UseScrollReturn {
 		accelX.reset()
 	}, [dispatchX, accelX])
 
-	const scrollToStart = useCallback(() => {
-		if (primaryAxis === "horizontal") {
-			scrollToStartX()
-		} else {
-			scrollToStartY()
-		}
-	}, [primaryAxis, scrollToStartX, scrollToStartY])
-
 	const scrollToEndY = useCallback(() => {
 		const current = stateYRef.current
 		const maxOffset = Math.max(0, current.contentSize - current.viewportSize)
@@ -445,27 +418,6 @@ export function useScroll(options: UseScrollOptions = {}): UseScrollReturn {
 		accelX.reset()
 	}, [dispatchX, accelX])
 
-	const scrollToEnd = useCallback(() => {
-		if (primaryAxis === "horizontal") {
-			scrollToEndX()
-		} else {
-			scrollToEndY()
-		}
-	}, [primaryAxis, scrollToEndX, scrollToEndY])
-
-	// Handle content size changes (for sticky scroll)
-	const handleContentSize = useCallback(
-		(width: number, height: number) => {
-			if (enableY && controlledContentHeight === undefined) {
-				dispatchY({ type: "set-content", size: height })
-			}
-			if (enableX && controlledContentWidth === undefined) {
-				dispatchX({ type: "set-content", size: width })
-			}
-		},
-		[controlledContentHeight, controlledContentWidth, dispatchX, dispatchY, enableX, enableY],
-	)
-
 	useLayoutEffect(() => {
 		if (!enableY || controlledContentHeight === undefined) return
 		dispatchY({ type: "set-content", size: controlledContentHeight })
@@ -476,19 +428,35 @@ export function useScroll(options: UseScrollOptions = {}): UseScrollReturn {
 		dispatchX({ type: "set-content", size: controlledContentWidth })
 	}, [controlledContentWidth, dispatchX, enableX])
 
-	// Handle viewport size changes (reported by scroll component)
-	const handleViewportSize = useCallback(
-		(width: number, height: number) => {
+	const handleScrollLayout = useCallback(
+		(event: ScrollLayoutChange) => {
 			if (enableY) {
-				viewportYRef.current = height
-				dispatchY({ type: "set-viewport", size: height })
+				viewportYRef.current = event.viewport.height
+				dispatchY({ type: "set-viewport", size: event.viewport.height })
+				if (controlledContentHeight === undefined) {
+					dispatchY({ type: "set-content", size: event.content.height })
+				}
+				dispatchY({ type: "sync-effective-offset", offset: event.offset.y })
 			}
 			if (enableX) {
-				viewportXRef.current = width
-				dispatchX({ type: "set-viewport", size: width })
+				viewportXRef.current = event.viewport.width
+				dispatchX({ type: "set-viewport", size: event.viewport.width })
+				if (controlledContentWidth === undefined) {
+					dispatchX({ type: "set-content", size: event.content.width })
+				}
+				dispatchX({ type: "sync-effective-offset", offset: event.offset.x })
 			}
+			onScrollLayoutChange?.(event)
 		},
-		[dispatchX, dispatchY, enableX, enableY],
+		[
+			controlledContentHeight,
+			controlledContentWidth,
+			dispatchX,
+			dispatchY,
+			enableX,
+			enableY,
+			onScrollLayoutChange,
+		],
 	)
 
 	// Keyboard handler
@@ -497,7 +465,7 @@ export function useScroll(options: UseScrollOptions = {}): UseScrollReturn {
 			// Mouse wheel comes as pageup/pagedown with meta=true
 			// Handle separately from keyboard since enableKeyboard shouldn't disable mouse
 			if (key.meta && enableMouseWheel && (key.name === "pageup" || key.name === "pagedown")) {
-				const multiplier = primaryAxis === "horizontal" && !enableY ? accelX.tick() : accelY.tick()
+				const multiplier = useHorizontalPrimary && !enableY ? accelX.tick() : accelY.tick()
 				const delta = Math.ceil(arrowSpeed * multiplier)
 				if (axis === "horizontal") {
 					scrollByX(key.name === "pageup" ? -delta : delta)
@@ -569,7 +537,7 @@ export function useScroll(options: UseScrollOptions = {}): UseScrollReturn {
 			accelX,
 			accelY,
 			enableY,
-			primaryAxis,
+			useHorizontalPrimary,
 			scrollByX,
 			scrollByY,
 			scrollToEndX,
@@ -585,7 +553,7 @@ export function useScroll(options: UseScrollOptions = {}): UseScrollReturn {
 	// Uses refs to avoid stale closures, but re-creates when viewport size changes
 	// so selection effects can re-run after measurement updates.
 	// Bypasses clampOffset because it uses totalSize for accurate clamping
-	const scrollToVisible = useCallback(
+	const scrollIntoView = useCallback(
 		(
 			position: number,
 			itemSize = 1,
@@ -633,17 +601,6 @@ export function useScroll(options: UseScrollOptions = {}): UseScrollReturn {
 		[dispatchX],
 	)
 
-	const setOffset = useCallback(
-		(newOffset: number) => {
-			if (primaryAxis === "horizontal") {
-				setOffsetX(newOffset)
-			} else {
-				setOffsetY(newOffset)
-			}
-		},
-		[primaryAxis, setOffsetX, setOffsetY],
-	)
-
 	// Calculate derived state
 	const maxOffsetY = Math.max(0, internalY.contentSize - internalY.viewportSize)
 	const maxOffsetX = Math.max(0, internalX.contentSize - internalX.viewportSize)
@@ -652,19 +609,14 @@ export function useScroll(options: UseScrollOptions = {}): UseScrollReturn {
 	const atStartX = internalX.offset <= 0
 	const atEndX = internalX.offset >= maxOffsetX
 
-	const primaryState = primaryAxis === "horizontal" ? internalX : internalY
-	const primaryMaxOffset = primaryAxis === "horizontal" ? maxOffsetX : maxOffsetY
-	const primaryAtStart = primaryAxis === "horizontal" ? atStartX : atStartY
-	const primaryAtEnd = primaryAxis === "horizontal" ? atEndX : atEndY
-
 	const state: ScrollState = {
-		offset: primaryState.offset,
-		maxOffset: primaryMaxOffset,
-		viewportSize: primaryState.viewportSize,
-		viewportMeasured: primaryState.viewportMeasured,
-		contentSize: primaryState.contentSize,
-		atStart: primaryAtStart,
-		atEnd: primaryAtEnd,
+		offsetY: internalY.offset,
+		maxOffsetY,
+		viewportSizeY: internalY.viewportSize,
+		viewportMeasuredY: internalY.viewportMeasured,
+		contentSizeY: internalY.contentSize,
+		atStartY,
+		atEndY,
 		offsetX: internalX.offset,
 		maxOffsetX,
 		viewportSizeX: internalX.viewportSize,
@@ -674,39 +626,27 @@ export function useScroll(options: UseScrollOptions = {}): UseScrollReturn {
 		atEndX,
 	}
 
-	// Handle effective offset sync from host (when sticky adjusts the offset)
-	const handleEffectiveOffset = useCallback((effectiveOffset: number) => {
-		dispatchY({ type: "sync-effective-offset", offset: effectiveOffset })
-	}, [dispatchY])
-
-	const handleEffectiveOffsetX = useCallback((effectiveOffsetX: number) => {
-		dispatchX({ type: "sync-effective-offset", offset: effectiveOffsetX })
-	}, [dispatchX])
-
 	const scrollProps: ScrollProps = {
-		offset: enableY ? internalY.offset : 0,
+		offsetY: enableY ? internalY.offset : 0,
 		offsetX: enableX ? internalX.offset : 0,
 		axis,
 		align,
 		sticky,
 		showScrollbar,
-		onContentSize: handleContentSize,
-		onViewportSize: handleViewportSize,
-		onEffectiveOffset: enableY ? handleEffectiveOffset : undefined,
-		onEffectiveOffsetX: enableX ? handleEffectiveOffsetX : undefined,
+		onScrollLayoutChange: handleScrollLayout,
 	}
 
 	return {
 		state,
-		setOffset,
+		setOffsetY,
 		setOffsetX,
-		scrollBy,
+		scrollByY,
 		scrollByX,
-		scrollToStart,
-		scrollToEnd,
+		scrollToStartY,
+		scrollToEndY,
 		scrollToStartX,
 		scrollToEndX,
-		scrollToVisible,
+		scrollIntoView,
 		scrollProps,
 	}
 }

package/src/hosts/canvas.ts

@@ -5,12 +5,12 @@ import {
 	type BorderKind,
 	borderChars,
 	drawBorder,
+	fillRectWithInheritedBg,
 	resolveBgStyle,
-	resolveInheritedBgStyle,
 	styleIdFromProps,
 	toColorValue,
 } from "../utils/index.js"
-import { BaseHost } from "./base.js"
+import { LeafHost } from "./leaf.js"
 
 export type { BorderKind }
 
@@ -67,7 +67,7 @@ export interface CanvasProps extends CommonProps {
 	inheritBg?: boolean
 }
 
-export class CanvasHost extends BaseHost {
+export class CanvasHost extends LeafHost {
 	draw: CanvasProps["draw"] = () => {}
 	fixedWidth?: number
 	fixedHeight?: number
@@ -91,15 +91,12 @@ export class CanvasHost extends BaseHost {
 		if (!this.rect) return
 		const { x: ox, y: oy, w, h } = this.rect
 
-		// Get inherited background for use in drawing functions
-		const { value: inheritedBgValue, styleId: inheritedBgStyleId } = this.inheritBg
-			? resolveInheritedBgStyle(palette, undefined, this.parent)
-			: { value: undefined, styleId: 0 }
-
 		// Pre-fill with inherited background if requested
-		if (this.inheritBg && inheritedBgValue !== undefined) {
-			buffer.fillRect(ox, oy, w, h, " ".codePointAt(0)!, inheritedBgStyleId)
-		}
+		const inheritedBgValue = this.inheritBg
+			? fillRectWithInheritedBg(buffer, palette, { x: ox, y: oy, w, h }, undefined, this.parent, {
+					skipWhenUndefined: true,
+				}).value
+			: undefined
 
 		// Create draw context
 		const ctx: DrawContext = {

package/src/hosts/codeblock.ts

@@ -2,7 +2,7 @@ import { type CellBuffer, type Color, Colors, displayWidth, type Palette } from
 import type { HighlightLine } from "../highlight.js"
 import type { CommonProps, HostContext, Size } from "../reconciler/types.js"
 import { type Padding, type PaddingInput, resolveBgStyle, resolvePadding, styleIdFromProps } from "../utils/index.js"
-import { BaseHost } from "./base.js"
+import { LeafHost } from "./leaf.js"
 
 export interface CodeBlockProps extends CommonProps {
 	lines: HighlightLine[]
@@ -17,7 +17,7 @@ function lineDisplayWidth(line: HighlightLine): number {
 	return line.reduce((w, token) => w + displayWidth(token.text), 0)
 }
 
-export class CodeBlockHost extends BaseHost {
+export class CodeBlockHost extends LeafHost {
 	lines: HighlightLine[] = [[]]
 	lineNumbers = false
 	padding: Padding = { top: 0, right: 0, bottom: 0, left: 0 }

package/src/hosts/flex-container.ts

@@ -15,7 +15,7 @@ import {
 import { BaseHost } from "./base.js"
 
 export type CrossAlignment<A extends FlexAxis> = A extends "vertical"
-	? "leading" | "center" | "trailing"
+	? "left" | "center" | "right"
 	: "top" | "center" | "bottom"
 
 export interface FlexContainerProps<A extends FlexAxis> extends CommonProps {
@@ -30,7 +30,7 @@ export interface FlexContainerProps<A extends FlexAxis> extends CommonProps {
 function toFlexAlignment<A extends FlexAxis>(axis: A, alignment: CrossAlignment<A>): FlexAlignment {
 	if (alignment === "center") return "center"
 	if (axis === "vertical") {
-		return alignment === "leading" ? "start" : "end"
+		return alignment === "left" ? "start" : "end"
 	} else {
 		return alignment === "top" ? "start" : "end"
 	}
@@ -104,7 +104,7 @@ export class FlexContainerHost<A extends FlexAxis> extends BaseHost {
 
 	override layout(rect: Rect): void {
 		const layoutRect = this.layoutWithConstraints(rect)
-		const stretchCross = this.axis === "vertical" ? this.alignment === "leading" : this.alignment === "top"
+		const stretchCross = this.axis === "vertical" ? this.alignment === "left" : this.alignment === "top"
 		const insetX = this.padding.left + this.padding.right
 		const insetY = this.padding.top + this.padding.bottom
 		const innerRect: Rect = {
@@ -146,7 +146,7 @@ export class FlexContainerHost<A extends FlexAxis> extends BaseHost {
 		// Reset to axis-specific default when undefined
 		this.alignment =
 			(props.alignment as CrossAlignment<A> | undefined) ??
-			((this.axis === "vertical" ? "leading" : "top") as CrossAlignment<A>)
+			((this.axis === "vertical" ? "left" : "top") as CrossAlignment<A>)
 		this.padding = resolvePadding(props.padding as FlexContainerProps<A>["padding"])
 		this.bg = props.bg as Color | undefined
 	}

package/src/hosts/index.ts

@@ -19,8 +19,17 @@ export { CodeBlockHost, type CodeBlockProps } from "./codeblock.js"
 export { HStackHost, type HStackProps } from "./hstack.js"
 export { OverlayHost, type OverlayProps } from "./overlay.js"
 export { OverlayItemHost, type OverlayItemProps } from "./overlay-item.js"
-export { ScrollHost, type ScrollProps } from "./scroll.js"
+export {
+	ScrollHost,
+	type ScrollAlign,
+	type ScrollAlignX,
+	type ScrollAlignY,
+	type ScrollAxis,
+	type ScrollLayoutChange,
+	type ScrollProps,
+} from "./scroll.js"
 export { SingleChildHost } from "./single-child.js"
+export { LeafHost } from "./leaf.js"
 export { SpacerHost, type SpacerProps } from "./spacer.js"
 export {
 	RawTextHost,

package/src/hosts/layout-helpers.ts

@@ -0,0 +1,20 @@
+import type { Rect, Size } from "../reconciler/types.js"
+import type { HostInstance } from "../reconciler/types.js"
+import { alignedChildRect, type HAlign, type VAlign } from "../utils/index.js"
+
+type Alignment = { h?: HAlign; v?: VAlign }
+
+export function layoutAlignedChildren(
+	layoutRect: Rect,
+	children: HostInstance[],
+	cachedSizes: Size[],
+	alignmentForChild: (child: HostInstance, index: number) => Alignment,
+	startIndex = 0,
+): void {
+	for (let i = startIndex; i < children.length; i++) {
+		const child = children[i]
+		const size = cachedSizes[i] ?? child.measure(layoutRect.w, layoutRect.h)
+		const alignment = alignmentForChild(child, i)
+		child.layout(alignedChildRect(layoutRect, size, alignment.h ?? "center", alignment.v ?? "center"))
+	}
+}

package/src/hosts/leaf.ts

@@ -0,0 +1,36 @@
+import type { HostInstance } from "../reconciler/types.js"
+import { BaseHost } from "./base.js"
+
+/**
+ * Base host that rejects children.
+ * Any attempted child insertion is ignored with a warning (once).
+ */
+export abstract class LeafHost extends BaseHost {
+	private warned = false
+
+	override appendChild(child: HostInstance): void {
+		this.rejectChild(child)
+	}
+
+	override insertBefore(child: HostInstance, _before: HostInstance): void {
+		this.rejectChild(child)
+	}
+
+	override removeChild(child: HostInstance): void {
+		const idx = this.children.indexOf(child)
+		if (idx >= 0) {
+			this.children.splice(idx, 1)
+		}
+		if (child.parent === this) {
+			child.parent = null
+		}
+	}
+
+	private rejectChild(child: HostInstance): void {
+		if (!this.warned) {
+			console.warn(`[effect-tui] <${this.type}> does not support children; child ignored.`)
+			this.warned = true
+		}
+		child.parent = null
+	}
+}

package/src/hosts/overlay.ts

@@ -18,8 +18,8 @@
 
 import type { CellBuffer, Palette, Rect, Size } from "@effect-tui/core"
 import type { CommonProps, HostContext } from "../reconciler/types.js"
-import { alignedChildRect } from "../utils/index.js"
 import { BaseHost } from "./base.js"
+import { layoutAlignedChildren } from "./layout-helpers.js"
 import type { OverlayItemHost } from "./overlay-item.js"
 
 export interface OverlayProps extends CommonProps {}
@@ -66,14 +66,16 @@ export class OverlayHost extends BaseHost {
 		}
 
 		// Layout overlay children with their alignment
-		for (let i = 1; i < this.children.length; i++) {
-			const child = this.children[i]
-			const size = this.cachedSizes[i] ?? child.measure(layoutRect.w, layoutRect.h)
-
-			// Read alignment from OverlayItemHost (use type check, not instanceof, for bundler compatibility)
-			const alignment = child.type === "overlayItem" ? (child as OverlayItemHost).alignment : {}
-			child.layout(alignedChildRect(layoutRect, size, alignment.h ?? "center", alignment.v ?? "center"))
-		}
+		layoutAlignedChildren(
+			layoutRect,
+			this.children,
+			this.cachedSizes,
+			(child) => {
+				// Read alignment from OverlayItemHost (use type check, not instanceof, for bundler compatibility)
+				return child.type === "overlayItem" ? (child as OverlayItemHost).alignment : {}
+			},
+			1,
+		)
 	}
 
 	override render(buffer: CellBuffer, palette: Palette): void {