@robota-sdk/agent-ui-terminal 3.0.0-beta.81

package/src/execution-workspace-switcher-selection.ts

@@ -0,0 +1,118 @@
+/**
+ * The switcher's selection state: where the cursor is, which slice of entries is on screen, and what
+ * a keypress does to both.
+ *
+ * Split out of `ExecutionWorkspaceSwitcher.tsx` (CLI-1994 + CLI-2004 both grew that file past its
+ * size budget) along the seam that was already there: this half owns "what is selected", the
+ * component owns "what is drawn".
+ */
+
+import { useEffect, useRef, useState } from 'react';
+
+import {
+  applySelectionInput,
+  createSelectionFlowState,
+  normalizeSelectionState,
+  type ISelectionFlowState,
+  type TSelectionInputAction,
+} from './flows/selection-flow.js';
+
+import type { IExecutionWorkspaceEntry } from '@robota-sdk/agent-interface-execution';
+import type React from 'react';
+
+/** How many entries the list shows at once; the rest scroll. Read only by this module. */
+const MAX_VISIBLE_WORKSPACE_ENTRIES = 8;
+
+export interface IUseWorkspaceSwitcherSelectionInput {
+  entries: IExecutionWorkspaceEntry[];
+  selectedEntryId?: string;
+  onSelect: (entryId: string) => void;
+  onClose: () => void;
+}
+
+export function useWorkspaceSwitcherSelection({
+  entries,
+  selectedEntryId,
+  onSelect,
+  onClose,
+}: IUseWorkspaceSwitcherSelectionInput): {
+  normalized: ISelectionFlowState;
+  visibleEntries: IExecutionWorkspaceEntry[];
+  applyAction: (action: TSelectionInputAction) => void;
+} {
+  const [state, setState] = useState<ISelectionFlowState>(() => createSelectionFlowState());
+  const stateRef = useRef(state);
+
+  useEffect(() => {
+    const selectedIndex = Math.max(
+      0,
+      entries.findIndex((entry) => entry.id === selectedEntryId),
+    );
+    const nextState = createNormalizedSelection({ selectedIndex, itemCount: entries.length });
+    stateRef.current = nextState;
+    setState(nextState);
+  }, [entries.length, selectedEntryId]);
+
+  const normalized = createNormalizedSelection({
+    selectedIndex: state.selectedIndex,
+    scrollOffset: state.scrollOffset,
+    itemCount: entries.length,
+  });
+  if (normalized !== state) stateRef.current = normalized;
+  return {
+    normalized,
+    visibleEntries: entries.slice(
+      normalized.scrollOffset,
+      normalized.scrollOffset + MAX_VISIBLE_WORKSPACE_ENTRIES,
+    ),
+    applyAction: createApplyAction({ entries, stateRef, setState, onSelect, onClose }),
+  };
+}
+
+function createApplyAction({
+  entries,
+  stateRef,
+  setState,
+  onSelect,
+  onClose,
+}: {
+  entries: IExecutionWorkspaceEntry[];
+  stateRef: React.MutableRefObject<ISelectionFlowState>;
+  setState: React.Dispatch<React.SetStateAction<ISelectionFlowState>>;
+  onSelect: (entryId: string) => void;
+  onClose: () => void;
+}): (action: TSelectionInputAction) => void {
+  return (action): void => {
+    const result = applySelectionInput(stateRef.current, action, {
+      itemCount: entries.length,
+      maxVisible: MAX_VISIBLE_WORKSPACE_ENTRIES,
+    });
+    const nextState =
+      result.effect.type === 'select' || result.effect.type === 'cancel'
+        ? { ...result.state, resolved: false }
+        : result.state;
+    stateRef.current = nextState;
+    setState(nextState);
+    if (result.effect.type === 'cancel') {
+      onClose();
+    } else if (result.effect.type === 'select') {
+      const entry = entries[result.effect.index];
+      if (entry) onSelect(entry.id);
+    }
+  };
+}
+
+function createNormalizedSelection(input: {
+  selectedIndex: number;
+  scrollOffset?: number;
+  itemCount: number;
+}): ISelectionFlowState {
+  return normalizeSelectionState(
+    {
+      selectedIndex: input.selectedIndex,
+      scrollOffset: input.scrollOffset ?? 0,
+      resolved: false,
+    },
+    { itemCount: input.itemCount, maxVisible: MAX_VISIBLE_WORKSPACE_ENTRIES },
+  );
+}

