fix: support nested StaticRender objects and optimize StaticRender API to ensure elements are really removed from the DOM.

GEMINI.md

@@ -143,3 +143,4 @@ This module managed the actual output to the terminal `stdout` in the legacy ren
 
 - **`<Static>`**: This component is considered a legacy feature. It is intended for permanently outputting text above the active Ink app (like a log). However, it is **not fully supported in alternate buffer mode** and will NEVER be supported by the new worker-based renderer. The architectural challenge is that `<Static>` relies on side-effects that can conflict with the strict timing requirements of `useLayoutEffect` used in the main rendering loop, potentially leading to out-of-order output or visual glitches in full-screen apps.
 - **`<StaticRender>`**: This is the more modern and efficient replacement for `<Static>`, designed to work better with the new rendering pipeline and avoid the pitfalls of the legacy implementation. This is the only static-style component supported by the new renderer. Use this instead of `<Static>` for new developments.
+- **Performance vs Linting:** Avoid "fixing" `max-params` (or similar) warnings by refactoring function arguments into objects with named properties (e.g. `({a, b, c})`) on hot-path rendering code, as this adds unnecessary object allocation overhead per call. Ignore the linter warning using a disable comment (e.g. `// eslint-disable-next-line max-params`) instead.

examples/nested-static/index.ts

@@ -0,0 +1,15 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import React from 'react';
+import {render} from '../../src/index.js';
+import NestedStaticDemo from './nested-static.js';
+
+render(React.createElement(NestedStaticDemo), {
+	renderProcess: true,
+	terminalBuffer: true,
+	incrementalRendering: true,
+});

examples/nested-static/nested-static.tsx

