@alchemy.run/sigil 0.0.0-alpha.8 → 0.0.0-alpha.9

package/README.md

@@ -164,6 +164,7 @@ _(PRs welcome. Append new entries at the end. Repos must have 100+ stars and sho
   - [`<Spacer>`](#spacer)
   - [`<Static>`](#static)
   - [`<Transform>`](#transform)
+  - [`<VirtualList>`](#virtuallist)
 - [Hooks](#hooks)
   - [`useInput`](#useinputinputhandler-options)
   - [`usePaste`](#usepastehandler-options)
@@ -171,6 +172,7 @@ _(PRs welcome. Append new entries at the end. Repos must have 100+ stars and sho
   - [`useStdin`](#usestdin)
   - [`useStdout`](#usestdout)
   - [`useBoxMetrics`](#useboxmetricsref)
+  - [`useVirtualScroll`](#usevirtualscrolloptions)
   - [`useStderr`](#usestderr)
   - [`useWindowSize`](#usewindowsize)
   - [`useFocus`](#usefocusoptions)
@@ -1655,6 +1657,87 @@ Type: `number`
 
 The zero-indexed line number of the line that's currently being transformed.
 
+### `<VirtualList>`
+
+A vertically windowed list. Only the items that intersect the viewport are rendered, inside a clipped box that scrolls by whole rows. Items may have different heights, and the item at the top edge may be partially visible.
+
+Give it a fixed `height`, or omit it and bound an ancestor instead: the list then takes the height of its content and shrinks to whatever rows the container leaves over. Siblings that must keep their size need `flexShrink={0}`, because every `<Box>` shrinks by default.
+
+```jsx
+import { useState } from "react";
+import { render, Box, Text, VirtualList, useInput, useWindowSize } from "@alchemy.run/sigil";
+
+const entries = Array.from({ length: 200 }, (_, index) => `entry ${index}`);
+
+const Example = () => {
+  const { rows } = useWindowSize();
+  const [cursor, setCursor] = useState(0);
+
+  useInput((_, key) => {
+    if (key.upArrow) setCursor((index) => Math.max(0, index - 1));
+    if (key.downArrow) setCursor((index) => Math.min(entries.length - 1, index + 1));
+  });
+
+  return (
+    <Box flexDirection="column" maxHeight={rows}>
+      <Box flexShrink={0}>
+        <Text bold>Entries</Text>
+      </Box>
+      <VirtualList
+        items={entries}
+        itemHeight={() => 1}
+        focusedIndex={cursor}
+        renderItem={(entry, index) => <Text inverse={index === cursor}>{entry}</Text>}
+      />
+      <Box flexShrink={0}>
+        <Text dimColor>↑/↓ move</Text>
+      </Box>
+    </Box>
+  );
+};
+
+render(<Example />);
+```
+
+#### items
+
+Type: `ReadonlyArray<Item>`
+
+Items to window over.
+
+#### itemHeight
+
+Type: `(item: Item, index: number) => number`
+
+Height of an item in rows. It must match what `renderItem` produces for it: the window is computed from these numbers, never from the rendered output.
+
+#### renderItem
+
+Type: `(item: Item, index: number) => ReactNode`
+
+Render one item. Only items intersecting the viewport are rendered.
+
+#### getKey
+
+Type: `(item: Item, index: number) => React.Key`
+
+React key for an item. Defaults to its index.
+
+#### focusedIndex
+
+Type: `number`
+
+Item to keep fully visible. When it changes, the list scrolls as little as necessary to show it. An item taller than the viewport is aligned to its top.
+
+#### height
+
+Type: `number`
+
+Viewport height in rows. When omitted the list shrinks to the space its container leaves over, as described above.
+
+> [!NOTE]
+> Until the first layout pass has measured the viewport, every item is rendered inside the clipped box so the first frame already looks right.
+
 ## Hooks
 
 ### useInput(inputHandler, options?)
@@ -2174,6 +2257,99 @@ Whether the currently tracked element has been measured.
 > [!NOTE]
 > The hook returns `{width: 0, height: 0, left: 0, top: 0}` until the first layout pass completes. It also returns zeros when the tracked ref is detached.
 
+### useVirtualScroll(options)
+
+A React hook that owns the scroll position of a windowed list and returns which items to render for it. The position is clamped to the scrollable range and, while `focusedIndex` is set, moved as little as necessary to keep that item fully visible.
+
+[`<VirtualList>`](#virtuallist) wraps this hook. Use it directly to draw your own chrome around the window, such as overflow markers or a scrollbar.
+
+```jsx
+import { Box, Text, useVirtualScroll } from "@alchemy.run/sigil";
+
+const Example = ({ lines, cursor }) => {
+  const { start, end, offset, hiddenAbove, hiddenBelow } = useVirtualScroll({
+    count: lines.length,
+    itemHeight: () => 1,
+    viewportHeight: 10,
+    focusedIndex: cursor,
+  });
+
+  return (
+    <Box flexDirection="column">
+      <Text dimColor>{hiddenAbove > 0 ? `↑ ${hiddenAbove} more` : ""}</Text>
+      <Box flexDirection="column" height={10} overflowY="hidden">
+        <Box flexDirection="column" flexShrink={0} marginTop={offset}>
+          {lines.slice(start, end).map((line, index) => (
+            <Text key={start + index} inverse={start + index === cursor}>
+              {line}
+            </Text>
+          ))}
+        </Box>
+      </Box>
+      <Text dimColor>{hiddenBelow > 0 ? `↓ ${hiddenBelow} more` : ""}</Text>
+    </Box>
+  );
+};
+```
+
+#### options
+
+##### count
+
+Type: `number`
+
+Number of items in the list.
+
+##### itemHeight
+
+Type: `(index: number) => number`
+
+Height of the item at `index` in rows. It must match what the item renders.
+
+##### viewportHeight
+
+Type: `number`
+
+Rows available to show items.
+
+##### focusedIndex
+
+Type: `number`
+
+Item that must stay fully visible. An item taller than the viewport is aligned to the top. Out-of-range values are ignored.
+
+#### Result
+
+##### start, end
+
+Type: `number`
+
+The items intersecting the viewport are `[start, end)`.
+
+##### offset
+
+Type: `number`
+
+Position of the `start` item relative to the top of the viewport. Zero or negative: a negative value means the item is partially scrolled out above. Apply it as `marginTop` on the box holding the rendered items.
+
+##### scrollTop, maxScrollTop, totalHeight
+
+Type: `number`
+
+The effective position, the largest position that still fills the viewport, and the height of every item combined, all in rows.
+
+##### hiddenAbove, hiddenBelow
+
+Type: `number`
+
+Rows scrolled out above the viewport and rows left below it.
+
+##### scrollTo(top), scrollBy(delta)
+
+Type: `(rows: number) => void`
+
+Move the viewport. While `focusedIndex` is set, a position that would hide it is corrected on the next render.
+
 ### useStderr()
 
 A React hook that returns the stderr stream and stderr-related utilities.

package/dist/index.d.ts

@@ -8,7 +8,7 @@ import { n as Text, r as Styles, t as Props$8 } from "./Text-DV9CuzAT.js";
 import { i as Node } from "./index-DDVME65c.js";
 import { t as CursorPosition } from "./cursor-position-D2LAkRG0.js";
 import { Writable } from "node:stream";
-import { PropsWithChildren, ReactNode, Ref, RefObject } from "react";
+import { Key as Key$1, PropsWithChildren, ReactNode, Ref, RefObject } from "react";
 import { EventEmitter } from "node:events";
 //#region src/kitty-keyboard.d.ts
 declare const kittyFlags: {
@@ -634,6 +634,48 @@ It's useful as a shortcut for filling all the available space between elements.
 */
 declare function Spacer(): import("react").JSX.Element;
 //#endregion
+//#region src/components/VirtualList.d.ts
+type Props$10<Item> = {
+  /**
+      Items to window over.
+      */
+  readonly items: ReadonlyArray<Item>;
+  /**
+      Height of an item in rows. It must match what `renderItem` produces for it:
+      the window is computed from these numbers, never from the rendered output.
+      */
+  readonly itemHeight: (item: Item, index: number) => number;
+  /**
+      Render one item. Only items intersecting the viewport are rendered.
+      */
+  readonly renderItem: (item: Item, index: number) => ReactNode;
+  /**
+      React key for an item. Defaults to its index.
+      */
+  readonly getKey?: (item: Item, index: number) => Key$1;
+  /**
+      Item to keep fully visible. When it changes, the list scrolls as little as
+      necessary to show it.
+      */
+  readonly focusedIndex?: number;
+  /**
+      Viewport height in rows. When omitted the list takes the height of its
+      content and shrinks to whatever space its container leaves: bound an
+      ancestor (`height` or `maxHeight`) and give the siblings that must keep
+      their size `flexShrink={0}`.
+      */
+  readonly height?: number;
+};
+/**
+A vertically windowed list: only the items intersecting the viewport are
+rendered, inside a clipped box that scrolls by whole rows. Items may have
+different heights, and the item at the top edge may be partially visible.
+
+Until the first layout pass has measured the viewport, every item is rendered
+inside the clipped box so the first frame already looks right.
+*/
+declare function VirtualList<Item>({ items, itemHeight, renderItem, getKey, focusedIndex, height }: Props$10<Item>): import("react").JSX.Element;
+//#endregion
 //#region src/hooks/use-capabilities.d.ts
 /**
 Returns everything knowable about the terminal: size, identity, platform,
@@ -891,7 +933,7 @@ A component that uses the `useFocus` hook becomes "focusable" to Ink, so when th
 declare const useFocus: ({ isActive, autoFocus, id: customId }?: Input) => Output$2;
 //#endregion
 //#region src/components/FocusContext.d.ts
-type Props$10 = {
+type Props$11 = {
   readonly activeId?: string;
   readonly add: (id: string, options: {
     autoFocus: boolean;
@@ -911,23 +953,23 @@ type Output$1 = {
   /**
       Enable focus management for all components.
       */
-  enableFocus: Props$10["enableFocus"];
+  enableFocus: Props$11["enableFocus"];
   /**
       Disable focus management for all components. The currently active component (if there's one) will lose its focus.
       */
-  disableFocus: Props$10["disableFocus"];
+  disableFocus: Props$11["disableFocus"];
   /**
       Switch focus to the next focusable component. If there's no active component right now, focus will be given to the first focusable component. If the active component is the last in the list of focusable components, focus will be switched to the first focusable component.
       */
-  focusNext: Props$10["focusNext"];
+  focusNext: Props$11["focusNext"];
   /**
       Switch focus to the previous focusable component. If there's no active component right now, focus will be given to the first focusable component. If the active component is the first in the list of focusable components, focus will be switched to the last focusable component.
       */
-  focusPrevious: Props$10["focusPrevious"];
+  focusPrevious: Props$11["focusPrevious"];
   /**
       Switch focus to the element with provided `id`. If there's no element with that `id`, focus is not changed.
       */
-  focus: Props$10["focus"];
+  focus: Props$11["focus"];
   /**
       The ID of the currently focused component, or `undefined` if no component is focused.
   
@@ -942,7 +984,7 @@ type Output$1 = {
       };
       ```
       */
-  activeId: Props$10["activeId"];
+  activeId: Props$11["activeId"];
 };
 /**
 A React hook that returns methods to enable or disable focus management for all components or manually switch focus to the next or previous components.
@@ -1111,6 +1153,129 @@ const Example = () => {
 */
 declare const useBoxMetrics: (ref: RefObject<DOMElement | null>) => UseBoxMetricsResult;
 //#endregion
+//#region src/virtual-scroll.d.ts
+/**
+Windowing math shared by `useVirtualScroll` and `<VirtualList>`.
+
+Items are stacked vertically and measured in terminal rows. The viewport shows
+`viewportHeight` rows of that stack starting `scrollTop` rows from the top.
+*/
+type VirtualScrollOptions = {
+  /**
+      Number of items in the list.
+      */
+  readonly count: number;
+  /**
+      Height of the item at `index` in rows. It must match what the item renders:
+      the window is computed from these numbers, never from the rendered output.
+      */
+  readonly itemHeight: (index: number) => number;
+  /**
+      Rows available to show items.
+      */
+  readonly viewportHeight: number;
+  /**
+      Requested distance of the viewport from the top of the list in rows. It is
+      clamped to the scrollable range and then moved as little as necessary to keep
+      `focusedIndex` fully visible.
+      */
+  readonly scrollTop: number;
+  /**
+      Item that must stay fully visible. An item taller than the viewport is aligned
+      to the top. Out-of-range values are ignored.
+      */
+  readonly focusedIndex?: number;
+};
+type VirtualScrollWindow = {
+  /**
+      Index of the first item that intersects the viewport.
+      */
+  readonly start: number;
+  /**
+      Index after the last item that intersects the viewport.
+      */
+  readonly end: number;
+  /**
+      Effective distance of the viewport from the top of the list in rows.
+      */
+  readonly scrollTop: number;
+  /**
+      Largest `scrollTop` that still fills the viewport.
+      */
+  readonly maxScrollTop: number;
+  /**
+      Height of every item combined in rows.
+      */
+  readonly totalHeight: number;
+  /**
+      Position of the `start` item relative to the top of the viewport. Zero or
+      negative: a negative value means the item is partially scrolled out above.
+      */
+  readonly offset: number;
+  /**
+      Rows scrolled out above the viewport.
+      */
+  readonly hiddenAbove: number;
+  /**
+      Rows left below the viewport.
+      */
+  readonly hiddenBelow: number;
+};
+//#endregion
+//#region src/hooks/use-virtual-scroll.d.ts
+type UseVirtualScrollOptions = Omit<VirtualScrollOptions, "scrollTop">;
+type UseVirtualScrollResult = VirtualScrollWindow & {
+  /**
+      Scroll so the viewport starts `top` rows from the top of the list.
+      */
+  readonly scrollTo: (top: number) => void;
+  /**
+      Scroll by `delta` rows; negative values scroll up.
+      */
+  readonly scrollBy: (delta: number) => void;
+};
+/**
+A React hook that owns the scroll position of a windowed list and returns which
+items to render for it. The position is clamped to the scrollable range and,
+while `focusedIndex` is set, moved as little as necessary to keep that item
+fully visible. Render the items in `[start, end)` inside an `overflowY="hidden"`
+box of `viewportHeight` rows, shifted up by `offset` rows.
+
+`<VirtualList>` wraps this hook; use it directly to draw your own chrome such
+as overflow markers or a scrollbar around the window.
+
+@example
+```tsx
+import { Box, Text, useVirtualScroll } from "@alchemy.run/sigil";
+
+const Example = ({ lines, cursor }: { lines: string[]; cursor: number }) => {
+    const { start, end, offset, hiddenAbove, hiddenBelow } = useVirtualScroll({
+        count: lines.length,
+        itemHeight: () => 1,
+        viewportHeight: 10,
+        focusedIndex: cursor,
+    });
+
+    return (
+        <Box flexDirection="column">
+            <Text dimColor>{hiddenAbove > 0 ? `↑ ${hiddenAbove} more` : ""}</Text>
+            <Box flexDirection="column" height={10} overflowY="hidden">
+                <Box flexDirection="column" flexShrink={0} marginTop={offset}>
+                    {lines.slice(start, end).map((line, index) => (
+                        <Text key={start + index} inverse={start + index === cursor}>
+                            {line}
+                        </Text>
+                    ))}
+                </Box>
+            </Box>
+            <Text dimColor>{hiddenBelow > 0 ? `↓ ${hiddenBelow} more` : ""}</Text>
+        </Box>
+    );
+};
+```
+*/
+declare const useVirtualScroll: (options: UseVirtualScrollOptions) => UseVirtualScrollResult;
+//#endregion
 //#region src/measure-element.d.ts
 type Output = {
   /**
@@ -1140,4 +1305,4 @@ Note: `measureElement()` returns `{x: 0, y: 0, width: 0, height: 0}` when called
 */
 declare const measureElement: (node: DOMElement) => Output;
 //#endregion
-export { type AnimationResult, AnsiText, type Props as AnsiTextProps, type Props$1 as AppProps, Box, type BoxMetrics, type Props$2 as BoxProps, type Capabilities, type CapabilitiesStore, type CapturedOutputSource, type ColorInfo, type ColorSupport, type ColorSupportLevel, type CursorPosition, type DOMElement, type Output as ElementMetrics, Hyperlink, type Props$3 as HyperlinkProps, type Instance, type Key, type KittyFlagName, type KittyKeyboardOptions, type Multiplexer, Newline, type Props$4 as NewlineProps, type PixelGeometry, type PixelSize, type ProgressOptions, type RenderOptions, type RenderToStringOptions, type RgbColor, Spacer, Static, type Props$5 as StaticProps, type Props$6 as StderrProps, type PublicProps as StdinProps, type Props$7 as StdoutProps, type SuspendTerminal, type TerminalAppearance, type TerminalIdentity, type TerminalQueryOptions, type TerminalQueryResult, type TerminalSuspension, Text, type Props$8 as TextProps, Transform, type Props$9 as TransformProps, type UseBoxMetricsResult, type WindowSize, applyTerminalQuery, capabilities, createSupportsColor, detectCapabilities, detectColorLevel, detectHyperlinkSupport, detectTerminal, detectUnicodeSupport, getCapabilities, getTerminalQuery, kittyFlags, kittyModifiers, measureElement, queryTerminal, refreshTerminalQuery, render, renderToString, useAnimation, useApp, useBoxMetrics, useCapabilities, useCapabilitiesChange, useClipboard, useCursor, useFocus, useFocusManager, useInput, useIsScreenReaderEnabled, useNotification, usePaste, usePointerShape, useProgress, useStderr, useStdin, useStdout, useTitle, useWindowSize, useWorkingDirectory };
+export { type AnimationResult, AnsiText, type Props as AnsiTextProps, type Props$1 as AppProps, Box, type BoxMetrics, type Props$2 as BoxProps, type Capabilities, type CapabilitiesStore, type CapturedOutputSource, type ColorInfo, type ColorSupport, type ColorSupportLevel, type CursorPosition, type DOMElement, type Output as ElementMetrics, Hyperlink, type Props$3 as HyperlinkProps, type Instance, type Key, type KittyFlagName, type KittyKeyboardOptions, type Multiplexer, Newline, type Props$4 as NewlineProps, type PixelGeometry, type PixelSize, type ProgressOptions, type RenderOptions, type RenderToStringOptions, type RgbColor, Spacer, Static, type Props$5 as StaticProps, type Props$6 as StderrProps, type PublicProps as StdinProps, type Props$7 as StdoutProps, type SuspendTerminal, type TerminalAppearance, type TerminalIdentity, type TerminalQueryOptions, type TerminalQueryResult, type TerminalSuspension, Text, type Props$8 as TextProps, Transform, type Props$9 as TransformProps, type UseBoxMetricsResult, type UseVirtualScrollOptions, type UseVirtualScrollResult, VirtualList, type Props$10 as VirtualListProps, type VirtualScrollWindow, type WindowSize, applyTerminalQuery, capabilities, createSupportsColor, detectCapabilities, detectColorLevel, detectHyperlinkSupport, detectTerminal, detectUnicodeSupport, getCapabilities, getTerminalQuery, kittyFlags, kittyModifiers, measureElement, queryTerminal, refreshTerminalQuery, render, renderToString, useAnimation, useApp, useBoxMetrics, useCapabilities, useCapabilitiesChange, useClipboard, useCursor, useFocus, useFocusManager, useInput, useIsScreenReaderEnabled, useNotification, usePaste, usePointerShape, useProgress, useStderr, useStdin, useStdout, useTitle, useVirtualScroll, useWindowSize, useWorkingDirectory };

package/dist/index.js

@@ -2,7 +2,7 @@ import { C as bsu, S as ansiEscapes, V as esu, W as link, _ as CSI } from "./sgr
 import { h as tokenizeAnsi, p as graphemes } from "./tokenize-AjqbvtiT.js";
 import { t as stringWidth } from "./string-width-CijQwpIk.js";
 import { n as sliceAnsi, r as wrapAnsi } from "./truncate-D31fhU6i.js";
-import { _ as squashTextNodes, a as reconciler, c as kittyModifiers, d as FocusContext, f as Text, g as transformAnsiLine, h as emitLayoutListeners, i as useStdinContext, l as resolveFlags, m as createNode, n as useInput, o as detectKittySupport, p as addLayoutListener, r as useStdin, s as kittyFlags, t as useFocus, u as StdinContext, v as accessibilityContext } from "./use-focus-BNG0xsb7.js";
+import { _ as squashTextNodes, a as reconciler, c as kittyModifiers, d as FocusContext, f as Text, g as transformAnsiLine, h as emitLayoutListeners, i as useStdinContext, l as resolveFlags, m as createNode, n as useInput, o as detectKittySupport, p as addLayoutListener, r as useStdin, s as kittyFlags, t as useFocus, u as StdinContext, v as accessibilityContext } from "./use-focus-Basd0ksv.js";
 import { a as isTty, i as isSigilDev, o as isWindows, r as isScreenReader, t as isInCi } from "./env-YVw64yZS.js";
 import { a as detectTerminal, i as detectHyperlinkSupport, n as detectCapabilities, o as detectUnicodeSupport, r as detectColorLevel, s as signalExit, t as createSupportsColor } from "./detect-B3dL4Q11.js";
 import { u as cliCursor } from "./osc-BFKKSqpg.js";
@@ -2602,6 +2602,181 @@ function Spacer() {
 	return /* @__PURE__ */ jsx(Box, { flexGrow: 1 });
 }
 //#endregion
+//#region src/virtual-scroll.ts
+const clamp = (value, min, max) => Math.min(Math.max(value, min), max);
+const wholeRows = (value) => Math.max(0, Math.floor(value)) || 0;
+/**
+Compute which items intersect a viewport over a vertical stack of items.
+*/
+const virtualScrollWindow = (options) => {
+	const count = wholeRows(options.count);
+	const viewportHeight = wholeRows(options.viewportHeight);
+	const tops = [];
+	let totalHeight = 0;
+	for (let index = 0; index < count; index++) {
+		tops.push(totalHeight);
+		totalHeight += wholeRows(options.itemHeight(index));
+	}
+	const bottomOf = (index) => index + 1 < count ? tops[index + 1] : totalHeight;
+	const maxScrollTop = Math.max(0, totalHeight - viewportHeight);
+	let scrollTop = clamp(Math.floor(options.scrollTop) || 0, 0, maxScrollTop);
+	const focused = options.focusedIndex;
+	if (focused !== void 0 && Number.isInteger(focused) && focused >= 0 && focused < count) {
+		const top = tops[focused];
+		const bottom = bottomOf(focused);
+		if (top < scrollTop) scrollTop = top;
+		else if (bottom > scrollTop + viewportHeight) scrollTop = Math.min(top, bottom - viewportHeight);
+		scrollTop = clamp(scrollTop, 0, maxScrollTop);
+	}
+	const viewportBottom = scrollTop + viewportHeight;
+	let start = 0;
+	while (start < count && bottomOf(start) <= scrollTop) start++;
+	let end = start;
+	while (end < count && tops[end] < viewportBottom) end++;
+	return {
+		start,
+		end,
+		scrollTop,
+		maxScrollTop,
+		totalHeight,
+		offset: start < end ? tops[start] - scrollTop : 0,
+		hiddenAbove: scrollTop,
+		hiddenBelow: Math.max(0, totalHeight - viewportBottom)
+	};
+};
+//#endregion
+//#region src/hooks/use-virtual-scroll.ts
+/**
+A React hook that owns the scroll position of a windowed list and returns which
+items to render for it. The position is clamped to the scrollable range and,
+while `focusedIndex` is set, moved as little as necessary to keep that item
+fully visible. Render the items in `[start, end)` inside an `overflowY="hidden"`
+box of `viewportHeight` rows, shifted up by `offset` rows.
+
+`<VirtualList>` wraps this hook; use it directly to draw your own chrome such
+as overflow markers or a scrollbar around the window.
+
+@example
+```tsx
+import { Box, Text, useVirtualScroll } from "@alchemy.run/sigil";
+
+const Example = ({ lines, cursor }: { lines: string[]; cursor: number }) => {
+const { start, end, offset, hiddenAbove, hiddenBelow } = useVirtualScroll({
+count: lines.length,
+itemHeight: () => 1,
+viewportHeight: 10,
+focusedIndex: cursor,
+});
+
+return (
+<Box flexDirection="column">
+<Text dimColor>{hiddenAbove > 0 ? `↑ ${hiddenAbove} more` : ""}</Text>
+<Box flexDirection="column" height={10} overflowY="hidden">
+<Box flexDirection="column" flexShrink={0} marginTop={offset}>
+{lines.slice(start, end).map((line, index) => (
+<Text key={start + index} inverse={start + index === cursor}>
+{line}
+</Text>
+))}
+</Box>
+</Box>
+<Text dimColor>{hiddenBelow > 0 ? `↓ ${hiddenBelow} more` : ""}</Text>
+</Box>
+);
+};
+```
+*/
+const useVirtualScroll = (options) => {
+	const [position, setPosition] = useState(0);
+	const window = virtualScrollWindow({
+		...options,
+		scrollTop: position
+	});
+	useEffect(() => {
+		if (window.scrollTop !== position) setPosition(window.scrollTop);
+	}, [window.scrollTop, position]);
+	const scrollTo = useCallback((top) => {
+		setPosition(top);
+	}, []);
+	const scrollBy = useCallback((delta) => {
+		setPosition((current) => current + delta);
+	}, []);
+	return {
+		...window,
+		scrollTo,
+		scrollBy
+	};
+};
+//#endregion
+//#region src/components/VirtualList.tsx
+/** @jsxImportSource react */
+const rootOf = (node) => {
+	let current = node;
+	while (current?.parentNode) current = current.parentNode;
+	return current?.nodeName === "ink-root" ? current : void 0;
+};
+/**
+A vertically windowed list: only the items intersecting the viewport are
+rendered, inside a clipped box that scrolls by whole rows. Items may have
+different heights, and the item at the top edge may be partially visible.
+
+Until the first layout pass has measured the viewport, every item is rendered
+inside the clipped box so the first frame already looks right.
+*/
+function VirtualList({ items, itemHeight, renderItem, getKey, focusedIndex, height }) {
+	const ref = useRef(null);
+	const [measured, setMeasured] = useState();
+	const measure = () => {
+		const next = ref.current?.yogaNode?.getComputedHeight();
+		if (next !== void 0) setMeasured((previous) => previous === next ? previous : next);
+	};
+	useLayoutEffect(() => {
+		if (height === void 0) measure();
+	});
+	useEffect(() => {
+		if (height !== void 0) return;
+		const root = rootOf(ref.current);
+		return root ? addLayoutListener(root, measure) : void 0;
+	});
+	const viewportHeight = height ?? measured;
+	const windowed = viewportHeight !== void 0;
+	const window = useVirtualScroll({
+		count: items.length,
+		itemHeight: (index) => itemHeight(items[index], index),
+		viewportHeight: viewportHeight ?? 0,
+		focusedIndex: windowed ? focusedIndex : void 0
+	});
+	const start = windowed ? window.start : 0;
+	const end = windowed ? window.end : items.length;
+	const offset = windowed ? window.offset : 0;
+	return /* @__PURE__ */ jsx(Box, {
+		ref,
+		flexDirection: "column",
+		overflowY: "hidden",
+		...height === void 0 ? {
+			height: window.totalHeight,
+			minHeight: 0,
+			flexShrink: 1
+		} : {
+			height,
+			flexShrink: 0
+		},
+		children: /* @__PURE__ */ jsx(Box, {
+			flexDirection: "column",
+			flexShrink: 0,
+			marginTop: offset,
+			children: items.slice(start, end).map((item, sliceIndex) => {
+				const index = start + sliceIndex;
+				return /* @__PURE__ */ jsx(Box, {
+					flexDirection: "column",
+					flexShrink: 0,
+					children: renderItem(item, index)
+				}, getKey ? getKey(item, index) : index);
+			})
+		})
+	});
+}
+//#endregion
 //#region src/hooks/use-capabilities.ts
 /**
 Returns everything knowable about the terminal: size, identity, platform,
@@ -3026,4 +3201,4 @@ const measureElement = (node) => {
 	};
 };
 //#endregion
-export { AnsiText, Box, Hyperlink, Newline, Spacer, Static, Text, Transform, applyTerminalQuery, capabilities, createSupportsColor, detectCapabilities, detectColorLevel, detectHyperlinkSupport, detectTerminal, detectUnicodeSupport, getCapabilities, getTerminalQuery, kittyFlags, kittyModifiers, measureElement, queryTerminal, refreshTerminalQuery, render, renderToString, useAnimation, useApp, useBoxMetrics, useCapabilities, useCapabilitiesChange, useClipboard, useCursor, useFocus, useFocusManager, useInput, useIsScreenReaderEnabled, useNotification, usePaste, usePointerShape, useProgress, useStderr, useStdin, useStdout, useTitle, useWindowSize, useWorkingDirectory };
+export { AnsiText, Box, Hyperlink, Newline, Spacer, Static, Text, Transform, VirtualList, applyTerminalQuery, capabilities, createSupportsColor, detectCapabilities, detectColorLevel, detectHyperlinkSupport, detectTerminal, detectUnicodeSupport, getCapabilities, getTerminalQuery, kittyFlags, kittyModifiers, measureElement, queryTerminal, refreshTerminalQuery, render, renderToString, useAnimation, useApp, useBoxMetrics, useCapabilities, useCapabilitiesChange, useClipboard, useCursor, useFocus, useFocusManager, useInput, useIsScreenReaderEnabled, useNotification, usePaste, usePointerShape, useProgress, useStderr, useStdin, useStdout, useTitle, useVirtualScroll, useWindowSize, useWorkingDirectory };

package/dist/router.js

@@ -1,4 +1,4 @@
-import { f as Text, n as useInput, t as useFocus } from "./use-focus-BNG0xsb7.js";
+import { f as Text, n as useInput, t as useFocus } from "./use-focus-Basd0ksv.js";
 import { Children, Fragment, createContext, isValidElement, startTransition, useCallback, useContext, useEffect, useLayoutEffect, useMemo, useRef, useState } from "react";
 import { Fragment as Fragment$1, jsx } from "react/jsx-runtime";
 //#region src/router/history.ts

package/dist/{use-focus-BNG0xsb7.js → use-focus-Basd0ksv.js}

@@ -564,7 +564,7 @@ const detectKittySupport = (stdin, stdout, onSupported) => {
 //#endregion
 //#region package.json
 var name = "@alchemy.run/sigil";
-var version = "0.0.0-alpha.8";
+var version = "0.0.0-alpha.9";
 //#endregion
 //#region src/reconciler.ts
 if (isSigilDev) await import("./devtools-DbthxoD1.js").catch(() => {});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alchemy.run/sigil",
-  "version": "0.0.0-alpha.8",
+  "version": "0.0.0-alpha.9",
   "description": "React for CLIs. A self-contained fork of Ink with an integrated TypeScript Yoga layout engine.",
   "keywords": [
     "cli",

package/src/components/VirtualList.tsx

@@ -0,0 +1,128 @@
+/** @jsxImportSource react */
+import { useEffect, useLayoutEffect, useRef, useState, type Key, type ReactNode } from "react";
+
+import { Box } from "#/components/Box.tsx";
+import { addLayoutListener, type DOMElement } from "#/dom.ts";
+import { useVirtualScroll } from "#/hooks/use-virtual-scroll.ts";
+
+export type Props<Item> = {
+  /**
+	Items to window over.
+	*/
+  readonly items: ReadonlyArray<Item>;
+
+  /**
+	Height of an item in rows. It must match what `renderItem` produces for it:
+	the window is computed from these numbers, never from the rendered output.
+	*/
+  readonly itemHeight: (item: Item, index: number) => number;
+
+  /**
+	Render one item. Only items intersecting the viewport are rendered.
+	*/
+  readonly renderItem: (item: Item, index: number) => ReactNode;
+
+  /**
+	React key for an item. Defaults to its index.
+	*/
+  readonly getKey?: (item: Item, index: number) => Key;
+
+  /**
+	Item to keep fully visible. When it changes, the list scrolls as little as
+	necessary to show it.
+	*/
+  readonly focusedIndex?: number;
+
+  /**
+	Viewport height in rows. When omitted the list takes the height of its
+	content and shrinks to whatever space its container leaves: bound an
+	ancestor (`height` or `maxHeight`) and give the siblings that must keep
+	their size `flexShrink={0}`.
+	*/
+  readonly height?: number;
+};
+
+const rootOf = (node: DOMElement | null): DOMElement | undefined => {
+  let current = node;
+  while (current?.parentNode) {
+    current = current.parentNode;
+  }
+  return current?.nodeName === "ink-root" ? current : undefined;
+};
+
+/**
+A vertically windowed list: only the items intersecting the viewport are
+rendered, inside a clipped box that scrolls by whole rows. Items may have
+different heights, and the item at the top edge may be partially visible.
+
+Until the first layout pass has measured the viewport, every item is rendered
+inside the clipped box so the first frame already looks right.
+*/
+export function VirtualList<Item>({
+  items,
+  itemHeight,
+  renderItem,
+  getKey,
+  focusedIndex,
+  height,
+}: Props<Item>) {
+  const ref = useRef<DOMElement>(null);
+  const [measured, setMeasured] = useState<number>();
+
+  const measure = () => {
+    const next = ref.current?.yogaNode?.getComputedHeight();
+    if (next !== undefined) {
+      setMeasured((previous) => (previous === next ? previous : next));
+    }
+  };
+
+  // Yoga has laid out the tree by the time layout effects run, so the height
+  // this box ended up with is readable synchronously after every commit.
+  useLayoutEffect(() => {
+    if (height === undefined) measure();
+  });
+
+  // Sibling-driven changes (a resize, chrome growing) re-layout without
+  // re-rendering this component; follow the root's layout commits for those.
+  useEffect(() => {
+    if (height !== undefined) return;
+    const root = rootOf(ref.current);
+    return root ? addLayoutListener(root, measure) : undefined;
+  });
+
+  const viewportHeight = height ?? measured;
+  const windowed = viewportHeight !== undefined;
+  const window = useVirtualScroll({
+    count: items.length,
+    itemHeight: (index) => itemHeight(items[index]!, index),
+    viewportHeight: viewportHeight ?? 0,
+    // Following the focus against an unmeasured (zero-row) viewport would pin
+    // the item to the top; wait for the real height so it moves minimally.
+    focusedIndex: windowed ? focusedIndex : undefined,
+  });
+  const start = windowed ? window.start : 0;
+  const end = windowed ? window.end : items.length;
+  const offset = windowed ? window.offset : 0;
+
+  return (
+    <Box
+      ref={ref}
+      flexDirection="column"
+      overflowY="hidden"
+      {...(height === undefined
+        ? { height: window.totalHeight, minHeight: 0, flexShrink: 1 }
+        : { height, flexShrink: 0 })}
+    >
+      <Box flexDirection="column" flexShrink={0} marginTop={offset}>
+        {items.slice(start, end).map((item, sliceIndex) => {
+          const index = start + sliceIndex;
+          return (
+            <Box key={getKey ? getKey(item, index) : index} flexDirection="column" flexShrink={0}>
+              {renderItem(item, index)}
+            </Box>
+          );
+        })}
+      </Box>
+    </Box>
+  );
+}

package/src/hooks/use-virtual-scroll.ts

@@ -0,0 +1,84 @@
+import { useCallback, useEffect, useState } from "react";
+
+import {
+  virtualScrollWindow,
+  type VirtualScrollOptions,
+  type VirtualScrollWindow,
+} from "#/virtual-scroll.ts";
+
+export type UseVirtualScrollOptions = Omit<VirtualScrollOptions, "scrollTop">;
+
+export type UseVirtualScrollResult = VirtualScrollWindow & {
+  /**
+	Scroll so the viewport starts `top` rows from the top of the list.
+	*/
+  readonly scrollTo: (top: number) => void;
+
+  /**
+	Scroll by `delta` rows; negative values scroll up.
+	*/
+  readonly scrollBy: (delta: number) => void;
+};
+
+/**
+A React hook that owns the scroll position of a windowed list and returns which
+items to render for it. The position is clamped to the scrollable range and,
+while `focusedIndex` is set, moved as little as necessary to keep that item
+fully visible. Render the items in `[start, end)` inside an `overflowY="hidden"`
+box of `viewportHeight` rows, shifted up by `offset` rows.
+
+`<VirtualList>` wraps this hook; use it directly to draw your own chrome such
+as overflow markers or a scrollbar around the window.
+
+@example
+```tsx
+import { Box, Text, useVirtualScroll } from "@alchemy.run/sigil";
+
+const Example = ({ lines, cursor }: { lines: string[]; cursor: number }) => {
+	const { start, end, offset, hiddenAbove, hiddenBelow } = useVirtualScroll({
+		count: lines.length,
+		itemHeight: () => 1,
+		viewportHeight: 10,
+		focusedIndex: cursor,
+	});
+
+	return (
+		<Box flexDirection="column">
+			<Text dimColor>{hiddenAbove > 0 ? `↑ ${hiddenAbove} more` : ""}</Text>
+			<Box flexDirection="column" height={10} overflowY="hidden">
+				<Box flexDirection="column" flexShrink={0} marginTop={offset}>
+					{lines.slice(start, end).map((line, index) => (
+						<Text key={start + index} inverse={start + index === cursor}>
+							{line}
+						</Text>
+					))}
+				</Box>
+			</Box>
+			<Text dimColor>{hiddenBelow > 0 ? `↓ ${hiddenBelow} more` : ""}</Text>
+		</Box>
+	);
+};
+```
+*/
+export const useVirtualScroll = (options: UseVirtualScrollOptions): UseVirtualScrollResult => {
+  const [position, setPosition] = useState(0);
+  const window = virtualScrollWindow({ ...options, scrollTop: position });
+
+  // Persist clamping and follow-focus corrections so the next scroll starts
+  // from where the viewport actually is, not from the stale request.
+  useEffect(() => {
+    if (window.scrollTop !== position) {
+      setPosition(window.scrollTop);
+    }
+  }, [window.scrollTop, position]);
+
+  const scrollTo = useCallback((top: number) => {
+    setPosition(top);
+  }, []);
+
+  const scrollBy = useCallback((delta: number) => {
+    setPosition((current) => current + delta);
+  }, []);
+
+  return { ...window, scrollTo, scrollBy };
+};

package/src/index.ts

@@ -22,6 +22,8 @@ export { Hyperlink } from "#/components/Hyperlink.tsx";
 export type { Props as NewlineProps } from "#/components/Newline.tsx";
 export { Newline } from "#/components/Newline.tsx";
 export { Spacer } from "#/components/Spacer.tsx";
+export type { Props as VirtualListProps } from "#/components/VirtualList.tsx";
+export { VirtualList } from "#/components/VirtualList.tsx";
 // Keep the Ink-compatible root surface fixed. New terminal-core APIs live on
 // their focused subpaths rather than leaking through this entry point.
 export type {
@@ -80,6 +82,12 @@ export type { WindowSize } from "#/hooks/use-window-size.ts";
 export { useWindowSize } from "#/hooks/use-window-size.ts";
 export type { BoxMetrics, UseBoxMetricsResult } from "#/hooks/use-box-metrics.ts";
 export { useBoxMetrics } from "#/hooks/use-box-metrics.ts";
+export type { VirtualScrollWindow } from "#/virtual-scroll.ts";
+export type {
+  UseVirtualScrollOptions,
+  UseVirtualScrollResult,
+} from "#/hooks/use-virtual-scroll.ts";
+export { useVirtualScroll } from "#/hooks/use-virtual-scroll.ts";
 export type { CursorPosition } from "#/cursor-position.ts";
 export { measureElement } from "#/measure-element.ts";
 export type { ElementMetrics } from "#/measure-element.ts";

package/src/virtual-scroll.ts

@@ -0,0 +1,133 @@
+/**
+Windowing math shared by `useVirtualScroll` and `<VirtualList>`.
+
+Items are stacked vertically and measured in terminal rows. The viewport shows
+`viewportHeight` rows of that stack starting `scrollTop` rows from the top.
+*/
+export type VirtualScrollOptions = {
+  /**
+	Number of items in the list.
+	*/
+  readonly count: number;
+
+  /**
+	Height of the item at `index` in rows. It must match what the item renders:
+	the window is computed from these numbers, never from the rendered output.
+	*/
+  readonly itemHeight: (index: number) => number;
+
+  /**
+	Rows available to show items.
+	*/
+  readonly viewportHeight: number;
+
+  /**
+	Requested distance of the viewport from the top of the list in rows. It is
+	clamped to the scrollable range and then moved as little as necessary to keep
+	`focusedIndex` fully visible.
+	*/
+  readonly scrollTop: number;
+
+  /**
+	Item that must stay fully visible. An item taller than the viewport is aligned
+	to the top. Out-of-range values are ignored.
+	*/
+  readonly focusedIndex?: number;
+};
+
+export type VirtualScrollWindow = {
+  /**
+	Index of the first item that intersects the viewport.
+	*/
+  readonly start: number;
+
+  /**
+	Index after the last item that intersects the viewport.
+	*/
+  readonly end: number;
+
+  /**
+	Effective distance of the viewport from the top of the list in rows.
+	*/
+  readonly scrollTop: number;
+
+  /**
+	Largest `scrollTop` that still fills the viewport.
+	*/
+  readonly maxScrollTop: number;
+
+  /**
+	Height of every item combined in rows.
+	*/
+  readonly totalHeight: number;
+
+  /**
+	Position of the `start` item relative to the top of the viewport. Zero or
+	negative: a negative value means the item is partially scrolled out above.
+	*/
+  readonly offset: number;
+
+  /**
+	Rows scrolled out above the viewport.
+	*/
+  readonly hiddenAbove: number;
+
+  /**
+	Rows left below the viewport.
+	*/
+  readonly hiddenBelow: number;
+};
+
+const clamp = (value: number, min: number, max: number): number =>
+  Math.min(Math.max(value, min), max);
+
+const wholeRows = (value: number): number => Math.max(0, Math.floor(value)) || 0;
+
+/**
+Compute which items intersect a viewport over a vertical stack of items.
+*/
+export const virtualScrollWindow = (options: VirtualScrollOptions): VirtualScrollWindow => {
+  const count = wholeRows(options.count);
+  const viewportHeight = wholeRows(options.viewportHeight);
+
+  const tops: number[] = [];
+  let totalHeight = 0;
+  for (let index = 0; index < count; index++) {
+    tops.push(totalHeight);
+    totalHeight += wholeRows(options.itemHeight(index));
+  }
+  const bottomOf = (index: number): number => (index + 1 < count ? tops[index + 1]! : totalHeight);
+
+  const maxScrollTop = Math.max(0, totalHeight - viewportHeight);
+  let scrollTop = clamp(Math.floor(options.scrollTop) || 0, 0, maxScrollTop);
+
+  const focused = options.focusedIndex;
+  if (focused !== undefined && Number.isInteger(focused) && focused >= 0 && focused < count) {
+    const top = tops[focused]!;
+    const bottom = bottomOf(focused);
+    if (top < scrollTop) {
+      scrollTop = top;
+    } else if (bottom > scrollTop + viewportHeight) {
+      // Align the bottom edge; an item taller than the viewport shows its top.
+      scrollTop = Math.min(top, bottom - viewportHeight);
+    }
+    scrollTop = clamp(scrollTop, 0, maxScrollTop);
+  }
+
+  const viewportBottom = scrollTop + viewportHeight;
+  let start = 0;
+  while (start < count && bottomOf(start) <= scrollTop) start++;
+  let end = start;
+  while (end < count && tops[end]! < viewportBottom) end++;
+
+  return {
+    start,
+    end,
+    scrollTop,
+    maxScrollTop,
+    totalHeight,
+    offset: start < end ? tops[start]! - scrollTop : 0,
+    hiddenAbove: scrollTop,
+    hiddenBelow: Math.max(0, totalHeight - viewportBottom),
+  };
+};