package/src/execution-workspace-view-model.ts

@@ -0,0 +1,139 @@
+import { workspaceStatusKind } from './status-glyph.js';
+
+import type { TUiStatusKind } from './status-glyph.js';
+import type {
+  IExecutionDetailRecord,
+  IExecutionWorkspaceEntry,
+  IExecutionWorkspaceSnapshot,
+  TExecutionWorkspaceStatus,
+} from '@robota-sdk/agent-interface-execution';
+
+// "Active" for the in-flight COUNT (countActiveBackgroundWorkspaceEntries) —
+// intentionally includes `waiting_permission` (a task awaiting permission is still
+// in flight). This is a different question from the status KIND used for
+// colour/glyph (where `waiting_permission` maps to its own 'waiting' kind via
+// `workspaceStatusKind`), so the two lists differ on purpose.
+const ACTIVE_STATUSES: readonly TExecutionWorkspaceStatus[] = [
+  'active',
+  'queued',
+  'running',
+  'waiting_permission',
+  'sleeping',
+];
+const DETAIL_RECORD_TEXT_LIMIT = 160;
+const PREVIEW_WHITESPACE = /\s+/g;
+const PREVIEW_SEPARATOR = ' ';
+
+export interface IExecutionWorkspaceEntryRow {
+  id: string;
+  radio: '●' | '○';
+  /** SCREEN-1992: the five-word state, rendered beside the radio and carried in the accessible text. */
+  state: string;
+  title: string;
+  subtitle?: string;
+  statusLabel: string;
+  preview?: string;
+  /** SCREEN-2002: the status KIND; the component resolves its colour from the live theme. */
+  statusKind: TUiStatusKind;
+  isSelected: boolean;
+  accessibleText: string;
+}
+
+export interface IExecutionWorkspaceEntryRowOptions {
+  selectedEntryId?: string;
+}
+
+export function getDefaultBackgroundWorkspaceEntries(
+  snapshot: IExecutionWorkspaceSnapshot | null,
+): IExecutionWorkspaceEntry[] {
+  return (snapshot?.entries ?? []).filter(
+    (entry) => entry.kind === 'background_task' && entry.visibility === 'default',
+  );
+}
+
+export function countActiveBackgroundWorkspaceEntries(
+  snapshot: IExecutionWorkspaceSnapshot | null,
+): number {
+  return getDefaultBackgroundWorkspaceEntries(snapshot).filter((entry) =>
+    ACTIVE_STATUSES.includes(entry.status),
+  ).length;
+}
+
+export function formatExecutionWorkspaceEntryRow(
+  entry: IExecutionWorkspaceEntry,
+  options: IExecutionWorkspaceEntryRowOptions = {},
+): IExecutionWorkspaceEntryRow {
+  const isSelected = entry.id === options.selectedEntryId;
+  const row = {
+    id: entry.id,
+    radio: isSelected ? '●' : '○',
+    state: entry.state,
+    title: formatEntryTitle(entry),
+    subtitle: formatEntrySubtitle(entry),
+    statusLabel: formatStatusLabel(entry.status),
+    preview: trimPreview(entry.preview ?? entry.currentAction),
+    statusKind: getEntryStatusKind(entry),
+    isSelected,
+  } satisfies Omit<IExecutionWorkspaceEntryRow, 'accessibleText'>;
+  return { ...row, accessibleText: formatAccessibleText(row) };
+}
+
+export function formatExecutionDetailRecord(record: IExecutionDetailRecord): string {
+  const text = record.text.trim().replace(PREVIEW_WHITESPACE, PREVIEW_SEPARATOR);
+  if (!text) return record.kind;
+  return text.length > DETAIL_RECORD_TEXT_LIMIT
+    ? `${text.slice(0, DETAIL_RECORD_TEXT_LIMIT)}...`
+    : text;
+}
+
+function formatEntryTitle(entry: IExecutionWorkspaceEntry): string {
+  if (entry.kind === 'main_thread') return entry.title;
+  if (entry.kind === 'background_group') return `${entry.title} group`;
+  if (entry.taskKind === 'agent') return `${entry.title} agent`;
+  if (entry.taskKind === 'process') return entry.title || 'Process';
+  if (entry.taskKind === 'scheduled') return entry.title || 'Scheduled';
+  return entry.title;
+}
+
+function formatEntrySubtitle(entry: IExecutionWorkspaceEntry): string | undefined {
+  if (entry.kind === 'main_thread') return entry.subtitle;
+  const parts = [
+    entry.taskKind,
+    entry.subtitle,
+    entry.attention === 'none' ? undefined : entry.attention,
+  ];
+  return (
+    parts
+      .filter((part): part is string => typeof part === 'string' && part.length > 0)
+      .join(' · ') || undefined
+  );
+}
+
+function formatStatusLabel(status: TExecutionWorkspaceStatus): string {
+  return status.replace(/_/g, ' ');
+}
+
+// SCREEN-2002: the view model names the status KIND, not a colour — a colour belongs to the theme
+// resolved at render time, and the kind is what keeps an entry's colour matching the glyph shown for
+// the same status everywhere (SCREEN-007). The component resolves it through `statusGlyphColor`.
+function getEntryStatusKind(entry: IExecutionWorkspaceEntry): TUiStatusKind {
+  return workspaceStatusKind(entry.status, entry.attention);
+}
+
+function trimPreview(value: string | undefined): string | undefined {
+  const preview = value?.trim().replace(PREVIEW_WHITESPACE, PREVIEW_SEPARATOR);
+  return preview || undefined;
+}
+
+function formatAccessibleText(row: Omit<IExecutionWorkspaceEntryRow, 'accessibleText'>): string {
+  const parts = [
+    `${row.radio} ${row.state}`,
+    row.title,
+    row.statusLabel,
+    row.subtitle,
+    row.preview,
+  ];
+  return parts
+    .filter((part): part is string => typeof part === 'string' && part.length > 0)
+    .join(' · ');
+}

