dsh-code 0.9.0 → 1.0.0

package/src/render/animations.ts

@@ -1,9 +1,9 @@
 /**
  * Terminal animation frame tables derived from the web design language:
  * the StateDot "ongoing" pixel chase (3×3 ring, 125ms flat-hold brightness
- * steps, 1s cycle) becomes the single-cell stepped pulse below and the
- * full-ring clockwise braille chase in {@link BUSY_CHASE_FRAMES}, and the
- * streaming caret blink is the Claude-Code convention.
+ * steps, 1s cycle) becomes the full-ring clockwise braille chase in
+ * {@link BUSY_CHASE_FRAMES}, and the streaming caret blink is the
+ * Claude-Code convention.
  *
  * The DeepSeek model-switch easter egg ports Codex's effort-ignition "Wave"
  * style (`codex-rs/tui/src/bottom_pane/effort_ignition_styles.rs`): switching
@@ -19,14 +19,6 @@
 
 import type { RgbTriple } from '../theme.ts'
 
-/** Single-cell stepped pulse: flat holds mirroring the web's 125ms keyframes. */
-export const PULSE_FRAMES = ['█', '█', '▆', '▃', '▁', '▃', '▆', '█'] as const
-
-/** Pulse frame for a monotonic tick. */
-export function pulseFrame(tick: number): string {
-  return PULSE_FRAMES[tick % PULSE_FRAMES.length] ?? PULSE_FRAMES[0]
-}
-
 /**
  * The web StateDot "ongoing" chase in terminal form: three cells of the 3×3
  * ring trail clockwise around the eight outer positions, one braille glyph
@@ -59,11 +51,15 @@ export function caretVisible(tick: number): boolean {
 export const DEEPSEEK_WAVE_TICK_MS = 33
 
 /**
- * The two DeepSeek wave tiers. The concept maps Codex's reasoning tiers to
+ * The DeepSeek wave tiers. The concept maps Codex's reasoning tiers to
  * model ids: `flash` runs the Max parameters, `deepseek` (pro models) runs
  * the Ultra parameters (dual band + tail sparkles on the Wave style).
+ * `unknown` is the "Into the Unknown" variant: it reuses the deepseek tier's
+ * exact parameters (dual band, durations, sparkles) for NON-DeepSeek models
+ * running a reasoning effort above high — the wordmark renders differently
+ * but the motion is identical.
  */
-export type DeepseekWaveTier = 'flash' | 'deepseek'
+export type DeepseekWaveTier = 'flash' | 'deepseek' | 'unknown'
 
 /**
  * The three ignition styles — Codex `IgnitionStyle`: a traveling crest
@@ -72,18 +68,18 @@ export type DeepseekWaveTier = 'flash' | 'deepseek'
  */
 export type DeepseekWaveStyle = 'wave' | 'aurora' | 'pulse'
 
-/** All styles in canonical order, for random selection and tests. */
-export const DEEPSEEK_WAVE_STYLES: readonly DeepseekWaveStyle[] = ['wave', 'aurora', 'pulse']
+/** All styles in canonical order, for random selection. */
+const DEEPSEEK_WAVE_STYLES: readonly DeepseekWaveStyle[] = ['wave', 'aurora', 'pulse']
 
 /** Wave half-width in columns — Codex WAVE_HALF_WIDTH (9). */
 export const WAVE_HALF_WIDTH = 9
 
 /** Pulse ring half-width in columns — Codex PULSE_HALF_WIDTH (4.5). */
-export const PULSE_HALF_WIDTH = 4.5
+const PULSE_HALF_WIDTH = 4.5
 
 /** Sparkle start and frame cadence — Codex SPARK_START / SPARK_FRAME. */
-export const SPARK_START_MS = 900
-export const SPARK_FRAME_MS = 100
+const SPARK_START_MS = 900
+const SPARK_FRAME_MS = 100
 
 /** Sparkle glyphs in frame order — Codex SPARK_GLYPHS (`· ✦ ✧`). */
 export const SPARK_GLYPHS = ['·', '✦', '✧'] as const
@@ -100,30 +96,36 @@ export const DEEPSEEK_WAVE_BANDS: Readonly<Record<DeepseekWaveStyle, Readonly<Re
     flash: [[0.10, 0.75, 1.0]],
     // Wave-Ultra: two offset bands for a richer crest.
     deepseek: [[0.10, 0.70, 1.0], [0.35, 0.55, 1.0]],
