ink 6.8.0 → 7.0.1

package/build/hooks/use-input.js

@@ -1,9 +1,10 @@
-import { useEffect } from 'react';
+import { useEffect, useEffectEvent } from 'react';
 import parseKeypress, { nonAlphanumericKeys } from '../parse-keypress.js';
 import reconciler from '../reconciler.js';
-import useStdin from './use-stdin.js';
+import { useStdinContext } from './use-stdin.js';
 /**
-This hook is used for handling user input. It's a more convenient alternative to using `StdinContext` and listening for `data` events. The callback you pass to `useInput` is called for each character when the user enters any input. However, if the user pastes text and it's more than one character, the callback will be called only once, and the whole string will be passed as `input`.
+A React hook that returns `void` and handles user input.
+It's a more convenient alternative to using `StdinContext` and listening for `data` events. The callback you pass to `useInput` is called for each character when the user enters any input. However, if the user pastes text and it's more than one character, the callback will be called only once, and the whole string will be passed as `input`.
 
 ```
 import {useInput} from 'ink';
@@ -25,7 +26,7 @@ const UserInput = () => {
 */
 const useInput = (inputHandler, options = {}) => {
     // eslint-disable-next-line @typescript-eslint/naming-convention
-    const { stdin, setRawMode, internal_exitOnCtrlC, internal_eventEmitter } = useStdin();
+    const { setRawMode, internal_exitOnCtrlC, internal_eventEmitter } = useStdinContext();
     useEffect(() => {
         if (options.isActive === false) {
             return;
@@ -35,90 +36,91 @@ const useInput = (inputHandler, options = {}) => {
             setRawMode(false);
         };
     }, [options.isActive, setRawMode]);
-    useEffect(() => {
-        if (options.isActive === false) {
-            return;
-        }
-        const handleData = (data) => {
-            const keypress = parseKeypress(data);
-            const key = {
-                upArrow: keypress.name === 'up',
-                downArrow: keypress.name === 'down',
-                leftArrow: keypress.name === 'left',
-                rightArrow: keypress.name === 'right',
-                pageDown: keypress.name === 'pagedown',
-                pageUp: keypress.name === 'pageup',
-                home: keypress.name === 'home',
-                end: keypress.name === 'end',
-                return: keypress.name === 'return',
-                escape: keypress.name === 'escape',
-                ctrl: keypress.ctrl,
-                shift: keypress.shift,
-                tab: keypress.name === 'tab',
-                backspace: keypress.name === 'backspace',
-                delete: keypress.name === 'delete',
-                // `parseKeypress` parses \u001B\u001B[A (meta + up arrow) as meta = false
-                // but with option = true, so we need to take this into account here
-                // to avoid breaking changes in Ink.
-                // TODO(vadimdemedes): consider removing this in the next major version.
-                meta: keypress.meta || keypress.name === 'escape' || keypress.option,
-                // Kitty keyboard protocol modifiers
-                super: keypress.super ?? false,
-                hyper: keypress.hyper ?? false,
-                capsLock: keypress.capsLock ?? false,
-                numLock: keypress.numLock ?? false,
-                eventType: keypress.eventType,
-            };
-            let input;
-            if (keypress.isKittyProtocol) {
-                // Use text-as-codepoints field for printable keys (needed when
-                // reportAllKeysAsEscapeCodes flag is enabled), suppress non-printable
-                if (keypress.isPrintable) {
-                    input = keypress.text ?? keypress.name;
-                }
-                else if (keypress.ctrl && keypress.name.length === 1) {
-                    // Ctrl+letter via codepoint 1-26 form: not printable text, but
-                    // the letter name must flow through so handlers (e.g. exitOnCtrlC
-                    // checking `input === 'c' && key.ctrl`) still work.
-                    input = keypress.name;
-                }
-                else {
-                    input = '';
-                }
+    const handleData = useEffectEvent((data) => {
+        const keypress = parseKeypress(data);
+        const key = {
+            upArrow: keypress.name === 'up',
+            downArrow: keypress.name === 'down',
+            leftArrow: keypress.name === 'left',
+            rightArrow: keypress.name === 'right',
+            pageDown: keypress.name === 'pagedown',
+            pageUp: keypress.name === 'pageup',
+            home: keypress.name === 'home',
+            end: keypress.name === 'end',
+            return: keypress.name === 'return',
+            escape: keypress.name === 'escape',
+            ctrl: keypress.ctrl,
+            shift: keypress.shift,
+            tab: keypress.name === 'tab',
+            backspace: keypress.name === 'backspace',
+            delete: keypress.name === 'delete',
+            meta: keypress.meta,
+            // Kitty keyboard protocol modifiers
+            super: keypress.super ?? false,
+            hyper: keypress.hyper ?? false,
+            capsLock: keypress.capsLock ?? false,
+            numLock: keypress.numLock ?? false,
+            eventType: keypress.eventType,
+        };
+        let input;
+        if (keypress.isKittyProtocol) {
+            // Use text-as-codepoints field for printable keys (needed when
+            // reportAllKeysAsEscapeCodes flag is enabled), suppress non-printable
+            if (keypress.isPrintable) {
+                input = keypress.text ?? keypress.name;
             }
-            else if (keypress.ctrl) {
+            else if (keypress.ctrl && keypress.name.length === 1) {
+                // Ctrl+letter via codepoint 1-26 form: not printable text, but
+                // the letter name must flow through so handlers (e.g. exitOnCtrlC
+                // checking `input === 'c' && key.ctrl`) still work.
                 input = keypress.name;
             }
             else {
-                input = keypress.sequence;
-            }
-            if (!keypress.isKittyProtocol &&
-                nonAlphanumericKeys.includes(keypress.name)) {
                 input = '';
             }
-            // Strip meta if it's still remaining after `parseKeypress`
-            // TODO(vadimdemedes): remove this in the next major version.
-            if (input.startsWith('\u001B')) {
-                input = input.slice(1);
-            }
-            if (input.length === 1 &&
-                typeof input[0] === 'string' &&
-                /[A-Z]/.test(input[0])) {
-                key.shift = true;
-            }
-            // If app is not supposed to exit on Ctrl+C, then let input listener handle it
-            if (!(input === 'c' && key.ctrl) || !internal_exitOnCtrlC) {
-                // @ts-expect-error TypeScript types for `batchedUpdates` require an argument, but React's codebase doesn't provide it and it works without it as expected.
-                reconciler.batchedUpdates(() => {
-                    inputHandler(input, key);
-                });
-            }
-        };
-        internal_eventEmitter?.on('input', handleData);
+        }
+        else if (keypress.ctrl) {
+            // Keypress.name is guaranteed non-undefined by parseKeypress,
+            // but guard defensively since a TypeError here would crash the
+            // entire Ink app (see https://github.com/vadimdemedes/ink/issues/901).
+            input = keypress.name ?? '';
+        }
+        else {
+            input = keypress.sequence;
+        }
+        if (!keypress.isKittyProtocol &&
+            nonAlphanumericKeys.includes(keypress.name)) {
+            input = '';
+        }
+        // Strip escape prefix from broken/incomplete sequences that
+        // parseKeypress did not fully resolve (e.g. a flushed "\u001B[").
+        if (input.startsWith('\u001B')) {
+            input = input.slice(1);
+        }
+        if (input.length === 1 && /[A-Z]/.test(input)) {
+            key.shift = true;
+        }
+        // If app is supposed to exit on Ctrl+C, skip input listeners.
+        if (input === 'c' && key.ctrl && internal_exitOnCtrlC) {
+            return;
+        }
+        // Use discreteUpdates to assign DiscreteEventPriority to state
+        // updates from keyboard input, ensuring they are processed at the
+        // highest priority in concurrent mode.
+        // @ts-expect-error Types require 5 arguments (fn, a, b, c, d) but only fn is needed at runtime.
+        reconciler.discreteUpdates(() => {
+            inputHandler(input, key);
+        });
+    });
+    useEffect(() => {
+        if (options.isActive === false) {
+            return;
+        }
+        internal_eventEmitter.on('input', handleData);
         return () => {
-            internal_eventEmitter?.removeListener('input', handleData);
+            internal_eventEmitter.removeListener('input', handleData);
         };
-    }, [options.isActive, stdin, internal_exitOnCtrlC, inputHandler]);
+    }, [options.isActive, internal_eventEmitter]);
 };
 export default useInput;
 //# sourceMappingURL=use-input.js.map

package/build/hooks/use-input.js.map

@@ -1 +1 @@
-{"version":3,"file":"use-input.js","sourceRoot":"","sources":["../../src/hooks/use-input.ts"],"names":[],"mappings":"AAAA,OAAO,EAAC,SAAS,EAAC,MAAM,OAAO,CAAC;AAChC,OAAO,aAAa,EAAE,EAAC,mBAAmB,EAAC,MAAM,sBAAsB,CAAC;AACxE,OAAO,UAAU,MAAM,kBAAkB,CAAC;AAC1C,OAAO,QAAQ,MAAM,gBAAgB,CAAC;AAqItC;;;;;;;;;;;;;;;;;;;;EAoBE;AACF,MAAM,QAAQ,GAAG,CAAC,YAAqB,EAAE,UAAmB,EAAE,EAAE,EAAE;IACjE,gEAAgE;IAChE,MAAM,EAAC,KAAK,EAAE,UAAU,EAAE,oBAAoB,EAAE,qBAAqB,EAAC,GACrE,QAAQ,EAAE,CAAC;IAEZ,SAAS,CAAC,GAAG,EAAE;QACd,IAAI,OAAO,CAAC,QAAQ,KAAK,KAAK,EAAE,CAAC;YAChC,OAAO;QACR,CAAC;QAED,UAAU,CAAC,IAAI,CAAC,CAAC;QAEjB,OAAO,GAAG,EAAE;YACX,UAAU,CAAC,KAAK,CAAC,CAAC;QACnB,CAAC,CAAC;IACH,CAAC,EAAE,CAAC,OAAO,CAAC,QAAQ,EAAE,UAAU,CAAC,CAAC,CAAC;IAEnC,SAAS,CAAC,GAAG,EAAE;QACd,IAAI,OAAO,CAAC,QAAQ,KAAK,KAAK,EAAE,CAAC;YAChC,OAAO;QACR,CAAC;QAED,MAAM,UAAU,GAAG,CAAC,IAAY,EAAE,EAAE;YACnC,MAAM,QAAQ,GAAG,aAAa,CAAC,IAAI,CAAC,CAAC;YAErC,MAAM,GAAG,GAAQ;gBAChB,OAAO,EAAE,QAAQ,CAAC,IAAI,KAAK,IAAI;gBAC/B,SAAS,EAAE,QAAQ,CAAC,IAAI,KAAK,MAAM;gBACnC,SAAS,EAAE,QAAQ,CAAC,IAAI,KAAK,MAAM;gBACnC,UAAU,EAAE,QAAQ,CAAC,IAAI,KAAK,OAAO;gBACrC,QAAQ,EAAE,QAAQ,CAAC,IAAI,KAAK,UAAU;gBACtC,MAAM,EAAE,QAAQ,CAAC,IAAI,KAAK,QAAQ;gBAClC,IAAI,EAAE,QAAQ,CAAC,IAAI,KAAK,MAAM;gBAC9B,GAAG,EAAE,QAAQ,CAAC,IAAI,KAAK,KAAK;gBAC5B,MAAM,EAAE,QAAQ,CAAC,IAAI,KAAK,QAAQ;gBAClC,MAAM,EAAE,QAAQ,CAAC,IAAI,KAAK,QAAQ;gBAClC,IAAI,EAAE,QAAQ,CAAC,IAAI;gBACnB,KAAK,EAAE,QAAQ,CAAC,KAAK;gBACrB,GAAG,EAAE,QAAQ,CAAC,IAAI,KAAK,KAAK;gBAC5B,SAAS,EAAE,QAAQ,CAAC,IAAI,KAAK,WAAW;gBACxC,MAAM,EAAE,QAAQ,CAAC,IAAI,KAAK,QAAQ;gBAClC,0EAA0E;gBAC1E,oEAAoE;gBACpE,oCAAoC;gBACpC,wEAAwE;gBACxE,IAAI,EAAE,QAAQ,CAAC,IAAI,IAAI,QAAQ,CAAC,IAAI,KAAK,QAAQ,IAAI,QAAQ,CAAC,MAAM;gBACpE,oCAAoC;gBACpC,KAAK,EAAE,QAAQ,CAAC,KAAK,IAAI,KAAK;gBAC9B,KAAK,EAAE,QAAQ,CAAC,KAAK,IAAI,KAAK;gBAC9B,QAAQ,EAAE,QAAQ,CAAC,QAAQ,IAAI,KAAK;gBACpC,OAAO,EAAE,QAAQ,CAAC,OAAO,IAAI,KAAK;gBAClC,SAAS,EAAE,QAAQ,CAAC,SAAS;aAC7B,CAAC;YAEF,IAAI,KAAa,CAAC;YAClB,IAAI,QAAQ,CAAC,eAAe,EAAE,CAAC;gBAC9B,+DAA+D;gBAC/D,sEAAsE;gBACtE,IAAI,QAAQ,CAAC,WAAW,EAAE,CAAC;oBAC1B,KAAK,GAAG,QAAQ,CAAC,IAAI,IAAI,QAAQ,CAAC,IAAI,CAAC;gBACxC,CAAC;qBAAM,IAAI,QAAQ,CAAC,IAAI,IAAI,QAAQ,CAAC,IAAI,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;oBACxD,+DAA+D;oBAC/D,kEAAkE;oBAClE,oDAAoD;oBACpD,KAAK,GAAG,QAAQ,CAAC,IAAI,CAAC;gBACvB,CAAC;qBAAM,CAAC;oBACP,KAAK,GAAG,EAAE,CAAC;gBACZ,CAAC;YACF,CAAC;iBAAM,IAAI,QAAQ,CAAC,IAAI,EAAE,CAAC;gBAC1B,KAAK,GAAG,QAAQ,CAAC,IAAI,CAAC;YACvB,CAAC;iBAAM,CAAC;gBACP,KAAK,GAAG,QAAQ,CAAC,QAAQ,CAAC;YAC3B,CAAC;YAED,IACC,CAAC,QAAQ,CAAC,eAAe;gBACzB,mBAAmB,CAAC,QAAQ,CAAC,QAAQ,CAAC,IAAI,CAAC,EAC1C,CAAC;gBACF,KAAK,GAAG,EAAE,CAAC;YACZ,CAAC;YAED,2DAA2D;YAC3D,6DAA6D;YAC7D,IAAI,KAAK,CAAC,UAAU,CAAC,QAAQ,CAAC,EAAE,CAAC;gBAChC,KAAK,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;YACxB,CAAC;YAED,IACC,KAAK,CAAC,MAAM,KAAK,CAAC;gBAClB,OAAO,KAAK,CAAC,CAAC,CAAC,KAAK,QAAQ;gBAC5B,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,EACrB,CAAC;gBACF,GAAG,CAAC,KAAK,GAAG,IAAI,CAAC;YAClB,CAAC;YAED,8EAA8E;YAC9E,IAAI,CAAC,CAAC,KAAK,KAAK,GAAG,IAAI,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,oBAAoB,EAAE,CAAC;gBAC3D,2JAA2J;gBAC3J,UAAU,CAAC,cAAc,CAAC,GAAG,EAAE;oBAC9B,YAAY,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC;gBAC1B,CAAC,CAAC,CAAC;YACJ,CAAC;QACF,CAAC,CAAC;QAEF,qBAAqB,EAAE,EAAE,CAAC,OAAO,EAAE,UAAU,CAAC,CAAC;QAE/C,OAAO,GAAG,EAAE;YACX,qBAAqB,EAAE,cAAc,CAAC,OAAO,EAAE,UAAU,CAAC,CAAC;QAC5D,CAAC,CAAC;IACH,CAAC,EAAE,CAAC,OAAO,CAAC,QAAQ,EAAE,KAAK,EAAE,oBAAoB,EAAE,YAAY,CAAC,CAAC,CAAC;AACnE,CAAC,CAAC;AAEF,eAAe,QAAQ,CAAC"}
+{"version":3,"file":"use-input.js","sourceRoot":"","sources":["../../src/hooks/use-input.ts"],"names":[],"mappings":"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"}

package/build/hooks/use-is-screen-reader-enabled.d.ts

@@ -1,5 +1,6 @@
 /**
-Returns whether a screen reader is enabled. This is useful when you want to render different output for screen readers.
+A React hook that returns whether a screen reader is enabled.
+This is useful when you want to render different output for screen readers.
 */
 declare const useIsScreenReaderEnabled: () => boolean;
 export default useIsScreenReaderEnabled;

package/build/hooks/use-is-screen-reader-enabled.js

@@ -1,7 +1,8 @@
 import { useContext } from 'react';
 import { accessibilityContext } from '../components/AccessibilityContext.js';
 /**
-Returns whether a screen reader is enabled. This is useful when you want to render different output for screen readers.
+A React hook that returns whether a screen reader is enabled.
+This is useful when you want to render different output for screen readers.
 */
 const useIsScreenReaderEnabled = () => {
     const { isScreenReaderEnabled } = useContext(accessibilityContext);

package/build/hooks/use-is-screen-reader-enabled.js.map

@@ -1 +1 @@
-{"version":3,"file":"use-is-screen-reader-enabled.js","sourceRoot":"","sources":["../../src/hooks/use-is-screen-reader-enabled.ts"],"names":[],"mappings":"AAAA,OAAO,EAAC,UAAU,EAAC,MAAM,OAAO,CAAC;AACjC,OAAO,EAAC,oBAAoB,EAAC,MAAM,uCAAuC,CAAC;AAE3E;;EAEE;AACF,MAAM,wBAAwB,GAAG,GAAY,EAAE;IAC9C,MAAM,EAAC,qBAAqB,EAAC,GAAG,UAAU,CAAC,oBAAoB,CAAC,CAAC;IACjE,OAAO,qBAAqB,CAAC;AAC9B,CAAC,CAAC;AAEF,eAAe,wBAAwB,CAAC"}
+{"version":3,"file":"use-is-screen-reader-enabled.js","sourceRoot":"","sources":["../../src/hooks/use-is-screen-reader-enabled.ts"],"names":[],"mappings":"AAAA,OAAO,EAAC,UAAU,EAAC,MAAM,OAAO,CAAC;AACjC,OAAO,EAAC,oBAAoB,EAAC,MAAM,uCAAuC,CAAC;AAE3E;;;EAGE;AACF,MAAM,wBAAwB,GAAG,GAAY,EAAE;IAC9C,MAAM,EAAC,qBAAqB,EAAC,GAAG,UAAU,CAAC,oBAAoB,CAAC,CAAC;IACjE,OAAO,qBAAqB,CAAC;AAC9B,CAAC,CAAC;AAEF,eAAe,wBAAwB,CAAC"}

package/build/hooks/use-paste.d.ts

@@ -0,0 +1,35 @@
+type Options = {
+    /**
+    Enable or disable the paste handler. Useful when multiple components use `usePaste` and only one should be active at a time.
+
+    @default true
+    */
+    isActive?: boolean;
+};
+/**
+A React hook that calls `handler` whenever the user pastes text in the terminal. Bracketed paste mode (`\x1b[?2004h`) is automatically enabled while the hook is active, so pasted text arrives as a single string rather than being misinterpreted as individual key presses.
+
+`usePaste` and `useInput` can be used together in the same component. They operate on separate event channels, so paste content is never forwarded to `useInput` handlers when `usePaste` is active.
+
+```
+import {useInput, usePaste} from 'ink';
+
+const MyInput = () => {
+    useInput((input, key) => {
+        // Only receives typed characters and key events, not pasted text.
+        if (key.return) {
+            // Submit
+        }
+    });
+
+    usePaste((text) => {
+        // Receives the full pasted string, including newlines.
+        console.log('Pasted:', text);
+    });
+
+    return …
+};
+```
+*/
+declare const usePaste: (handler: (text: string) => void, options?: Options) => void;
+export default usePaste;

package/build/hooks/use-paste.js

@@ -0,0 +1,62 @@
+import { useEffect, useEffectEvent } from 'react';
+import reconciler from '../reconciler.js';
+import { useStdinContext } from './use-stdin.js';
+/**
+A React hook that calls `handler` whenever the user pastes text in the terminal. Bracketed paste mode (`\x1b[?2004h`) is automatically enabled while the hook is active, so pasted text arrives as a single string rather than being misinterpreted as individual key presses.
+
+`usePaste` and `useInput` can be used together in the same component. They operate on separate event channels, so paste content is never forwarded to `useInput` handlers when `usePaste` is active.
+
+```
+import {useInput, usePaste} from 'ink';
+
+const MyInput = () => {
+    useInput((input, key) => {
+        // Only receives typed characters and key events, not pasted text.
+        if (key.return) {
+            // Submit
+        }
+    });
+
+    usePaste((text) => {
+        // Receives the full pasted string, including newlines.
+        console.log('Pasted:', text);
+    });
+
+    return …
+};
+```
+*/
+const usePaste = (handler, options = {}) => {
+    // eslint-disable-next-line @typescript-eslint/naming-convention
+    const { setRawMode, setBracketedPasteMode, internal_eventEmitter } = useStdinContext();
+    useEffect(() => {
+        if (options.isActive === false) {
+            return;
+        }
+        setRawMode(true);
+        setBracketedPasteMode(true);
+        return () => {
+            setRawMode(false);
+            setBracketedPasteMode(false);
+        };
+    }, [options.isActive, setRawMode, setBracketedPasteMode]);
+    const handlePaste = useEffectEvent((text) => {
+        // Use discreteUpdates to assign DiscreteEventPriority to state
+        // updates triggered by paste, matching the priority of useInput.
+        // @ts-expect-error Types require 5 arguments (fn, a, b, c, d) but only fn is needed at runtime.
+        reconciler.discreteUpdates(() => {
+            handler(text);
+        });
+    });
+    useEffect(() => {
+        if (options.isActive === false) {
+            return;
+        }
+        internal_eventEmitter.on('paste', handlePaste);
+        return () => {
+            internal_eventEmitter.removeListener('paste', handlePaste);
+        };
+    }, [options.isActive, internal_eventEmitter]);
+};
+export default usePaste;
+//# sourceMappingURL=use-paste.js.map

package/build/hooks/use-paste.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-paste.js","sourceRoot":"","sources":["../../src/hooks/use-paste.ts"],"names":[],"mappings":"AAAA,OAAO,EAAC,SAAS,EAAE,cAAc,EAAC,MAAM,OAAO,CAAC;AAChD,OAAO,UAAU,MAAM,kBAAkB,CAAC;AAC1C,OAAO,EAAC,eAAe,EAAC,MAAM,gBAAgB,CAAC;AAW/C;;;;;;;;;;;;;;;;;;;;;;;;EAwBE;AACF,MAAM,QAAQ,GAAG,CAChB,OAA+B,EAC/B,UAAmB,EAAE,EACd,EAAE;IACT,gEAAgE;IAChE,MAAM,EAAC,UAAU,EAAE,qBAAqB,EAAE,qBAAqB,EAAC,GAC/D,eAAe,EAAE,CAAC;IAEnB,SAAS,CAAC,GAAG,EAAE;QACd,IAAI,OAAO,CAAC,QAAQ,KAAK,KAAK,EAAE,CAAC;YAChC,OAAO;QACR,CAAC;QAED,UAAU,CAAC,IAAI,CAAC,CAAC;QACjB,qBAAqB,CAAC,IAAI,CAAC,CAAC;QAE5B,OAAO,GAAG,EAAE;YACX,UAAU,CAAC,KAAK,CAAC,CAAC;YAClB,qBAAqB,CAAC,KAAK,CAAC,CAAC;QAC9B,CAAC,CAAC;IACH,CAAC,EAAE,CAAC,OAAO,CAAC,QAAQ,EAAE,UAAU,EAAE,qBAAqB,CAAC,CAAC,CAAC;IAE1D,MAAM,WAAW,GAAG,cAAc,CAAC,CAAC,IAAY,EAAE,EAAE;QACnD,+DAA+D;QAC/D,iEAAiE;QACjE,gGAAgG;QAChG,UAAU,CAAC,eAAe,CAAC,GAAG,EAAE;YAC/B,OAAO,CAAC,IAAI,CAAC,CAAC;QACf,CAAC,CAAC,CAAC;IACJ,CAAC,CAAC,CAAC;IAEH,SAAS,CAAC,GAAG,EAAE;QACd,IAAI,OAAO,CAAC,QAAQ,KAAK,KAAK,EAAE,CAAC;YAChC,OAAO;QACR,CAAC;QAED,qBAAqB,CAAC,EAAE,CAAC,OAAO,EAAE,WAAW,CAAC,CAAC;QAE/C,OAAO,GAAG,EAAE;YACX,qBAAqB,CAAC,cAAc,CAAC,OAAO,EAAE,WAAW,CAAC,CAAC;QAC5D,CAAC,CAAC;IACH,CAAC,EAAE,CAAC,OAAO,CAAC,QAAQ,EAAE,qBAAqB,CAAC,CAAC,CAAC;AAC/C,CAAC,CAAC;AAEF,eAAe,QAAQ,CAAC"}

package/build/hooks/use-stderr.d.ts

@@ -1,5 +1,5 @@
 /**
-`useStderr` is a React hook that exposes the stderr stream.
+A React hook that returns the stderr stream.
 */
 declare const useStderr: () => import("../components/StderrContext.js").Props;
 export default useStderr;

package/build/hooks/use-stderr.js

@@ -1,7 +1,7 @@
 import { useContext } from 'react';
 import StderrContext from '../components/StderrContext.js';
 /**
-`useStderr` is a React hook that exposes the stderr stream.
+A React hook that returns the stderr stream.
 */
 const useStderr = () => useContext(StderrContext);
 export default useStderr;

package/build/hooks/use-stdin.d.ts

@@ -1,5 +1,7 @@
+import { type PublicProps, type Props } from '../components/StdinContext.js';
 /**
-`useStdin` is a React hook that exposes the stdin stream.
+A React hook that returns the stdin stream and stdin-related utilities.
 */
-declare const useStdin: () => import("../components/StdinContext.js").Props;
+declare const useStdin: () => PublicProps;
+export declare const useStdinContext: () => Props;
 export default useStdin;

package/build/hooks/use-stdin.js

@@ -1,8 +1,9 @@
 import { useContext } from 'react';
 import StdinContext from '../components/StdinContext.js';
 /**
-`useStdin` is a React hook that exposes the stdin stream.
+A React hook that returns the stdin stream and stdin-related utilities.
 */
 const useStdin = () => useContext(StdinContext);
+export const useStdinContext = () => useContext(StdinContext);
 export default useStdin;
 //# sourceMappingURL=use-stdin.js.map

package/build/hooks/use-stdin.js.map

@@ -1 +1 @@
-{"version":3,"file":"use-stdin.js","sourceRoot":"","sources":["../../src/hooks/use-stdin.ts"],"names":[],"mappings":"AAAA,OAAO,EAAC,UAAU,EAAC,MAAM,OAAO,CAAC;AACjC,OAAO,YAAY,MAAM,+BAA+B,CAAC;AAEzD;;EAEE;AACF,MAAM,QAAQ,GAAG,GAAG,EAAE,CAAC,UAAU,CAAC,YAAY,CAAC,CAAC;AAChD,eAAe,QAAQ,CAAC"}
+{"version":3,"file":"use-stdin.js","sourceRoot":"","sources":["../../src/hooks/use-stdin.ts"],"names":[],"mappings":"AAAA,OAAO,EAAC,UAAU,EAAC,MAAM,OAAO,CAAC;AACjC,OAAO,YAGN,MAAM,+BAA+B,CAAC;AAEvC;;EAEE;AACF,MAAM,QAAQ,GAAG,GAAgB,EAAE,CAAC,UAAU,CAAC,YAAY,CAAC,CAAC;AAE7D,MAAM,CAAC,MAAM,eAAe,GAAG,GAAU,EAAE,CAAC,UAAU,CAAC,YAAY,CAAC,CAAC;AAErE,eAAe,QAAQ,CAAC"}

package/build/hooks/use-stdout.d.ts

@@ -1,5 +1,5 @@
 /**
-`useStdout` is a React hook that exposes the stdout stream where Ink renders your app.
+A React hook that returns the stdout stream where Ink renders your app.
 */
 declare const useStdout: () => import("../components/StdoutContext.js").Props;
 export default useStdout;

package/build/hooks/use-stdout.js

@@ -1,7 +1,7 @@
 import { useContext } from 'react';
 import StdoutContext from '../components/StdoutContext.js';
 /**
-`useStdout` is a React hook that exposes the stdout stream where Ink renders your app.
+A React hook that returns the stdout stream where Ink renders your app.
 */
 const useStdout = () => useContext(StdoutContext);
 export default useStdout;

package/build/hooks/use-window-size.d.ts

@@ -0,0 +1,18 @@
+/**
+Dimensions of the terminal window.
+*/
+export type WindowSize = {
+    /**
+    Number of columns (horizontal character cells).
+    */
+    readonly columns: number;
+    /**
+    Number of rows (vertical character cells).
+    */
+    readonly rows: number;
+};
+/**
+A React hook that returns the current terminal window dimensions and re-renders the component whenever the terminal is resized.
+*/
+declare const useWindowSize: () => WindowSize;
+export default useWindowSize;

package/build/hooks/use-window-size.js

@@ -0,0 +1,22 @@
+import { useState, useEffect } from 'react';
+import { getWindowSize } from '../utils.js';
+import useStdout from './use-stdout.js';
+/**
+A React hook that returns the current terminal window dimensions and re-renders the component whenever the terminal is resized.
+*/
+const useWindowSize = () => {
+    const { stdout } = useStdout();
+    const [size, setSize] = useState(() => getWindowSize(stdout));
+    useEffect(() => {
+        const onResize = () => {
+            setSize(getWindowSize(stdout));
+        };
+        stdout.on('resize', onResize);
+        return () => {
+            stdout.off('resize', onResize);
+        };
+    }, [stdout]);
+    return size;
+};
+export default useWindowSize;
+//# sourceMappingURL=use-window-size.js.map

package/build/hooks/use-window-size.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-window-size.js","sourceRoot":"","sources":["../../src/hooks/use-window-size.ts"],"names":[],"mappings":"AAAA,OAAO,EAAC,QAAQ,EAAE,SAAS,EAAC,MAAM,OAAO,CAAC;AAC1C,OAAO,EAAC,aAAa,EAAC,MAAM,aAAa,CAAC;AAC1C,OAAO,SAAS,MAAM,iBAAiB,CAAC;AAiBxC;;EAEE;AACF,MAAM,aAAa,GAAG,GAAe,EAAE;IACtC,MAAM,EAAC,MAAM,EAAC,GAAG,SAAS,EAAE,CAAC;IAC7B,MAAM,CAAC,IAAI,EAAE,OAAO,CAAC,GAAG,QAAQ,CAAa,GAAG,EAAE,CAAC,aAAa,CAAC,MAAM,CAAC,CAAC,CAAC;IAE1E,SAAS,CAAC,GAAG,EAAE;QACd,MAAM,QAAQ,GAAG,GAAG,EAAE;YACrB,OAAO,CAAC,aAAa,CAAC,MAAM,CAAC,CAAC,CAAC;QAChC,CAAC,CAAC;QAEF,MAAM,CAAC,EAAE,CAAC,QAAQ,EAAE,QAAQ,CAAC,CAAC;QAE9B,OAAO,GAAG,EAAE;YACX,MAAM,CAAC,GAAG,CAAC,QAAQ,EAAE,QAAQ,CAAC,CAAC;QAChC,CAAC,CAAC;IACH,CAAC,EAAE,CAAC,MAAM,CAAC,CAAC,CAAC;IAEb,OAAO,IAAI,CAAC;AACb,CAAC,CAAC;AAEF,eAAe,aAAa,CAAC"}

package/build/index.d.ts

@@ -7,7 +7,7 @@ export { default as Box } from './components/Box.js';
 export type { Props as TextProps } from './components/Text.js';
 export { default as Text } from './components/Text.js';
 export type { Props as AppProps } from './components/AppContext.js';
-export type { Props as StdinProps } from './components/StdinContext.js';
+export type { PublicProps as StdinProps } from './components/StdinContext.js';
 export type { Props as StdoutProps } from './components/StdoutContext.js';
 export type { Props as StderrProps } from './components/StderrContext.js';
 export type { Props as StaticProps } from './components/Static.js';
@@ -19,6 +19,7 @@ export { default as Newline } from './components/Newline.js';
 export { default as Spacer } from './components/Spacer.js';
 export type { Key } from './hooks/use-input.js';
 export { default as useInput } from './hooks/use-input.js';
+export { default as usePaste } from './hooks/use-paste.js';
 export { default as useApp } from './hooks/use-app.js';
 export { default as useStdin } from './hooks/use-stdin.js';
 export { default as useStdout } from './hooks/use-stdout.js';
@@ -27,6 +28,12 @@ export { default as useFocus } from './hooks/use-focus.js';
 export { default as useFocusManager } from './hooks/use-focus-manager.js';
 export { default as useIsScreenReaderEnabled } from './hooks/use-is-screen-reader-enabled.js';
 export { default as useCursor } from './hooks/use-cursor.js';
+export type { AnimationResult } from './hooks/use-animation.js';
+export { default as useAnimation } from './hooks/use-animation.js';
+export type { WindowSize } from './hooks/use-window-size.js';
+export { default as useWindowSize } from './hooks/use-window-size.js';
+export type { BoxMetrics, UseBoxMetricsResult } from './hooks/use-box-metrics.js';
+export { default as useBoxMetrics } from './hooks/use-box-metrics.js';
 export type { CursorPosition } from './log-update.js';
 export { default as measureElement } from './measure-element.js';
 export type { DOMElement } from './dom.js';

package/build/index.js

@@ -7,6 +7,7 @@ export { default as Transform } from './components/Transform.js';
 export { default as Newline } from './components/Newline.js';
 export { default as Spacer } from './components/Spacer.js';
 export { default as useInput } from './hooks/use-input.js';
+export { default as usePaste } from './hooks/use-paste.js';
 export { default as useApp } from './hooks/use-app.js';
 export { default as useStdin } from './hooks/use-stdin.js';
 export { default as useStdout } from './hooks/use-stdout.js';
@@ -15,6 +16,9 @@ export { default as useFocus } from './hooks/use-focus.js';
 export { default as useFocusManager } from './hooks/use-focus-manager.js';
 export { default as useIsScreenReaderEnabled } from './hooks/use-is-screen-reader-enabled.js';
 export { default as useCursor } from './hooks/use-cursor.js';
+export { default as useAnimation } from './hooks/use-animation.js';
+export { default as useWindowSize } from './hooks/use-window-size.js';
+export { default as useBoxMetrics } from './hooks/use-box-metrics.js';
 export { default as measureElement } from './measure-element.js';
 export { kittyFlags, kittyModifiers } from './kitty-keyboard.js';
 //# sourceMappingURL=index.js.map

package/build/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAC,OAAO,IAAI,MAAM,EAAC,MAAM,aAAa,CAAC;AAE9C,OAAO,EAAC,OAAO,IAAI,cAAc,EAAC,MAAM,uBAAuB,CAAC;AAEhE,OAAO,EAAC,OAAO,IAAI,GAAG,EAAC,MAAM,qBAAqB,CAAC;AAEnD,OAAO,EAAC,OAAO,IAAI,IAAI,EAAC,MAAM,sBAAsB,CAAC;AAMrD,OAAO,EAAC,OAAO,IAAI,MAAM,EAAC,MAAM,wBAAwB,CAAC;AAEzD,OAAO,EAAC,OAAO,IAAI,SAAS,EAAC,MAAM,2BAA2B,CAAC;AAE/D,OAAO,EAAC,OAAO,IAAI,OAAO,EAAC,MAAM,yBAAyB,CAAC;AAC3D,OAAO,EAAC,OAAO,IAAI,MAAM,EAAC,MAAM,wBAAwB,CAAC;AAEzD,OAAO,EAAC,OAAO,IAAI,QAAQ,EAAC,MAAM,sBAAsB,CAAC;AACzD,OAAO,EAAC,OAAO,IAAI,MAAM,EAAC,MAAM,oBAAoB,CAAC;AACrD,OAAO,EAAC,OAAO,IAAI,QAAQ,EAAC,MAAM,sBAAsB,CAAC;AACzD,OAAO,EAAC,OAAO,IAAI,SAAS,EAAC,MAAM,uBAAuB,CAAC;AAC3D,OAAO,EAAC,OAAO,IAAI,SAAS,EAAC,MAAM,uBAAuB,CAAC;AAC3D,OAAO,EAAC,OAAO,IAAI,QAAQ,EAAC,MAAM,sBAAsB,CAAC;AACzD,OAAO,EAAC,OAAO,IAAI,eAAe,EAAC,MAAM,8BAA8B,CAAC;AACxE,OAAO,EAAC,OAAO,IAAI,wBAAwB,EAAC,MAAM,yCAAyC,CAAC;AAC5F,OAAO,EAAC,OAAO,IAAI,SAAS,EAAC,MAAM,uBAAuB,CAAC;AAE3D,OAAO,EAAC,OAAO,IAAI,cAAc,EAAC,MAAM,sBAAsB,CAAC;AAE/D,OAAO,EAAC,UAAU,EAAE,cAAc,EAAC,MAAM,qBAAqB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAC,OAAO,IAAI,MAAM,EAAC,MAAM,aAAa,CAAC;AAE9C,OAAO,EAAC,OAAO,IAAI,cAAc,EAAC,MAAM,uBAAuB,CAAC;AAEhE,OAAO,EAAC,OAAO,IAAI,GAAG,EAAC,MAAM,qBAAqB,CAAC;AAEnD,OAAO,EAAC,OAAO,IAAI,IAAI,EAAC,MAAM,sBAAsB,CAAC;AAMrD,OAAO,EAAC,OAAO,IAAI,MAAM,EAAC,MAAM,wBAAwB,CAAC;AAEzD,OAAO,EAAC,OAAO,IAAI,SAAS,EAAC,MAAM,2BAA2B,CAAC;AAE/D,OAAO,EAAC,OAAO,IAAI,OAAO,EAAC,MAAM,yBAAyB,CAAC;AAC3D,OAAO,EAAC,OAAO,IAAI,MAAM,EAAC,MAAM,wBAAwB,CAAC;AAEzD,OAAO,EAAC,OAAO,IAAI,QAAQ,EAAC,MAAM,sBAAsB,CAAC;AACzD,OAAO,EAAC,OAAO,IAAI,QAAQ,EAAC,MAAM,sBAAsB,CAAC;AACzD,OAAO,EAAC,OAAO,IAAI,MAAM,EAAC,MAAM,oBAAoB,CAAC;AACrD,OAAO,EAAC,OAAO,IAAI,QAAQ,EAAC,MAAM,sBAAsB,CAAC;AACzD,OAAO,EAAC,OAAO,IAAI,SAAS,EAAC,MAAM,uBAAuB,CAAC;AAC3D,OAAO,EAAC,OAAO,IAAI,SAAS,EAAC,MAAM,uBAAuB,CAAC;AAC3D,OAAO,EAAC,OAAO,IAAI,QAAQ,EAAC,MAAM,sBAAsB,CAAC;AACzD,OAAO,EAAC,OAAO,IAAI,eAAe,EAAC,MAAM,8BAA8B,CAAC;AACxE,OAAO,EAAC,OAAO,IAAI,wBAAwB,EAAC,MAAM,yCAAyC,CAAC;AAC5F,OAAO,EAAC,OAAO,IAAI,SAAS,EAAC,MAAM,uBAAuB,CAAC;AAE3D,OAAO,EAAC,OAAO,IAAI,YAAY,EAAC,MAAM,0BAA0B,CAAC;AAEjE,OAAO,EAAC,OAAO,IAAI,aAAa,EAAC,MAAM,4BAA4B,CAAC;AAEpE,OAAO,EAAC,OAAO,IAAI,aAAa,EAAC,MAAM,4BAA4B,CAAC;AAEpE,OAAO,EAAC,OAAO,IAAI,cAAc,EAAC,MAAM,sBAAsB,CAAC;AAE/D,OAAO,EAAC,UAAU,EAAE,cAAc,EAAC,MAAM,qBAAqB,CAAC"}

package/build/ink.d.ts

@@ -30,13 +30,45 @@ export type Options = {
     - `useTransition` and `useDeferredValue` are fully functional
     - Updates can be interrupted for higher priority work
 
-    Note: Concurrent mode changes the timing of renders. Some tests may need to use `act()` to properly await updates. The `concurrent` option only takes effect on the first render for a given stdout. If you need to change the rendering mode, call `unmount()` first.
+    Note: Concurrent mode changes the timing of renders. Some tests may need to use `act()` to properly await updates. Reusing the same stdout across multiple `render()` calls without unmounting is unsupported. Call `unmount()` first if you need to change the rendering mode or create a fresh instance.
 
     @default false
     @experimental
     */
     concurrent?: boolean;
     kittyKeyboard?: KittyKeyboardOptions;
+    /**
+    Override automatic interactive mode detection.
+
+    By default, Ink detects whether the environment is interactive based on CI detection (via [`is-in-ci`](https://github.com/sindresorhus/is-in-ci)) and `stdout.isTTY`. Most users should not need to set this.
+
+    When non-interactive, Ink disables ANSI erase sequences, cursor manipulation, synchronized output, resize handling, and kitty keyboard auto-detection, writing only the final frame at unmount.
+
+    Set to `false` to force non-interactive mode or `true` to force interactive mode when the automatic detection doesn't suit your use case.
+
+    Note: Reusing the same stdout across multiple `render()` calls without unmounting is unsupported. Call `unmount()` first if you need to change this option or create a fresh instance.
+
+    @default true (false if in CI or `stdout.isTTY` is falsy)
+
+    @see {@link RenderOptions.interactive}
+    */
+    interactive?: boolean;
+    /**
+    Render the app in the terminal's alternate screen buffer. When enabled, the app renders on a separate screen, and the original terminal content is restored when the app exits. This is the same mechanism used by programs like vim, htop, and less.
+
+    Note: The terminal's scrollback buffer is not available while in the alternate screen. This is standard terminal behavior; programs like vim use the alternate screen specifically to avoid polluting the user's scrollback history.
+
+    Note: Ink intentionally treats alternate-screen teardown output as disposable. It does not preserve or replay teardown-time frames, hook writes, or `console.*` output after restoring the primary screen.
+
+    Only works in interactive mode. Ignored when `interactive` is `false` or in a non-interactive environment (CI, piped stdout).
+
+    Note: Reusing the same stdout across multiple `render()` calls without unmounting is unsupported. Call `unmount()` first if you need to change this option or create a fresh instance.
+
+    @default false
+
+    @see {@link RenderOptions.alternateScreen}
+    */
+    alternateScreen?: boolean;
 };
 export default class Ink {
     /**
@@ -48,6 +80,9 @@ export default class Ink {
     private cursorPosition;
     private readonly throttledLog;
     private readonly isScreenReaderEnabled;
+    private readonly interactive;
+    private readonly renderThrottleMs;
+    private alternateScreen;
     private isUnmounted;
     private isUnmounting;
     private lastOutput;
@@ -57,7 +92,7 @@ export default class Ink {
     private readonly container;
     private readonly rootNode;
     private fullStaticOutput;
-    private exitPromise?;
+    private readonly exitPromise;
     private exitResult;
     private beforeExitHandler?;
     private restoreConsole?;
@@ -66,8 +101,8 @@ export default class Ink {
     private hasPendingThrottledRender;
     private kittyProtocolEnabled;
     private cancelKittyDetection?;
+    private nextRenderCommit?;
     constructor(options: Options);
-    getTerminalWidth: () => number;
     resized: () => void;
     resolveExitPromise: (result?: unknown) => void;
     rejectExitPromise: (reason?: Error) => void;
@@ -82,8 +117,18 @@ export default class Ink {
     writeToStderr(data: string): void;
     unmount(error?: Error | number | null): void;
     waitUntilExit(): Promise<unknown>;
+    waitUntilRenderFlush(): Promise<void>;
     clear(): void;
     patchConsole(): void;
+    private setAlternateScreen;
+    private resolveInteractiveOption;
+    private resolveAlternateScreenOption;
+    private shouldSync;
+    private writeBestEffort;
+    private awaitExit;
+    private hasPendingConcurrentWork;
+    private awaitNextRender;
+    private renderInteractiveFrame;
     private initKittyKeyboard;
     private confirmKittySupport;
     private enableKittyProtocol;