package/src/external-prompt-notice.tsx

@@ -0,0 +1,38 @@
+/**
+ * FLOW-2006: the line that says a prompt did not come from the person at the keyboard.
+ *
+ * A deep link can fill the composer, so the provenance has to be visible for as long as the composer
+ * holds exactly what the link supplied — otherwise a prompt the user never typed reads exactly like
+ * one they did. The moment that text is edited, sent or cleared the label goes: what is there is then
+ * the user's own, and a label that outlived the text would be claiming otherwise. Above the long
+ * threshold it also carries the character count and says to read the whole thing, because a long
+ * prompt pushes its own instructions off screen.
+ */
+import React from 'react';
+
+import { Text } from './SafeText.js';
+
+/** Above this many characters the notice escalates from a label to a review instruction. */
+export const EXTERNAL_PROMPT_REVIEW_THRESHOLD = 1000;
+export const EXTERNAL_PROMPT_NOTICE = 'Prompt from an external link';
+
+export interface IExternalPromptNoticeProps {
+  /** The composer's current text, so the notice can size its warning to what is actually there. */
+  readonly value: string;
+}
+
+/** The notice text for a value, or `undefined` when there is nothing to say. */
+export function externalPromptNotice(value: string): string | undefined {
+  if (value.length === 0) return undefined;
+  return value.length > EXTERNAL_PROMPT_REVIEW_THRESHOLD
+    ? `${EXTERNAL_PROMPT_NOTICE} — ${value.length} characters; scroll and review the full text before sending`
+    : EXTERNAL_PROMPT_NOTICE;
+}
+
+export default function ExternalPromptNotice({
+  value,
+}: IExternalPromptNoticeProps): React.ReactElement | null {
+  const notice = externalPromptNotice(value);
+  if (notice === undefined) return null;
+  return <Text dimColor>{notice}</Text>;
+}

package/src/flows/__tests__/background-focus-flow.test.ts

