@effect-tui/react 0.13.0 → 0.14.1

package/src/hosts/text.ts

@@ -1,12 +1,25 @@
 import { type CellBuffer, type Color, displayWidth, type Palette } from "@effect-tui/core"
 import type { ColorMotionValue } from "../motion/color-motion-value.js"
-import type { CommonProps, HostContext, Rect, Size } from "../reconciler/types.js"
-import { resolveInheritedBgStyle, styleIdFromProps } from "../utils/index.js"
+import type { CommonProps, HostContext, HostInstance, Rect, Size } from "../reconciler/types.js"
+import { resolveInheritedBgStyle, styleIdFromProps, wrapSpans } from "../utils/index.js"
 import { BaseHost, getInheritedBg } from "./base.js"
 
 /** Color prop that can be a static Color or a spring-animated ColorMotionValue */
 export type ColorProp = Color | ColorMotionValue
 
+/** A span of text with optional styling */
+export interface StyledSpan {
+	text: string
+	fg?: Color
+	bg?: Color
+	bold?: boolean
+	dimmed?: boolean
+	italic?: boolean
+	underline?: boolean
+	strikethrough?: boolean
+	inverse?: boolean
+}
+
 export interface TextProps extends CommonProps {
 	fg?: ColorProp
 	bg?: ColorProp
@@ -18,6 +31,8 @@ export interface TextProps extends CommonProps {
 	inverse?: boolean
 	/** If true, wrap text to multiple lines (default: false, text is truncated) */
 	wrap?: boolean
+	/** Optional styled spans (bypasses child parsing) */
+	spans?: StyledSpan[]
 }
 
 export class TextHost extends BaseHost {
@@ -38,7 +53,10 @@ export class TextHost extends BaseHost {
 	private cachedContent: string | null = null
 	// Cache for styled mode
 	private cachedStyledLines: StyledSpan[][] | null = null
+	private cachedSpans: StyledSpan[] | null = null
 	private hasSpans = false
+	private explicitSpans: StyledSpan[] | null = null
+	private prepared = false
 
 	constructor(props: TextProps, ctx: HostContext) {
 		super("text", props, ctx)
@@ -109,64 +127,24 @@ export class TextHost extends BaseHost {
 		return spans
 	}
 
-	/** Wrap spans into lines, breaking at word boundaries (same logic as StyledTextHost) */
-	private wrapSpans(spans: StyledSpan[], maxWidth: number): StyledSpan[][] {
-		const lines: StyledSpan[][] = [[]]
-		let lineWidth = 0
-
-		for (const span of spans) {
-			// Split span text into words (keeping whitespace as separate tokens)
-			const tokens = span.text.split(/(\s+)/)
-
-			for (const token of tokens) {
-				if (!token) continue
-				const tokenWidth = displayWidth(token)
-				const isWhitespace = /^\s+$/.test(token)
-
-				if (lineWidth + tokenWidth <= maxWidth) {
-					// Token fits on current line
-					lines[lines.length - 1].push({ ...span, text: token })
-					lineWidth += tokenWidth
-				} else if (isWhitespace) {
-					// Skip whitespace at line break
-					continue
-				} else if (tokenWidth <= maxWidth) {
-					// Start new line with this token
-					lines.push([{ ...span, text: token }])
-					lineWidth = tokenWidth
-				} else {
-					// Token is longer than maxWidth - break by character
-					let charLine = ""
-					let charLineWidth = 0
-					for (const ch of token) {
-						const chWidth = displayWidth(ch)
-						if (lineWidth + charLineWidth + chWidth > maxWidth && (charLine || lineWidth > 0)) {
-							if (charLine) {
-								lines[lines.length - 1].push({ ...span, text: charLine })
-							}
-							lines.push([])
-							lineWidth = 0
-							charLine = ch
-							charLineWidth = chWidth
-						} else {
-							charLine += ch
-							charLineWidth += chWidth
-						}
-					}
-					if (charLine) {
-						lines[lines.length - 1].push({ ...span, text: charLine })
-						lineWidth += charLineWidth
-					}
-				}
-			}
+	private prepareContent(): void {
+		this.invalidateContent()
+		const useExplicitSpans = this.explicitSpans !== null
+		if (useExplicitSpans) {
+			this.hasSpans = false
+			this.cachedSpans = null
+			this.prepared = true
+			return
 		}
 
-		// Remove empty lines at the end
-		while (lines.length > 0 && lines[lines.length - 1].length === 0) {
-			lines.pop()
-		}
+		this.hasSpans = this.checkForSpans()
+		this.cachedSpans = this.hasSpans ? this.collectSpans() : null
+		this.prepared = true
+	}
 
-		return lines.length > 0 ? lines : [[]]
+	private ensurePrepared(): void {
+		if (this.prepared) return
+		this.prepareContent()
 	}
 
 	/** Invalidate content cache when children change */
@@ -174,29 +152,50 @@ export class TextHost extends BaseHost {
 		this.cachedContent = null
 		this.cachedLines = null
 		this.cachedStyledLines = null
+		this.cachedSpans = null
+		this.prepared = false
 	}
 
-	measure(maxW: number, maxH: number): Size {
-		// Invalidate content cache at start of measure (will be recomputed on demand)
+	protected override prepareSelf(): void {
+		this.prepareContent()
+	}
+
+	override appendChild(child: HostInstance): void {
+		super.appendChild(child)
 		this.invalidateContent()
-		this.hasSpans = this.checkForSpans()
+	}
+
+	override removeChild(child: HostInstance): void {
+		super.removeChild(child)
+		this.invalidateContent()
+	}
+
+	override insertBefore(child: HostInstance, before: HostInstance): void {
+		super.insertBefore(child, before)
+		this.invalidateContent()
+	}
+
+	measure(maxW: number, maxH: number): Size {
+		const constrained = this.constrainProposal(maxW, maxH)
+		this.ensurePrepared()
+		const useExplicitSpans = this.explicitSpans !== null
 
 		// Styled mode: use span-aware rendering
-		if (this.hasSpans) {
-			const spans = this.collectSpans()
+		if (useExplicitSpans || this.hasSpans) {
+			const spans = useExplicitSpans ? this.explicitSpans! : (this.cachedSpans ?? this.collectSpans())
 			if (this.wrap) {
-				this.cachedStyledLines = this.wrapSpans(spans, maxW)
-				this.cachedWidth = maxW
-				const h = Math.min(this.cachedStyledLines.length, maxH)
+				this.cachedStyledLines = wrapSpans(spans, constrained.w)
+				this.cachedWidth = constrained.w
+				const h = Math.min(this.cachedStyledLines.length, constrained.h)
 				const w = this.cachedStyledLines.reduce(
 					(max, line) => Math.max(max, line.reduce((sum, span) => sum + displayWidth(span.text), 0)),
 					0,
 				)
-				return { w, h }
+				return this.constrainResult({ w, h })
 			}
 			// Non-wrap styled mode
 			const totalWidth = spans.reduce((sum, span) => sum + displayWidth(span.text), 0)
-			return { w: Math.min(totalWidth, maxW), h: 1 }
+			return this.constrainResult({ w: Math.min(totalWidth, constrained.w), h: 1 })
 		}
 
 		// Simple mode: single style for all content
@@ -206,19 +205,19 @@ export class TextHost extends BaseHost {
 		if (this.wrap) {
 			// Wrap mode: may span multiple lines. Cache result for render()
 			this.cachedLines = rawLines.flatMap((line, idx) =>
-				idx < rawLines.length - 1 ? [...this.wrapText(line, maxW), ""] : this.wrapText(line, maxW),
+				idx < rawLines.length - 1 ? [...this.wrapText(line, constrained.w), ""] : this.wrapText(line, constrained.w),
 			)
-			this.cachedWidth = maxW
+			this.cachedWidth = constrained.w
 			const w = this.cachedLines.reduce((max, line) => Math.max(max, displayWidth(line)), 0)
-			return { w, h: Math.min(this.cachedLines.length, maxH) }
+			return this.constrainResult({ w, h: Math.min(this.cachedLines.length, constrained.h) })
 		}
 
 		// Default: respect explicit newlines but do not wrap long words
 		this.cachedLines = null
-		const widths = rawLines.map((line) => Math.min(displayWidth(line), maxW))
+		const widths = rawLines.map((line) => Math.min(displayWidth(line), constrained.w))
 		const w = widths.reduce((max, val) => Math.max(max, val), 0)
-		const h = Math.min(rawLines.length, maxH)
-		return { w, h }
+		const h = Math.min(rawLines.length, constrained.h)
+		return this.constrainResult({ w, h })
 	}
 
 	/** Wrap text to fit within maxWidth, preferring word boundaries */
@@ -276,29 +275,34 @@ export class TextHost extends BaseHost {
 	}
 
 	override layout(rect: Rect): void {
-		super.layout(rect)
+		const layoutRect = this.layoutWithConstraints(rect)
 		// Layout children (RawTextHost nodes) at same position
 		for (const child of this.children) {
-			child.layout(rect)
+			child.layout(layoutRect)
 		}
 	}
 
 	render(buffer: CellBuffer, palette: Palette): void {
-		if (!this.rect) return
+		if (!this.rect) {
+			this.prepared = false
+			return
+		}
+		this.ensurePrepared()
 
 		// If text has no bg, inherit from parent box for proper highlight rendering
 		const { value: bgValue, styleId: bgStyleId } = resolveInheritedBgStyle(palette, this.bg, this.parent)
 		const inheritedBg = this.bg ?? getInheritedBg(this.parent)
+		const useExplicitSpans = this.explicitSpans !== null
 
 		// Styled mode: render with per-span styles
-		if (this.hasSpans) {
-			const spans = this.collectSpans()
+		if (useExplicitSpans || this.hasSpans) {
 			const lines =
 				this.wrap && this.cachedStyledLines && this.cachedWidth === this.rect.w
 					? this.cachedStyledLines
-					: this.wrap
-						? this.wrapSpans(spans, this.rect.w)
-						: [spans]
+					: (() => {
+							const spans = useExplicitSpans ? this.explicitSpans! : (this.cachedSpans ?? this.collectSpans())
+							return this.wrap ? wrapSpans(spans, this.rect.w) : [spans]
+						})()
 
 			for (let y = 0; y < Math.min(lines.length, this.rect.h); y++) {
 				let x = this.rect.x
@@ -320,6 +324,7 @@ export class TextHost extends BaseHost {
 					x += displayWidth(span.text)
 				}
 			}
+			this.prepared = false
 			return
 		}
 
@@ -356,6 +361,7 @@ export class TextHost extends BaseHost {
 				const lineWidth = Math.min(displayWidth(lines[i]), this.rect.w)
 				buffer.drawText(this.rect.x, this.rect.y + i, lines[i], styleId, lineWidth)
 			}
+			this.prepared = false
 			return
 		}
 
@@ -369,6 +375,7 @@ export class TextHost extends BaseHost {
 			const lineWidth = Math.min(displayWidth(rawLines[i]), this.rect.w)
 			buffer.drawText(this.rect.x, this.rect.y + i, rawLines[i], styleId, lineWidth)
 		}
+		this.prepared = false
 	}
 
 	override updateProps(props: Record<string, unknown>): void {
@@ -387,6 +394,7 @@ export class TextHost extends BaseHost {
 		this.strikethrough = Boolean(props.strikethrough)
 		this.inverse = Boolean(props.inverse)
 		this.wrap = Boolean(props.wrap)
+		this.explicitSpans = "spans" in props ? ((props.spans as StyledSpan[] | undefined) ?? []) : null
 	}
 }
 
@@ -506,178 +514,3 @@ export class SpanHost extends BaseHost {
 		this.inverse = props.inverse !== undefined ? Boolean(props.inverse) : Boolean(textStyle?.inverse)
 	}
 }
-
-// ============================================================================
-// Styled Text Host - for inline formatted text that wraps as a unit
-// ============================================================================
-
-/** A span of text with optional styling */
-export interface StyledSpan {
-	text: string
-	fg?: Color
-	bg?: Color
-	bold?: boolean
-	dimmed?: boolean
-	italic?: boolean
-	underline?: boolean
-	strikethrough?: boolean
-	inverse?: boolean
-}
-
-export interface StyledTextProps extends CommonProps {
-	/** Array of styled text spans */
-	spans: StyledSpan[]
-	/** Default text color */
-	fg?: Color
-	/** Default background color */
-	bg?: Color
-	/** If true, wrap text to multiple lines */
-	wrap?: boolean
-}
-
-/**
- * Host for rendering multiple styled spans that wrap as a unit.
- * Unlike using hstack with multiple text elements, this properly
- * wraps styled inline text across lines.
- */
-export class StyledTextHost extends BaseHost {
-	spans: StyledSpan[] = []
-	fg?: Color
-	bg?: Color
-	wrap = false
-
-	// Cache wrapped lines - each line is an array of spans
-	private cachedLines: StyledSpan[][] | null = null
-	private cachedWidth = 0
-
-	constructor(props: StyledTextProps, ctx: HostContext) {
-		super("styledtext", props, ctx)
-		this.updateProps(props as unknown as Record<string, unknown>)
-	}
-
-	measure(maxW: number, maxH: number): Size {
-		if (this.wrap) {
-			this.cachedLines = this.wrapSpans(this.spans, maxW)
-			this.cachedWidth = maxW
-			const h = Math.min(this.cachedLines.length, maxH)
-			const w = this.cachedLines.reduce(
-				(max, line) => Math.max(max, line.reduce((sum, span) => sum + displayWidth(span.text), 0)),
-				0,
-			)
-			return { w, h }
-		}
-
-		// Non-wrap mode: single line, may truncate
-		const totalWidth = this.spans.reduce((sum, span) => sum + displayWidth(span.text), 0)
-		return { w: Math.min(totalWidth, maxW), h: 1 }
-	}
-
-	/** Wrap spans into lines, breaking at word boundaries */
-	private wrapSpans(spans: StyledSpan[], maxWidth: number): StyledSpan[][] {
-		const lines: StyledSpan[][] = [[]]
-		let lineWidth = 0
-
-		for (const span of spans) {
-			// Split span text into words (keeping whitespace as separate tokens)
-			const tokens = span.text.split(/(\s+)/)
-
-			for (const token of tokens) {
-				if (!token) continue
-				const tokenWidth = displayWidth(token)
-				const isWhitespace = /^\s+$/.test(token)
-
-				if (lineWidth + tokenWidth <= maxWidth) {
-					// Token fits on current line
-					lines[lines.length - 1].push({ ...span, text: token })
-					lineWidth += tokenWidth
-				} else if (isWhitespace) {
-					// Skip whitespace at line break
-					continue
-				} else if (tokenWidth <= maxWidth) {
-					// Start new line with this token
-					lines.push([{ ...span, text: token }])
-					lineWidth = tokenWidth
-				} else {
-					// Token is longer than maxWidth - break by character
-					let charLine = ""
-					let charLineWidth = 0
-					for (const ch of token) {
-						const chWidth = displayWidth(ch)
-						if (lineWidth + charLineWidth + chWidth > maxWidth && (charLine || lineWidth > 0)) {
-							if (charLine) {
-								lines[lines.length - 1].push({ ...span, text: charLine })
-							}
-							lines.push([])
-							lineWidth = 0
-							charLine = ch
-							charLineWidth = chWidth
-						} else {
-							charLine += ch
-							charLineWidth += chWidth
-						}
-					}
-					if (charLine) {
-						lines[lines.length - 1].push({ ...span, text: charLine })
-						lineWidth += charLineWidth
-					}
-				}
-			}
-		}
-
-		// Remove empty lines at the end
-		while (lines.length > 0 && lines[lines.length - 1].length === 0) {
-			lines.pop()
-		}
-
-		return lines.length > 0 ? lines : [[]]
-	}
-
-	override layout(rect: Rect): void {
-		super.layout(rect)
-	}
-
-	render(buffer: CellBuffer, palette: Palette): void {
-		if (!this.rect) return
-
-		const inheritedBg = this.bg ?? getInheritedBg(this.parent)
-
-		// Get lines to render
-		const lines =
-			this.wrap && this.cachedLines && this.cachedWidth === this.rect.w
-				? this.cachedLines
-				: this.wrap
-					? this.wrapSpans(this.spans, this.rect.w)
-					: [this.spans]
-
-		for (let y = 0; y < Math.min(lines.length, this.rect.h); y++) {
-			let x = this.rect.x
-			for (const span of lines[y]) {
-				const styleId = styleIdFromProps(palette, {
-					fg: span.fg ?? this.fg,
-					bg: span.bg ?? inheritedBg,
-					bold: span.bold,
-					dimmed: span.dimmed,
-					italic: span.italic,
-					underline: span.underline,
-					strikethrough: span.strikethrough,
-					inverse: span.inverse,
-				})
-				const availableWidth = this.rect.w - (x - this.rect.x)
-				if (availableWidth <= 0) break
-				const textWidth = Math.min(displayWidth(span.text), availableWidth)
-				buffer.drawText(x, this.rect.y + y, span.text, styleId, textWidth)
-				x += displayWidth(span.text)
-			}
-		}
-	}
-
-	override updateProps(props: Record<string, unknown>): void {
-		super.updateProps(props)
-		this.spans = (props.spans as StyledSpan[] | undefined) ?? []
-		this.fg = props.fg as Color | undefined
-		this.bg = props.bg as Color | undefined
-		this.wrap = Boolean(props.wrap)
-		// Invalidate cache when props change
-		this.cachedLines = null
-	}
-}

package/src/hosts/zstack.ts

@@ -1,6 +1,6 @@
 import type { CellBuffer, Palette } from "@effect-tui/core"
 import type { CommonProps, HostContext, Rect, Size } from "../reconciler/types.js"
-import { alignInRect, type HAlign, type VAlign } from "../utils/index.js"
+import { alignedChildRect, type HAlign, type VAlign } from "../utils/index.js"
 import { BaseHost } from "./base.js"
 
 export interface ZStackProps extends CommonProps {
@@ -43,19 +43,12 @@ export class ZStackHost extends BaseHost {
 	}
 
 	override layout(rect: Rect): void {
-		super.layout(rect)
+		const layoutRect = this.layoutWithConstraints(rect)
 
 		for (let i = 0; i < this.children.length; i++) {
 			const child = this.children[i]
-			const size = this.cachedSizes[i] ?? child.measure(rect.w, rect.h)
-			const { x, y } = alignInRect(rect, size, this.alignmentH, this.alignmentV)
-
-			child.layout({
-				x,
-				y,
-				w: Math.min(rect.w, size.w),
-				h: Math.min(rect.h, size.h),
-			})
+			const size = this.cachedSizes[i] ?? child.measure(layoutRect.w, layoutRect.h)
+			child.layout(alignedChildRect(layoutRect, size, this.alignmentH, this.alignmentV))
 		}
 	}
 

package/src/reconciler/types.ts

@@ -29,6 +29,9 @@ export interface HostInstance {
 	/** Render to buffer */
 	render(buffer: CellBuffer, palette: Palette): void
 
+	/** Optional pre-frame hook for cache prep (called before measure/layout/render). */
+	prepareFrame?(): void
+
 	/** Update props from React */
 	updateProps(props: Record<string, unknown>): void
 

package/src/renderer/core/FrameBuilder.ts

@@ -18,6 +18,9 @@ export class FrameBuilder {
 	 * Returns timing information for each phase.
 	 */
 	build(root: HostInstance, buffer: CellBuffer, palette: Palette, width: number, height: number): FrameTimings {
+		// Pre-frame cache prep (optional)
+		root.prepareFrame?.()
+
 		// Clear buffer
 		let t = Prof.startPhase()
 		const clearStart = performance.now()

package/src/renderer/input/InputProcessor.ts

@@ -1,4 +1,5 @@
 import { ANSI, decodeInput, type KeyMsg, type MouseMsg } from "@effect-tui/core"
+import { requestExit } from "../../exit.js"
 
 export interface InputProcessorConfig {
 	exitOnCtrlC: boolean
@@ -33,7 +34,9 @@ export class InputProcessor {
 				const endIdx = chunk.indexOf(ANSI.paste.endMarker)
 				if (endIdx >= 0) {
 					this.pasteBuffer += chunk.slice(0, endIdx)
-					this.config.dispatchPaste(this.pasteBuffer)
+					this.config.flushSync(() => {
+						this.config.dispatchPaste(this.pasteBuffer)
+					})
 					this.pasteBuffer = ""
 					this.pasteActive = false
 					chunk = chunk.slice(endIdx + ANSI.paste.endMarker.length)
@@ -104,7 +107,7 @@ export class InputProcessor {
 					if (this.config.onQuit) {
 						this.config.onQuit()
 					} else {
-						process.exit(0)
+						requestExit(0)
 					}
 				}
 			}

package/src/renderer/lifecycle/RenderCache.ts

@@ -0,0 +1,13 @@
+export type RenderCache<T> = Map<string, T>
+
+const getGlobalCache = (): Map<string, unknown> => {
+	const globalAny = globalThis as typeof globalThis & {
+		__effectTuiRenderCache?: Map<string, unknown>
+	}
+	if (!globalAny.__effectTuiRenderCache) {
+		globalAny.__effectTuiRenderCache = new Map()
+	}
+	return globalAny.__effectTuiRenderCache
+}
+
+export const getRenderCache = <T>(): RenderCache<T> => getGlobalCache() as RenderCache<T>

package/src/renderer/lifecycle/index.ts

@@ -1,3 +1,4 @@
 export { EventBus } from "./EventBus.js"
+export { getRenderCache, type RenderCache } from "./RenderCache.js"
 export { ResizeManager, type ResizeResult, type ResizeState } from "./ResizeManager.js"
 export { TerminalSetup, type TerminalSetupConfig } from "./TerminalSetup.js"

package/src/renderer-types.ts

@@ -83,7 +83,7 @@ export interface RendererOptions {
 	mode?: "fullscreen" | "inline"
 	/** Exit the process on Ctrl+C unless preventDefault was called. Defaults to true. */
 	exitOnCtrlC?: boolean
-	/** Handle SIGINT/SIGTERM and restore terminal. Defaults to true. */
+	/** Handle SIGINT/SIGTERM and process exit cleanup. Defaults to true. */
 	handleSignals?: boolean
 	/** Exit the process after handling SIGINT/SIGTERM. Defaults to true. */
 	exitOnSignal?: boolean

package/src/renderer.ts

@@ -11,7 +11,7 @@ import type { HostContext } from "./reconciler/types.js"
 // Extracted modules
 import { FrameBuilder, RendererState } from "./renderer/core/index.js"
 import { InputProcessor } from "./renderer/input/index.js"
-import { EventBus, TerminalSetup } from "./renderer/lifecycle/index.js"
+import { EventBus, getRenderCache, TerminalSetup } from "./renderer/lifecycle/index.js"
 import { FullscreenRenderer, InlineRenderer, StaticContentRenderer } from "./renderer/modes/index.js"
 import { RendererContext } from "./renderer-context.js"
 import { startDevRuntime, type DevOptions } from "./dev.js"
@@ -370,11 +370,11 @@ export function createRenderer(options?: RendererOptions): TuiRenderer {
 		renderer.stop()
 	}
 
-	// Handle normal process exit (synchronous - runs before exit completes)
-	onExit = () => cleanup()
-	process.on("exit", onExit)
-
 	if (handleSignals) {
+		// Handle normal process exit (synchronous - runs before exit completes)
+		onExit = () => cleanup()
+		process.on("exit", onExit)
+
 		// Handle SIGINT (Ctrl+C from shell, not from TUI input) and SIGTERM
 		onSignal = (signal: NodeJS.Signals) => {
 			cleanup()
@@ -468,18 +468,6 @@ export type RenderOptions = RendererOptions &
 		importMeta: ImportMetaLike
 	}
 
-type RenderCache = Map<string, RenderInstance>
-
-const getRenderCache = (): RenderCache => {
-	const globalAny = globalThis as typeof globalThis & {
-		__effectTuiRenderCache?: RenderCache
-	}
-	if (!globalAny.__effectTuiRenderCache) {
-		globalAny.__effectTuiRenderCache = new Map()
-	}
-	return globalAny.__effectTuiRenderCache
-}
-
 const stripQuery = (url: string): string => url.split("?")[0]
 
 const createRenderInstance = (
@@ -558,14 +546,10 @@ export function render(element: ReactNode, options?: RenderOptions): RenderInsta
 	}
 
 	const baseUrl = stripQuery(importMeta.url)
-	const renderCache = getRenderCache()
+	const renderCache = getRenderCache<RenderInstance>()
 	const cached = renderCache.get(baseUrl)
 	if (cached) return cached
 
-	if (!importMeta.main) {
-		throw new Error("[effect-tui] render(..., { dev: true }) must be called from the entry module")
-	}
-
 	const renderer = createRenderer(options)
 	const root = createRoot(renderer)
 	const entryPath = fileURLToPath(new URL(baseUrl))

package/src/test/render-tui.ts

@@ -64,6 +64,7 @@ export function renderTUI(element: ReactElement, options?: RenderTUIOptions): Re
 		stdin: stdin as any,
 		manualMode: true,
 		skipTerminalSetup: true,
+		handleSignals: false,
 		mode: options?.mode,
 		diff: options?.diff,
 	})

package/src/utils/alignment.ts

@@ -48,3 +48,21 @@ export function alignInRect(
 
 	return { x, y }
 }
+
+/**
+ * Calculate a child rect aligned within a container rect, clamped to container size.
+ */
+export function alignedChildRect(
+	rect: Rect,
+	size: Size,
+	hAlign: HAlign = "center",
+	vAlign: VAlign = "center",
+): Rect {
+	const { x, y } = alignInRect(rect, size, hAlign, vAlign)
+	return {
+		x,
+		y,
+		w: Math.min(rect.w, size.w),
+		h: Math.min(rect.h, size.h),
+	}
+}

package/src/utils/index.ts

@@ -1,4 +1,4 @@
-export { alignInRect, type HAlign, type VAlign } from "./alignment.js"
+export { alignInRect, alignedChildRect, type HAlign, type VAlign } from "./alignment.js"
 export {
 	type BorderChars,
 	type BorderKind,
@@ -11,6 +11,7 @@ export {
 export { type FlexAlignment, type FlexAxis, type FlexMeasureResult, layoutFlex, measureFlex } from "./flex-layout.js"
 export { type Padding, type PaddingInput, resolvePadding } from "./padding.js"
 export {
+	fillRectWithInheritedBg,
 	resolveBgStyle,
 	resolveInheritedBgStyle,
 	type StyleInput,
@@ -19,3 +20,4 @@ export {
 	styleSpecFromProps,
 	toColorValue,
 } from "./styles.js"
+export { wrapSpans } from "./text-wrap.js"