@@ -0,0 +1,360 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import process from 'node:process';
+import React, {
+	useState,
+	useEffect,
+	useReducer,
+	useRef,
+	useLayoutEffect,
+} from 'react';
+import {
+	Box,
+	Text,
+	StaticRender,
+	useInput,
+	getInnerHeight,
+	getScrollHeight,
+	type DOMElement,
+} from '../../src/index.js';
+
+const renderCounts = new Map<string, number>();
+
+function TrackedText({
+	name,
+	children,
+	color,
+}: {
+	readonly name: string;
+	readonly children: React.ReactNode;
+	readonly color?: string;
+}) {
+	return (
+		<Text color={color}>
+			<ink-text
+				internal_transform={text => {
+					const count = (renderCounts.get(name) || 0) + 1;
+					renderCounts.set(name, count);
+					return `${text} [Rebuilt: ${count}]`;
+				}}
+			>
+				{children}
+			</ink-text>
+		</Text>
+	);
+}
+
+type ScrollState = {
+	scrollTop: number;
+};
+
+type ScrollAction =
+	| {type: 'up'; delta: number}
+	| {type: 'down'; delta: number; max: number}
+	| {type: 'setTop'; value: number};
+
+function scrollReducer(state: ScrollState, action: ScrollAction): ScrollState {
+	switch (action.type) {
+		case 'up': {
+			return {
+				...state,
+				scrollTop: Math.max(0, state.scrollTop - action.delta),
+			};
+		}
+
+		case 'down': {
+			return {
+				...state,
+				scrollTop: Math.min(state.scrollTop + action.delta, action.max),
+			};
+		}
+
+		case 'setTop': {
+			return {
+				...state,
+				scrollTop: action.value,
+			};
+		}
+	}
+}
+
+export function useTerminalSize(): {columns: number; rows: number} {
+	const [size, setSize] = useState({
+		columns: process.stdout.columns || 80,
+		rows: process.stdout.rows || 20,
+	});
+
+	useEffect(() => {
+		const updateSize = () => {
+			setSize({
+				columns: process.stdout.columns || 80,
+				rows: process.stdout.rows || 20,
+			});
+		};
+
+		process.stdout.on('resize', updateSize);
+
+		return () => {
+			process.stdout.off('resize', updateSize);
+		};
+	}, []);
+
+	return size;
+}
+
+const InnerStatic = React.memo(({id}: {readonly id: string}) => {
+	return (
+		<StaticRender width={50}>
+			{() => (
+				<Box
+					flexDirection="column"
+					borderStyle="single"
+					borderColor="yellow"
+					paddingX={1}
+				>
+					<TrackedText name={`inner-${id}`} color="yellow">
+						Inner Item {id}
+					</TrackedText>
+					<Text dimColor>
+						Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed do
+						eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim
+						ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut
+						aliquip ex ea commodo consequat. Duis aute irure dolor in
+						reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla.
+					</Text>
+					{id === '1-1' && (
+						<Box marginTop={1}>
+							<StaticRender width={44}>
+								{() => (
+									<Box
+										flexDirection="column"
+										borderStyle="round"
+										borderColor="green"
+										paddingX={1}
+									>
+										<TrackedText name="nested-1" color="green">
+											Nested Item 1
+										</TrackedText>
+										<TrackedText name="nested-2" color="green">
+											Nested Item 2
+										</TrackedText>
+										<TrackedText name="nested-3" color="green">
+											Nested Item 3
+										</TrackedText>
+									</Box>
+								)}
+							</StaticRender>
+						</Box>
+					)}
+				</Box>
+			)}
+		</StaticRender>
+	);
+});
+
+const OuterGroup = React.memo(
+	({groupId, items}: {readonly groupId: number; readonly items: number[]}) => {
+		return (
+			<Box
+				width={60}
+				flexDirection="column"
+				borderStyle="double"
+				borderColor="blue"
+				marginBottom={1}
+				paddingX={1}
+			>
+				<TrackedText name={`outer-${groupId}`} color="cyan">
+					Outer Group {groupId}
+				</TrackedText>
+
+				<Box flexDirection="column" gap={1} marginTop={1}>
+					{items.map(itemId => (
+						<InnerStatic
+							key={`inner-${groupId}-${itemId}`}
+							id={`${groupId}-${itemId}`}
+						/>
+					))}
+				</Box>
+			</Box>
+		);
+	},
+);
+
+export default function NestedStaticDemo() {
+	const [count, setCount] = useState(0);
+	const [groups, setGroups] = useState<Array<{id: number; items: number[]}>>([
+		{id: 1, items: Array.from({length: 1000}, (_, i) => i + 1)},
+	]);
+	const [scrollState, dispatch] = useReducer(scrollReducer, {scrollTop: 0});
+	const {scrollTop} = scrollState;
+	const {columns, rows} = useTerminalSize();
+
+	const reference = useRef<DOMElement>(null);
+	const sizeReference = useRef({innerHeight: 0, scrollHeight: 0});
+	const [shouldScrollToBottom, setShouldScrollToBottom] = useState(true);
+
+	useLayoutEffect(() => {
+		if (reference.current) {
+			const innerHeight = getInnerHeight(reference.current);
+			const scrollHeight = getScrollHeight(reference.current);
+
+			sizeReference.current = {innerHeight, scrollHeight};
+
+			if (shouldScrollToBottom) {
+				dispatch({
+					type: 'setTop',
+					value: Math.max(0, scrollHeight - innerHeight),
+				});
+				setShouldScrollToBottom(false);
+			}
+		}
+	});
+
+	const [nextItemId, setNextItemId] = useState(1001);
+
+	useInput((input, key) => {
+		if (input === ' ') {
+			setGroups(previousGroups => {
+				const newGroups = [...previousGroups];
+				const firstGroup = newGroups[0];
+				if (firstGroup) {
+					newGroups[0] = {
+						...firstGroup,
+						items: [...firstGroup.items, nextItemId],
+					};
+					setNextItemId(id => id + 1);
+				}
+
+				return newGroups;
+			});
+			setShouldScrollToBottom(true);
+			return;
+		}
+
+		if (input === 'n') {
+			setGroups(previousGroups => {
+				const nextGroupId =
+					previousGroups.length > 0
+						? Math.max(...previousGroups.map(g => g.id)) + 1
+						: 1;
+				return [...previousGroups, {id: nextGroupId, items: [1]}];
+			});
+			setShouldScrollToBottom(true);
+			return;
+		}
+
+		if (key.upArrow || input === 'w') {
+			dispatch({type: 'up', delta: key.shift ? 10 : 1});
+			return;
+		}
+
+		if (key.downArrow || input === 's') {
+			dispatch({
+				type: 'down',
+				delta: key.shift ? 10 : 1,
+				max: Math.max(
+					0,
+					sizeReference.current.scrollHeight -
+						sizeReference.current.innerHeight,
+				),
+			});
+			return;
+		}
+
+		if (input === 'u') {
+			dispatch({
+				type: 'up',
+				delta: Math.floor(sizeReference.current.scrollHeight / 2),
+			});
+			return;
+		}
+
+		if (input === 'd') {
+			dispatch({
+				type: 'down',
+				delta: Math.floor(sizeReference.current.scrollHeight / 2),
+				max: Math.max(
+					0,
+					sizeReference.current.scrollHeight -
+						sizeReference.current.innerHeight,
+				),
+			});
+		}
+	});
+
+	useEffect(() => {
+		const timer = setInterval(() => {
+			setCount(previous => previous + 1);
+		}, 5000);
+
+		const addTimer = setInterval(() => {
+			setGroups(previousGroups => {
+				const newGroups = [...previousGroups];
+				const firstGroup = newGroups[0];
+				if (firstGroup) {
+					newGroups[0] = {
+						...firstGroup,
+						items: [...firstGroup.items, nextItemId],
+					};
+					setNextItemId(id => id + 1);
+				}
+
+				return newGroups;
+			});
+			setShouldScrollToBottom(true);
+		}, 5000);
+
+		return () => {
+			clearInterval(timer);
+			clearInterval(addTimer);
+		};
+	}, [nextItemId]);
+
+	return (
+		<Box flexDirection="column" height={rows} width={columns}>
+			<Box
+				ref={reference}
+				overflowToBackbuffer
+				scrollbar
+				flexDirection="column"
+				flexGrow={1}
+				flexShrink={1}
+				overflowX="hidden"
+				overflowY="scroll"
+				paddingRight={0}
+				scrollTop={scrollTop}
+				width={columns}
+			>
+				<Box flexShrink={0} flexDirection="column">
+					{groups.map(group => (
+						<OuterGroup
+							key={`group-outer-${group.id}`}
+							groupId={group.id}
+							items={group.items}
+						/>
+					))}
+				</Box>
+			</Box>
+
+			<Box
+				borderTop
+				borderStyle="single"
+				flexDirection="column"
+				flexShrink={0}
+				overflow="hidden"
+			>
+				<Text color="green">Nested StaticRender Demo</Text>
+				<Text>Press [Space] to add item to Group 1, [n] to add new Group.</Text>
+				<Text>
+					Arrows to scroll. [u]/[d] scroll up/down by half total height.
+					ScrollTop: {scrollTop}
+				</Text>
+				<Text>Timer: {count}</Text>
+			</Box>
+		</Box>
+	);
+}

examples/resize-observer/index.tsx

@@ -116,9 +116,11 @@ function App() {
 			</Box>
 
 			<StaticRender width={80}>
-				<Box padding={1} borderStyle="single" borderColor="magenta">
-					<Text>I am a StaticRender block to test layout sizing.</Text>
-				</Box>
+				{() => (
+					<Box padding={1} borderStyle="single" borderColor="magenta">
+						<Text>I am a StaticRender block to test layout sizing.</Text>
+					</Box>
+				)}
 			</StaticRender>
 
 			<Text>