@@ -0,0 +1,48 @@
+import { describe, expect, it } from 'vitest';
+
+import { resolveBackgroundFocusKey } from '../background-focus-flow.js';
+
+const KEY = { upArrow: false, downArrow: false, return: false, escape: false };
+
+describe('resolveBackgroundFocusKey (SCREEN-014)', () => {
+  it('↓ moves down, clamped at the last item', () => {
+    expect(resolveBackgroundFocusKey(0, 3, { ...KEY, downArrow: true })).toEqual({
+      type: 'move',
+      index: 1,
+    });
+    expect(resolveBackgroundFocusKey(2, 3, { ...KEY, downArrow: true })).toEqual({
+      type: 'move',
+      index: 2,
+    });
+  });
+
+  it('↑ moves up; ↑ past the first item returns focus to the input (null)', () => {
+    expect(resolveBackgroundFocusKey(2, 3, { ...KEY, upArrow: true })).toEqual({
+      type: 'move',
+      index: 1,
+    });
+    expect(resolveBackgroundFocusKey(0, 3, { ...KEY, upArrow: true })).toEqual({
+      type: 'move',
+      index: null,
+    });
+  });
+
+  it('Enter opens the highlighted task', () => {
+    expect(resolveBackgroundFocusKey(1, 3, { ...KEY, return: true })).toEqual({
+      type: 'open',
+      index: 1,
+    });
+  });
+
+  it('Esc exits to the input', () => {
+    expect(resolveBackgroundFocusKey(1, 3, { ...KEY, escape: true })).toEqual({ type: 'exit' });
+  });
+
+  it('an emptied list always exits', () => {
+    expect(resolveBackgroundFocusKey(0, 0, { ...KEY, downArrow: true })).toEqual({ type: 'exit' });
+  });
+
+  it('ignores unrelated keys', () => {
+    expect(resolveBackgroundFocusKey(1, 3, KEY)).toEqual({ type: 'none' });
+  });
+});

package/src/flows/__tests__/defer-submit.test.ts

@@ -0,0 +1,87 @@
+import { describe, expect, it, vi } from 'vitest';
+
+import {
+  cancelDeferredSubmit,
+  createDeferSubmitState,
+  scheduleDeferredSubmit,
+} from '../defer-submit.js';
+
+/**
+ * CLI-061 — the deferred-submit orchestration. The load-bearing property: at fire time the submit reads
+ * `readLatest()` (the LIVE value), so a trailing IME character applied AFTER the schedule is included. The
+ * pre-fix path submitted the value captured at Enter time — this test fails against that.
+ */
+describe('scheduleDeferredSubmit (CLI-061)', () => {
+  /** A synchronous "scheduler" that captures the callback so the test fires it deterministically. */
+  function manualScheduler() {
+    let fired: (() => void) | undefined;
+    return {
+      schedule: (fn: () => void) => {
+        fired = fn;
+        return 1 as unknown as ReturnType<typeof setTimeout>;
+      },
+      fire: () => fired?.(),
+    };
+  }
+
+  it('submits the LATEST value at fire time, not the value at schedule time (the trailing char)', () => {
+    const state = createDeferSubmitState();
+    const submit = vi.fn();
+    const sched = manualScheduler();
+
+    // Value at Enter/schedule time is the pre-trailing-char string...
+    let live = '안녕하세';
+    scheduleDeferredSubmit(state, () => live, submit, 50, sched.schedule);
+    expect(submit).not.toHaveBeenCalled(); // deferred, not immediate
+
+    // ...the trailing syllable lands during the window...
+    live = '안녕하세요';
+    sched.fire();
+
+    expect(submit).toHaveBeenCalledTimes(1);
+    expect(submit).toHaveBeenCalledWith('안녕하세요'); // FULL value — fails on the pre-fix immediate submit
+  });
+
+  it('ignores a second submit while one is in flight (no double-submit)', () => {
+    const state = createDeferSubmitState();
+    const submit = vi.fn();
+    const sched = manualScheduler();
+
+    scheduleDeferredSubmit(state, () => 'a', submit, 50, sched.schedule);
+    scheduleDeferredSubmit(state, () => 'a', submit, 50, sched.schedule); // second Enter within the window
+    sched.fire();
+
+    expect(submit).toHaveBeenCalledTimes(1);
+  });
+
+  it('a fresh submit is allowed after the previous one fires', () => {
+    const state = createDeferSubmitState();
+    const submit = vi.fn();
+    const sched = manualScheduler();
+
+    scheduleDeferredSubmit(state, () => 'a', submit, 50, sched.schedule);
+    sched.fire();
+    scheduleDeferredSubmit(state, () => 'b', submit, 50, sched.schedule);
+    sched.fire();
+
+    expect(submit.mock.calls).toEqual([['a'], ['b']]);
+  });
+
+  it('cancel clears a pending timer and releases the guard (no submit after unmount)', () => {
+    const state = createDeferSubmitState();
+    const submit = vi.fn();
+    const clear = vi.fn();
+    const sched = manualScheduler();
+
+    scheduleDeferredSubmit(state, () => 'a', submit, 50, sched.schedule);
+    cancelDeferredSubmit(state, clear);
+
+    expect(clear).toHaveBeenCalledTimes(1);
+    expect(state.timer).toBeNull();
+    expect(state.isSubmitting).toBe(false);
+    // A new submit is possible again after cancel.
+    scheduleDeferredSubmit(state, () => 'b', submit, 50, sched.schedule);
+    sched.fire();
+    expect(submit).toHaveBeenCalledWith('b');
+  });
+});

