Add cursor shape control to useCursor hook

[ganassini]

Summary

Adds cursor shape control to the useCursor() hook (via a new shape option), exposing DECSCUSR (CSI Ps SP q) control. Supported shapes: block, bar, underline, plus blinking- variants, and default to actively restore the terminal's user-configured shape.

The shape is restored to the terminal default (CSI 0 SP q) on done(), SIGINT, and unhandled React tree throws, so apps never leak a custom cursor shape back to the parent shell.

Why

Cursor-shape control is the standard way TUI libraries and editors signal mode changes — ratatui exposes it via Frame::set_cursor_position + cursor style, and neovim (and vim itself) toggles between block/bar/underline on mode switches via DECSCUSR. Ink had no equivalent, so consumers building modal interfaces had to write the escape sequences manually and remember to clean up on exit.

Motivation

Programs built on Ink that implement modal input — Claude Code's input area, anything with a vim mode, REPLs distinguishing normal/insert states — benefit from a first-class API. Doing this in userland is doable but fragile: the restore-on-exit path requires hooking into Ink's signal/throw handling, which isn't part of the public surface.

Test plan

• npm test passes
• New log-update tests cover shape emission, idempotence, done() restore, sync() fullscreen path
• New useCursor tests cover React-level idempotence, non-interactive suppression, unmount/remount
• New PTY-based exit tests verify restore on SIGINT and on unhandled throw

[sindresorhus]

I think the feature makes sense, but I’d strongly prefer not adding setCursorShape() as a second independent imperative setter.

The more React shaped API would be one declarative cursor intent:

useCursor({
	position: {x, y},
	shape: 'bar',
});

That maps much better to React’s lifecycle. When the component renders, it declares the cursor state for that frame. When it updates, the cursor state updates. When it unmounts, that intent disappears and Ink can cleanly hide or reset it. With a separate setCursorShape() API, shape and position become two loosely coupled pieces of global terminal state, which creates awkward semantics like undefined meaning “leave the previous terminal shape as is”. That is surprising in React, where absence of a rendered owner usually means cleanup.

It also keeps the public model smaller. Cursor position, visibility, shape, blink, and maybe color are all attributes of the same terminal cursor. Treating them as one cursor object avoids duplicated dirty state and lifecycle handling in log-update, and matches what higher level TUI APIs tend to do.

tl;dr expose it as declarative cursor state rather than adding setCursorShape(). That gives us clearer unmount behavior, a smaller API surface, and room to add future cursor attributes without adding more independent setters.

[sindresorhus]

This currently removes the published return value from useCursor(). In v7.0.4, useCursor() returns {setCursorPosition}, and the README documents that pattern. With this change, existing code like const {setCursorPosition} = useCursor(); will throw at runtime. I think the declarative options API should be additive. The new API is better, but we don't want to break backwards compatibility.

Second, the unmount cleanup does not actually restore the cursor shape while the Ink app keeps running. The cleanup stores undefined, but undefined intentionally emits no DECSCUSR bytes, so a child that set shape: 'underline' can unmount and leave the terminal cursor underline until the whole app exits. This also conflicts with the new docs saying the cursor state is released when the component unmounts. I manually checked the bytes after unmounting a shape-owning child, and there was no CSI 0 SP q reset written, just the redraw/sync bytes. Might be worth adding a test for that exact case, becuase the current remount test only proves the next mount re-emits the shape.

[ganassini]

Will look into that.