@mobius-os/mobius 0.3.31 → 0.3.34

package/README.md

@@ -130,6 +130,13 @@ npm test                   # all three
 
 ## Build an installable package
 
+The TUI release version has one source of truth: `mobius/tui/package.json`.
+The welcome screen, npm package metadata, artifact filename, and download
+manifest all read that value. `package-lock.json` mirrors it as generated npm
+metadata; do not edit it as a separate release setting. The AIMUX bundle
+version (`BUNDLE_VER`) is an independent Python runtime cache version and is
+not the TUI version.
+
 From the repository root:
 
 ```bash

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mobius-os/mobius",
-  "version": "0.3.31",
+  "version": "0.3.34",
   "type": "module",
   "description": "Mobius terminal client. Reuses Mobius frontend TypeScript types and jsonl entry shapes.",
   "bin": {
@@ -19,6 +19,7 @@
     "test:reconnect": "tsx tests/reconnect.test.tsx",
     "test:screen": "FORCE_COLOR=1 tsx tests/screen.test.tsx",
     "test:scroll": "tsx tests/scroll.test.tsx",
+    "test:viewport": "tsx tests/viewport.test.ts",
     "test:selection": "FORCE_COLOR=1 tsx tests/selection.test.tsx",
     "test": "npm run typecheck && npm run test:ui && npm run test:integration"
   },

package/src/components/Chat.tsx

@@ -13,11 +13,14 @@ import { useChat } from '../hooks/useChat.js'
 import { MobiusClient } from '../api.js'
 import { viewsForEntry, dedupeUserEntries, isAssistantOutput } from '../lib/entry-view.js'
 import {
-  displayWidth, compareSel, entryScreenLines, entryScreenRows,
-  buildTranscriptModel, computeTranscriptGeometry, screenToSelPoint,
+  displayWidth, compareSel, entryScreenRows, screenToSelPoint,
   buildSelectionMap, buildSelectionText, osc52,
   type TranscriptModel, type TranscriptGeometry, type SelPoint, type ScreenRow,
 } from '../lib/screen-text.js'
+import {
+  createRowAccess, moveAnchorByRows, sliceViewport, tailAnchor,
+  type RowAnchor,
+} from '../lib/transcript-viewport.js'
 import type { ReadyState } from './PrepScreen.js'
 import type { AnyEntry } from '../types.js'
 import { ConfigFlow, ReconfigFlow, type ConfigResult } from './ConfigFlow.js'
@@ -45,8 +48,7 @@ interface TerminalSize {
   isTty: boolean
 }
 
-import { createRequire } from 'node:module'
-const VERSION = createRequire(import.meta.url)('../../package.json').version
+import { TUI_VERSION } from '../version.js'
 const DEFAULT_COMPOSER_ROWS = 5
 const STATUS_ROWS = 3
 
@@ -62,7 +64,9 @@ const SLASH_COMMANDS = [
 export function ChatScreen({ client, ready, webUserId, resumeSessionId, onClear, onResume, onQuit, onReconfigure, onConfigCancel, aimuxStatus }: ChatProps) {
   const chat = useChat({ client, ready, resumeSessionId })
   const [showHelp, setShowHelp] = useState(false)
-  const [scrollBack, setScrollBack] = useState(0)
+  // null means "follow the tail". A concrete anchor identifies the exact row
+  // at the top of the viewport while the user browses history.
+  const [rowAnchor, setRowAnchor] = useState<RowAnchor | null>(null)
   const [composerRows, setComposerRows] = useState(DEFAULT_COMPOSER_ROWS)
   const [modelLabel, setModelLabel] = useState<string | null>(null)
   const [configOpen, setConfigOpen] = useState(false)
@@ -100,7 +104,7 @@ export function ChatScreen({ client, ready, webUserId, resumeSessionId, onClear,
       return
     }
     setShowHelp(false)
-    setScrollBack(0)
+    setRowAnchor(null)
     void chat.send(t)
   }, [chat, runSlash])
 
@@ -116,39 +120,66 @@ export function ChatScreen({ client, ready, webUserId, resumeSessionId, onClear,
   // (type:user / response_item.message[user] / event_msg.user_message) 合并成 1 条,
   // 避免在累积视图里把同一条提问显示多次.
   const dedupedEntries = useMemo(() => dedupeUserEntries(chat.entries), [chat.entries])
-  // Cache: entry index → rendered line count. Cleared when entries or columns change.
-  const entryLines = useRef<Map<number, number>>(new Map())
-  useEffect(() => { entryLines.current.clear() }, [dedupedEntries, terminal.columns])
-  const getEntryLines = useCallback((i: number) => {
-    const c = entryLines.current.get(i)
-    if (c !== undefined) return c
-    const n = entryScreenLines(viewsForEntry(dedupedEntries[i]), terminal.columns).length || 1
-    entryLines.current.set(i, n)
-    return n
-  }, [dedupedEntries, terminal.columns])
+  const pendingEntry = useMemo<AnyEntry | null>(() => chat.pendingUser === null ? null : ({
+    type: 'user',
+    __id: '__pending-user__',
+    message: { role: 'user', content: chat.pendingUser },
+  }), [chat.pendingUser])
+  const transcriptEntries = useMemo(
+    () => pendingEntry ? [...dedupedEntries, pendingEntry] : dedupedEntries,
+    [dedupedEntries, pendingEntry],
+  )
+
+  // Markdown parsing and wrapping are paid once per entry/terminal width. Keep
+  // the two most recent widths so resize-back does not immediately reparse the
+  // whole visible history, while bounding cache growth during repeated resizes.
+  const rowCache = useRef<WeakMap<AnyEntry, Map<number, ScreenRow[]>>>(new WeakMap())
+  const rowsForEntry = useCallback((entry: AnyEntry): readonly ScreenRow[] => {
+    let widths = rowCache.current.get(entry)
+    if (!widths) {
+      widths = new Map()
+      rowCache.current.set(entry, widths)
+    }
+    const cached = widths.get(terminal.columns)
+    if (cached) return cached
+    const rows = entryScreenRows(viewsForEntry(entry), terminal.columns)
+    if (widths.size >= 2) widths.delete(widths.keys().next().value!)
+    widths.set(terminal.columns, rows)
+    return rows
+  }, [terminal.columns])
+  const rowAccess = useMemo(() => createRowAccess(
+    transcriptEntries,
+    // UUID is stable across SSE history replay; __id is only the local fallback
+    // for entries that do not carry a backend identity (notably the optimistic
+    // pending user row).
+    (entry, index) => String(entry.uuid ?? entry.__id ?? `entry-${index}`),
+    (entry) => rowsForEntry(entry),
+  ), [transcriptEntries, rowsForEntry])
   const viewportRows = terminal.isTty ? Math.max(9, terminal.rows - 1) : terminal.rows
   const activityRows = (chat.typing ? 2 : 0) + (chat.error ? 1 : 0)
   const helpRows = showHelp ? SLASH_COMMANDS.length + 3 : 0
-  const transcriptRows = Math.max(1, viewportRows - composerRows - STATUS_ROWS - activityRows - helpRows - 3)
-  const fitted = useMemo(
-    () => fitTranscript(dedupedEntries, transcriptRows, terminal.columns, scrollBack),
-    [dedupedEntries, transcriptRows, terminal.columns, scrollBack],
+  // Conversation chrome is exactly two rows: compact header + navigation.
+  const transcriptRows = Math.max(1, viewportRows - composerRows - STATUS_ROWS - activityRows - helpRows - 2)
+  const tail = useMemo(() => tailAnchor(rowAccess, transcriptRows), [rowAccess, transcriptRows])
+  const effectiveAnchor = rowAnchor ?? tail
+  const viewport = useMemo(
+    () => sliceViewport(rowAccess, effectiveAnchor, transcriptRows),
+    [rowAccess, effectiveAnchor, transcriptRows],
   )
-  const showWelcome = dedupedEntries.length === 0 && chat.pendingUser === null && scrollBack === 0
-
-  // Keep a history page pinned while new events stream in. At the latest page,
-  // new output continues to auto-follow as usual.
-  const prevLenRef = useRef(dedupedEntries.length)
-  useEffect(() => {
-    const previous = prevLenRef.current
-    const current = dedupedEntries.length
-    prevLenRef.current = current
-    if (current > previous && scrollBack > 0) {
-      setScrollBack(value => value + current - previous)
-    } else if (scrollBack > current) {
-      setScrollBack(current)
-    }
-  }, [dedupedEntries.length, scrollBack])
+  const showWelcome = transcriptEntries.length === 0
+  const pageRows = Math.max(1, transcriptRows - 1)
+
+  const scrollRows = useCallback((deltaRows: number) => {
+    if (deltaRows === 0) return
+    selState.current = null
+    setSel(null)
+    setRowAnchor(previous => {
+      const start = previous ?? tailAnchor(rowAccess, transcriptRows)
+      const next = moveAnchorByRows(rowAccess, start, deltaRows)
+      if (deltaRows > 0 && !sliceViewport(rowAccess, next, transcriptRows).hasNewer) return null
+      return next
+    })
+  }, [rowAccess, transcriptRows])
 
   // Show the model's friendly label (e.g. "GPT-5.6-Sol") in the header/status
   // instead of its opaque key (e.g. "codex:mobiusdefaultaabb").
@@ -174,16 +205,13 @@ export function ChatScreen({ client, ready, webUserId, resumeSessionId, onClear,
       if (isEscapeKeypress(_input, key)) onConfigCancel(handlerRef.current.sessionId)
       return
     }
-    const step = Math.max(1, fitted.entries.length)
-    if (key.pageUp) setScrollBack(value => Math.min(dedupedEntries.length, value + step))
-    else if (key.pageDown) setScrollBack(value => Math.max(0, value - step))
+    if (key.pageUp) scrollRows(-pageRows)
+    else if (key.pageDown) scrollRows(pageRows)
   }, { interactive: false })
 
-  const olderHint = !showWelcome && (fitted.hiddenOlder > 0 || scrollBack > 0)
-    ? fitted.hiddenOlder > 0
-      ? `↑ 还有 ${fitted.hiddenOlder} 条较早记录 · 滚轮/PageUp 翻页 · 拖动选中文本`
-      : '已到最早记录 · 滚轮/PageDown 翻页 · 拖动选中文本'
-    : null
+  const navigationHint = viewport.hasOlder
+    ? `${viewport.hasNewer ? '↑ 较早内容 · ↓ 较新内容' : '↑ 还有较早内容'} · 滚轮 3 行 · PageUp/PageDown ${pageRows} 行 · 拖动选中文本`
+    : `${viewport.hasNewer ? '已到最早 · ↓ 还有较新内容' : '全部内容'} · 滚轮 3 行 · PageUp/PageDown ${pageRows} 行 · 拖动选中文本`
 
   // Mouse: wheel pages through history in small fixed steps, and a left-button
   // drag selects transcript text (tmux-style: the app owns the mouse, draws its
@@ -195,23 +223,16 @@ export function ChatScreen({ client, ready, webUserId, resumeSessionId, onClear,
   const [sel, setSel] = useState<{ anchor: SelPoint; end: SelPoint; active: boolean } | null>(null)
   const [copyNotice, setCopyNotice] = useState<string | null>(null)
 
-  // Geometry + text model must mirror the rendered transcript so a screen
-  // (row, col) maps to the right entry/line/char. Recompute with the fitted view.
-  const tipShown = dedupedEntries.length === 0 && chat.pendingUser === null && !showHelp
-  const geometry: TranscriptGeometry = useMemo(() => computeTranscriptGeometry({
-    viewportRows,
-    composerRows,
-    statusRows: STATUS_ROWS,
-    activityRows,
-    helpRows,
-    showWelcome,
-    welcomeRows: 10,
-    olderHintShown: olderHint !== null,
-    tipShown,
-  }), [viewportRows, composerRows, activityRows, helpRows, showWelcome, olderHint, tipShown])
+  // Selection uses the exact virtual rows mounted below. There is no separate
+  // fitting/geometry pass, so hit-testing, rendering and clipboard extraction
+  // cannot disagree about which rows are on screen.
+  const geometry: TranscriptGeometry = useMemo(
+    () => ({ boxTop: 2, boxH: transcriptRows }),
+    [transcriptRows],
+  )
   const transcriptModel: TranscriptModel = useMemo(
-    () => buildTranscriptModel(fitted.entries, terminal.columns),
-    [fitted.entries, terminal.columns],
+    () => ({ entries: viewport.rows.map(item => [item.row.plain]), totalRows: viewport.rows.length }),
+    [viewport.rows],
   )
   const selMap = useMemo(
     () => (sel?.active ? buildSelectionMap(transcriptModel, sel.anchor, sel.end) : null),
@@ -227,25 +248,7 @@ export function ChatScreen({ client, ready, webUserId, resumeSessionId, onClear,
 
   useMouseEvents({
     onWheel: (delta) => {
-      if (delta === 0) return
-      const targetLines = 2
-      let lines = 0
-      let next = scrollBack
-      const n = dedupedEntries.length
-      if (delta > 0) {
-        // scroll up (older): hide more entries from the tail
-        for (let i = n - 1 - next; i >= 0 && lines < targetLines; i--) {
-          lines += getEntryLines(i)
-          next++
-        }
-      } else {
-        // scroll down (newer): unhide entries from the tail
-        for (let i = n - next; i < n && lines < targetLines; i++) {
-          lines += getEntryLines(i)
-          next--
-        }
-      }
-      setScrollBack(Math.min(n, Math.max(0, next)))
+      scrollRows(delta * -3)
     },
     onPress: (row, col) => {
       const p = screenToSelPoint(row, col, transcriptModel, geometry)
@@ -325,34 +328,25 @@ export function ChatScreen({ client, ready, webUserId, resumeSessionId, onClear,
           ? <WelcomeCard ready={ready} columns={terminal.columns} resumed={Boolean(resumeSessionId)} modelDisplay={modelDisplay} />
           : <CompactHeader ready={ready} sessionId={chat.sessionId} columns={terminal.columns} />}
 
-        {/* Older-records hint is pinned OUTSIDE the flex-end scroll box so it is
-            always the first line of the transcript, spanning the full width,
-            instead of floating mid-screen when the transcript has spare rows. */}
-        {olderHint !== null
-          ? <Box width="100%" flexShrink={0}><Text dimColor wrap="truncate-end">  {olderHint}</Text></Box>
+        {!showWelcome
+          ? <Box width="100%" flexShrink={0}><Text dimColor wrap="truncate-end">  {navigationHint}</Text></Box>
           : null}
 
-        <Box flexGrow={1} flexShrink={1} flexDirection="column" justifyContent={showWelcome || fitted.hiddenOlder > 0 ? 'flex-start' : 'flex-end'} overflowY="hidden">
-          {fitted.peekRows.length > 0
-            ? <Box width="100%" flexShrink={0} flexDirection="column">
-                {fitted.peekRows.map((row, index) => (
-                  <ScreenText
-                    key={`peek-${index}`}
-                    row={row}
-                    text={`${index === 0 ? '  ⋯ ' : '    '}${row.styled}`}
-                  />
-                ))}
-              </Box>
-            : null}
-          {fitted.entries.map((entry, index) => {
-            const entrySel = selMap?.get(index)
-            const key = entry.__id ?? `entry-${fitted.startIndex + index}`
-            return <EntryScreen key={key} entry={entry} columns={terminal.columns} sel={entrySel} />
-          })}
-          {chat.pendingUser !== null ? <UserLine text={chat.pendingUser} /> : null}
-          {fitted.hiddenRecent > 0
-            ? <Box width="100%" flexShrink={0}><Text dimColor wrap="truncate-end">  ↓ 滚轮/PageDown 翻页 · 较新 {fitted.hiddenRecent} 条</Text></Box>
-            : null}
+        <Box
+          height={showWelcome ? undefined : transcriptRows}
+          flexGrow={showWelcome ? 1 : 0}
+          flexShrink={showWelcome ? 1 : 0}
+          flexDirection="column"
+          justifyContent="flex-end"
+          overflowY="hidden"
+        >
+          {!showWelcome ? viewport.rows.map((item, index) => {
+            const range = selMap?.get(index)?.get(0)
+            const text = range && range.start < range.end
+              ? highlightScreenRow(item.row.styled, range.start, range.end)
+              : item.row.styled
+            return <ScreenText key={`${item.entryId}:${item.rowIndex}`} row={item.row} text={text || ' '} />
+          }) : null}
         </Box>
 
         {dedupedEntries.length === 0 && chat.pendingUser === null && !showHelp
@@ -417,7 +411,7 @@ function WelcomeCard({ ready, columns, resumed, modelDisplay }: { ready: ReadySt
         <Text>
           <Text dimColor>{'>_ '}</Text>
           <Text bold>Mobius</Text>
-          <Text dimColor> (v{VERSION})</Text>
+          <Text dimColor> (v{TUI_VERSION})</Text>
         </Text>
         <Text> </Text>
         <MetaRow label="model:" value={modelDisplay} hint="/help 查看命令" labelWidth={labelWidth} />
@@ -452,29 +446,6 @@ function CompactHeader({ ready, sessionId, columns }: { ready: ReadyState; sessi
   )
 }
 
-// Normal and selected transcript rows use the exact same component tree. Mouse
-// motion now changes only ANSI background bytes inside a row; it never swaps a
-// rich Markdown entry for a structurally different plain-text entry, which used
-// to make long/styled messages jump as the selection crossed entry boundaries.
-function EntryScreen({ entry, columns, sel }: {
-  entry: AnyEntry
-  columns: number
-  sel?: Map<number, { start: number; end: number }>
-}) {
-  const rows = entryScreenRows(viewsForEntry(entry), columns)
-  return (
-    <Box flexDirection="column">
-      {rows.map((row, index) => {
-        const range = sel?.get(index)
-        const text = range && range.start < range.end
-          ? highlightScreenRow(row.styled, range.start, range.end)
-          : row.styled
-        return <ScreenText key={index} row={row} text={text || ' '} />
-      })}
-    </Box>
-  )
-}
-
 function ScreenText({ row, text }: { row: ScreenRow; text: string }) {
   const tone = row.tone
   const color = tone === 'tool' ? 'cyan'
@@ -529,13 +500,6 @@ function highlightScreenRow(styled: string, start: number, end: number): string
   return out
 }
 
-function UserLine({ text }: { text: string }) {
-  const lines = text.split('\n')
-  if (lines[0] !== undefined) lines[0] = `› ${lines[0]}`
-  for (let i = 1; i < lines.length; i++) lines[i] = `  ${lines[i]}`
-  return <Box marginTop={1}><Text bold>{lines.join('\n')}</Text></Box>
-}
-
 function WorkingIndicator({ firstQuery }: { firstQuery: boolean }) {
   const startedAt = useRef(Date.now())
   const [animationFrame, setAnimationFrame] = useState(0)
@@ -1104,60 +1068,3 @@ function clickableUrl(url: string, maxLen?: number): string {
 
 // displayWidth is imported from src/lib/screen-text.ts (CJK/emoji-aware), used
 // here to size the AIMUX status block so the web URL truncates exactly.
-
-export function fitTranscript(entries: AnyEntry[], rowBudget: number, columns: number, scrollBack = 0): {
-  entries: AnyEntry[]
-  /** Tail rows of the next older entry, used to fill spare space above the viewport. */
-  peekRows: ScreenRow[]
-  hiddenOlder: number
-  hiddenRecent: number
-  startIndex: number
-} {
-  const tail = Math.max(0, entries.length - scrollBack)
-  const available = tail === 0 ? [] : entries.slice(0, tail)
-  const renderedRows = available.map((entry) => entryScreenRows(viewsForEntry(entry), columns))
-  const fit = (budget: number) => {
-    let rows = 0
-    let first = available.length
-    for (let index = available.length - 1; index >= 0; index--) {
-      const nextRows = renderedRows[index].length
-      if (first < available.length && rows + nextRows > budget) break
-      rows += nextRows
-      first = index
-    }
-    return { first, rows }
-  }
-
-  const base = fit(rowBudget)
-  let fitted = base
-  let first = fitted.first
-  let peekRows: ScreenRow[] = []
-  // When older history exists, guarantee at least one row for the tail of the
-  // next older message. If complete entries exactly consume the budget, refit
-  // them with one fewer row; only the oldest complete entry can drop out, while
-  // the latest content remains visible. A single oversized entry keeps its
-  // original rendering because it cannot safely donate a row.
-  if (first > 0 && fitted.rows <= rowBudget) {
-    if (fitted.rows === rowBudget && rowBudget > 1) {
-      const reduced = fit(rowBudget - 1)
-      if (reduced.first > 0 && reduced.rows <= rowBudget - 1) {
-        fitted = reduced
-        first = reduced.first
-      }
-    }
-    const olderRows = renderedRows[first - 1].slice()
-    while (olderRows.length > 0 && !olderRows[0].plain.trim()) olderRows.shift()
-    while (olderRows.length > 0 && !olderRows[olderRows.length - 1].plain.trim()) olderRows.pop()
-    const spare = rowBudget - fitted.rows
-    if (spare > 0 && olderRows.length > 0) {
-      peekRows = olderRows.slice(-spare)
-    }
-  }
-  return {
-    entries: available.slice(first),
-    peekRows,
-    hiddenOlder: first,
-    hiddenRecent: entries.length - tail,
-    startIndex: first,
-  }
-}

package/src/components/primitives.tsx

@@ -192,6 +192,26 @@ export function parseMouseEvents(input: string): MouseEventInfo[] {
   return out
 }
 
+/** Collapse each contiguous wheel burst into one delta without reordering clicks. */
+export function coalesceMouseEvents(events: MouseEventInfo[]): MouseEventInfo[] {
+  const out: MouseEventInfo[] = []
+  let wheelDelta = 0
+  const flushWheel = () => {
+    if (wheelDelta !== 0) out.push({ kind: 'wheel', delta: wheelDelta })
+    wheelDelta = 0
+  }
+  for (const event of events) {
+    if (event.kind === 'wheel') {
+      wheelDelta += event.delta
+    } else {
+      flushWheel()
+      out.push(event)
+    }
+  }
+  flushWheel()
+  return out
+}
+
 /**
  * Enables terminal mouse tracking for the lifetime of the calling component and
  * forwards mouse events (wheel + left-button press/motion/release) to the given
@@ -228,7 +248,7 @@ export function useMouseEvents(handlers: {
       // A single read() chunk may carry several events and a sequence may be
       // split across chunks, so accumulate and re-scan.
       buf += String(chunk)
-      for (const e of parseMouseEvents(buf)) {
+      for (const e of coalesceMouseEvents(parseMouseEvents(buf))) {
         if (e.kind === 'wheel') refs.current.onWheel?.(e.delta)
         else if (e.kind === 'press') refs.current.onPress?.(e.row, e.col)
         else if (e.kind === 'motion') refs.current.onMotion?.(e.row, e.col)

package/src/lib/entry-view.ts

@@ -638,18 +638,18 @@ export function toolLabel(name: string): string {
 // agent 输出, 则视为同一次输入的重复入口 → 丢弃, 避免 TUI 把同一条提问显示多次.
 export function userTextOf(e: AnyEntry): string {
   if (e?.type === 'event_msg' && e?.payload?.type === 'user_message') {
-    return String(e?.payload?.message || '').trim()
+    return canonicalUserText(String(e?.payload?.message || ''))
   }
   if (e?.type === 'response_item' && e?.payload?.type === 'message' && e?.payload?.role === 'user') {
     const c = e?.payload?.content
-    if (typeof c === 'string') return c.trim()
-    if (Array.isArray(c)) return c.map((b: any) => b?.text || b?.input_text || '').filter(Boolean).join('\n').trim()
+    if (typeof c === 'string') return canonicalUserText(c)
+    if (Array.isArray(c)) return canonicalUserText(c.map((b: any) => b?.text || b?.input_text || '').filter(Boolean).join('\n'))
     return ''
   }
   if (e?.type === 'user') {
     const c = e?.message?.content
-    if (typeof c === 'string') return c.trim()
-    if (Array.isArray(c)) return c.filter((b: any) => b?.type === 'text').map((b: any) => b?.text || '').join('\n').trim()
+    if (typeof c === 'string') return canonicalUserText(c)
+    if (Array.isArray(c)) return canonicalUserText(c.filter((b: any) => b?.type === 'text').map((b: any) => b?.text || '').join('\n'))
     return ''
   }
   return ''
@@ -669,6 +669,11 @@ export function stripUserFraming(text: string): string {
   return after || text
 }
 
+/** Canonical user text for duplicate event identities (framed vs plain). */
+function canonicalUserText(text: string): string {
+  return stripUserFraming(text).replace(/\s+/g, ' ').trim()
+}
+
 export function isAssistantOutput(e: AnyEntry): boolean {
   if (e?.type === 'assistant') return true
   if (e?.type === 'event_msg' && e?.payload?.type === 'agent_message') return true

package/src/lib/screen-text.ts

@@ -13,7 +13,6 @@
 import wrapAnsi from 'wrap-ansi'
 import { renderMarkdownLines } from '../markdown.js'
 import { toolLabel, viewsForEntry, type EntryView } from './entry-view.js'
-import type { AnyEntry } from '../types.js'
 
 // ── shared text helpers (mirrored from Chat.tsx, kept here to avoid a cycle) ─
 export function displayWidth(str: string): number {
@@ -221,11 +220,6 @@ export function entryScreenRows(views: EntryView[], columns: number): ScreenRow[
   return lines
 }
 
-/** Plain projection used by fitting, geometry, hit-testing, and copying. */
-export function entryScreenLines(views: EntryView[], columns: number): string[] {
-  return entryScreenRows(views, columns).map(row => row.plain)
-}
-
 // ── vertical geometry ────────────────────────────────────────────────────────
 export interface TranscriptGeometry {
   /** Screen row where the transcript box's top edge sits. */
@@ -240,30 +234,6 @@ export interface TranscriptGeometry {
  * (`flexShrink=0`); the middle column holds header + hint + transcript (flexGrow)
  * + tip + help. Margins that render as extra rows are counted explicitly.
  */
-export function computeTranscriptGeometry(opts: {
-  viewportRows: number
-  composerRows: number
-  statusRows: number
-  activityRows: number
-  helpRows: number
-  showWelcome: boolean
-  welcomeRows: number
-  olderHintShown: boolean
-  tipShown: boolean
-}): TranscriptGeometry {
-  // The composer's reported height already includes its marginTop; the status
-  // area and working indicator rows are already folded into statusRows and
-  // activityRows. No extra +1 here — calibrated against the rendered frame.
-  const bottomH = opts.activityRows + opts.composerRows + opts.statusRows
-  const midH = opts.viewportRows - bottomH
-  const headerH = opts.showWelcome ? opts.welcomeRows : 1
-  const hintH = opts.olderHintShown ? 1 : 0
-  const tipH = opts.tipShown ? 2 : 0 // marginTop 1 + content 1
-  const helpH = opts.helpRows > 0 ? opts.helpRows + 1 : 0 // +1 marginTop
-  const boxTop = headerH + hintH + tipH + helpH
-  return { boxTop, boxH: Math.max(0, midH - boxTop) }
-}
-
 // ── selection mapping ────────────────────────────────────────────────────────
 export interface SelPoint {
   entry: number // index into the fitted entries
@@ -276,11 +246,6 @@ export interface TranscriptModel {
   totalRows: number
 }
 
-export function buildTranscriptModel(fittedEntries: AnyEntry[], columns: number): TranscriptModel {
-  const entries = fittedEntries.map((e) => entryScreenLines(viewsForEntry(e), columns))
-  return { entries, totalRows: entries.reduce((sum, l) => sum + l.length, 0) }
-}
-
 /** Convert a screen (row, col) into a SelPoint, or null if outside the transcript. */
 export function screenToSelPoint(
   screenRow: number,

package/src/lib/transcript-viewport.ts

@@ -0,0 +1,162 @@
+/**
+ * Pure row-level transcript viewport.
+ *
+ * Entries are materialized lazily through RowAccess.rowsAt(). Navigation keeps
+ * an entry/row anchor, so moving by N rows is exact even when one entry is much
+ * taller than the terminal. No React or Ink dependency belongs in this file.
+ */
+
+export interface RowAnchor {
+  entryId: string
+  entryIndex: number
+  rowIndex: number
+}
+
+export interface ViewportRow<T> {
+  entryId: string
+  entryIndex: number
+  rowIndex: number
+  row: T
+}
+
+export interface RowAccess<T> {
+  length: number
+  idAt: (index: number) => string
+  indexOf: (entryId: string) => number
+  rowsAt: (index: number) => readonly T[]
+}
+
+export interface ViewportSlice<T> {
+  anchor: RowAnchor | null
+  rows: ViewportRow<T>[]
+  hasOlder: boolean
+  hasNewer: boolean
+}
+
+export function createRowAccess<E, T>(
+  entries: readonly E[],
+  getId: (entry: E, index: number) => string,
+  getRows: (entry: E, index: number) => readonly T[],
+): RowAccess<T> {
+  const ids = entries.map(getId)
+  const indexById = new Map(ids.map((id, index) => [id, index]))
+  return {
+    length: entries.length,
+    idAt: (index) => ids[index] ?? '',
+    indexOf: (entryId) => indexById.get(entryId) ?? -1,
+    rowsAt: (index) => index >= 0 && index < entries.length ? getRows(entries[index], index) : [],
+  }
+}
+
+function previousNonEmpty<T>(access: RowAccess<T>, from: number): number {
+  for (let index = from; index >= 0; index--) {
+    if (access.rowsAt(index).length > 0) return index
+  }
+  return -1
+}
+
+function nextNonEmpty<T>(access: RowAccess<T>, from: number): number {
+  for (let index = from; index < access.length; index++) {
+    if (access.rowsAt(index).length > 0) return index
+  }
+  return -1
+}
+
+function resolveAnchor<T>(access: RowAccess<T>, anchor: RowAnchor | null): RowAnchor | null {
+  if (!anchor || access.length === 0) return null
+  let entryIndex = access.indexOf(anchor.entryId)
+  if (entryIndex < 0) entryIndex = Math.max(0, Math.min(access.length - 1, anchor.entryIndex))
+
+  let rows = access.rowsAt(entryIndex)
+  if (rows.length === 0) {
+    const next = nextNonEmpty(access, entryIndex + 1)
+    const previous = previousNonEmpty(access, entryIndex - 1)
+    entryIndex = next >= 0 ? next : previous
+    if (entryIndex < 0) return null
+    rows = access.rowsAt(entryIndex)
+  }
+
+  return {
+    entryId: access.idAt(entryIndex),
+    entryIndex,
+    rowIndex: Math.max(0, Math.min(rows.length - 1, anchor.rowIndex)),
+  }
+}
+
+export function tailAnchor<T>(access: RowAccess<T>, viewportRows: number): RowAnchor | null {
+  let remaining = Math.max(1, Math.floor(viewportRows))
+  let first: RowAnchor | null = null
+  for (let entryIndex = access.length - 1; entryIndex >= 0; entryIndex--) {
+    const rows = access.rowsAt(entryIndex)
+    if (rows.length === 0) continue
+    first = { entryId: access.idAt(entryIndex), entryIndex, rowIndex: 0 }
+    if (rows.length >= remaining) {
+      return { entryId: access.idAt(entryIndex), entryIndex, rowIndex: rows.length - remaining }
+    }
+    remaining -= rows.length
+  }
+  return first
+}
+
+/** Move the top-row anchor by an exact signed row delta. Positive means newer. */
+export function moveAnchorByRows<T>(access: RowAccess<T>, anchor: RowAnchor | null, deltaRows: number): RowAnchor | null {
+  const resolved = resolveAnchor(access, anchor)
+  if (!resolved || deltaRows === 0) return resolved
+
+  let entryIndex = resolved.entryIndex
+  let rowIndex = resolved.rowIndex
+  let remaining = Math.abs(Math.trunc(deltaRows))
+
+  if (deltaRows > 0) {
+    while (remaining > 0) {
+      const rows = access.rowsAt(entryIndex)
+      const within = rows.length - 1 - rowIndex
+      if (remaining <= within) { rowIndex += remaining; remaining = 0; break }
+      remaining -= within
+      const next = nextNonEmpty(access, entryIndex + 1)
+      if (next < 0) { rowIndex = rows.length - 1; break }
+      entryIndex = next
+      rowIndex = 0
+      remaining -= 1
+    }
+  } else {
+    while (remaining > 0) {
+      if (remaining <= rowIndex) { rowIndex -= remaining; remaining = 0; break }
+      remaining -= rowIndex
+      const previous = previousNonEmpty(access, entryIndex - 1)
+      if (previous < 0) { rowIndex = 0; break }
+      entryIndex = previous
+      rowIndex = access.rowsAt(entryIndex).length - 1
+      remaining -= 1
+    }
+  }
+
+  return { entryId: access.idAt(entryIndex), entryIndex, rowIndex }
+}
+
+export function sliceViewport<T>(access: RowAccess<T>, anchor: RowAnchor | null, viewportRows: number): ViewportSlice<T> {
+  const resolved = resolveAnchor(access, anchor)
+  const limit = Math.max(0, Math.floor(viewportRows))
+  if (!resolved || limit === 0) return { anchor: resolved, rows: [], hasOlder: false, hasNewer: false }
+
+  const visible: ViewportRow<T>[] = []
+  let entryIndex = resolved.entryIndex
+  let rowIndex = resolved.rowIndex
+  while (entryIndex < access.length && visible.length < limit) {
+    const rows = access.rowsAt(entryIndex)
+    for (; rowIndex < rows.length && visible.length < limit; rowIndex++) {
+      visible.push({ entryId: access.idAt(entryIndex), entryIndex, rowIndex, row: rows[rowIndex] })
+    }
+    entryIndex = nextNonEmpty(access, entryIndex + 1)
+    rowIndex = 0
+    if (entryIndex < 0) break
+  }
+
+  const hasOlder = resolved.rowIndex > 0 || previousNonEmpty(access, resolved.entryIndex - 1) >= 0
+  const last = visible.at(-1)
+  const hasNewer = !!last && (
+    last.rowIndex < access.rowsAt(last.entryIndex).length - 1 ||
+    nextNonEmpty(access, last.entryIndex + 1) >= 0
+  )
+  return { anchor: resolved, rows: visible, hasOlder, hasNewer }
+}

package/src/version.ts

@@ -0,0 +1,21 @@
+/**
+ * The TUI package version has one source of truth: package.json.
+ *
+ * Keep all runtime/UI consumers behind this module so a release cannot show
+ * a stale hard-coded version while the npm package has already been bumped.
+ */
+import { createRequire } from 'node:module'
+
+interface TuiPackageMetadata {
+  name?: string
+  version?: string
+}
+
+const packageJson = createRequire(import.meta.url)('../package.json') as TuiPackageMetadata
+
+if (!packageJson.version) {
+  throw new Error('TUI package.json is missing a version')
+}
+
+export const TUI_VERSION = packageJson.version
+export const TUI_PACKAGE_NAME = packageJson.name ?? '@mobius-os/mobius'

package/tests/screen.test.tsx

@@ -20,8 +20,9 @@ import { Box, Text } from 'ink'
 import { render } from 'ink-testing-library'
 import { Screen } from '../src/components/Screen.js'
 import { Select } from '../src/components/primitives.js'
-import { fitTranscript } from '../src/components/Chat.js'
-import type { AnyEntry } from '../src/types.js'
+import { entryScreenRows } from '../src/lib/screen-text.js'
+import { viewsForEntry } from '../src/lib/entry-view.js'
+import { createRowAccess, sliceViewport, tailAnchor } from '../src/lib/transcript-viewport.js'
 
 const delay = (ms: number) => new Promise<void>(r => setTimeout(r, ms))
 const strip = (s: string) => s.replace(/\x1b\[[0-9;?]*[a-zA-Z]/g, '')
@@ -36,17 +37,17 @@ const ROWS = 24
 async function main() {
   console.log('\n[SCREEN] no-residue picker transitions\n')
 
-  // A hidden older entry may contribute only its tail rows when the viewport
-  // has one spare row. That preview must retain the entry's foreground style;
-  // rendering it as a bare dimColor string makes a clipped cyan Markdown link
-  // look gray even though the rest of the message is colored.
-  const styledEntries: AnyEntry[] = [
+  // A partial message is now represented by the same styled ScreenRow as a
+  // complete message. Virtual slicing must preserve its ANSI foreground bytes.
+  const styledEntries = [
     { type: 'assistant', uuid: 'styled-old', message: { role: 'assistant', content: [{ type: 'text', text: '[彩色链接](https://example.com)' }] } },
     { type: 'assistant', uuid: 'styled-new', message: { role: 'assistant', content: [{ type: 'text', text: '最新消息' }] } },
   ]
-  const fitted = fitTranscript(styledEntries, 3, 80)
-  ok(fitted.peekRows.length === 1, 'small viewport exposes one tail row from the hidden message')
-  ok(fitted.peekRows[0]?.styled.includes('\x1b[') && fitted.peekRows[0]?.styled.includes('彩色链接'), 'partial older row keeps its ANSI foreground styling')
+  const rowAccess = createRowAccess(styledEntries, entry => entry.uuid, entry => entryScreenRows(viewsForEntry(entry), 80))
+  const viewport = sliceViewport(rowAccess, tailAnchor(rowAccess, 3), 3)
+  const partial = viewport.rows.find(item => item.entryId === 'styled-old')?.row
+  ok(partial !== undefined, 'small viewport exposes a row from the partial older message')
+  ok(!!partial?.styled.includes('\x1b[') && partial.styled.includes('彩色链接'), 'partial older row keeps its ANSI foreground styling')
 
   // ── 1. Without Screen, a tall frame overflows the terminal (the bug). ───────
   const tall = render(

package/tests/scroll.test.tsx

@@ -138,7 +138,7 @@ async function main() {
     const tailFrame = strip(lastFrame() ?? '')
 
     ok(tailFrame.includes('回答 24'), 'latest entry visible at tail (not hidden)')
-    ok(tailFrame.includes('PageUp'), 'older-records hint offers PageUp (nothing is silently lost)')
+    ok(tailFrame.includes('↑ 还有较早内容') && tailFrame.includes('滚轮 3 行'), 'navigation reports older content and the exact wheel step')
 
     // ── live resize: refit one dynamic frame, never retain old-width output ──
     resize(stdout as unknown as NodeJS.WriteStream, 52, 18)
@@ -157,21 +157,20 @@ async function main() {
     ok(tallAnswers > narrowAnswers, 'larger resize reveals more history in the same viewport')
     ok((tallFrame.match(/>_ Mobius/g) ?? []).length === 1, 'larger resize still has one dynamic header')
 
-    // The "↑ 还有 N 条较早记录" hint must be pinned to the FIRST line below the
-    // header and span the full width — it must not float mid-transcript when the
-    // viewport has spare rows (regression for real terminals, which bound the
-    // transcript box height via stdout.isTTY).
+    // Navigation is a fixed one-row part of the conversation chrome. It must be
+    // the FIRST line below the header and state the exact PageUp/PageDown step.
     const tallLines = tallFrame.split('\n')
-    const hintIdx = tallLines.findIndex(l => l.includes('较早记录'))
-    ok(hintIdx === 1, `older-records hint is the first line under the header (line ${hintIdx}, expected 1)`)
+    const hintIdx = tallLines.findIndex(l => l.includes('滚轮 3 行'))
+    ok(hintIdx === 1, `navigation is the first line under the header (line ${hintIdx}, expected 1)`)
+    ok(/PageUp\/PageDown \d+ 行/.test(tallLines[hintIdx] ?? ''), 'navigation exposes the deterministic page size')
     const messageRows = tallLines.slice(hintIdx + 1).filter(line => line.trim())
-    ok(messageRows.length > 0 && messageRows[0].includes('⋯'), 'older message tail is visible immediately after the history hint')
+    ok(messageRows.length > 0 && messageRows[0].includes('回答'), 'a real virtualized message row follows navigation without a synthetic peek row')
 
     // ── PageUp: viewport scrolls back over history ────────────────────────────
     stdin.write('\x1b[5~')                                   // PageUp
     await delay(300)
     const upFrame = strip(lastFrame() ?? '')
-    ok(upFrame.includes('PageDown'), 'after PageUp: a PageDown hint appears (scrolled up)')
+    ok(upFrame.includes('↓ 较新内容'), 'after PageUp: navigation reports newer content below')
     ok(!upFrame.includes('回答 24'), 'after PageUp: latest entry paged out of view')
     ok(/回答 \d+/.test(upFrame), 'after PageUp: an older entry is visible')
 
@@ -185,7 +184,7 @@ async function main() {
     stdin.write('\x1b[<64;5;5M')                             // wheel up = scroll back
     await delay(300)
     const wheelUp = strip(lastFrame() ?? '')
-    ok(wheelUp.includes('PageDown'), 'wheel up: a PageDown hint appears (scrolled back)')
+    ok(wheelUp.includes('↓ 较新内容'), 'wheel up: navigation reports newer content below')
     ok(!wheelUp.includes('回答 24'), 'wheel up: latest entry paged out of view')
     ok(/回答 \d+/.test(wheelUp), 'wheel up: an older entry is visible')
 
@@ -199,7 +198,7 @@ async function main() {
     stdin.write('\x1b[M' + String.fromCharCode(96, 50, 50))
     await delay(300)
     const legacyUp = strip(lastFrame() ?? '')
-    ok(legacyUp.includes('PageDown'), 'legacy wheel up: a PageDown hint appears (scrolled back)')
+    ok(legacyUp.includes('↓ 较新内容'), 'legacy wheel up: navigation reports newer content below')
     ok(!legacyUp.includes('回答 24'), 'legacy wheel up: latest entry paged out of view')
 
     stdin.write('\x1b[M' + String.fromCharCode(97, 50, 50))  // wheel down Cb = 0x61
@@ -229,13 +228,15 @@ async function main() {
     await bootToChat(second.stdin, second.lastFrame)
     await populateTranscript(second.stdin, emitEntry)
     const before = strip(second.lastFrame() ?? '')
+    const beforeAnswers = before.match(/回答 \d+/g) ?? []
     ok(before.includes('回答 24'), 'disable-mouse: latest entry visible before wheel')
 
     second.stdin.write('\x1b[<64;5;5M')                    // wheel up — must be ignored
     await delay(300)
     const after = strip(second.lastFrame() ?? '')
+    const afterAnswers = after.match(/回答 \d+/g) ?? []
     ok(after.includes('回答 24'), 'disable-mouse: wheel up leaves latest entry in view')
-    ok(!after.includes('PageDown'), 'disable-mouse: wheel up does NOT scroll (no PageDown hint)')
+    ok(JSON.stringify(afterAnswers) === JSON.stringify(beforeAnswers), 'disable-mouse: wheel up leaves the visible row window unchanged')
   } finally {
     second.unmount()
     delete process.env.MOBIUS_TUI_DISABLE_MOUSE

package/tests/selection.test.tsx

@@ -139,7 +139,7 @@ async function main() {
     const row1 = lines.findIndex(l => l.includes('回答 1'))
     const row3 = lines.findIndex(l => l.includes('回答 3'))
     ok(row1 >= 0 && row3 >= 0, `found 回答 1 (row ${row1}) and 回答 3 (row ${row3}) in the transcript`)
-    ok(!frame.includes('PageDown'), 'all entries fit — no paging hints at rest')
+    ok(frame.includes('全部内容') && !frame.includes('↑ 较早内容') && !frame.includes('↓ 还有较新内容'), 'all entries fit — navigation reports the complete transcript')
 
     // press on 回答 1 (col 4 → first content char), drag to 回答 3 (col beyond EOL)
     stdin.write(`\x1b[<0;5;${row1 + 1}M`)                 // left-button press (SGR 1-based)

package/tests/ui.test.tsx

@@ -22,7 +22,7 @@ import { PrepScreen } from '../src/components/PrepScreen.js'
 import { Select, TextInput } from '../src/components/primitives.js'
 import { MobiusClient } from '../src/api.js'
 import { renderMarkdownLines } from '../src/markdown.js'
-import { viewsForEntry, toolLabel } from '../src/lib/entry-view.js'
+import { dedupeUserEntries, viewsForEntry, toolLabel } from '../src/lib/entry-view.js'
 import { SseConnection } from '../src/sse.js'
 import type { ReadyState } from '../src/components/PrepScreen.js'
 
@@ -263,6 +263,17 @@ function testMarkdownCodeRendering() {
   ok(unlabelled.length === 1 && unlabelled[0].text === 'echo $HOME' && unlabelled[0].code, 'unlabelled code stays plain instead of being guessed as bash')
 }
 
+function testFirstUserEntryDedupe() {
+  console.log('\n[UI 4b] first user message event deduplication')
+  const framed = '上下文注入\n\n## 用户的问题\n\n你好，检查首条消息'
+  const entries = [
+    { type: 'user', uuid: 'framed-user', message: { role: 'user', content: framed } },
+    { type: 'event_msg', uuid: 'plain-user', payload: { type: 'user_message', message: '你好，检查首条消息' } },
+  ]
+  const deduped = dedupeUserEntries(entries as any)
+  ok(deduped.length === 1, 'framed and plain first-turn user events render once')
+}
+
 // ════════════════════════════════════════════════════════════════════════════
 // TEST 5 — Prep screen renders the project picker when cwd is unbound
 // ════════════════════════════════════════════════════════════════════════════
@@ -865,6 +876,7 @@ async function main() {
   await testChat()
   await testResumedWorkingStatus()
   testMarkdownCodeRendering()
+  testFirstUserEntryDedupe()
   await testPrepRender()
   await testSelectViewport()
   await testProjectPickerEscQuit()

package/tests/viewport.test.ts

@@ -0,0 +1,83 @@
+import { performance } from 'node:perf_hooks'
+import { coalesceMouseEvents, parseMouseEvents } from '../src/components/primitives.js'
+import {
+  createRowAccess, moveAnchorByRows, sliceViewport, tailAnchor,
+  type RowAnchor,
+} from '../src/lib/transcript-viewport.js'
+
+interface Entry { id: string; rows: number[] }
+
+let passed = 0
+let failed = 0
+function ok(condition: boolean, message: string): void {
+  if (condition) { passed += 1; console.log(`  ✓ ${message}`) }
+  else { failed += 1; console.error(`  ✗ ${message}`) }
+}
+
+function access(entries: Entry[]) {
+  return createRowAccess(entries, entry => entry.id, entry => entry.rows)
+}
+
+function sameAnchor(actual: RowAnchor | null, entryId: string, rowIndex: number): boolean {
+  return actual?.entryId === entryId && actual.rowIndex === rowIndex
+}
+
+function main(): void {
+  console.log('\n[VIEWPORT] exact row-level transcript navigation\n')
+
+  const long = access([{ id: 'long', rows: Array.from({ length: 1000 }, (_, i) => i) }])
+  const tail = tailAnchor(long, 24)
+  ok(sameAnchor(tail, 'long', 976), '1000-row entry tails at row 976 in a 24-row viewport')
+  const pageUp = moveAnchorByRows(long, tail, -23)
+  ok(sameAnchor(pageUp, 'long', 953), 'PageUp moves exactly 23 rows inside one long entry')
+  ok(sameAnchor(moveAnchorByRows(long, pageUp, 23), 'long', 976), 'PageDown exactly reverses PageUp')
+
+  const mixed = access([
+    { id: 'a', rows: [0, 1] },
+    { id: 'b', rows: Array.from({ length: 50 }, (_, i) => i) },
+    { id: 'c', rows: [0, 1, 2] },
+    { id: 'd', rows: Array.from({ length: 1000 }, (_, i) => i) },
+  ])
+  const crossed = moveAnchorByRows(mixed, { entryId: 'd', entryIndex: 3, rowIndex: 0 }, -4)
+  ok(sameAnchor(crossed, 'b', 49), 'row navigation crosses mixed-height entry boundaries exactly')
+  const mixedUp = moveAnchorByRows(mixed, tailAnchor(mixed, 24), -777)
+  ok(JSON.stringify(moveAnchorByRows(mixed, mixedUp, 777)) === JSON.stringify(tailAnchor(mixed, 24)), 'large mixed-height PageUp/PageDown movement is reversible')
+
+  const startSlice = sliceViewport(long, { entryId: 'long', entryIndex: 0, rowIndex: 0 }, 24)
+  const middleSlice = sliceViewport(long, { entryId: 'long', entryIndex: 0, rowIndex: 500 }, 24)
+  const endSlice = sliceViewport(long, tail, 24)
+  ok(startSlice.rows[0]?.row === 0, 'long entry start is directly accessible')
+  ok(middleSlice.rows[0]?.row === 500, 'long entry middle is directly accessible')
+  ok(endSlice.rows.at(-1)?.row === 999, 'long entry end is directly accessible')
+  ok(startSlice.rows.length === 24 && middleSlice.rows.length === 24 && endSlice.rows.length === 24, 'only viewport-height rows are materialized in each slice')
+
+  const resized = access([{ id: 'long', rows: Array.from({ length: 700 }, (_, i) => i) }])
+  const restored = sliceViewport(resized, { entryId: 'long', entryIndex: 0, rowIndex: 500 }, 10).anchor
+  ok(sameAnchor(restored, 'long', 500), 'resize preserves a historical entry/row anchor')
+  ok(sameAnchor(tailAnchor(resized, 10), 'long', 690), 'tail-follow mode recomputes against the resized layout')
+
+  const appended = access([
+    { id: 'long', rows: Array.from({ length: 1000 }, (_, i) => i) },
+    { id: 'new', rows: [0, 1, 2] },
+  ])
+  const held = sliceViewport(appended, pageUp, 24).anchor
+  ok(sameAnchor(held, 'long', 953), 'new entries do not move a historical anchor')
+  ok(sameAnchor(tailAnchor(appended, 24), 'long', 979), 'tail-follow mode automatically includes newly appended rows')
+
+  const burst = '\x1b[<64;5;5M'.repeat(5)
+  const coalesced = coalesceMouseEvents(parseMouseEvents(burst))
+  ok(coalesced.length === 1 && coalesced[0]?.kind === 'wheel' && coalesced[0].delta === 5, 'five wheel events in one input chunk coalesce into one +5 action')
+  ok(sameAnchor(moveAnchorByRows(long, tail, -3 * (coalesced[0]?.kind === 'wheel' ? coalesced[0].delta : 0)), 'long', 961), 'five wheel notches move exactly 15 rows')
+
+  const thousand = access(Array.from({ length: 1000 }, (_, i) => ({ id: `e-${i}`, rows: [i] })))
+  for (let i = 0; i < 100; i++) sliceViewport(thousand, moveAnchorByRows(thousand, tailAnchor(thousand, 24), -i), 24)
+  const started = performance.now()
+  for (let i = 0; i < 1000; i++) sliceViewport(thousand, moveAnchorByRows(thousand, tailAnchor(thousand, 24), -(i % 900)), 24)
+  const averageMs = (performance.now() - started) / 1000
+  ok(averageMs < 5, `1000-entry viewport navigation averages under 5ms (${averageMs.toFixed(3)}ms)`)
+
+  console.log(`\n==== VIEWPORT RESULT: ${passed} passed, ${failed} failed ====\n`)
+  process.exit(failed === 0 ? 0 : 1)
+}
+
+main()