package/src/flows/__tests__/real-cursor-flow.test.ts

@@ -0,0 +1,124 @@
+/**
+ * CLI-062 — unit tables for the real-cursor pure flow.
+ *
+ * `computeCursorCell` maps (absolute input origin, value, cursor index, wrap width) to the
+ * hardware-cursor cell, reusing the wrap-aware `displayOffset` math the input's vertical
+ * navigation already trusts. `shouldPositionRealCursor` is the crash-avoidance guard: every
+ * `false` row below is a SIGSEGV-invariant case (the historical Terminal.app crash geometry —
+ * see .design/investigations/2026-07-25-cli-062-ime-cursor-design.md, invariants I1/I2/I5).
+ */
+
+import { describe, expect, it } from 'vitest';
+
+import { computeCursorCell, shouldPositionRealCursor } from '../real-cursor-flow.js';
+
+describe('computeCursorCell', () => {
+  const origin = { absX: 3, absY: 2 };
+
+  it('ASCII value, cursor at end, no wrap width', () => {
+    expect(computeCursorCell({ ...origin, value: 'hello', cursor: 5 })).toEqual({ x: 8, y: 2 });
+  });
+
+  it('ASCII value, cursor at start', () => {
+    expect(computeCursorCell({ ...origin, value: 'hello', cursor: 0 })).toEqual({ x: 3, y: 2 });
+  });
+
+  it('CJK wide chars count 2 columns each (안녕 → 4 columns)', () => {
+    expect(computeCursorCell({ ...origin, value: '안녕', cursor: 2, availableWidth: 20 })).toEqual({
+      x: 7,
+      y: 2,
+    });
+  });
+
+  it('mid-string cursor inside a CJK value', () => {
+    expect(
+      computeCursorCell({ ...origin, value: '안녕하세요', cursor: 2, availableWidth: 20 }),
+    ).toEqual({ x: 7, y: 2 });
+  });
+
+  it('no wrap width: CJK offset is the plain display-width sum', () => {
+    expect(computeCursorCell({ ...origin, value: '안녕하', cursor: 3 })).toEqual({ x: 9, y: 2 });
+  });
+
+  it('wraps to the next row when the offset passes the width', () => {
+    expect(
+      computeCursorCell({ ...origin, value: 'a'.repeat(12), cursor: 12, availableWidth: 10 }),
+    ).toEqual({ x: 5, y: 3 });
+  });
+
+  it('exact-width boundary lands on column 0 of the next row', () => {
+    expect(
+      computeCursorCell({ ...origin, value: 'a'.repeat(12), cursor: 10, availableWidth: 10 }),
+    ).toEqual({ x: 3, y: 3 });
+  });
+
+  it('wide char straddling the wrap boundary is pushed to the next row (display gap preserved)', () => {
+    // 9 ASCII cols + a wide char that cannot fit in the last column: displayOffset skips the
+    // dead column (9 → 10) then adds the wide char (→ 12) — cursor lands at row+1, col 2.
+    expect(
+      computeCursorCell({ ...origin, value: 'aaaaaaaaa안', cursor: 10, availableWidth: 10 }),
+    ).toEqual({ x: 5, y: 3 });
+  });
+
+  it('empty value (placeholder case) → the origin cell', () => {
+    expect(computeCursorCell({ ...origin, value: '', cursor: 0, availableWidth: 20 })).toEqual({
+      x: 3,
+      y: 2,
+    });
+  });
+
+  it('cursor index beyond the value length clamps to the end', () => {
+    expect(computeCursorCell({ ...origin, value: 'ab', cursor: 99 })).toEqual({ x: 5, y: 2 });
+  });
+
+  it('non-positive availableWidth behaves as unwrapped', () => {
+    expect(computeCursorCell({ ...origin, value: 'hello', cursor: 5, availableWidth: 0 })).toEqual({
+      x: 8,
+      y: 2,
+    });
+  });
+});
+
+describe('shouldPositionRealCursor (every false row is a SIGSEGV-invariant case)', () => {
+  const ok = { hasMeasured: true, y: 3, frameHeight: 8, viewportRows: 24, capability: true };
+
+  it('positions when measured, in-bounds, frame smaller than viewport, capability on', () => {
+    expect(shouldPositionRealCursor(ok)).toBe(true);
+  });
+
+  it('measured y === 0 is valid (only a GUESSED y:0 is the bug class, not a measured one)', () => {
+    expect(shouldPositionRealCursor({ ...ok, y: 0 })).toBe(true);
+  });
+
+  it('I5/gate: capability off → never position', () => {
+    expect(shouldPositionRealCursor({ ...ok, capability: false })).toBe(false);
+  });
+
+  it('I1: no measurement yet → never position (the historical hardcoded y:0 class)', () => {
+    expect(shouldPositionRealCursor({ ...ok, hasMeasured: false })).toBe(false);
+  });
+
+  it('I2: frame fills the viewport (ink fullscreen path, off-by-one) → never position', () => {
+    expect(shouldPositionRealCursor({ ...ok, frameHeight: 24 })).toBe(false);
+  });
+
+  it('I2: frame overflows the viewport (cursorUp clamps at screen top — crash geometry) → never', () => {
+    expect(shouldPositionRealCursor({ ...ok, frameHeight: 30 })).toBe(false);
+  });
+
+  it('I2: y below the frame → never position', () => {
+    expect(shouldPositionRealCursor({ ...ok, y: 8 })).toBe(false);
+  });
+
+  it('I2: negative y → never position', () => {
+    expect(shouldPositionRealCursor({ ...ok, y: -1 })).toBe(false);
+  });
+
+  it('degenerate viewport (0 rows) → never position', () => {
+    expect(shouldPositionRealCursor({ ...ok, viewportRows: 0 })).toBe(false);
+  });
+
+  it('degenerate frame (0 height) → never position', () => {
+    expect(shouldPositionRealCursor({ ...ok, frameHeight: 0 })).toBe(false);
+  });
+});

