@oh-my-pi/pi-tui 13.7.3 → 13.7.5

package/CHANGELOG.md

@@ -2,6 +2,11 @@
 
 ## [Unreleased]
 
+## [13.7.5] - 2026-03-04
+### Changed
+
+- Extracted word navigation logic into reusable `moveWordLeft` and `moveWordRight` utility functions for consistent cursor movement across components
+
 ## [13.6.2] - 2026-03-03
 ### Fixed
 

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@oh-my-pi/pi-tui",
-	"version": "13.7.3",
+	"version": "13.7.5",
 	"description": "Terminal User Interface library with differential rendering for efficient text-based applications",
 	"homepage": "https://github.com/can1357/oh-my-pi",
 	"author": "Can Boluk",
@@ -33,8 +33,8 @@
 		"test": "bun test test/*.test.ts"
 	},
 	"dependencies": {
-		"@oh-my-pi/pi-natives": "13.7.3",
-		"@oh-my-pi/pi-utils": "13.7.3",
+		"@oh-my-pi/pi-natives": "13.7.5",
+		"@oh-my-pi/pi-utils": "13.7.5",
 		"marked": "^17.0"
 	},
 	"devDependencies": {

package/src/components/editor.ts

@@ -6,7 +6,15 @@ import { matchesKey } from "../keys";
 import { KillRing } from "../kill-ring";
 import type { SymbolTheme } from "../symbols";
 import { type Component, CURSOR_MARKER, type Focusable } from "../tui";
-import { getSegmenter, isPunctuationChar, isWhitespaceChar, padding, truncateToWidth, visibleWidth } from "../utils";
+import {
+	getSegmenter,
+	getWordNavKind,
+	moveWordLeft,
+	moveWordRight,
+	padding,
+	truncateToWidth,
+	visibleWidth,
+} from "../utils";
 import { SelectList, type SelectListTheme } from "./select-list";
 
 const segmenter = getSegmenter();
@@ -51,7 +59,7 @@ function wordWrapLine(line: string, maxWidth: number): TextChunk[] {
 
 	for (const seg of segmenter.segment(line)) {
 		const grapheme = seg.segment;
-		const graphemeIsWhitespace = isWhitespaceChar(grapheme);
+		const graphemeIsWhitespace = getWordNavKind(grapheme) === "whitespace";
 
 		if (currentToken === "") {
 			inWhitespace = graphemeIsWhitespace;
@@ -89,6 +97,27 @@ function wordWrapLine(line: string, maxWidth: number): TextChunk[] {
 	let chunkStartIndex = 0;
 	let atLineStart = true; // Track if we're at the start of a line (for skipping whitespace)
 
+	function consumePrefixToWidth(text: string, availableWidth: number): { text: string; len: number } {
+		let prefix = "";
+		let prefixWidth = 0;
+		let len = 0;
+		for (const seg of segmenter.segment(text)) {
+			const grapheme = seg.segment;
+			const graphemeWidth = visibleWidth(grapheme);
+			if (prefixWidth + graphemeWidth > availableWidth) break;
+			prefix += grapheme;
+			prefixWidth += graphemeWidth;
+			len += grapheme.length;
+			if (prefixWidth === availableWidth) break;
+		}
+		return { text: prefix, len };
+	}
+	function hasWideGrapheme(text: string): boolean {
+		for (const seg of segmenter.segment(text)) {
+			if (visibleWidth(seg.segment) > 1) return true;
+		}
+		return false;
+	}
 	for (const token of tokens) {
 		const tokenWidth = visibleWidth(token.text);
 
@@ -101,28 +130,46 @@ function wordWrapLine(line: string, maxWidth: number): TextChunk[] {
 
 		// If this single token is wider than maxWidth, we need to break it
 		if (tokenWidth > maxWidth) {
-			// First, push any accumulated chunk
+			// If we're mid-line, try to use the remaining width by consuming a prefix of this long token.
+			let consumedPrefix = "";
+			let consumedPrefixLen = 0; // JS string index (code units) consumed from token.text
+			if (currentChunk && currentWidth < maxWidth) {
+				const remainingWidth = maxWidth - currentWidth;
+				const consumed = consumePrefixToWidth(token.text, remainingWidth);
+				consumedPrefix = consumed.text;
+				consumedPrefixLen = consumed.len;
+			}
+			// First, push any accumulated chunk (optionally filled with the prefix).
 			if (currentChunk) {
-				chunks.push({
-					text: currentChunk,
-					startIndex: chunkStartIndex,
-					endIndex: token.startIndex,
-				});
-				currentChunk = "";
-				currentWidth = 0;
-				chunkStartIndex = token.startIndex;
+				if (consumedPrefix) {
+					chunks.push({
+						text: currentChunk + consumedPrefix,
+						startIndex: chunkStartIndex,
+						endIndex: token.startIndex + consumedPrefixLen,
+					});
+					currentChunk = "";
+					currentWidth = 0;
+					chunkStartIndex = token.startIndex + consumedPrefixLen;
+				} else {
+					chunks.push({
+						text: currentChunk,
+						startIndex: chunkStartIndex,
+						endIndex: token.startIndex,
+					});
+					currentChunk = "";
+					currentWidth = 0;
+					chunkStartIndex = token.startIndex;
+				}
 			}
-
-			// Break the long token by grapheme
+			// Break the remaining long token by grapheme
+			const remainingText = consumedPrefixLen > 0 ? token.text.slice(consumedPrefixLen) : token.text;
 			let tokenChunk = "";
 			let tokenChunkWidth = 0;
-			let tokenChunkStart = token.startIndex;
-			let tokenCharIndex = token.startIndex;
-
-			for (const seg of segmenter.segment(token.text)) {
+			let tokenChunkStart = token.startIndex + consumedPrefixLen;
+			let tokenCharIndex = token.startIndex + consumedPrefixLen;
+			for (const seg of segmenter.segment(remainingText)) {
 				const grapheme = seg.segment;
 				const graphemeWidth = visibleWidth(grapheme);
-
 				if (tokenChunkWidth + graphemeWidth > maxWidth && tokenChunk) {
 					chunks.push({
 						text: tokenChunk,
@@ -138,7 +185,6 @@ function wordWrapLine(line: string, maxWidth: number): TextChunk[] {
 				}
 				tokenCharIndex += grapheme.length;
 			}
-
 			// Keep remainder as start of next chunk
 			if (tokenChunk) {
 				currentChunk = tokenChunk;
@@ -150,6 +196,25 @@ function wordWrapLine(line: string, maxWidth: number): TextChunk[] {
 
 		// Check if adding this token would exceed width
 		if (currentWidth + tokenWidth > maxWidth) {
+			// For wide-character tokens (e.g., CJK runs), prefer using remaining width before wrapping
+			// the whole token to the next line. This avoids leaving a short ASCII word alone.
+			if (currentChunk && !token.isWhitespace && currentWidth < maxWidth && hasWideGrapheme(token.text)) {
+				const remainingWidth = maxWidth - currentWidth;
+				const consumed = consumePrefixToWidth(token.text, remainingWidth);
+				if (consumed.text) {
+					chunks.push({
+						text: currentChunk + consumed.text,
+						startIndex: chunkStartIndex,
+						endIndex: token.startIndex + consumed.len,
+					});
+					const remainder = token.text.slice(consumed.len);
+					currentChunk = remainder;
+					currentWidth = visibleWidth(remainder);
+					chunkStartIndex = token.startIndex + consumed.len;
+					atLineStart = false;
+					continue;
+				}
+			}
 			// Push current chunk (trimming trailing whitespace for display)
 			const trimmedChunk = currentChunk.trimEnd();
 			if (trimmedChunk || chunks.length === 0) {
@@ -159,7 +224,6 @@ function wordWrapLine(line: string, maxWidth: number): TextChunk[] {
 					endIndex: chunkStartIndex + currentChunk.length,
 				});
 			}
-
 			// Start new line - skip leading whitespace
 			atLineStart = true;
 			if (token.isWhitespace) {
@@ -1942,35 +2006,7 @@ export class Editor implements Component, Focusable {
 			return;
 		}
 
-		const textBeforeCursor = currentLine.slice(0, this.#state.cursorCol);
-		const graphemes = [...segmenter.segment(textBeforeCursor)];
-		let newCol = this.#state.cursorCol;
-
-		// Skip trailing whitespace
-		while (graphemes.length > 0 && isWhitespaceChar(graphemes[graphemes.length - 1]?.segment || "")) {
-			newCol -= graphemes.pop()?.segment.length || 0;
-		}
-
-		if (graphemes.length > 0) {
-			const lastGrapheme = graphemes[graphemes.length - 1]?.segment || "";
-			if (isPunctuationChar(lastGrapheme)) {
-				// Skip punctuation run
-				while (graphemes.length > 0 && isPunctuationChar(graphemes[graphemes.length - 1]?.segment || "")) {
-					newCol -= graphemes.pop()?.segment.length || 0;
-				}
-			} else {
-				// Skip word run
-				while (
-					graphemes.length > 0 &&
-					!isWhitespaceChar(graphemes[graphemes.length - 1]?.segment || "") &&
-					!isPunctuationChar(graphemes[graphemes.length - 1]?.segment || "")
-				) {
-					newCol -= graphemes.pop()?.segment.length || 0;
-				}
-			}
-		}
-
-		this.#setCursorCol(newCol);
+		this.#setCursorCol(moveWordLeft(currentLine, this.#state.cursorCol));
 	}
 
 	/**
@@ -2019,36 +2055,7 @@ export class Editor implements Component, Focusable {
 			return;
 		}
 
-		const textAfterCursor = currentLine.slice(this.#state.cursorCol);
-		const segments = segmenter.segment(textAfterCursor);
-		const iterator = segments[Symbol.iterator]();
-		let next = iterator.next();
-		let newCol = this.#state.cursorCol;
-
-		// Skip leading whitespace
-		while (!next.done && isWhitespaceChar(next.value.segment)) {
-			newCol += next.value.segment.length;
-			next = iterator.next();
-		}
-
-		if (!next.done) {
-			const firstGrapheme = next.value.segment;
-			if (isPunctuationChar(firstGrapheme)) {
-				// Skip punctuation run
-				while (!next.done && isPunctuationChar(next.value.segment)) {
-					newCol += next.value.segment.length;
-					next = iterator.next();
-				}
-			} else {
-				// Skip word run
-				while (!next.done && !isWhitespaceChar(next.value.segment) && !isPunctuationChar(next.value.segment)) {
-					newCol += next.value.segment.length;
-					next = iterator.next();
-				}
-			}
-		}
-
-		this.#setCursorCol(newCol);
+		this.#setCursorCol(moveWordRight(currentLine, this.#state.cursorCol));
 	}
 
 	// Helper method to check if cursor is at start of message (for slash command detection)

package/src/components/input.ts

@@ -2,7 +2,15 @@ import { BracketedPasteHandler } from "../bracketed-paste";
 import { getEditorKeybindings } from "../keybindings";
 import { KillRing } from "../kill-ring";
 import { type Component, CURSOR_MARKER, type Focusable } from "../tui";
-import { getSegmenter, isPunctuationChar, isWhitespaceChar, padding, visibleWidth } from "../utils";
+import {
+	getSegmenter,
+	getWordNavKind,
+	moveWordLeft,
+	moveWordRight,
+	padding,
+	sliceWithWidth,
+	visibleWidth,
+} from "../utils";
 
 const segmenter = getSegmenter();
 
@@ -173,7 +181,7 @@ export class Input implements Component, Focusable {
 	}
 
 	#insertCharacter(text: string): void {
-		const isWordChunk = [...text].every(ch => !isWhitespaceChar(ch));
+		const isWordChunk = [...segmenter.segment(text)].every(seg => getWordNavKind(seg.segment) !== "whitespace");
 		// Undo coalescing: consecutive word typing coalesces into one undo unit.
 		if (!isWordChunk || this.#lastAction !== "type-word") {
 			this.#pushUndo();
@@ -336,68 +344,15 @@ export class Input implements Component, Focusable {
 			return;
 		}
 		this.#lastAction = null;
-
-		const textBeforeCursor = this.#value.slice(0, this.#cursor);
-		const graphemes = [...segmenter.segment(textBeforeCursor)];
-
-		// Skip trailing whitespace
-		while (graphemes.length > 0 && isWhitespaceChar(graphemes[graphemes.length - 1]?.segment || "")) {
-			this.#cursor -= graphemes.pop()?.segment.length || 0;
-		}
-
-		if (graphemes.length > 0) {
-			const lastGrapheme = graphemes[graphemes.length - 1]?.segment || "";
-			if (isPunctuationChar(lastGrapheme)) {
-				// Skip punctuation run
-				while (graphemes.length > 0 && isPunctuationChar(graphemes[graphemes.length - 1]?.segment || "")) {
-					this.#cursor -= graphemes.pop()?.segment.length || 0;
-				}
-			} else {
-				// Skip word run
-				while (
-					graphemes.length > 0 &&
-					!isWhitespaceChar(graphemes[graphemes.length - 1]?.segment || "") &&
-					!isPunctuationChar(graphemes[graphemes.length - 1]?.segment || "")
-				) {
-					this.#cursor -= graphemes.pop()?.segment.length || 0;
-				}
-			}
-		}
+		this.#cursor = moveWordLeft(this.#value, this.#cursor);
 	}
 
 	#moveWordForwards(): void {
 		if (this.#cursor >= this.#value.length) {
 			return;
 		}
-
 		this.#lastAction = null;
-		const textAfterCursor = this.#value.slice(this.#cursor);
-		const segments = segmenter.segment(textAfterCursor);
-		const iterator = segments[Symbol.iterator]();
-		let next = iterator.next();
-
-		// Skip leading whitespace
-		while (!next.done && isWhitespaceChar(next.value.segment)) {
-			this.#cursor += next.value.segment.length;
-			next = iterator.next();
-		}
-
-		if (!next.done) {
-			const firstGrapheme = next.value.segment;
-			if (isPunctuationChar(firstGrapheme)) {
-				// Skip punctuation run
-				while (!next.done && isPunctuationChar(next.value.segment)) {
-					this.#cursor += next.value.segment.length;
-					next = iterator.next();
-				}
-			} else {
-				// Skip word run
-				while (!next.done && !isWhitespaceChar(next.value.segment) && !isPunctuationChar(next.value.segment)) {
-					this.#cursor += next.value.segment.length;
-					next = iterator.next();
-				}
-			}
-		}
+		this.#cursor = moveWordRight(this.#value, this.#cursor);
 	}
 
 	#handlePaste(pastedText: string): void {
@@ -425,61 +380,37 @@ export class Input implements Component, Focusable {
 			return [prompt];
 		}
 
-		let visibleText = "";
-		let cursorDisplay = this.#cursor;
-
-		if (this.#value.length < availableWidth) {
-			// Everything fits (leave room for cursor at end)
-			visibleText = this.#value;
-		} else {
-			// Need horizontal scrolling
-			// Reserve one character for cursor if it's at the end
-			const scrollWidth = this.#cursor === this.#value.length ? availableWidth - 1 : availableWidth;
-			const halfWidth = Math.floor(scrollWidth / 2);
-
-			const findValidStart = (start: number) => {
-				while (start < this.#value.length) {
-					const charCode = this.#value.charCodeAt(start);
-					// this is low surrogate, not a valid start
-					if (charCode >= 0xdc00 && charCode < 0xe000) {
-						start++;
-						continue;
-					}
-					break;
-				}
-				return start;
-			};
-
-			const findValidEnd = (end: number) => {
-				while (end > 0) {
-					const charCode = this.#value.charCodeAt(end - 1);
-					// this is high surrogate, might be split.
-					if (charCode >= 0xd800 && charCode < 0xdc00) {
-						end--;
-						continue;
-					}
-					break;
-				}
-				return end;
-			};
-
-			if (this.#cursor < halfWidth) {
-				// Cursor near start
-				visibleText = this.#value.slice(0, findValidEnd(scrollWidth));
-				cursorDisplay = this.#cursor;
-			} else if (this.#cursor > this.#value.length - halfWidth) {
-				// Cursor near end
-				const start = findValidStart(this.#value.length - scrollWidth);
-				visibleText = this.#value.slice(start);
-				cursorDisplay = this.#cursor - start;
-			} else {
-				// Cursor in middle
-				const start = findValidStart(this.#cursor - halfWidth);
-				visibleText = this.#value.slice(start, findValidEnd(start + scrollWidth));
-				cursorDisplay = this.#cursor - start;
+		const cursorIndex = this.#cursor;
+		// Ensure we always have a grapheme to invert at the cursor (space at end).
+		const displayValue = cursorIndex >= this.#value.length ? `${this.#value} ` : this.#value;
+
+		const totalCols = visibleWidth(displayValue);
+		const cursorCols = visibleWidth(displayValue.slice(0, cursorIndex));
+
+		// Width of the grapheme at the cursor, for ensuring it fits in the viewport.
+		const cursorIter = segmenter.segment(displayValue.slice(cursorIndex))[Symbol.iterator]();
+		const cursorG = cursorIter.next().value?.segment ?? " ";
+		const cursorGWidth = visibleWidth(cursorG);
+
+		const maxStart = Math.max(0, totalCols - availableWidth);
+		let startCol = 0;
+		if (totalCols > availableWidth) {
+			const half = Math.floor(availableWidth / 2);
+			startCol = Math.max(0, Math.min(maxStart, cursorCols - half));
+
+			// Ensure the cursor grapheme is inside the viewport (and fits fully if wide).
+			const maxCursorRel = Math.max(0, availableWidth - cursorGWidth);
+			const cursorRel = cursorCols - startCol;
+			if (cursorRel > maxCursorRel) {
+				startCol = Math.max(0, Math.min(maxStart, cursorCols - maxCursorRel));
 			}
 		}
 
+		const visibleText = sliceWithWidth(displayValue, startCol, availableWidth, true).text;
+		const prefixText = sliceWithWidth(displayValue, startCol, Math.max(0, cursorCols - startCol), true).text;
+		let cursorDisplay = prefixText.length;
+		cursorDisplay = Math.max(0, Math.min(cursorDisplay, visibleText.length));
+
 		// Build line with fake cursor
 		// Insert cursor character at cursor position
 		const graphemes = [...segmenter.segment(visibleText.slice(cursorDisplay))];
@@ -491,16 +422,20 @@ export class Input implements Component, Focusable {
 
 		// Hardware cursor marker (zero-width, emitted before fake cursor for IME positioning)
 		const marker = this.focused ? CURSOR_MARKER : "";
-
 		// Use inverse video to show cursor
 		const cursorChar = `\x1b[7m${atCursor}\x1b[27m`; // ESC[7m = reverse video, ESC[27m = normal
-		const textWithCursor = beforeCursor + marker + cursorChar + afterCursor;
 
-		// Calculate visual width
-		const visualLength = visibleWidth(textWithCursor);
+		// Clamp only the trailing text (measured in terminal cells), keeping the cursor marker intact.
+		const beforeWidth = visibleWidth(beforeCursor);
+		const cursorWidth = visibleWidth(atCursor);
+		const remainingAfterWidth = Math.max(0, availableWidth - beforeWidth - cursorWidth);
+		const clampedAfterCursor = sliceWithWidth(afterCursor, 0, remainingAfterWidth, true).text;
+		const renderedNoMarker = beforeCursor + cursorChar + clampedAfterCursor;
+		const textWithCursor = beforeCursor + marker + cursorChar + clampedAfterCursor;
+
+		const visualLength = visibleWidth(renderedNoMarker);
 		const pad = padding(Math.max(0, availableWidth - visualLength));
 		const line = prompt + textWithCursor + pad;
-
 		return [line];
 	}
 }

package/src/utils.ts

@@ -97,6 +97,167 @@ export function isPunctuationChar(char: string): boolean {
 	return ASCII_PUNCTUATION[code] ?? false;
 }
 
+export type WordNavKind = "whitespace" | "delimiter" | "cjk" | "word" | "other";
+
+const WORD_NAV_RE_WHITESPACE = /^\p{White_Space}$/u;
+const WORD_NAV_RE_PUNCT = /^\p{P}$/u;
+const WORD_NAV_RE_SYMBOL = /^\p{S}$/u;
+const WORD_NAV_RE_LETTER = /^\p{L}$/u;
+const WORD_NAV_RE_NUMBER = /^\p{N}$/u;
+const WORD_NAV_RE_HAN = /^\p{Script=Han}$/u;
+const WORD_NAV_RE_HIRAGANA = /^\p{Script=Hiragana}$/u;
+const WORD_NAV_RE_KATAKANA = /^\p{Script=Katakana}$/u;
+const WORD_NAV_RE_HANGUL = /^\p{Script=Hangul}$/u;
+
+function firstCodePointChar(str: string): string {
+	const cp = str.codePointAt(0);
+	if (cp === undefined) return "";
+	return String.fromCodePoint(cp);
+}
+
+/**
+ * Coarse Unicode-aware character classification for word navigation (Option/Alt + Left/Right).
+ * This intentionally avoids language-specific word segmentation for predictability across scripts.
+ */
+export function getWordNavKind(grapheme: string): WordNavKind {
+	if (!grapheme) return "other";
+	const ch = firstCodePointChar(grapheme);
+	if (!ch) return "other";
+	if (WORD_NAV_RE_WHITESPACE.test(ch)) return "whitespace";
+	if (WORD_NAV_RE_PUNCT.test(ch) || WORD_NAV_RE_SYMBOL.test(ch)) return "delimiter";
+	if (
+		WORD_NAV_RE_HAN.test(ch) ||
+		WORD_NAV_RE_HIRAGANA.test(ch) ||
+		WORD_NAV_RE_KATAKANA.test(ch) ||
+		WORD_NAV_RE_HANGUL.test(ch)
+	) {
+		return "cjk";
+	}
+	if (ch === "_" || WORD_NAV_RE_LETTER.test(ch) || WORD_NAV_RE_NUMBER.test(ch)) return "word";
+	return "other";
+}
+
+const WORD_NAV_JOINERS = new Set(["'", "’", "-", "‐", "‑"]);
+
+export function isWordNavJoiner(grapheme: string): boolean {
+	const ch = firstCodePointChar(grapheme);
+	return WORD_NAV_JOINERS.has(ch);
+}
+
+/**
+ * Move the cursor one "word" to the left using Unicode-aware coarse navigation.
+ *
+ * Returns a new cursor index in the range [0, text.length].
+ */
+export function moveWordLeft(text: string, cursor: number): number {
+	const len = text.length;
+	if (len === 0) return 0;
+	let i = Math.min(Math.max(cursor, 0), len);
+	if (i === 0) return 0;
+
+	const graphemes = [...segmenter.segment(text.slice(0, i))];
+	if (graphemes.length === 0) return 0;
+
+	// Skip trailing whitespace.
+	while (graphemes.length > 0 && getWordNavKind(graphemes[graphemes.length - 1]?.segment || "") === "whitespace") {
+		i -= graphemes.pop()?.segment.length || 0;
+	}
+	if (i === 0 || graphemes.length === 0) return i;
+
+	const kind = getWordNavKind(graphemes[graphemes.length - 1]?.segment || "");
+	if (kind === "delimiter" || kind === "cjk") {
+		while (graphemes.length > 0 && getWordNavKind(graphemes[graphemes.length - 1]?.segment || "") === kind) {
+			i -= graphemes.pop()?.segment.length || 0;
+		}
+		return i;
+	}
+
+	if (kind === "word") {
+		// Skip word run (letters/numbers/underscore), keeping common joiners inside words.
+		let hasRightWord = false;
+		while (graphemes.length > 0) {
+			const g = graphemes[graphemes.length - 1]?.segment || "";
+			const k = getWordNavKind(g);
+			if (k === "word") {
+				hasRightWord = true;
+				i -= graphemes.pop()?.segment.length || 0;
+				continue;
+			}
+			if (hasRightWord && k === "delimiter" && isWordNavJoiner(g)) {
+				const left = graphemes[graphemes.length - 2]?.segment || "";
+				if (getWordNavKind(left) === "word") {
+					i -= graphemes.pop()?.segment.length || 0;
+					continue;
+				}
+			}
+			break;
+		}
+		return i;
+	}
+
+	// Fallback: move by one grapheme.
+	i -= graphemes.pop()?.segment.length || 0;
+	return Math.max(0, i);
+}
+
+/**
+ * Move the cursor one "word" to the right using Unicode-aware coarse navigation.
+ *
+ * Returns a new cursor index in the range [0, text.length].
+ */
+export function moveWordRight(text: string, cursor: number): number {
+	const len = text.length;
+	if (len === 0) return 0;
+	let i = Math.min(Math.max(cursor, 0), len);
+	if (i === len) return len;
+
+	const iterator = segmenter.segment(text.slice(i))[Symbol.iterator]();
+	let next = iterator.next();
+
+	// Skip leading whitespace.
+	while (!next.done && getWordNavKind(next.value.segment) === "whitespace") {
+		i += next.value.segment.length;
+		next = iterator.next();
+	}
+	if (next.done) return i;
+
+	const firstKind = getWordNavKind(next.value.segment);
+	if (firstKind === "delimiter" || firstKind === "cjk") {
+		while (!next.done && getWordNavKind(next.value.segment) === firstKind) {
+			i += next.value.segment.length;
+			next = iterator.next();
+		}
+		return i;
+	}
+
+	if (firstKind === "word") {
+		let hasLeftWord = false;
+		while (!next.done) {
+			const segment = next.value.segment;
+			const k = getWordNavKind(segment);
+			if (k === "word") {
+				hasLeftWord = true;
+				i += segment.length;
+				next = iterator.next();
+				continue;
+			}
+			if (hasLeftWord && k === "delimiter" && isWordNavJoiner(segment)) {
+				const lookahead = iterator.next();
+				if (!lookahead.done && getWordNavKind(lookahead.value.segment) === "word") {
+					i += segment.length;
+					next = lookahead;
+					continue;
+				}
+			}
+			break;
+		}
+		return i;
+	}
+
+	// Fallback: move by one grapheme.
+	return i + next.value.segment.length;
+}
+
 /**
  * Apply background color to a line, padding to full width.
  *
@@ -117,6 +278,7 @@ export function applyBackgroundToLine(line: string, width: number, bgFn: (text:
 
 /**
  * Extract a range of visible columns from a line. Handles ANSI codes and wide chars.
+ *
  * @param strict - If true, exclude wide chars at boundary that would extend past the range
  */
 export function sliceByColumn(line: string, startCol: number, length: number, strict = false): string {