nastech-tui 0.0.1

package/src/__tests__/textInputBurstInput.test.ts

@@ -0,0 +1,40 @@
+import { describe, expect, it } from 'vitest'
+
+import { applyPrintableInsert, shouldRouteMultiCharInputAsPaste } from '../components/textInput.js'
+
+describe('applyPrintableInsert', () => {
+  it('applies non-bracketed multi-character bursts immediately', () => {
+    const burst = applyPrintableInsert('abc', 3, 'xxxxx')
+
+    const repeated = [...'xxxxx'].reduce(
+      (state, ch) => applyPrintableInsert(state.value, state.cursor, ch)!,
+      { cursor: 3, value: 'abc' }
+    )
+
+    expect(burst).toEqual({ cursor: 8, value: 'abcxxxxx' })
+    expect(burst).toEqual(repeated)
+  })
+
+  it('replaces the selected range for burst input', () => {
+    expect(applyPrintableInsert('abZZef', 4, 'cd', { end: 4, start: 2 })).toEqual({
+      cursor: 4,
+      value: 'abcdef'
+    })
+  })
+
+  it('rejects control or escape-bearing input', () => {
+    expect(applyPrintableInsert('abc', 3, '\x1b[200~pasted')).toBeNull()
+    expect(applyPrintableInsert('abc', 3, '\t')).toBeNull()
+  })
+})
+
+describe('shouldRouteMultiCharInputAsPaste', () => {
+  it('keeps newline-bearing chunks on the paste path', () => {
+    expect(shouldRouteMultiCharInputAsPaste('hello\nworld')).toBe(true)
+    expect(shouldRouteMultiCharInputAsPaste('hello\r\nworld'.replace(/\r\n/g, '\n'))).toBe(true)
+  })
+
+  it('treats repeated printable key bursts as immediate input', () => {
+    expect(shouldRouteMultiCharInputAsPaste('xxxxx')).toBe(false)
+  })
+})

package/src/__tests__/textInputCursorSourceOfTruth.test.ts