package/src/flows/background-focus-flow.ts

@@ -0,0 +1,44 @@
+/**
+ * SCREEN-014: pure reducer for keyboard navigation of the inline background-work list.
+ *
+ * Kept out of the App component so the navigation rules are exhaustively unit-testable without
+ * rendering the whole TUI. The App's `useInput` translates the resulting action into focus/selection
+ * state changes.
+ */
+
+/** A key event relevant to background-list navigation (subset of Ink's key object). */
+export interface IBackgroundFocusKey {
+  upArrow: boolean;
+  downArrow: boolean;
+  return: boolean;
+  escape: boolean;
+}
+
+export type TBackgroundFocusAction =
+  | { type: 'move'; index: number | null } // null = focus returns to the prompt input
+  | { type: 'open'; index: number } // open the highlighted task's inline detail
+  | { type: 'exit' } // leave the list, focus the prompt input
+  | { type: 'none' }; // unhandled key — ignore
+
+/**
+ * Resolve a keypress while the background list holds focus.
+ *
+ * - ↑ moves up; ↑ past the first item returns focus to the input (`move` to `null`).
+ * - ↓ moves down, clamped at the last item.
+ * - Enter opens the highlighted task.
+ * - Esc (or an emptied list) exits to the input.
+ */
+export function resolveBackgroundFocusKey(
+  current: number,
+  entryCount: number,
+  key: IBackgroundFocusKey,
+): TBackgroundFocusAction {
+  if (entryCount <= 0) return { type: 'exit' };
+  if (key.upArrow) return { type: 'move', index: current > 0 ? current - 1 : null };
+  if (key.downArrow) {
+    return { type: 'move', index: current < entryCount - 1 ? current + 1 : current };
+  }
+  if (key.return) return { type: 'open', index: Math.min(Math.max(current, 0), entryCount - 1) };
+  if (key.escape) return { type: 'exit' };
+  return { type: 'none' };
+}

