@alchemy.run/sigil 0.0.0-alpha.1 → 0.0.0-alpha.10

package/README.md

@@ -1,7 +1,3 @@
-[![](https://raw.githubusercontent.com/vshymanskyy/StandWithUkraine/main/banner2-direct.svg)](https://github.com/vshymanskyy/StandWithUkraine/blob/main/docs/README.md)
-
----
-
 <div align="center">
 	<br>
 	<h1>Sigil</h1>
@@ -15,13 +11,29 @@
 - **Self-contained**: the only runtime dependencies are `react-reconciler` and `scheduler`. Everything else — the ANSI/terminal subsystem (`src/ansi/`), styling, width measurement, wrapping — is first-class TypeScript in this repository.
 - **Integrated layout engine**: layout is computed by a TypeScript port of [Yoga](https://github.com/facebook/yoga) (`src/yoga/`) instead of the Yoga WASM binary, continuously verified against an f64-patched reference Yoga build via differential fuzzing.
 - **Modern toolchain**: built with [Vite+](https://viteplus.dev) (Vitest, Oxlint, Oxfmt, tsdown) and TypeScript 7.
+- **Structured terminal core**: cells retain semantic colors, gradients, links, and graphemes through layout and composition, then serialize for the target terminal profile.
+
+Low-level integrations are available through focused `ansi`, `capabilities`, `color`, `router`, `screen`, `terminal`, and `yoga` subpaths. See the [architecture guide](docs/architecture.md), [API stability policy](docs/api-stability.md), [color semantics](docs/color-semantics.md), and [performance notes](docs/performance.md).
 
 Upstream Ink and Yoga are tracked as submodules in `.vendor/` — upstream's test suites run against this codebase as part of the regular test run. See `THIRD_PARTY_NOTICES.md` for attribution.
 
-The documentation below is inherited from Ink; the API is unchanged apart from imports
+The familiar Ink component and hook surface remains available from the package root. Sigil also adds terminal-aware APIs described below. The longer API reference is inherited from Ink and uses Sigil imports where applicable.
+
+## Sigil extensions
+
+- **Structured rendering** — layout produces a semantic `Screen` of grapheme-aware cells before terminal-specific ANSI serialization. Import low-level primitives from `@alchemy.run/sigil/screen`, `@alchemy.run/sigil/color`, and `@alchemy.run/sigil/terminal`.
+- **Terminal capabilities** — `getCapabilities()` returns the current snapshot, while `capabilities.subscribe()` and `useCapabilitiesChange()` observe live terminal reports. The framework-free API is available from `@alchemy.run/sigil/capabilities`.
+- **Terminal integrations** — `<Hyperlink>` provides OSC 8 links with a fallback. `useTitle`, `useWorkingDirectory`, `useProgress`, `useNotification`, `useClipboard`, and `usePointerShape` manage session-scoped OSC state.
+- **ANSI-aware text** — `<AnsiText>` interprets ANSI-styled input without flattening its semantic colors before rendering.
+- **Routing** — `@alchemy.run/sigil/router` provides an in-memory router designed for terminal applications. See the [routing recipe](recipes/routing.md).
+- **Testing** — the repository includes an internal emulator-backed E2E harness and interactive explorer. These utilities are not part of the public API while their design is evolving.
+
+Sigil requires Node.js 22 or newer and React 19.2 or newer.
 
 ---
 
+[![](https://raw.githubusercontent.com/vshymanskyy/StandWithUkraine/main/banner2-direct.svg)](https://github.com/vshymanskyy/StandWithUkraine/blob/main/docs/README.md)
+
 Ink provides the same component-based UI building experience that React offers in the browser, but for command-line apps.
 It uses [Yoga](https://github.com/facebook/yoga) to build Flexbox layouts in the terminal, so most CSS-like properties are available in Ink as well.
 If you are already familiar with React, you already know Ink.
@@ -60,19 +72,19 @@ import React, { useState, useEffect } from "react";
 import { render, Text } from "@alchemy.run/sigil";
 
 const Counter = () => {
-	const [counter, setCounter] = useState(0);
+  const [counter, setCounter] = useState(0);
 
-	useEffect(() => {
-		const timer = setInterval(() => {
-			setCounter((previousCounter) => previousCounter + 1);
-		}, 100);
+  useEffect(() => {
+    const timer = setInterval(() => {
+      setCounter((previousCounter) => previousCounter + 1);
+    }, 100);
 
-		return () => {
-			clearInterval(timer);
-		};
-	}, []);
+    return () => {
+      clearInterval(timer);
+    };
+  }, []);
 
-	return <Text color="green">{counter} tests passed</Text>;
+  return <Text color="green">{counter} tests passed</Text>;
 };
 
 render(<Counter />);
@@ -152,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)
@@ -159,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)
@@ -202,7 +216,7 @@ npm install --save-dev @babel/preset-react
 
 ```json
 {
-	"presets": ["@babel/preset-react"]
+  "presets": ["@babel/preset-react"]
 }
 ```
 
@@ -266,18 +280,18 @@ This component can display text and change its style to make it bold, underlined
 import { render, Text } from "@alchemy.run/sigil";
 
 const Example = () => (
-	<>
-		<Text color="green">I am green</Text>
-		<Text color="black" backgroundColor="white">
-			I am black on white
-		</Text>
-		<Text color="#ffffff">I am white</Text>
-		<Text bold>I am bold</Text>
-		<Text italic>I am italic</Text>
-		<Text underline>I am underline</Text>
-		<Text strikethrough>I am strikethrough</Text>
-		<Text inverse>I am inversed</Text>
-	</>
+  <>
+    <Text color="green">I am green</Text>
+    <Text color="black" backgroundColor="white">
+      I am black on white
+    </Text>
+    <Text color="#ffffff">I am white</Text>
+    <Text bold>I am bold</Text>
+    <Text italic>I am italic</Text>
+    <Text underline>I am underline</Text>
+    <Text strikethrough>I am strikethrough</Text>
+    <Text inverse>I am inversed</Text>
+  </>
 );
 
 render(<Example />);
@@ -324,7 +338,7 @@ Dim the color (make it less bright).
 
 ```jsx
 <Text color="red" dimColor>
-	Dimmed Red
+  Dimmed Red
 </Text>
 ```
 
@@ -367,7 +381,7 @@ Invert background and foreground colors.
 
 ```jsx
 <Text inverse color="yellow">
-	Inversed Yellow
+  Inversed Yellow
 </Text>
 ```
 
@@ -421,9 +435,9 @@ It's like `<div style="display: flex">` in the browser.
 import { render, Box, Text } from "@alchemy.run/sigil";
 
 const Example = () => (
-	<Box margin={2}>
-		<Text>This is a box with margin</Text>
-	</Box>
+  <Box margin={2}>
+    <Text>This is a box with margin</Text>
+  </Box>
 );
 
 render(<Example />);
@@ -440,17 +454,17 @@ You can also set it as a percentage, which will calculate the width based on the
 
 ```jsx
 <Box width={4}>
-	<Text>X</Text>
+  <Text>X</Text>
 </Box>
 //=> 'X   '
 ```
 
 ```jsx
 <Box width={10}>
-	<Box width="50%">
-		<Text>X</Text>
-	</Box>
-	<Text>Y</Text>
+  <Box width="50%">
+    <Text>X</Text>
+  </Box>
+  <Text>Y</Text>
 </Box>
 //=> 'X    Y'
 ```
@@ -464,17 +478,17 @@ You can also set it as a percentage, which will calculate the height based on th
 
 ```jsx
 <Box height={4}>
-	<Text>X</Text>
+  <Text>X</Text>
 </Box>
 //=> 'X\n\n\n'
 ```
 
 ```jsx
 <Box height={6} flexDirection="column">
-	<Box height="50%">
-		<Text>X</Text>
-	</Box>
-	<Text>Y</Text>
+  <Box height="50%">
+    <Text>X</Text>
+  </Box>
+  <Text>Y</Text>
 </Box>
 //=> 'X\n\n\nY\n\n'
 ```
@@ -648,9 +662,9 @@ Size of the gap between an element's columns and rows. A shorthand for `columnGa
 
 ```jsx
 <Box gap={1} width={3} flexWrap="wrap">
-	<Text>A</Text>
-	<Text>B</Text>
-	<Text>C</Text>
+  <Text>A</Text>
+  <Text>B</Text>
+  <Text>C</Text>
 </Box>
 // A B
 //
@@ -666,8 +680,8 @@ Size of the gap between an element's columns.
 
 ```jsx
 <Box columnGap={1}>
-	<Text>A</Text>
-	<Text>B</Text>
+  <Text>A</Text>
+  <Text>B</Text>
 </Box>
 // A B
 ```
@@ -681,8 +695,8 @@ Size of the gap between an element's rows.
 
 ```jsx
 <Box flexDirection="column" rowGap={1}>
-	<Text>A</Text>
-	<Text>B</Text>
+  <Text>A</Text>
+  <Text>B</Text>
 </Box>
 // A
 //
@@ -700,10 +714,10 @@ See [flex-grow](https://css-tricks.com/almanac/properties/f/flex-grow/).
 
 ```jsx
 <Box>
-	<Text>Label:</Text>
-	<Box flexGrow={1}>
-		<Text>Fills all remaining space</Text>
-	</Box>
+  <Text>Label:</Text>
+  <Box flexGrow={1}>
+    <Text>Fills all remaining space</Text>
+  </Box>
 </Box>
 ```
 
@@ -716,12 +730,12 @@ See [flex-shrink](https://css-tricks.com/almanac/properties/f/flex-shrink/).
 
 ```jsx
 <Box width={20}>
-	<Box flexShrink={2} width={10}>
-		<Text>Will be 1/4</Text>
-	</Box>
-	<Box width={10}>
-		<Text>Will be 3/4</Text>
-	</Box>
+  <Box flexShrink={2} width={10}>
+    <Text>Will be 1/4</Text>
+  </Box>
+  <Box width={10}>
+    <Text>Will be 3/4</Text>
+  </Box>
 </Box>
 ```
 
@@ -733,20 +747,20 @@ See [flex-basis](https://css-tricks.com/almanac/properties/f/flex-basis/).
 
 ```jsx
 <Box width={6}>
-	<Box flexBasis={3}>
-		<Text>X</Text>
-	</Box>
-	<Text>Y</Text>
+  <Box flexBasis={3}>
+    <Text>X</Text>
+  </Box>
+  <Text>Y</Text>
 </Box>
 //=> 'X  Y'
 ```
 
 ```jsx
 <Box width={6}>
-	<Box flexBasis="50%">
-		<Text>X</Text>
-	</Box>
-	<Text>Y</Text>
+  <Box flexBasis="50%">
+    <Text>X</Text>
+  </Box>
+  <Text>Y</Text>
 </Box>
 //=> 'X  Y'
 ```
@@ -799,8 +813,8 @@ See [flex-wrap](https://css-tricks.com/almanac/properties/f/flex-wrap/).
 
 ```jsx
 <Box width={2} flexWrap="wrap">
-	<Text>A</Text>
-	<Text>BC</Text>
+  <Text>A</Text>
+  <Text>BC</Text>
 </Box>
 // A
 // B C
@@ -808,9 +822,9 @@ See [flex-wrap](https://css-tricks.com/almanac/properties/f/flex-wrap/).
 
 ```jsx
 <Box flexDirection="column" height={2} flexWrap="wrap">
-	<Text>A</Text>
-	<Text>B</Text>
-	<Text>C</Text>
+  <Text>A</Text>
+  <Text>B</Text>
+  <Text>C</Text>
 </Box>
 // A C
 // B
@@ -1049,37 +1063,37 @@ Ink uses border styles from the [`cli-boxes`](https://github.com/sindresorhus/cl
 
 ```jsx
 <Box flexDirection="column">
-	<Box>
-		<Box borderStyle="single" marginRight={2}>
-			<Text>single</Text>
-		</Box>
-
-		<Box borderStyle="double" marginRight={2}>
-			<Text>double</Text>
-		</Box>
-
-		<Box borderStyle="round" marginRight={2}>
-			<Text>round</Text>
-		</Box>
-
-		<Box borderStyle="bold">
-			<Text>bold</Text>
-		</Box>
-	</Box>
-
-	<Box marginTop={1}>
-		<Box borderStyle="singleDouble" marginRight={2}>
-			<Text>singleDouble</Text>
-		</Box>
-
-		<Box borderStyle="doubleSingle" marginRight={2}>
-			<Text>doubleSingle</Text>
-		</Box>
-
-		<Box borderStyle="classic">
-			<Text>classic</Text>
-		</Box>
-	</Box>
+  <Box>
+    <Box borderStyle="single" marginRight={2}>
+      <Text>single</Text>
+    </Box>
+
+    <Box borderStyle="double" marginRight={2}>
+      <Text>double</Text>
+    </Box>
+
+    <Box borderStyle="round" marginRight={2}>
+      <Text>round</Text>
+    </Box>
+
+    <Box borderStyle="bold">
+      <Text>bold</Text>
+    </Box>
+  </Box>
+
+  <Box marginTop={1}>
+    <Box borderStyle="singleDouble" marginRight={2}>
+      <Text>singleDouble</Text>
+    </Box>
+
+    <Box borderStyle="doubleSingle" marginRight={2}>
+      <Text>doubleSingle</Text>
+    </Box>
+
+    <Box borderStyle="classic">
+      <Text>classic</Text>
+    </Box>
+  </Box>
 </Box>
 ```
 
@@ -1089,18 +1103,18 @@ Alternatively, pass a custom border style like so:
 
 ```jsx
 <Box
-	borderStyle={{
-		topLeft: "↘",
-		top: "↓",
-		topRight: "↙",
-		left: "→",
-		bottomLeft: "↗",
-		bottom: "↑",
-		bottomRight: "↖",
-		right: "←",
-	}}
+  borderStyle={{
+    topLeft: "↘",
+    top: "↓",
+    topRight: "↙",
+    left: "→",
+    bottomLeft: "↗",
+    bottom: "↑",
+    bottomRight: "↖",
+    right: "←",
+  }}
 >
-	<Text>Custom</Text>
+  <Text>Custom</Text>
 </Box>
 ```
 
@@ -1115,7 +1129,7 @@ A shorthand for setting `borderTopColor`, `borderRightColor`, `borderBottomColor
 
 ```jsx
 <Box borderStyle="round" borderColor="green">
-	<Text>Green Rounded Box</Text>
+  <Text>Green Rounded Box</Text>
 </Box>
 ```
 
@@ -1130,7 +1144,7 @@ Accepts the same values as [`color`](#color) in `<Text>` component.
 
 ```jsx
 <Box borderStyle="round" borderTopColor="green">
-	<Text>Hello world</Text>
+  <Text>Hello world</Text>
 </Box>
 ```
 
@@ -1143,7 +1157,7 @@ Accepts the same values as [`color`](#color) in `<Text>` component.
 
 ```jsx
 <Box borderStyle="round" borderRightColor="green">
-	<Text>Hello world</Text>
+  <Text>Hello world</Text>
 </Box>
 ```
 
@@ -1156,7 +1170,7 @@ Accepts the same values as [`color`](#color) in `<Text>` component.
 
 ```jsx
 <Box borderStyle="round" borderBottomColor="green">
-	<Text>Hello world</Text>
+  <Text>Hello world</Text>
 </Box>
 ```
 
@@ -1169,7 +1183,7 @@ Accepts the same values as [`color`](#color) in `<Text>` component.
 
 ```jsx
 <Box borderStyle="round" borderLeftColor="green">
-	<Text>Hello world</Text>
+  <Text>Hello world</Text>
 </Box>
 ```
 
@@ -1183,7 +1197,7 @@ A shorthand for setting `borderTopDimColor`, `borderBottomDimColor`, `borderLeft
 
 ```jsx
 <Box borderStyle="round" borderDimColor>
-	<Text>Hello world</Text>
+  <Text>Hello world</Text>
 </Box>
 ```
 
@@ -1196,7 +1210,7 @@ Dim the top border color.
 
 ```jsx
 <Box borderStyle="round" borderTopDimColor>
-	<Text>Hello world</Text>
+  <Text>Hello world</Text>
 </Box>
 ```
 
@@ -1209,7 +1223,7 @@ Dim the bottom border color.
 
 ```jsx
 <Box borderStyle="round" borderBottomDimColor>
-	<Text>Hello world</Text>
+  <Text>Hello world</Text>
 </Box>
 ```
 
@@ -1222,7 +1236,7 @@ Dim the left border color.
 
 ```jsx
 <Box borderStyle="round" borderLeftDimColor>
-	<Text>Hello world</Text>
+  <Text>Hello world</Text>
 </Box>
 ```
 
@@ -1235,7 +1249,7 @@ Dim the right border color.
 
 ```jsx
 <Box borderStyle="round" borderRightDimColor>
-	<Text>Hello world</Text>
+  <Text>Hello world</Text>
 </Box>
 ```
 
@@ -1249,7 +1263,7 @@ A shorthand for setting `borderTopBackgroundColor`, `borderRightBackgroundColor`
 
 ```jsx
 <Box borderStyle="round" borderColor="white" borderBackgroundColor="green">
-	<Text>Hello world</Text>
+  <Text>Hello world</Text>
 </Box>
 ```
 
@@ -1263,7 +1277,7 @@ Falls back to `borderBackgroundColor` if not specified.
 
 ```jsx
 <Box borderStyle="round" borderColor="white" borderTopBackgroundColor="green">
-	<Text>Hello world</Text>
+  <Text>Hello world</Text>
 </Box>
 ```
 
@@ -1277,7 +1291,7 @@ Falls back to `borderBackgroundColor` if not specified.
 
 ```jsx
 <Box borderStyle="round" borderColor="white" borderBottomBackgroundColor="green">
-	<Text>Hello world</Text>
+  <Text>Hello world</Text>
 </Box>
 ```
 
@@ -1291,7 +1305,7 @@ Falls back to `borderBackgroundColor` if not specified.
 
 ```jsx
 <Box borderStyle="round" borderColor="white" borderRightBackgroundColor="green">
-	<Text>Hello world</Text>
+  <Text>Hello world</Text>
 </Box>
 ```
 
@@ -1305,7 +1319,7 @@ Falls back to `borderBackgroundColor` if not specified.
 
 ```jsx
 <Box borderStyle="round" borderColor="white" borderLeftBackgroundColor="green">
-	<Text>Hello world</Text>
+  <Text>Hello world</Text>
 </Box>
 ```
 
@@ -1349,27 +1363,29 @@ Accepts the same values as [`color`](#color) in the `<Text>` component.
 
 ```jsx
 <Box flexDirection="column">
-	<Box backgroundColor="red" width={20} height={5} alignSelf="flex-start">
-		<Text>Red background</Text>
-	</Box>
+  <Box backgroundColor="red" width={20} height={5} alignSelf="flex-start">
+    <Text>Red background</Text>
+  </Box>
 
-	<Box backgroundColor="#FF8800" width={20} height={3} marginTop={1} alignSelf="flex-start">
-		<Text>Orange background</Text>
-	</Box>
+  <Box backgroundColor="#FF8800" width={20} height={3} marginTop={1} alignSelf="flex-start">
+    <Text>Orange background</Text>
+  </Box>
 
-	<Box backgroundColor="rgb(0, 255, 0)" width={20} height={3} marginTop={1} alignSelf="flex-start">
-		<Text>Green background</Text>
-	</Box>
+  <Box backgroundColor="rgb(0, 255, 0)" width={20} height={3} marginTop={1} alignSelf="flex-start">
+    <Text>Green background</Text>
+  </Box>
 </Box>
 ```
 
 The background color fills the entire `<Box>` area and is inherited by child `<Text>` components unless they specify their own `backgroundColor`.
 
+Use `backgroundColor=""` to paint the box with explicit blank cells on the terminal's default background. This is useful for opaque compositor layers: lower-layer glyphs are erased without assuming what color the user's terminal background is. Omitting `backgroundColor` keeps the box transparent.
+
 ```jsx
 <Box backgroundColor="blue" alignSelf="flex-start">
-	<Text>Blue inherited </Text>
-	<Text backgroundColor="yellow">Yellow override </Text>
-	<Text>Blue inherited again</Text>
+  <Text>Blue inherited </Text>
+  <Text backgroundColor="yellow">Yellow override </Text>
+  <Text>Blue inherited again</Text>
 </Box>
 ```
 
@@ -1377,7 +1393,7 @@ Background colors work with borders and padding:
 
 ```jsx
 <Box backgroundColor="cyan" borderStyle="round" padding={1} alignSelf="flex-start">
-	<Text>Background with border and padding</Text>
+  <Text>Background with border and padding</Text>
 </Box>
 ```
 
@@ -1399,11 +1415,11 @@ Number of newlines to insert.
 import { render, Text, Newline } from "@alchemy.run/sigil";
 
 const Example = () => (
-	<Text>
-		<Text color="green">Hello</Text>
-		<Newline />
-		<Text color="red">World</Text>
-	</Text>
+  <Text>
+    <Text color="green">Hello</Text>
+    <Newline />
+    <Text color="red">World</Text>
+  </Text>
 );
 
 render(<Example />);
@@ -1427,11 +1443,11 @@ For example, using `<Spacer>` in a `<Box>` with default flex direction (`row`) w
 import { render, Box, Text, Spacer } from "@alchemy.run/sigil";
 
 const Example = () => (
-	<Box>
-		<Text>Left</Text>
-		<Spacer />
-		<Text>Right</Text>
-	</Box>
+  <Box>
+    <Text>Left</Text>
+    <Spacer />
+    <Text>Right</Text>
+  </Box>
 );
 
 render(<Example />);
@@ -1444,11 +1460,11 @@ Note that the container needs to be tall enough to see this in effect.
 import { render, Box, Text, Spacer } from "@alchemy.run/sigil";
 
 const Example = () => (
-	<Box flexDirection="column" height={10}>
-		<Text>Top</Text>
-		<Spacer />
-		<Text>Bottom</Text>
-	</Box>
+  <Box flexDirection="column" height={10}>
+    <Text>Top</Text>
+    <Spacer />
+    <Text>Bottom</Text>
+  </Box>
 );
 
 render(<Example />);
@@ -1472,51 +1488,51 @@ import React, { useState, useEffect } from "react";
 import { render, Static, Box, Text } from "@alchemy.run/sigil";
 
 const Example = () => {
-	const [tests, setTests] = useState([]);
-
-	useEffect(() => {
-		let completedTests = 0;
-		let timer;
-
-		const run = () => {
-			// Fake 10 completed tests
-			if (completedTests++ < 10) {
-				setTests((previousTests) => [
-					...previousTests,
-					{
-						id: previousTests.length,
-						title: `Test #${previousTests.length + 1}`,
-					},
-				]);
-
-				timer = setTimeout(run, 100);
-			}
-		};
-
-		run();
-
-		return () => {
-			clearTimeout(timer);
-		};
-	}, []);
-
-	return (
-		<>
-			{/* This part will be rendered once to the terminal */}
-			<Static items={tests}>
-				{(test) => (
-					<Box key={test.id}>
-						<Text color="green">✔ {test.title}</Text>
-					</Box>
-				)}
-			</Static>
-
-			{/* This part keeps updating as state changes */}
-			<Box marginTop={1}>
-				<Text dimColor>Completed tests: {tests.length}</Text>
-			</Box>
-		</>
-	);
+  const [tests, setTests] = useState([]);
+
+  useEffect(() => {
+    let completedTests = 0;
+    let timer;
+
+    const run = () => {
+      // Fake 10 completed tests
+      if (completedTests++ < 10) {
+        setTests((previousTests) => [
+          ...previousTests,
+          {
+            id: previousTests.length,
+            title: `Test #${previousTests.length + 1}`,
+          },
+        ]);
+
+        timer = setTimeout(run, 100);
+      }
+    };
+
+    run();
+
+    return () => {
+      clearTimeout(timer);
+    };
+  }, []);
+
+  return (
+    <>
+      {/* This part will be rendered once to the terminal */}
+      <Static items={tests}>
+        {(test) => (
+          <Box key={test.id}>
+            <Text color="green">✔ {test.title}</Text>
+          </Box>
+        )}
+      </Static>
+
+      {/* This part keeps updating as state changes */}
+      <Box marginTop={1}>
+        <Text dimColor>Completed tests: {tests.length}</Text>
+      </Box>
+    </>
+  );
 };
 
 render(<Example />);
@@ -1558,16 +1574,16 @@ Note that a `key` must be assigned to the root component.
 
 ```jsx
 <Static items={["a", "b", "c"]}>
-	{(item, index) => {
-		// This function is called for every item in ['a', 'b', 'c']
-		// `item` is 'a', 'b', 'c'
-		// `index` is 0, 1, 2
-		return (
-			<Box key={index}>
-				<Text>Item: {item}</Text>
-			</Box>
-		);
-	}}
+  {(item, index) => {
+    // This function is called for every item in ['a', 'b', 'c']
+    // `item` is 'a', 'b', 'c'
+    // `index` is 0, 1, 2
+    return (
+      <Box key={index}>
+        <Text>Item: {item}</Text>
+      </Box>
+    );
+  }}
 </Static>
 ```
 
@@ -1588,9 +1604,9 @@ That's what the `<Transform>` component does: it gives you an output string of i
 import { render, Transform } from "@alchemy.run/sigil";
 
 const Example = () => (
-	<Transform transform={(output) => output.toUpperCase()}>
-		<Text>Hello World</Text>
-	</Transform>
+  <Transform transform={(output) => output.toUpperCase()}>
+    <Text>Hello World</Text>
+  </Transform>
 );
 
 render(<Example />);
@@ -1606,18 +1622,18 @@ For example, to implement a hanging indent component, you can indent all the lin
 import { render, Transform } from "@alchemy.run/sigil";
 
 const HangingIndent = ({ indent = 4, children }) => (
-	<Transform transform={(line, index) => (index === 0 ? line : " ".repeat(indent) + line)}>
-		{children}
-	</Transform>
+  <Transform transform={(line, index) => (index === 0 ? line : " ".repeat(indent) + line)}>
+    {children}
+  </Transform>
 );
 
 const text =
-	"WHEN I WROTE the following pages, or rather the bulk of them, " +
-	"I lived alone, in the woods, a mile from any neighbor, in a " +
-	"house which I had built myself, on the shore of Walden Pond, " +
-	"in Concord, Massachusetts, and earned my living by the labor " +
-	"of my hands only. I lived there two years and two months. At " +
-	"present I am a sojourner in civilized life again.";
+  "WHEN I WROTE the following pages, or rather the bulk of them, " +
+  "I lived alone, in the woods, a mile from any neighbor, in a " +
+  "house which I had built myself, on the shore of Walden Pond, " +
+  "in Concord, Massachusetts, and earned my living by the labor " +
+  "of my hands only. I lived there two years and two months. At " +
+  "present I am a sojourner in civilized life again.";
 
 render(<HangingIndent indent={4}>{text}</HangingIndent>);
 ```
@@ -1641,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?)
@@ -1955,7 +2052,7 @@ import { useApp } from "@alchemy.run/sigil";
 const { suspendTerminal } = useApp();
 
 await suspendTerminal(async () => {
-	await runEditor();
+  await runEditor();
 });
 ```
 
@@ -1965,9 +2062,9 @@ When called without a callback, it returns a suspension you resume yourself. `re
 const suspension = await suspendTerminal();
 
 try {
-	await runEditor();
+  await runEditor();
 } finally {
-	await suspension.resume();
+  await suspension.resume();
 }
 ```
 
@@ -2013,9 +2110,9 @@ A component using `setRawMode` might want to use `isRawModeSupported` to nicely
 import { useStdin } from "@alchemy.run/sigil";
 
 const Example = () => {
-	const { isRawModeSupported } = useStdin();
+  const { isRawModeSupported } = useStdin();
 
-	return isRawModeSupported ? <MyInputComponent /> : <MyComponentThatDoesntUseInput />;
+  return isRawModeSupported ? <MyInputComponent /> : <MyComponentThatDoesntUseInput />;
 };
 ```
 
@@ -2116,14 +2213,14 @@ import { useRef } from "react";
 import { Box, Text, useBoxMetrics } from "@alchemy.run/sigil";
 
 const Example = () => {
-	const ref = useRef(null);
-	const { width, height, left, top, hasMeasured } = useBoxMetrics(ref);
-
-	return (
-		<Box ref={ref}>
-			<Text>{hasMeasured ? `${width}x${height} at ${left},${top}` : "Measuring..."}</Text>
-		</Box>
-	);
+  const ref = useRef(null);
+  const { width, height, left, top, hasMeasured } = useBoxMetrics(ref);
+
+  return (
+    <Box ref={ref}>
+      <Text>{hasMeasured ? `${width}x${height} at ${left},${top}` : "Measuring..."}</Text>
+    </Box>
+  );
 };
 ```
 
@@ -2160,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.
@@ -2217,13 +2407,13 @@ A React hook that returns the current terminal dimensions and re-renders the com
 import { Text, useWindowSize } from "@alchemy.run/sigil";
 
 const Example = () => {
-	const { columns, rows } = useWindowSize();
+  const { columns, rows } = useWindowSize();
 
-	return (
-		<Text>
-			{columns}x{rows}
-		</Text>
-	);
+  return (
+    <Text>
+      {columns}x{rows}
+    </Text>
+  );
 };
 ```
 
@@ -2240,7 +2430,7 @@ Type: `number`
 Number of rows (vertical character cells).
 
 > [!NOTE]
-> When the terminal is resized narrower, ghost lines may briefly appear depending on the terminal emulator's reflow behavior.
+> On terminals that send in-band size reports (mode 2048, e.g. Ghostty, kitty, foot) the frame is repainted as soon as the report arrives, since the emulator has already rewrapped by then. Elsewhere the size comes from the PTY, which can run ahead of or behind the emulator, so resize events are coalesced: the frame is erased and repainted about 50 ms after the size stops changing and is briefly absent during a window drag. Painting mid-rewrap is what leaves ghost rows behind.
 
 ### useFocus(options?)
 
@@ -2277,9 +2467,9 @@ Set a component's focus ID, which can be used to programmatically focus the comp
 import { render, useFocus, Text } from "@alchemy.run/sigil";
 
 const Example = () => {
-	const { isFocused } = useFocus();
+  const { isFocused } = useFocus();
 
-	return <Text>{isFocused ? "I am focused" : "I am not focused"}</Text>;
+  return <Text>{isFocused ? "I am focused" : "I am not focused"}</Text>;
 };
 
 render(<Example />);
@@ -2413,9 +2603,9 @@ The ID of the currently focused component, or `undefined` if no component is foc
 import { Text, useFocusManager } from "@alchemy.run/sigil";
 
 const Example = () => {
-	const { activeId } = useFocusManager();
+  const { activeId } = useFocusManager();
 
-	return <Text>Focused: {activeId ?? "none"}</Text>;
+  return <Text>Focused: {activeId ?? "none"}</Text>;
 };
 ```
 
@@ -2430,21 +2620,21 @@ import { Box, Text, useCursor } from "@alchemy.run/sigil";
 import stringWidth from "string-width";
 
 const TextInput = () => {
-	const [text, setText] = useState("");
-	const { setCursorPosition } = useCursor();
-
-	const prompt = "> ";
-	setCursorPosition({ x: stringWidth(prompt + text), y: 1 });
-
-	return (
-		<Box flexDirection="column">
-			<Text>Type here:</Text>
-			<Text>
-				{prompt}
-				{text}
-			</Text>
-		</Box>
-	);
+  const [text, setText] = useState("");
+  const { setCursorPosition } = useCursor();
+
+  const prompt = "> ";
+  setCursorPosition({ x: stringWidth(prompt + text), y: 1 });
+
+  return (
+    <Box flexDirection="column">
+      <Text>Type here:</Text>
+      <Text>
+        {prompt}
+        {text}
+      </Text>
+    </Box>
+  );
 };
 ```
 
@@ -2481,11 +2671,11 @@ This is useful when you want to render different output for screen readers.
 import { useIsScreenReaderEnabled, Text } from "@alchemy.run/sigil";
 
 const Example = () => {
-	const isScreenReaderEnabled = useIsScreenReaderEnabled();
+  const isScreenReaderEnabled = useIsScreenReaderEnabled();
 
-	return (
-		<Text>{isScreenReaderEnabled ? "Screen reader is enabled" : "Screen reader is disabled"}</Text>
-	);
+  return (
+    <Text>{isScreenReaderEnabled ? "Screen reader is enabled" : "Screen reader is disabled"}</Text>
+  );
 };
 ```
 
@@ -2497,10 +2687,10 @@ A React hook that drives animations. Returns a frame counter, elapsed time, fram
 import { Text, useAnimation } from "@alchemy.run/sigil";
 
 const Spinner = () => {
-	const { frame } = useAnimation({ interval: 80 });
-	const characters = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
+  const { frame } = useAnimation({ interval: 80 });
+  const characters = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
 
-	return <Text>{characters[frame % characters.length]}</Text>;
+  return <Text>{characters[frame % characters.length]}</Text>;
 };
 ```
 
@@ -2622,11 +2812,11 @@ Return `true` to take ownership of a chunk: Ink will not display it, letting the
 const [transcript, setTranscript] = useState([]);
 
 render(<App transcript={transcript} />, {
-	patchConsole: "stdio",
-	onCapturedOutput(stream, data) {
-		setTranscript((previous) => [...previous, { stream, data }]);
-		return true;
-	},
+  patchConsole: "stdio",
+  onCapturedOutput(stream, data) {
+    setTranscript((previous) => [...previous, { stream, data }]);
+    return true;
+  },
 });
 ```
 
@@ -2642,7 +2832,7 @@ To run code after output is flushed, use [`waitUntilRenderFlush()`](#waituntilre
 ###### isScreenReaderEnabled
 
 Type: `boolean`\
-Default: `process.env['INK_SCREEN_READER'] === 'true'`
+Default: `process.env['SIGIL_SCREEN_READER'] === 'true'`
 
 Enable screen reader support. See [Screen Reader Support](#screen-reader-support).
 
@@ -2663,14 +2853,6 @@ This controls how frequently the UI can update to prevent excessive re-rendering
 Higher values allow more frequent updates but may impact performance.
 Setting it to a lower value may be useful for components that update very frequently, to reduce CPU usage.
 
-###### incrementalRendering
-
-Type: `boolean`\
-Default: `false`
-
-Enable incremental rendering mode which only updates changed lines instead of redrawing the entire output.
-This can reduce flickering and improve performance for frequently updating UIs.
-
 ###### concurrent
 
 Type: `boolean`\
@@ -2748,10 +2930,10 @@ render(<MyApp />, { kittyKeyboard: { mode: "auto" } });
 import { render } from "@alchemy.run/sigil";
 
 render(<MyApp />, {
-	kittyKeyboard: {
-		mode: "enabled",
-		flags: ["disambiguateEscapeCodes", "reportEventTypes"],
-	},
+  kittyKeyboard: {
+    mode: "enabled",
+    flags: ["disambiguateEscapeCodes", "reportEventTypes"],
+  },
 });
 ```
 
@@ -2803,9 +2985,9 @@ Useful for generating documentation, writing output to files, testing, or any sc
 import { renderToString, Text, Box } from "@alchemy.run/sigil";
 
 const output = renderToString(
-	<Box padding={1}>
-		<Text color="green">Hello World</Text>
-	</Box>,
+  <Box padding={1}>
+    <Text color="green">Hello World</Text>
+  </Box>,
 );
 
 console.log(output);
@@ -2836,7 +3018,7 @@ Width of the virtual terminal in columns. Controls where text wrapping occurs.
 
 ```jsx
 const output = renderToString(<Text>{"A".repeat(100)}</Text>, {
-	columns: 40,
+  columns: 40,
 });
 // Text wraps at 40 columns
 ```
@@ -2938,20 +3120,20 @@ See [Refs](https://reactjs.org/docs/refs-and-the-dom.html) for more information
 import { render, measureElement, Box, Text } from "@alchemy.run/sigil";
 
 const Example = () => {
-	const ref = useRef();
-
-	useEffect(() => {
-		const { x, y, width, height } = measureElement(ref.current);
-		// x = 0, y = 0, width = 100, height = 1
-	}, []);
-
-	return (
-		<Box width={100}>
-			<Box ref={ref}>
-				<Text>This box will stretch to 100 width</Text>
-			</Box>
-		</Box>
-	);
+  const ref = useRef();
+
+  useEffect(() => {
+    const { x, y, width, height } = measureElement(ref.current);
+    // x = 0, y = 0, width = 100, height = 1
+  }, []);
+
+  return (
+    <Box width={100}>
+      <Box ref={ref}>
+        <Text>This box will stretch to 100 width</Text>
+      </Box>
+    </Box>
+  );
 };
 
 render(<Example />);
@@ -2979,10 +3161,10 @@ Check out [ink-testing-library](https://github.com/vadimdemedes/ink-testing-libr
 
 ![](media/devtools.jpg)
 
-Ink supports [React Devtools](https://github.com/facebook/react/tree/master/packages/react-devtools) out of the box. To enable integration with React Devtools in your Ink-based CLI, first ensure you have installed the optional `react-devtools-core` dependency, and then run your app with the `DEV=true` environment variable:
+Ink supports [React Devtools](https://github.com/facebook/react/tree/master/packages/react-devtools) out of the box. To enable integration with React Devtools in your Ink-based CLI, first ensure you have installed the optional `react-devtools-core` dependency, and then run your app with the `SIGIL_DEV=true` environment variable:
 
 ```sh
-DEV=true my-cli
+SIGIL_DEV=true my-cli
 ```
 
 Then, start React Devtools itself:
@@ -3001,7 +3183,7 @@ You can even inspect and change the props of components, and see the results imm
 
 Ink has basic support for screen readers.
 
-To enable it, you can either pass the `isScreenReaderEnabled` option to the `render` function or set the `INK_SCREEN_READER` environment variable to `true`.
+To enable it, you can either pass the `isScreenReaderEnabled` option to the `render` function or set the `SIGIL_SCREEN_READER` environment variable to `true`.
 
 Ink implements a small subset of functionality from the [ARIA specification](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA).
 
@@ -3015,7 +3197,7 @@ For example, for this code:
 
 ```jsx
 <Box aria-role="checkbox" aria-state={{ checked: true }}>
-	<Text>Accept terms and conditions</Text>
+  <Text>Accept terms and conditions</Text>
 </Box>
 ```
 
@@ -3031,8 +3213,8 @@ For example, if you are building a progress bar, you can use `aria-label` to pro
 
 ```jsx
 <Box>
-	<Box width="50%" height={1} backgroundColor="green" />
-	<Text aria-label="Progress: 50%">50%</Text>
+  <Box width="50%" height={1} backgroundColor="green" />
+  <Text aria-label="Progress: 50%">50%</Text>
 </Box>
 ```
 
@@ -3168,6 +3350,10 @@ npm run example examples/[example name]
 - [Static](examples/static/static.tsx) - Use the `<Static>` component to render permanent output.
 - [Child process](examples/subprocess-output) - Renders output from a child process.
 - [Router](examples/router/router.tsx) - Navigate between routes using React Router's `MemoryRouter`.
+- [Charm brightness](examples/charm-brightness/brightness.tsx) - A native port of Lip Gloss's progressive lightening and darkening demo.
+- [Charm canvas](examples/charm-canvas/canvas.tsx) - Layered fields and gradient-bordered cards inspired by Lip Gloss's compositor demo.
+- [Charm layout](examples/charm-layout/layout.tsx) - The Lip Gloss layout showcase rebuilt with React, Yoga, gradients, and compositing.
+- [Charm profile](examples/charm-profile/profile.tsx) - The Lip Gloss SSH profile showcase adapted to Sigil's stream-scoped terminal capabilities.
 
 ## Continuous Integration