+    // Into the Unknown reuses the Ultra parameters verbatim.
+    unknown: [[0.10, 0.70, 1.0], [0.35, 0.55, 1.0]],
   },
   aurora: {
     // Aurora-Max: two drifting bands (hues 0 and 1).
     flash: [[0.35, 0.15, 0.0], [-0.50, 0.60, 1.0]],
     // Aurora-Ultra: a third band adds hue 2.
     deepseek: [[0.35, 0.15, 0.0], [-0.50, 0.60, 1.0], [0.75, 0.35, 2.0]],
+    unknown: [[0.35, 0.15, 0.0], [-0.50, 0.60, 1.0], [0.75, 0.35, 2.0]],
   },
   pulse: {
     // Pulse-Max: one expanding ring.
     flash: [[0.10, 0.60, 1.0]],
     // Pulse-Ultra: two rings (inner weaker, outer stronger).
     deepseek: [[0.10, 0.55, 0.8], [0.45, 0.55, 1.1]],
+    unknown: [[0.10, 0.55, 0.8], [0.45, 0.55, 1.1]],
   },
 }
 
 /** Extra display time applied to every Codex ignition style. */
-export const DEEPSEEK_WAVE_DURATION_EXTENSION_MS = 200
+const DEEPSEEK_WAVE_DURATION_EXTENSION_MS = 200
 
 /** Original Codex duration used as the animation's sampling timeline. */
 function deepseekWaveBaseDuration(tier: DeepseekWaveTier, style: DeepseekWaveStyle): number {
+  // The unknown tier reuses the deepseek (pro) durations exactly.
+  const pro = tier === 'deepseek' || tier === 'unknown'
   switch (style) {
-    case 'aurora': return tier === 'flash' ? 1300 : 1600
-    case 'pulse': return tier === 'flash' ? 900 : 1250
-    case 'wave': return tier === 'flash' ? 1000 : 1300
+    case 'aurora': return pro ? 1600 : 1300
+    case 'pulse': return pro ? 1250 : 900
+    case 'wave': return pro ? 1300 : 1000
   }
 }
 
@@ -155,15 +157,6 @@ export function deepseekWaveStyleRandom(previous: DeepseekWaveStyle | undefined)
   return candidates[Math.floor(Math.random() * candidates.length)] ?? 'wave'
 }
 