package/src/flows/cjk-cursor-motion.ts

@@ -0,0 +1,75 @@
+/**
+ * CJK-aware cursor geometry and motion.
+ *
+ * Display columns and character indices are different things when a character is two columns wide;
+ * these functions are the translation between them, and the two cursor moves built on it.
+ *
+ * Extracted from `cjk-text-input-flow.ts` (CLI-2004) by responsibility — that module routes
+ * keystrokes, this one measures and moves.
+ */
+
+import stringWidth from 'string-width';
+
+import type { ICjkTextInputFlowState, TCjkTextInputEffect } from './cjk-text-input-types.js';
+
+interface ICjkMotionResult {
+  state: ICjkTextInputFlowState;
+  effect: TCjkTextInputEffect;
+}
+
+export function displayOffset(chars: string[], charIndex: number, width: number): number {
+  let offset = 0;
+  for (let i = 0; i < charIndex && i < chars.length; i++) {
+    const w = stringWidth(chars[i]!);
+    const col = offset % width;
+    if (col + w > width) offset += width - col;
+    offset += w;
+  }
+  return offset;
+}
+
+export function charIndexAtDisplayOffset(chars: string[], target: number, width: number): number {
+  let offset = 0;
+  for (let i = 0; i < chars.length; i++) {
+    if (offset >= target) return i;
+    const w = stringWidth(chars[i]!);
+    const col = offset % width;
+    if (col + w > width) offset += width - col;
+    offset += w;
+  }
+  return chars.length;
+}
+
+export function moveCursorVertically(
+  state: ICjkTextInputFlowState,
+  direction: 'up' | 'down',
+  availableWidth: number | undefined,
+): ICjkMotionResult {
+  if (!availableWidth || availableWidth <= 0) {
+    return { state, effect: { type: 'none' } };
+  }
+  const chars = [...state.value];
+  const offset = displayOffset(chars, state.cursor, availableWidth);
+  const target = direction === 'up' ? offset - availableWidth : offset + availableWidth;
+  if (target < 0) {
+    return { state, effect: { type: 'none' } };
+  }
+  const cursor = charIndexAtDisplayOffset(chars, target, availableWidth);
+  if (cursor === state.cursor) {
+    return { state, effect: { type: 'none' } };
+  }
+  return { state: { ...state, cursor }, effect: { type: 'render' } };
+}
+
+export function moveCursorHorizontally(
+  state: ICjkTextInputFlowState,
+  direction: 'left' | 'right',
+): ICjkMotionResult {
+  if (direction === 'left' && state.cursor > 0) {
+    return { state: { ...state, cursor: state.cursor - 1 }, effect: { type: 'render' } };
+  }
+  if (direction === 'right' && state.cursor < state.value.length) {
+    return { state: { ...state, cursor: state.cursor + 1 }, effect: { type: 'render' } };
+  }
+  return { state, effect: { type: 'none' } };
+}