@@ -0,0 +1,50 @@
+import { readFileSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+import { describe, expect, it } from 'vitest'
+
+// Locate textInput.tsx relative to this test file so the assertion
+// survives moves of the test fixture itself.
+const TEXT_INPUT_PATH = join(dirname(fileURLToPath(import.meta.url)), '..', 'components', 'textInput.tsx')
+const source = readFileSync(TEXT_INPUT_PATH, 'utf8')
+
+// Closes Copilot follow-up on PR #26717: the original cursor-drift
+// fix bumped Ink's displayCursor / cursorDeclaration on fast-echo, but
+// if TextInput itself re-renders before the deferred 16ms `setCur`
+// flushes (parent state change, status-bar tick, spinner) the layout
+// effect inside `useDeclaredCursor` re-publishes a declaration
+// computed from the STALE React `cur` state and clobbers the Ink-level
+// bump. The fix is structural: read `curRef.current` (always
+// up-to-date) when computing the layout, not the `cur` state.
+//
+// This file pins that invariant. Switching back to `cur` state — or
+// re-introducing a memo keyed on `cur` that uses `curRef.current`
+// inside but stops re-computing on rerender — is a regression and
+// should be caught here, not via a flaky integration test that mounts
+// Ink + stdin.
+describe('textInput cursor-layout source of truth', () => {
+  it('reads curRef.current (not the cur React state) for cursorLayout', () => {
+    // The line we care about. We allow whitespace / formatting drift,
+    // but the call itself must use `curRef.current`.
+    expect(source).toMatch(/cursorLayout\(\s*display\s*,\s*curRef\.current\s*,\s*columns\s*\)/)
+  })
+
+  it('does not pass the bare `cur` React state into cursorLayout', () => {
+    // Any `cursorLayout(display, cur, columns)` invocation would
+    // reintroduce the stale-declaration window.
+    expect(source).not.toMatch(/cursorLayout\(\s*display\s*,\s*cur\s*,\s*columns\s*\)/)
+  })
+
+  it('keeps the fast-echo notifier calls paired with the stdout writes', () => {
+    // Both fast-echo paths must call noteCursorAdvance, otherwise Ink
+    // never learns about the out-of-band write and drifts again. We
+    // tolerate explanatory comments in between (the rationale block is
+    // intentionally long), but the pairing itself must hold.
+    const backspacePattern = /stdout!\.write\(['"`]\\b \\b['"`]\)[\s\S]{0,1000}?noteCursorAdvance\(-1\)/
+    expect(source).toMatch(backspacePattern)
+
+    const appendPattern = /stdout!\.write\(text\)[\s\S]{0,1000}?noteCursorAdvance\(text\.length\)/
+    expect(source).toMatch(appendPattern)
+  })
+})

package/src/__tests__/textInputFastEcho.test.ts

@@ -0,0 +1,200 @@
+import { describe, expect, it } from 'vitest'
+
+import { canFastAppendShape, canFastBackspaceShape, supportsFastEchoTerminal } from '../components/textInput.js'
+
+// The fast-echo path bypasses Ink and writes characters directly to stdout
+// for the common case of typing plain English at the end of the line. These
+// tests pin the shape preconditions that make that bypass safe.
+//
+// Regression intent: any non-ASCII text — Vietnamese precomposed letters
+// (one grapheme, `text.length === 1`, `stringWidth === 1`, but produced
+// via IME composition across multiple keystrokes), combining marks
+// (zero width), CJK (double width), emoji (variable width), or anything
+// that could be produced by an in-flight IME composition — must NOT
+// take the bypass. Closes:
+//   - "TUI is experiencing font errors when using Unicode to type Vietnamese"
+//   - #5221  TUI input box renders incorrectly for CJK / East-Asian wide
+//   - #7443  CLI TUI renders and deletes Chinese characters incorrectly
+//   - #17602 / #17603  Chinese text scattering / ghosting
+
+describe('canFastAppendShape', () => {
+  const COLS = 40
+
+  it('accepts plain ASCII appended at end of single-line input', () => {
+    expect(canFastAppendShape('hello', 5, 'x', COLS, 5)).toBe(true)
+    expect(canFastAppendShape('hello', 5, ' world', COLS, 5)).toBe(true)
+  })
+
+  it('rejects when cursor is not at end of line', () => {
+    expect(canFastAppendShape('hello', 3, 'x', COLS, 5)).toBe(false)
+  })
+
+  it('rejects when current is empty (placeholder render path needed)', () => {
+    expect(canFastAppendShape('', 0, 'x', COLS, 0)).toBe(false)
+  })
+
+  it('rejects when current contains a newline (multi-line layout)', () => {
+    expect(canFastAppendShape('hi\nthere', 8, 'x', COLS, 5)).toBe(false)
+  })
+
+  it('rejects when appending would hit the wrap column', () => {
+    // Reaching cols on append must trigger a wrap, which the bypass
+    // cannot draw. Stay strictly below cols.
+    expect(canFastAppendShape('hello', 5, 'x', 6, 5)).toBe(false)
+  })
+
+  // -- Regression coverage: Vietnamese / combining marks / IME --
+
+  it('rejects Vietnamese precomposed letter ề (U+1EC1) — IME composition path', () => {
+    // 'ề' is one grapheme, length 1, width 1, but Vietnamese Telex/IME
+    // produces it via a multi-key composition. Fast-echo would commit the
+    // intermediate state to stdout and desync once the final commit
+    // arrives.
+    expect(canFastAppendShape('hello', 5, 'ề', COLS, 5)).toBe(false)
+  })
+
+  it('rejects Vietnamese tone marks ă, ơ, ư (Latin-Extended-A/B)', () => {
+    for (const ch of ['ă', 'ắ', 'ơ', 'ờ', 'ư', 'ự']) {
+      expect(canFastAppendShape('hello', 5, ch, COLS, 5)).toBe(false)
+    }
+  })
+
+  it('rejects NFD combining marks (U+0300 grave, U+0301 acute, U+0302 circumflex)', () => {
+    // Decomposed Vietnamese: 'e' + combining circumflex + combining grave
+    // = 'ề'. Each combining mark is zero-width but length 1; without the
+    // ASCII guard the second/third keypress would be fast-echoed and
+    // desync the cell column.
+    expect(canFastAppendShape('hello', 5, '\u0300', COLS, 5)).toBe(false)
+    expect(canFastAppendShape('hello', 5, '\u0301', COLS, 5)).toBe(false)
+    expect(canFastAppendShape('hello', 5, '\u0302', COLS, 5)).toBe(false)
+  })
+
+  it('rejects CJK (East-Asian wide) characters', () => {
+    expect(canFastAppendShape('hello', 5, '你', COLS, 5)).toBe(false)
+    expect(canFastAppendShape('hello', 5, '日本', COLS, 5)).toBe(false)
+  })
+
+  it('rejects emoji', () => {
+    expect(canFastAppendShape('hello', 5, '🙂', COLS, 5)).toBe(false)
+  })
+
+  it('rejects ANSI-bearing or control text', () => {
+    expect(canFastAppendShape('hello', 5, '\x1b[31m', COLS, 5)).toBe(false)
+    expect(canFastAppendShape('hello', 5, '\t', COLS, 5)).toBe(false)
+    expect(canFastAppendShape('hello', 5, '\x7f', COLS, 5)).toBe(false)
+  })
+
+  it('rejects NBSP and Latin-1 letters that would change the line shape', () => {
+    expect(canFastAppendShape('hello', 5, '\u00a0', COLS, 5)).toBe(false)
+    expect(canFastAppendShape('hello', 5, 'é', COLS, 5)).toBe(false)
+    expect(canFastAppendShape('hello', 5, 'ñ', COLS, 5)).toBe(false)
+  })
+})
+
+describe('canFastBackspaceShape', () => {
+  it('accepts deleting the last ASCII char', () => {
+    expect(canFastBackspaceShape('hello', 5)).toBe(true)
+  })
+
+  it('rejects when cursor is not at end', () => {
+    expect(canFastBackspaceShape('hello', 3)).toBe(false)
+  })
+
+  it('rejects when there is nothing to delete', () => {
+    expect(canFastBackspaceShape('', 0)).toBe(false)
+    expect(canFastBackspaceShape('hello', 0)).toBe(false)
+  })
+
+  it('rejects when value contains a newline', () => {
+    expect(canFastBackspaceShape('hi\nthere', 8)).toBe(false)
+  })
+
+  it('rejects deleting Vietnamese precomposed letter ề', () => {
+    // The "\b \b" shortcut clears one terminal cell; that's fine for a
+    // 1-cell ASCII char but if the previous grapheme is a Vietnamese
+    // letter that the IME may still be holding open, we want Ink to
+    // re-render so composition state stays consistent.
+    expect(canFastBackspaceShape('helloề', 'helloề'.length)).toBe(false)
+  })
+
+  it('rejects deleting a CJK character (2 cells)', () => {
+    expect(canFastBackspaceShape('hi你', 'hi你'.length)).toBe(false)
+  })
+
+  it('rejects deleting a NFD-composed grapheme with combining marks', () => {
+    // 'e' + U+0302 (circumflex) + U+0300 (grave) — final grapheme is one
+    // cluster but the previous-grapheme slice is multi-codepoint. Width
+    // is 1 but the bypass would be unsafe because the rendered cell
+    // already contained the combined glyph.
+    const s = 'hello' + 'e\u0302\u0300'
+    expect(canFastBackspaceShape(s, s.length)).toBe(false)
+  })
+
+  it('rejects deleting an emoji', () => {
+    expect(canFastBackspaceShape('hi🙂', 'hi🙂'.length)).toBe(false)
+  })
+
+  // Closes Copilot PR #26717 round 3: the "\b \b" sequence cannot move
+  // the terminal cursor onto the previous visual row across a
+  // soft-wrap boundary. When the caret sits at visual column 0 of a
+  // wrapped row (column == 0 in the computed cursor layout), backspace
+  // would leave the physical cursor in place while the logical caret
+  // moves up to the end of the previous visual line — desyncing both
+  // Ink's displayCursor model and the user-visible position. The fast
+  // path must fall through in that case so the normal Ink render path
+  // can lay out the correct cursor position.
+  it('rejects fast-backspace at a soft-wrap boundary when columns is known', () => {
+    // value width 6 in a column of 6 → cursorLayout produces (line 1, col 0)
+    // i.e. the caret has overflowed onto the next visual line.
+    const value = 'hello '
+    expect(canFastBackspaceShape(value, value.length, 6)).toBe(false)
+  })
+
+  it('rejects fast-backspace at an exact multiple of columns (wide wrap)', () => {
+    // 12 chars at width 6 → two full visual rows, caret at (line 2, col 0).
+    const value = 'abcdefghijkl'
+    expect(canFastBackspaceShape(value, value.length, 6)).toBe(false)
+  })
+
+  it('still accepts fast-backspace inside a wrapped line', () => {
+    // Caret mid-visual-line — "\b \b" can move the cursor one cell left
+    // without crossing a wrap boundary.
+    expect(canFastBackspaceShape('hello world', 'hello world'.length, 20)).toBe(true)
+    expect(canFastBackspaceShape('abcdefghi', 9, 6)).toBe(true) // visual line 1, col 3 → ok
+  })
+
+  it('skips the wrap-boundary check when columns is omitted (legacy contract)', () => {
+    // Callers that don't pass `columns` fall back to the pre-wrap-aware
+    // behavior — the function does NOT magically reject anything that
+    // could be a wrap boundary without the width. Production callers
+    // must always pass `columns`; this case is for unit tests of the
+    // pre-wrap shape contract.
+    expect(canFastBackspaceShape('hello ', 'hello '.length)).toBe(true)
+  })
+})
+
+describe('supportsFastEchoTerminal', () => {
+  it('disables fast-echo in Apple Terminal', () => {
+    expect(supportsFastEchoTerminal({ TERM_PROGRAM: 'Apple_Terminal' } as NodeJS.ProcessEnv)).toBe(false)
+  })
+
+  it('disables fast-echo by default in Termux mode', () => {
+    expect(
+      supportsFastEchoTerminal({ TERMUX_VERSION: '0.118.0', PREFIX: '/data/data/com.termux/files/usr' } as NodeJS.ProcessEnv)
+    ).toBe(false)
+  })
+
+  it('allows explicit Termux fast-echo opt-in via env override', () => {
+    expect(
+      supportsFastEchoTerminal({
+        NASTECH_TUI_TERMUX_FAST_ECHO: '1',
+        TERMUX_VERSION: '0.118.0'
+      } as NodeJS.ProcessEnv)
+    ).toBe(true)
+  })
+
+  it('keeps fast-echo enabled in VS Code and unknown non-Termux terminals', () => {
+    expect(supportsFastEchoTerminal({ TERM_PROGRAM: 'vscode' } as NodeJS.ProcessEnv)).toBe(true)
+    expect(supportsFastEchoTerminal({ TERM: 'xterm-256color' } as NodeJS.ProcessEnv)).toBe(true)
+  })
+})

package/src/__tests__/textInputLineNav.test.ts

@@ -0,0 +1,55 @@
+import { describe, expect, it } from 'vitest'
+
+import { lineNav } from '../components/textInput.js'
+
+describe('lineNav', () => {
+  it('returns null for single-line input (up)', () => {
+    expect(lineNav('hello world', 6, -1)).toBeNull()
+  })
+
+  it('returns null for single-line input (down)', () => {
+    expect(lineNav('hello world', 6, 1)).toBeNull()
+  })
+
+  it('returns null when cursor already on first line of a multiline block', () => {
+    expect(lineNav('one\ntwo\nthree', 2, -1)).toBeNull()
+  })
+
+  it('returns null when cursor on last line of a multiline block', () => {
+    expect(lineNav('one\ntwo\nthree', 10, 1)).toBeNull()
+  })
+
+  it('moves cursor up one line preserving column', () => {
+    // "hello\nworld" — cursor at col 3 of line 1 ('l' in world) → col 3 of line 0 ('l' in hello)
+    expect(lineNav('hello\nworld', 9, -1)).toBe(3)
+  })
+
+  it('moves cursor down one line preserving column', () => {
+    // cursor at col 2 of line 0 → col 2 of line 1
+    expect(lineNav('hello\nworld', 2, 1)).toBe(8)
+  })
+
+  it('clamps to end of shorter destination line on up', () => {
+    // col 10 on long line → clamp to end of short line "abc"
+    const s = 'abc\nlong long text'
+    const from = 14
+
+    expect(lineNav(s, from, -1)).toBe(3)
+  })
+
+  it('clamps to end of shorter destination line on down', () => {
+    // col 10 on line 0 → clamp to end of "abc" on line 1
+    const s = 'long long text\nabc'
+
+    expect(lineNav(s, 10, 1)).toBe(18)
+  })
+
+  it('handles empty lines correctly', () => {
+    // "a\n\nb" — cursor at line 2 (b) → up to empty line 1
+    expect(lineNav('a\n\nb', 3, -1)).toBe(2)
+  })
+
+  it('handles leading newline without crashing', () => {
+    expect(lineNav('\nfoo', 2, -1)).toBe(0)
+  })
+})

package/src/__tests__/textInputPassThrough.test.ts

@@ -0,0 +1,59 @@
+import { describe, expect, it } from 'vitest'
+
+import { shouldPassThroughToGlobalHandler, shouldPreserveCtrlJNewline } from '../components/textInput.js'
+import { DEFAULT_VOICE_RECORD_KEY, parseVoiceRecordKey } from '../lib/platform.js'
+
+const key = (overrides: Record<string, unknown> = {}) =>
+  ({ ctrl: false, meta: false, ...overrides }) as any
+
+describe('shouldPreserveCtrlJNewline', () => {
+  it('preserves Ctrl+J as newline in Ghostty even when tmux masks TERM/TERM_PROGRAM', () => {
+    expect(
+      shouldPreserveCtrlJNewline({
+        GHOSTTY_RESOURCES_DIR: '/usr/share/ghostty',
+        TERM: 'tmux-256color',
+        TERM_PROGRAM: 'tmux'
+      })
+    ).toBe(true)
+  })
+
+  it('keeps bare local POSIX LF-compatible prompts submitting on Ctrl+J', () => {
+    expect(shouldPreserveCtrlJNewline({ TERM: 'xterm-256color' })).toBe(false)
+  })
+})
+
+describe('shouldPassThroughToGlobalHandler', () => {
+  it('passes through the configured voice shortcut while composer is focused', () => {
+    expect(
+      shouldPassThroughToGlobalHandler('o', key({ ctrl: true }), parseVoiceRecordKey('ctrl+o'))
+    ).toBe(true)
+    expect(
+      shouldPassThroughToGlobalHandler('r', key({ meta: true }), parseVoiceRecordKey('alt+r'))
+    ).toBe(true)
+    expect(
+      shouldPassThroughToGlobalHandler(' ', key({ ctrl: true }), parseVoiceRecordKey('ctrl+space'))
+    ).toBe(true)
+    expect(
+      shouldPassThroughToGlobalHandler('', key({ ctrl: true, return: true }), parseVoiceRecordKey('ctrl+enter'))
+    ).toBe(true)
+  })
+
+  it('keeps the legacy default pass-through when no custom key is provided', () => {
+    expect(shouldPassThroughToGlobalHandler('b', key({ ctrl: true }), DEFAULT_VOICE_RECORD_KEY)).toBe(true)
+    expect(shouldPassThroughToGlobalHandler('b', key({ ctrl: true }))).toBe(true)
+  })
+
+  it('does not swallow ordinary typing keys', () => {
+    expect(shouldPassThroughToGlobalHandler('h', key(), parseVoiceRecordKey('ctrl+o'))).toBe(false)
+    expect(shouldPassThroughToGlobalHandler('o', key(), parseVoiceRecordKey('ctrl+o'))).toBe(false)
+  })
+
+  it('always passes through non-voice global control keys', () => {
+    expect(shouldPassThroughToGlobalHandler('c', key({ ctrl: true }))).toBe(true)
+    expect(shouldPassThroughToGlobalHandler('x', key({ ctrl: true }))).toBe(true)
+    expect(shouldPassThroughToGlobalHandler('', key({ escape: true }))).toBe(true)
+    expect(shouldPassThroughToGlobalHandler('', key({ tab: true }))).toBe(true)
+    expect(shouldPassThroughToGlobalHandler('', key({ pageUp: true }))).toBe(true)
+    expect(shouldPassThroughToGlobalHandler('', key({ pageDown: true }))).toBe(true)
+  })
+})

package/src/__tests__/textInputRightClick.test.ts

@@ -0,0 +1,48 @@
+import { describe, expect, it } from 'vitest'
+
+import { decideRightClickAction } from '../components/textInput.js'
+
+describe('decideRightClickAction', () => {
+  it('returns paste when there is no selection', () => {
+    expect(decideRightClickAction('hello world', null)).toEqual({ action: 'paste' })
+  })
+
+  it('returns paste for a collapsed (empty) range', () => {
+    expect(decideRightClickAction('hello world', { end: 5, start: 5 })).toEqual({
+      action: 'paste'
+    })
+  })
+
+  it('copies the slice when range covers non-empty text', () => {
+    expect(decideRightClickAction('hello world', { end: 5, start: 0 })).toEqual({
+      action: 'copy',
+      text: 'hello'
+    })
+  })
+
+  it('copies a middle slice', () => {
+    expect(decideRightClickAction('hello world', { end: 11, start: 6 })).toEqual({
+      action: 'copy',
+      text: 'world'
+    })
+  })
+
+  it('falls back to paste when slice is empty (out-of-range indices)', () => {
+    expect(decideRightClickAction('', { end: 5, start: 0 })).toEqual({ action: 'paste' })
+  })
+
+  it('handles unicode (emoji, CJK) in the slice', () => {
+    const value = 'hi 你好 🎉'
+    expect(decideRightClickAction(value, { end: 5, start: 3 })).toEqual({
+      action: 'copy',
+      text: '你好'
+    })
+  })
+
+  it('preserves leading/trailing whitespace in the copied slice', () => {
+    expect(decideRightClickAction('  spaced  ', { end: 10, start: 0 })).toEqual({
+      action: 'copy',
+      text: '  spaced  '
+    })
+  })
+})

package/src/__tests__/textInputWrap.test.ts

@@ -0,0 +1,151 @@
+import { wrapAnsi } from '@nastechai/ink'
+import { describe, expect, it } from 'vitest'
+
+import { offsetFromPosition } from '../components/textInput.js'
+import { composerPromptWidth, cursorLayout, inputVisualHeight, stableComposerColumns } from '../lib/inputMetrics.js'
+
+// Helper: compute the "end of text" position that wrap-ansi would render
+// the input to. This is what Ink's <Text wrap="wrap"> uses, so cursorLayout
+// MUST agree. Disagreement is the cursor-drift bug.
+function wrapAnsiEndPosition(text: string, cols: number): { line: number; column: number } {
+  const wrapped = wrapAnsi(text, cols, { hard: true, trim: false })
+  const lines = wrapped.split('\n')
+  const last = lines[lines.length - 1] ?? ''
+
+  return { line: lines.length - 1, column: last.length }
+}
+
+describe('cursorLayout — word-wrap parity with wrap-ansi', () => {
+  it('places cursor mid-line at its column', () => {
+    expect(cursorLayout('hello world', 6, 40)).toEqual({ column: 6, line: 0 })
+  })
+
+  it('places cursor at end of a non-full line', () => {
+    expect(cursorLayout('hi', 2, 10)).toEqual({ column: 2, line: 0 })
+  })
+
+  it('does not push exact-fill text onto a phantom next line', () => {
+    // Regression: the previous hand-rolled wrap algorithm forced the cursor
+    // onto (line+1, 0) when the text exactly filled the row. wrap-ansi keeps
+    // it on the same row (no soft-wrap), so the cursor must too — otherwise
+    // useDeclaredCursor parks the hardware cursor below the last char and
+    // the user sees several blank cells between text and cursor block
+    // (#cursor-drift-multiline).
+    expect(cursorLayout('abcdefgh', 8, 8)).toEqual({ column: 8, line: 0 })
+    expect(cursorLayout('abcdefgh', 8, 8)).toEqual(wrapAnsiEndPosition('abcdefgh', 8))
+  })
+
+  it('keeps short words on the current line when they fit (no phantom wrap)', () => {
+    // wrap-ansi: "hello wo" at cols=8 stays as one line "hello wo".
+    // The old cursorLayout incorrectly pushed to (1,0) because column=8 hit
+    // the column>=width check, but that disagreed with what Ink actually
+    // rendered.
+    expect(cursorLayout('hello wo', 8, 8)).toEqual({ column: 8, line: 0 })
+    expect(cursorLayout('hello wo', 8, 8)).toEqual(wrapAnsiEndPosition('hello wo', 8))
+  })
+
+  it('moves words across wrap boundaries instead of splitting them', () => {
+    // "hello wor" at cols=8: wrap-ansi breaks at the space, "hello \nwor".
+    expect(cursorLayout('hello wor', 9, 8)).toEqual({ column: 3, line: 1 })
+    expect(cursorLayout('hello worl', 10, 8)).toEqual({ column: 4, line: 1 })
+    expect(cursorLayout('hello world', 11, 8)).toEqual({ column: 5, line: 1 })
+
+    // Each must match what wrap-ansi would actually render.
+    expect(cursorLayout('hello wor', 9, 8)).toEqual(wrapAnsiEndPosition('hello wor', 8))
+    expect(cursorLayout('hello worl', 10, 8)).toEqual(wrapAnsiEndPosition('hello worl', 8))
+    expect(cursorLayout('hello world', 11, 8)).toEqual(wrapAnsiEndPosition('hello world', 8))
+  })
+
+  it('wraps the next word instead of splitting it at the right edge', () => {
+    const text = 'hello world baby chickens are so cool its really rainy outside but wish'
+
+    expect(cursorLayout(text, text.length, 70)).toEqual({ column: 4, line: 1 })
+    expect(inputVisualHeight(text, 70)).toBe(2)
+  })
+
+  it('honours explicit newlines', () => {
+    expect(cursorLayout('one\ntwo', 5, 40)).toEqual({ column: 1, line: 1 })
+    expect(cursorLayout('one\ntwo', 4, 40)).toEqual({ column: 0, line: 1 })
+  })
+
+  it('does not wrap when cursor is before the right edge', () => {
+    expect(cursorLayout('abcdefg', 7, 8)).toEqual({ column: 7, line: 0 })
+  })
+
+  it('matches wrap-ansi end-position for typing-style incremental input', () => {
+    // Pins the actual fix: type a long message char-by-char at a narrow
+    // width and assert the cursor follows wrap-ansi every step of the way.
+    // Before the fix, ~5 boundary positions per pass disagreed and Ink
+    // parked the cursor several cells past the last rendered character.
+    const MSG = 'on a new bb branch investigate and fix the cursor drift bug here'
+
+    for (const cols of [10, 14, 20, 30, 50, 80]) {
+      let acc = ''
+
+      for (const ch of MSG) {
+        acc += ch
+        expect(cursorLayout(acc, acc.length, cols)).toEqual(wrapAnsiEndPosition(acc, cols))
+      }
+    }
+  })
+})
+
+describe('input metrics helpers', () => {
+  it('computes visual height matching wrap-ansi line count', () => {
+    // Exact-fill text stays on one line in wrap-ansi (no phantom wrap), so
+    // visual height is 1. The previous implementation reported 2 here.
+    expect(inputVisualHeight('abcdefgh', 8)).toBe(1)
+    expect(inputVisualHeight('one\ntwo', 40)).toBe(2)
+    // Multi-line wrap case sanity
+    expect(inputVisualHeight('hello world', 8)).toBe(2)
+  })
+
+  it('counts the prompt gap as its own cell', () => {
+    expect(composerPromptWidth('>')).toBe(2)
+    expect(composerPromptWidth('❯')).toBe(2)
+    expect(composerPromptWidth('Ψ >')).toBe(4)
+  })
+
+  it('reserves gutters on wide panes without starving narrow composer width', () => {
+    expect(stableComposerColumns(100, 3)).toBe(93)
+    expect(stableComposerColumns(100, 5)).toBe(91)
+    expect(stableComposerColumns(10, 3)).toBe(5)
+    expect(stableComposerColumns(6, 3)).toBe(1)
+  })
+})
+
+describe('offsetFromPosition — word-wrap inverse of cursorLayout', () => {
+  it('returns 0 for empty input', () => {
+    expect(offsetFromPosition('', 0, 0, 10)).toBe(0)
+  })
+
+  it('maps clicks within a single line', () => {
+    expect(offsetFromPosition('hello', 0, 3, 40)).toBe(3)
+  })
+
+  it('maps clicks past end to value length', () => {
+    expect(offsetFromPosition('hi', 0, 10, 40)).toBe(2)
+  })
+
+  it('maps clicks on a wrapped second row at cols boundary', () => {
+    // Long words still hard-wrap when there is no word boundary.
+    expect(offsetFromPosition('abcdefghij', 1, 0, 8)).toBe(8)
+  })
+
+  it('maps clicks on a word-wrapped second row', () => {
+    // "hello world" at cols=8 wraps to "hello \nworld".
+    expect(offsetFromPosition('hello world', 1, 0, 8)).toBe(6)
+    expect(offsetFromPosition('hello world', 1, 3, 8)).toBe(9)
+  })
+
+  it('maps clicks on the moved final word', () => {
+    const text = 'hello world baby chickens are so cool its really rainy outside but wish'
+
+    expect(offsetFromPosition(text, 1, 0, 70)).toBe(text.indexOf('wish'))
+    expect(offsetFromPosition(text, 1, 3, 70)).toBe(text.indexOf('wish') + 3)
+  })
+
+  it('maps clicks past a \\n into the target line', () => {
+    expect(offsetFromPosition('one\ntwo', 1, 2, 40)).toBe(6)
+  })
+})