-/**
- * Blank-cell background the wave tint blends toward — fixed approximations
- * of the terminal's default background, mirroring Codex's
- * `user_message_bg_rgb` (which derives a near-black / near-white bubble tint
- * from the terminal background). The Ink layer picks the active theme's one.
- */
-export const WAVE_BASE_DARK: RgbTriple = [16, 18, 24]
-export const WAVE_BASE_LIGHT: RgbTriple = [242, 244, 248]
-
 /**
  * Tier for a `provider/model` label: a model id containing `flash` runs the
  * single-band flash tier; everything else (pro/reasoner/chat) runs the
@@ -270,14 +263,23 @@ function blendRgb(fg: RgbTriple, bg: RgbTriple, alpha: number): RgbTriple {
 }
 
 /**
- * The background color for one composer-row column at a tick — Codex
+ * Per-row phase share of the duration: the crest reaches the top row first
+ * and the bottom row last, sweeping down the band. 0.12 keeps the bottom
+ * row's lag inside the 200ms duration extension.
+ */
+const DEEPSEEK_WAVE_ROW_PHASE = 0.12
+
+/**
+ * The background color for one composer-band column at a tick — Codex
  * `paint_bands` + `Canvas::tint` for all three styles. Bands overlap with a
  * max for Wave/Pulse and a SUM for Aurora (Codex differs by style), the
  * weighted hues mix per column (Wave/Pulse always end on hue 0), the tint
  * blends the mixed hue toward the blank-cell base at the style's alpha cap,
  * and Aurora applies its own fade envelope. Returns `null` when the column
  * should stay transparent, so the row returns to no `backgroundColor` on
- * both ends.
+ * both ends. With `rows > 1` each row samples the same timeline shifted by a
+ * per-row phase offset, so the crest cascades down the band instead of
+ * painting every row identically.
  * @param tick - wave frame (0, 1, … at DEEPSEEK_WAVE_TICK_MS).
  * @param column - column index in the content row (0..width-1).
  * @param width - content-row width in columns.
@@ -285,6 +287,8 @@ function blendRgb(fg: RgbTriple, bg: RgbTriple, alpha: number): RgbTriple {
  * @param style - the ignition style.
  * @param hues - the tier's three hues.
  * @param base - the blank-cell base color the tint blends toward.
+ * @param row - row index in the band (0..rows-1; default 0 = old single-row).
+ * @param rows - band height in rows (default 1).
  * @returns the blended RGB background, or null for transparent.
  */
 export function deepseekWaveColumnBg(
@@ -295,9 +299,12 @@ export function deepseekWaveColumnBg(
   style: DeepseekWaveStyle,
   hues: readonly [RgbTriple, RgbTriple, RgbTriple],
   base: RgbTriple,
+  row = 0,
+  rows = 1,
 ): RgbTriple | null {
   const total = deepseekWaveBaseDuration(tier, style) / 1000
   const elapsed = deepseekWaveSampleElapsedMs(tick, tier, style) / 1000
+    - (row - (rows - 1) / 2) * total * DEEPSEEK_WAVE_ROW_PHASE
   const fade = style === 'aurora' ? envelope(elapsed, total, 0.25, 0.40) : 1
   const weights = [0, 0, 0]
   for (const band of DEEPSEEK_WAVE_BANDS[style][tier]) {
@@ -338,33 +345,6 @@ export function deepseekWaveSpark(tick: number): string | null {
   return SPARK_GLYPHS[frame] ?? null
 }
 
-/**
- * The composer BORDER color at a tick: the frame breathes with the wave —
- * the palette's static dim blends toward the tier accent as the crest is
- * alive and back, so the frame glows up while the wave sweeps and settles to
- * dim on both ends (first==last frame==dim, no hard jump).
- * @param tick - wave frame at DEEPSEEK_WAVE_TICK_MS.
- * @param tier - the wave tier.
- * @param hues - the tier's three hues; the border blends toward hues[0].
- * @param dim - the palette's static dim RGB (the resting border color).
- * @returns the blended border RGB.
- */
-export function deepseekWaveBorderColor(
-  tick: number,
-  tier: DeepseekWaveTier,
-  style: DeepseekWaveStyle,
-  hues: readonly [RgbTriple, RgbTriple, RgbTriple],
-  dim: RgbTriple,
-): RgbTriple {
-  const total = deepseekWaveBaseDuration(tier, style) / 1000
-  const elapsed = deepseekWaveSampleElapsedMs(tick, tier, style) / 1000
-  // The border stays visibly on the tier accent for the whole sweep (a
-  // floor keeps it glowing, not just cresting mid-wave): it ramps in as the
-  // first band launches and relaxes after the last crest passes.
-  const glow = envelope(elapsed, total, total * 0.25, total * 0.4)
-  return blendRgb(hues[0], dim, 0.25 + glow * 0.6)
-}
-
 /**
  * Whether the `deepseek` wordmark rides the wave at this tick: it fades in
  * shortly after the first crest launches and out before the wave settles,
@@ -404,3 +384,37 @@ export function isOfficialDeepSeekLabel(label: string): boolean {
   const model = slash < 0 ? '' : label.slice(slash + 1)
   return provider.toLowerCase().includes('deepseek') || model.toLowerCase().includes('deepseek')
 }
+
+/**
+ * Known reasoning-effort ranks in ascending order. Effort ids are opaque
+ * adapter-owned strings, so the rank table covers the conventional names
+ * (off → low → medium → high → xhigh → max/ultra); an unrecognized id
+ * ranks as unknown (0), which never triggers the high-effort wave.
+ */
+const EFFORT_RANK: Readonly<Record<string, number>> = {
+  off: 0,
+  none: 0,
+  low: 1,
+  medium: 2,
+  med: 2,
+  high: 3,
+  xhigh: 4,
+  'x-high': 4,
+  'very-high': 4,
+  max: 5,
+  maximum: 5,
+  ultra: 5,
+}
+
+/**
+ * True when an effective reasoning effort is STRICTLY above `high` — the
+ * trigger gate for the "Into the Unknown" wave on non-DeepSeek routes.
+ * Absent efforts and unrecognized ids never qualify.
+ * @param effort - the effective reasoning-effort id ('' or undefined when none).
+ * @returns whether the effort ranks above high.
+ */
+export function effortAboveHigh(effort: string | undefined): boolean {
+  if (effort === undefined || effort === '') return false
+  const rank = EFFORT_RANK[effort.trim().toLowerCase()]
+  return rank !== undefined && rank > 3
+}

package/src/render/editor.ts

@@ -0,0 +1,398 @@
+/**
+ * Pure composer editor model with Codex textarea semantics: a grapheme
+ * cursor over a column-safe multiline layout, word/piece motion, single-entry
+ * kill + yank, and the shell-recall boundary gate that keeps Up/Down usable
+ * inside a multiline draft.
+ *
+ * The model is intentionally string-offset based (UTF-16 indices clamped to
+ * grapheme boundaries) so the React state stays two primitives
+ * (value, cursor) and every operation here stays pure and testable.
+ *
+ * Word motion deviates from Codex's UAX#29 segmentation in one deliberate
+ * way: a run of same-class characters is ONE piece, so a CJK run moves as a
+ * single word (two hanzi are one Alt+B step, not two).
+ *
+ * @module @deepseek-ai/dsh-code/render/editor
+ */
+
+import { visibleColumns } from './markdown.ts'
+
+/** One grapheme cluster with its source span and display width in cells. */
+export interface GraphemeSpan {
+  text: string
+  start: number
+  end: number
+  width: number
+}
+
+const segmenter: Intl.Segmenter | undefined = typeof Intl !== 'undefined' && 'Segmenter' in Intl
+  ? new Intl.Segmenter('en', { granularity: 'grapheme' })
+  : undefined
+
+/**
+ * Split text into grapheme clusters. Falls back to code points when
+ * Intl.Segmenter is unavailable; the fallback still keeps surrogate pairs
+ * (emoji) atomic so the cursor can never split one.
+ */
+export function splitGraphemes(text: string): readonly GraphemeSpan[] {
+  if (text === '') return []
+  const spans: GraphemeSpan[] = []
+  if (segmenter !== undefined) {
+    for (const piece of segmenter.segment(text)) {
+      spans.push({
+        text: piece.segment,
+        start: piece.index,
+        end: piece.index + piece.segment.length,
+        width: visibleColumns(piece.segment),
+      })
+    }
+    return spans
+  }
+  let start = 0
+  for (const char of text) {
+    spans.push({ text: char, start, end: start + char.length, width: visibleColumns(char) })
+    start += char.length
+  }
+  return spans
+}
+
+/** Round one UTF-16 offset down to the grapheme boundary at or before it. */
+function floorBoundary(spans: readonly GraphemeSpan[], offset: number): number {
+  for (let index = spans.length - 1; index >= 0; index -= 1) {
+    const span = spans[index]!
+    if (span.end <= offset) return span.end
+    if (span.start < offset) return span.start
+  }
+  return 0
+}
+
+/** Clamp a cursor offset to the nearest grapheme boundary (surrogates, ZWJ, marks stay whole). */
+export function clampCursor(value: string, offset: number): number {
+  if (value === '') return 0
+  const target = Math.max(0, Math.min(value.length, Math.floor(offset)))
+  if (target === 0 || target === value.length) return target
+  const spans = splitGraphemes(value)
+  const down = floorBoundary(spans, target)
+  if (down === target) return target
+  const up = spans.find(span => span.start >= target)?.start ?? value.length
+  return up - target < target - down ? up : down
+}
+
+/**
+ * Delete the final grapheme cluster (append-only drafts without a cursor).
+ * Surrogate pairs and multi-codepoint emoji stay whole instead of leaving a
+ * lone trailing code unit behind.
+ */
+export function deleteLastGrapheme(text: string): string {
+  if (text === '') return ''
+  const spans = splitGraphemes(text)
+  return text.slice(0, spans[spans.length - 1]!.start)
+}
+
+/**
+ * Step the cursor by whole graphemes (negative steps left). The cursor is
+ * assumed to sit on a boundary; any drift is clamped first.
+ */
+export function moveCursorBy(value: string, offset: number, delta: number): number {
+  if (delta === 0 || value === '') return clampCursor(value, offset)
+  const spans = splitGraphemes(value)
+  const boundaries: number[] = [0]
+  for (const span of spans) boundaries.push(span.end)
+  const current = boundaries.indexOf(clampCursor(value, offset))
+  if (current === -1) return clampCursor(value, offset)
+  const next = Math.max(0, Math.min(boundaries.length - 1, current + delta))
+  return boundaries[next]!
+}
+
+/**
+ * Normalize text entering the draft: CRLF/CR become LF, tabs become two
+ * spaces (terminal tab stops are contextual and cannot join a deterministic
+ * row budget), and every other C0 control byte plus DEL is REMOVED — the
+ * draft is data, so a stray ESC (Windows Terminal file drops) disappears
+ * instead of rendering as literal backslash-x-1-b text. Newlines survive.
+ */
+export function sanitizeDraftText(text: string): string {
+  return text
+    .replaceAll('\r\n', '\n')
+    .replaceAll('\r', '\n')
+    // The draft is DATA, not display: strip C0 control bytes (the stray ESC
+    // that rides Windows Terminal file drops) and DEL instead of escaping
+    // them into visible "\x1b" text. Newlines survive; tabs widen.
+    .replace(/[\u0000-\u0008\u000b\u000c\u000e-\u001f\u007f]/gu, '')
+    .replaceAll('\t', '  ')
+}
+
+/** One physical editor row: wrapped text plus its boundary map. */
+export interface EditorRowModel {
+  /** Display text of the row (never contains `\n`; sanitized upstream). */
+  readonly text: string
+  /** Source offset of the first grapheme on the row. */
+  readonly start: number
+  /** Source offset just past the last grapheme on the row (before its newline). */
+  readonly end: number
+  /** Boundary offsets on the row, start to end inclusive. */
+  readonly offsets: readonly number[]
+  /** Display column of each boundary; `columns[i]` pairs with `offsets[i]`. */
+  readonly columns: readonly number[]
+  /** Code-unit cut in `text` at each boundary; `cuts[i]` pairs with `offsets[i]`. */
+  readonly cuts: readonly number[]
+}
+
+/** The wrapped physical-row model of one draft. */
+export interface EditorModel {
+  readonly rows: readonly EditorRowModel[]
+  readonly length: number
+}
+
+/**
+ * Hard-wrap the draft into column-safe physical rows. Wide graphemes never
+ * split across rows (a grapheme that does not fit flushes the row first) and
+ * explicit newlines end their row without occupying a cell.
+ */
+export function editorModel(value: string, columns: number): EditorModel {
+  const width = Math.max(1, Math.floor(columns))
+  const spans = splitGraphemes(value)
+  const rows: EditorRowModel[] = []
+  let text = ''
+  let start = 0
+  let used = 0
+  const offsets: number[] = [0]
+  const rowColumns: number[] = [0]
+  const rowCuts: number[] = [0]
+  const flush = (end: number): void => {
+    rows.push({ text, start, end, offsets: [...offsets], columns: [...rowColumns], cuts: [...rowCuts] })
+    text = ''
+    used = 0
+    offsets.length = 0
+    rowColumns.length = 0
+    rowCuts.length = 0
+  }
+  for (const span of spans) {
+    if (span.text === '\n') {
+      flush(span.start)
+      start = span.end
+      offsets.push(span.end)
+      rowColumns.push(0)
+      rowCuts.push(0)
+      continue
+    }
+    if (used > 0 && used + span.width > width) {
+      flush(span.start)
+      start = span.start
+      offsets.push(span.start)
+      rowColumns.push(0)
+      rowCuts.push(0)
+    }
+    text += span.text
+    used += span.width
+    offsets.push(span.end)
+    rowColumns.push(used)
+    rowCuts.push(text.length)
+  }
+  if (text !== '' || rows.length === 0) flush(value.length)
+  else if (offsets.length > 0) {
+    // Trailing newline leaves one pending empty boundary row.
+    rows.push({ text: '', start, end: value.length, offsets: [...offsets], columns: [...rowColumns], cuts: [...rowCuts] })
+  }
+  return { rows, length: value.length }
+}
+
+/** Where a cursor offset renders: the physical row and its display column. */
+export interface CaretSite {
+  row: number
+  column: number
+}
+
+/** Map a cursor offset to its caret site on the wrapped rows. */
+export function caretSite(model: EditorModel, offset: number): CaretSite {
+  const target = Math.max(0, Math.min(model.length, offset))
+  for (let index = model.rows.length - 1; index >= 0; index -= 1) {
+    const row = model.rows[index]!
+    const at = row.offsets.indexOf(target)
+    if (at >= 0) return { row: index, column: row.columns[at]! }
+  }
+  const last = model.rows[model.rows.length - 1]
+  return { row: model.rows.length - 1, column: last === undefined ? 0 : last.columns[last.columns.length - 1]! }
+}
+
+/**
+ * Move the caret across physical rows keeping a preferred display column
+ * (Codex `preferred_col`): horizontal moves reset the preference, vertical
+ * moves reuse it, clamped to each row's width.
+ */
+export function moveCursorVertically(model: EditorModel, offset: number, preferredColumn: number, delta: number): number {
+  const site = caretSite(model, offset)
+  const target = site.row + delta
+  if (target < 0 || target >= model.rows.length || delta === 0) return offset
+  const row = model.rows[target]!
+  const wanted = Math.max(0, Math.min(preferredColumn, row.columns[row.columns.length - 1]!))
+  let best = 0
+  for (let index = 1; index < row.columns.length; index += 1) {
+    if (row.columns[index]! <= wanted) best = index
+    else break
+  }
+  return row.offsets[best]!
+}
+
+/** The start/end offsets of the logical line containing the cursor. */
+export function lineBounds(value: string, offset: number): { start: number; end: number } {
+  const target = Math.max(0, Math.min(value.length, offset))
+  const start = value.lastIndexOf('\n', Math.max(0, target - 1)) + 1
+  const end = value.indexOf('\n', target)
+  return { start, end: end === -1 ? value.length : end }
+}
+
+/** Codex WORD_SEPARATORS: punctuation runs are their own word pieces. */
+const WORD_SEPARATORS = new Set('`~!@#$%^&*()-=+[{]}\\|;:\'",.<>/?')
+
+type PieceClass = 'space' | 'punct' | 'word'
+
+function classifyGrapheme(text: string): PieceClass {
+  if (/^\s$/u.test(text)) return 'space'
+  return WORD_SEPARATORS.has(text) ? 'punct' : 'word'
+}
+
+/** Maximal same-class runs of graphemes as [start, end) spans. */
+function pieceRuns(value: string): readonly { start: number; end: number; class: PieceClass }[] {
+  const runs: { start: number; end: number; class: PieceClass }[] = []
+  let current: { start: number; end: number; class: PieceClass } | undefined
+  for (const span of splitGraphemes(value)) {
+    const klass = span.text === '\n' ? 'space' : classifyGrapheme(span.text)
+    if (current !== undefined && current.class === klass) {
+      current.end = span.end
+      continue
+    }
+    current = { start: span.start, end: span.end, class: klass }
+    runs.push(current)
+  }
+  return runs
+}
+
+/**
+ * Codex `beginning_of_previous_word`: skip whitespace left, then land on the
+ * START of the trailing non-space piece (extending over separator pieces).
+ */
+export function moveWordLeft(value: string, offset: number): number {
+  const cursor = Math.max(0, Math.min(value.length, offset))
+  const runs = pieceRuns(value)
+  // Index of the last run that ends at or before the cursor.
+  let index = runs.length - 1
+  while (index >= 0 && runs[index]!.end > cursor) index -= 1
+  if (index < 0) return 0
+  if (runs[index]!.class === 'space') {
+    index -= 1
+    if (index < 0) return 0
+  }
+  let target = index
+  while (target > 0 && runs[target]!.class === 'punct' && runs[target - 1]!.class === 'punct') target -= 1
+  return runs[target]!.start
+}
+
+/**
+ * Codex `end_of_next_word`: skip whitespace right, then land on the END of
+ * the leading non-space piece (extending over separator pieces).
+ */
+export function moveWordRight(value: string, offset: number): number {
+  const cursor = Math.max(0, Math.min(value.length, offset))
+  const runs = pieceRuns(value)
+  let index = 0
+  while (index < runs.length && runs[index]!.start < cursor) index += 1
+  if (index >= runs.length) return value.length
+  if (runs[index]!.class === 'space') {
+    index += 1
+    if (index >= runs.length) return value.length
+  }
+  let target = index
+  while (target < runs.length - 1 && runs[target]!.class === 'punct' && runs[target + 1]!.class === 'punct') target += 1
+  return runs[target]!.end
+}
+
+/** One edit outcome: the next draft value, cursor, and killed span (if any). */
+export interface EditResult {
+  value: string
+  cursor: number
+  /** Text removed into the kill buffer; undefined when nothing was killed. */
+  killed: string | undefined
+}
+
+function replaceRange(value: string, cursor: number, start: number, end: number, killed: boolean): EditResult {
+  const from = Math.min(start, end)
+  const to = Math.max(start, end)
+  if (from >= to) return { value, cursor, killed: undefined }
+  const text = value.slice(from, to)
+  return {
+    value: value.slice(0, from) + value.slice(to),
+    cursor: Math.max(0, cursor - Math.max(0, Math.min(cursor, to) - from)),
+    killed: killed ? text : undefined,
+  }
+}
+
+/** Delete the grapheme cluster before the cursor. */
+export function deleteBackward(value: string, cursor: number): EditResult {
+  if (cursor === 0) return { value, cursor, killed: undefined }
+  const spans = splitGraphemes(value.slice(0, cursor))
+  const start = spans.length === 0 ? 0 : spans[spans.length - 1]!.start
+  return replaceRange(value, cursor, start, cursor, false)
+}
+
+/** Delete the grapheme cluster at the cursor. */
+export function deleteForward(value: string, cursor: number): EditResult {
+  if (cursor >= value.length) return { value, cursor, killed: undefined }
+  const span = splitGraphemes(value).find(candidate => candidate.start >= cursor)
+  return replaceRange(value, cursor, cursor, span === undefined ? value.length : span.end, false)
+}
+
+/** Delete back to the start of the previous word (fills the kill buffer). */
+export function deleteWordBackward(value: string, cursor: number): EditResult {
+  const start = moveWordLeft(value, cursor)
+  return replaceRange(value, cursor, start, cursor, true)
+}
+
+/** Delete forward to the end of the next word (fills the kill buffer). */
+export function deleteWordForward(value: string, cursor: number): EditResult {
+  const end = moveWordRight(value, cursor)
+  return replaceRange(value, cursor, cursor, end, true)
+}
+
+/** Ctrl+U: kill from the line start to the cursor; at BOL, kill the newline. */
+export function killToLineStart(value: string, cursor: number): EditResult {
+  const bounds = lineBounds(value, cursor)
+  if (cursor > bounds.start) return replaceRange(value, cursor, bounds.start, cursor, true)
+  if (bounds.start > 0) return replaceRange(value, cursor, bounds.start - 1, bounds.start, true)
+  return { value, cursor, killed: undefined }
+}
+
+/** Ctrl+K: kill from the cursor to the line end; at EOL, kill the newline. */
+export function killToLineEnd(value: string, cursor: number): EditResult {
+  const bounds = lineBounds(value, cursor)
+  if (cursor < bounds.end) return replaceRange(value, cursor, cursor, bounds.end, true)
+  if (bounds.end < value.length) return replaceRange(value, cursor, bounds.end, bounds.end + 1, true)
+  return { value, cursor, killed: undefined }
+}
+
+/** Insert sanitized text at the cursor. */
+export function insertText(value: string, cursor: number, text: string): EditResult {
+  const safe = sanitizeDraftText(text)
+  if (safe === '') return { value, cursor, killed: undefined }
+  return { value: value.slice(0, cursor) + safe + value.slice(cursor), cursor: cursor + safe.length, killed: undefined }
+}
+
+/**
+ * Composer editor row budget: the editor itself never grows past this many
+ * physical rows; deeper drafts scroll internally to keep the caret visible.
+ * Short terminals collapse toward one row so the live transcript keeps room.
+ */
+export function composerMaxRows(terminalRows: number): number {
+  return Math.max(1, Math.min(6, Math.floor((Math.max(1, terminalRows) - 10) / 3)))
+}
+
+/**
+ * Codex `should_handle_navigation`: Up/Down walk history only from an empty
+ * draft, or from a boundary of a draft that still exactly matches the last
+ * recalled entry. Any interior cursor position keeps vertical caret movement.
+ */
+export function shouldRecallNavigate(value: string, cursor: number, lastRecalled: string | null): boolean {
+  if (value === '') return true
+  if (cursor !== 0 && cursor !== value.length) return false
+  return lastRecalled === value
+}