dsh-code 0.3.0 → 0.5.0

package/src/internals.ts

@@ -11,6 +11,8 @@ import type { ReactElement } from 'react'
 
 /** A mounted terminal app instance; the runner owns unmount ordering. */
 export interface TuiMount {
+  /** Replace the root element while preserving Ink's single terminal owner. */
+  rerender(element: ReactElement): void
   /** Tear the terminal app down before flush and exit. */
   unmount(): void
 }
@@ -28,6 +30,9 @@ export const internals: {
   mount: (element: ReactElement): TuiMount => {
     const instance = render(element)
     return {
+      rerender(element: ReactElement): void {
+        instance.rerender(element)
+      },
       unmount(): void {
         instance.unmount()
       },

package/src/kernel-panels.ts

@@ -0,0 +1,254 @@
+/** Bounded, composer-safe panels for preset, session, and plugin kernel views. */
+
+import { createElement, useEffect, useMemo, useRef, useState, type ReactElement } from 'react'
+import { Box, Text, useInput, useStdout } from 'ink'
+import type { PresetRow } from './presets.ts'
+import type { PluginRow } from './plugin-inventory.ts'
+import type { SessionDirectoryOptions, SessionRow } from './session-directory.ts'
+import { panelViewport, revealRow } from './render/inspector.ts'
+import { textLines } from './render/lines.ts'
+import { singleLineText, truncateColumns } from './render/text.ts'
+import { TUI_RGB } from './theme.ts'
+
+function color(rgb: readonly [number, number, number]): string {
+  return `rgb(${rgb[0]}, ${rgb[1]}, ${rgb[2]})`
+}
+
+interface ListFrameProps {
+  readonly title: string
+  readonly rows: readonly { readonly key: string; readonly text: string; readonly disabled?: boolean }[]
+  readonly cursor: number
+  readonly loading: boolean
+  readonly error?: string
+  readonly query: string
+  readonly footer: string
+}
+
+function ListFrame(props: ListFrameProps): ReactElement {
+  const stdout = useStdout().stdout
+  const viewport = panelViewport(stdout?.columns ?? 80, stdout?.rows ?? 30)
+  if (viewport.maxHeight === 0) return createElement(Box, { display: 'none' })
+  if (viewport.compact) {
+    return createElement(Text, { wrap: 'truncate-end' }, truncateColumns(`${props.title} · esc close`, viewport.contentColumns))
+  }
+  const stateRows = props.loading
+    ? [{ key: 'loading', text: '  loading…' }]
+    : props.error !== undefined
+      ? [{ key: 'error', text: `  ${singleLineText(props.error)}` }]
+      : props.rows.length === 0
+        ? [{ key: 'empty', text: '  no matching entries' }]
+        : props.rows
+  const bodyRows = Math.max(1, viewport.bodyRows - 1)
+  const offset = revealRow(0, props.cursor, stateRows.length, bodyRows)
+  const visible = stateRows.slice(offset, offset + bodyRows)
+  return createElement(
+    Box,
+    { borderStyle: 'round', borderColor: color(TUI_RGB.dim), flexDirection: 'column', paddingX: 1 },
+    createElement(Text, { color: color(TUI_RGB.brandBright), wrap: 'truncate-end' }, truncateColumns(props.title, viewport.contentColumns)),
+    createElement(Text, { dimColor: true, wrap: 'truncate-end' }, truncateColumns(`search: ${props.query === '' ? 'type to filter' : props.query}`, viewport.contentColumns)),
+    ...visible.map((row, index) => {
+      const absolute = offset + index
+      const selected = !props.loading && props.error === undefined && props.rows.length > 0 && absolute === props.cursor
+      return createElement(Text, {
+        key: row.key,
+        color: selected ? color(TUI_RGB.brandBright) : row.disabled ? color(TUI_RGB.dim) : undefined,
+        dimColor: row.disabled,
+        wrap: 'truncate-end',
+      }, truncateColumns(`${selected ? '› ' : '  '}${row.text}`, viewport.contentColumns))
+    }),
+    createElement(Text, { dimColor: true, wrap: 'truncate-end' }, truncateColumns(props.footer, viewport.contentColumns)),
+  )
+}
+
+function editQuery(query: string, input: string, key: { backspace?: boolean; delete?: boolean }): string | undefined {
+  if (key.backspace || key.delete) return query.slice(0, -1)
+  if (input.length === 1 && input >= ' ' && input !== '\x7f') return query + input
+  return undefined
+}
+
+export function ModePanel({ current, load, select, close }: {
+  current: string
+  load(): Promise<readonly PresetRow[]>
+  select(id: string): void
+  close(): void
+}): ReactElement {
+  const [rows, setRows] = useState<readonly PresetRow[]>([])
+  const [query, setQuery] = useState('')
+  const [cursor, setCursor] = useState(0)
+  const [loading, setLoading] = useState(true)
+  const [error, setError] = useState<string>()
+  const refresh = (): void => {
+    setLoading(true); setError(undefined)
+    Promise.resolve().then(load).then(value => { setRows(value); setLoading(false) }, reason => {
+      setError(reason instanceof Error ? reason.message : String(reason)); setLoading(false)
+    })
+  }
+  useEffect(refresh, [])
+  const visible = useMemo(() => rows.filter(row => `${row.id} ${row.name ?? ''} ${row.description ?? ''}`.toLowerCase().includes(query.toLowerCase())), [rows, query])
+  useEffect(() => setCursor(value => Math.min(value, Math.max(0, visible.length - 1))), [visible.length])
+  useInput((input, key) => {
+    if (key.escape || input === 'q') return close()
+    if (input === 'r' && query === '') return refresh()
+    if (key.upArrow) return setCursor(value => visible.length === 0 ? 0 : (value + visible.length - 1) % visible.length)
+    if (key.downArrow) return setCursor(value => visible.length === 0 ? 0 : (value + 1) % visible.length)
+    if (key.return && visible[cursor]?.broken === undefined) return select(visible[cursor]!.id)
+    const next = editQuery(query, input, key)
+    if (next !== undefined) { setQuery(next); setCursor(0) }
+  })
+  return createElement(ListFrame, {
+    title: `/mode · current ${current}`,
+    rows: visible.map(row => ({ key: row.id, disabled: row.broken !== undefined, text: `${row.id === current ? '●' : '○'} ${row.name ?? row.id} · ${row.description ?? row.trust}${row.broken === undefined ? '' : ` · broken: ${row.broken}`}` })),
+    cursor, loading, error, query, footer: '↑↓ choose · enter switch · r refresh · esc close',
+  })
+}
+
+export function PluginPanel({ load, close, initialQuery = '' }: { load(): readonly PluginRow[]; close(): void; initialQuery?: string }): ReactElement {
+  const [epoch, setEpoch] = useState(0)
+  const [query, setQuery] = useState(initialQuery)
+  const [cursor, setCursor] = useState(0)
+  const [expanded, setExpanded] = useState(false)
+  const rows = useMemo(() => load().filter(row => `${row.entryId} ${row.moduleName} ${row.phase ?? ''}`.toLowerCase().includes(query.toLowerCase())), [epoch, query])
+  useEffect(() => setCursor(value => Math.min(value, Math.max(0, rows.length - 1))), [rows.length])
+  useInput((input, key) => {
+    if (key.escape || input === 'q') return close()
+    if (input === 'r' && query === '') return setEpoch(value => value + 1)
+    if (key.upArrow) return setCursor(value => rows.length === 0 ? 0 : (value + rows.length - 1) % rows.length)
+    if (key.downArrow) return setCursor(value => rows.length === 0 ? 0 : (value + 1) % rows.length)
+    if (key.return) return setExpanded(value => !value)
+    const next = editQuery(query, input, key)
+    if (next !== undefined) { setQuery(next); setCursor(0) }
+  })
+  return createElement(ListFrame, {
+    title: '/plugin · loader inspector',
+    rows: rows.map((row, index) => ({
+      key: row.entryId,
+      disabled: !row.enabled,
+      text: `${row.enabled ? '●' : '○'} ${row.entryId} · ${row.phase ?? 'not mounted'}${expanded && index === cursor ? ` · ${row.moduleName}` : ''}`,
+    })), cursor, loading: false, query, footer: '↑↓ inspect · enter details · r refresh · esc close',
+  })
+}
+
+export function ResumePanel({ currentCwd, load, readTranscript, select, close }: {
+  currentCwd: string
+  load(options: SessionDirectoryOptions, signal?: AbortSignal): Promise<readonly SessionRow[]>
+  readTranscript(id: string, signal?: AbortSignal): Promise<string>
+  select(row: SessionRow): void
+  close(): void
+}): ReactElement {
+  const [options, setOptions] = useState<SessionDirectoryOptions>({ sessions: 'roots', cwd: 'all', sort: 'newest', currentCwd, query: '' })
+  const [focus, setFocus] = useState(0)
+  const [density, setDensity] = useState<'comfortable' | 'dense'>('comfortable')
+  const [rows, setRows] = useState<readonly SessionRow[]>([])
+  const [cursor, setCursor] = useState(0)
+  const [loading, setLoading] = useState(true)
+  const [error, setError] = useState<string>()
+  const [expanded, setExpanded] = useState<string>()
+  const [transcript, setTranscript] = useState<{ id: string; text?: string; error?: string }>()
+  const transcriptLoad = useRef<AbortController>()
+  useEffect(() => () => transcriptLoad.current?.abort(), [])
+  useEffect(() => {
+    const controller = new AbortController()
+    setLoading(true); setError(undefined)
+    Promise.resolve().then(() => load(options, controller.signal)).then(value => {
+      if (!controller.signal.aborted) { setRows(value); setLoading(false) }
+    }, reason => {
+      if (!controller.signal.aborted) { setError(reason instanceof Error ? reason.message : String(reason)); setLoading(false) }
+    })
+    return () => controller.abort()
+  }, [options])
+  useEffect(() => setCursor(value => Math.min(value, Math.max(0, rows.length - 1))), [rows.length])
+  const cycle = (): void => {
+    if (focus === 3) {
+      setDensity(current => current === 'comfortable' ? 'dense' : 'comfortable')
+      return
+    }
+    setOptions(value => {
+      if (focus === 0) return { ...value, sessions: value.sessions === 'roots' ? 'all' : 'roots' }
+      if (focus === 1) return { ...value, cwd: value.cwd === 'all' ? 'current' : 'all' }
+      return { ...value, sort: value.sort === 'newest' ? 'oldest' : 'newest' }
+    })
+  }
+  useInput((input, key) => {
+    if (key.escape || input === 'q') return close()
+    if (key.tab) return setFocus(value => (value + (key.shift ? 3 : 1)) % 4)
+    if (key.leftArrow) return cycle()
+    if (key.rightArrow) return cycle()
+    if (key.upArrow) return setCursor(value => rows.length === 0 ? 0 : Math.max(0, value - 1))
+    if (key.downArrow) return setCursor(value => rows.length === 0 ? 0 : Math.min(rows.length - 1, value + 1))
+    if (key.pageUp) return setCursor(value => Math.max(0, value - 8))
+    if (key.pageDown) return setCursor(value => Math.min(rows.length - 1, value + 8))
+    if (input === 'g') return setCursor(0)
+    if (input === 'G') return setCursor(Math.max(0, rows.length - 1))
+    if (input === 'd') return setDensity(value => value === 'comfortable' ? 'dense' : 'comfortable')
+    if (input === 'e' && rows[cursor] !== undefined) {
+      return setExpanded(value => value === rows[cursor]!.id ? undefined : rows[cursor]!.id)
+    }
+    if (input === 't' && rows[cursor] !== undefined) {
+      const row = rows[cursor]!
+      transcriptLoad.current?.abort()
+      setTranscript({ id: row.id })
+      const controller = new AbortController()
+      transcriptLoad.current = controller
+      Promise.resolve().then(() => readTranscript(row.id, controller.signal)).then(
+        text => { if (!controller.signal.aborted) setTranscript({ id: row.id, text }) },
+        reason => { if (!controller.signal.aborted) setTranscript({ id: row.id, error: reason instanceof Error ? reason.message : String(reason) }) },
+      )
+      return
+    }
+    if (key.return && rows[cursor]?.resumable === true) return select(rows[cursor]!)
+    const next = editQuery(options.query, input, key)
+    if (next !== undefined) { setOptions(value => ({ ...value, query: next })); setCursor(0) }
+  }, { isActive: transcript === undefined })
+  if (transcript !== undefined) {
+    return createElement(DocumentPanel, {
+      title: `transcript · ${transcript.id}`,
+      text: transcript.text,
+      error: transcript.error,
+      close: () => { transcriptLoad.current?.abort(); setTranscript(undefined) },
+    })
+  }
+  const toolbar = `[${focus === 0 ? '>' : ''}${options.sessions}] [${focus === 1 ? '>' : ''}${options.cwd} cwd] [${focus === 2 ? '>' : ''}${options.sort}] [${focus === 3 ? '>' : ''}${density}]`
+  return createElement(ListFrame, {
+    title: `/resume · ${toolbar}`,
+    rows: rows.map(row => ({
+      key: row.id,
+      disabled: !row.resumable,
+      text: `${row.subagent ? '↳' : '○'} ${row.title ?? row.id.slice(-12)}${density === 'comfortable' ? ` · ${row.workspace} · ${row.preset}` : ''}${row.live ? ' · live' : ''}${expanded === row.id ? ` · ${row.id} · ${row.cwd}${row.parent === undefined ? '' : ` · parent ${row.parent}`}` : ''}`,
+    })), cursor, loading, error, query: options.query,
+    footer: 'type search · tab/←→ filters · ↑↓/pg navigate · e details · t transcript · enter resume',
+  })
+}
+
+function DocumentPanel({ title, text, error, close }: {
+  title: string
+  text?: string
+  error?: string
+  close(): void
+}): ReactElement {
+  const stdout = useStdout().stdout
+  const viewport = panelViewport(stdout?.columns ?? 80, stdout?.rows ?? 30)
+  const [scroll, setScroll] = useState(0)
+  const lines = useMemo(() => text === undefined ? [] : textLines(text, viewport.contentColumns).map(line => line.segments.map(segment => segment.text).join('')), [text, viewport.contentColumns])
+  useInput((input, key) => {
+    if (key.escape || input === 'q' || input === 't') return close()
+    if (key.upArrow) return setScroll(value => Math.max(0, value - 1))
+    if (key.downArrow) return setScroll(value => Math.min(Math.max(0, lines.length - viewport.bodyRows), value + 1))
+    if (key.pageUp) return setScroll(value => Math.max(0, value - Math.max(1, viewport.bodyRows - 1)))
+    if (key.pageDown) return setScroll(value => Math.min(Math.max(0, lines.length - viewport.bodyRows), value + Math.max(1, viewport.bodyRows - 1)))
+    if (input === 'g') return setScroll(0)
+    if (input === 'G') return setScroll(Math.max(0, lines.length - viewport.bodyRows))
+  })
+  if (viewport.compact) return createElement(Text, { wrap: 'truncate-end' }, truncateColumns('transcript · esc close', viewport.contentColumns))
+  const body = error !== undefined
+    ? [`error: ${singleLineText(error)}`]
+    : text === undefined
+      ? ['loading transcript…']
+      : lines.slice(scroll, scroll + viewport.bodyRows)
+  return createElement(
+    Box,
+    { borderStyle: 'round', borderColor: color(TUI_RGB.dim), flexDirection: 'column', paddingX: 1 },
+    createElement(Text, { color: color(TUI_RGB.brandBright), wrap: 'truncate-end' }, truncateColumns(title, viewport.contentColumns)),
+    ...body.map((line, index) => createElement(Text, { key: `${scroll}-${index}`, wrap: 'truncate-end' }, truncateColumns(line, viewport.contentColumns))),
+    createElement(Text, { dimColor: true, wrap: 'truncate-end' }, truncateColumns(`lines ${lines.length === 0 ? 0 : scroll + 1}-${Math.min(lines.length, scroll + viewport.bodyRows)}/${lines.length} · ↑↓/pg/g/G · t/esc close`, viewport.contentColumns)),
+  )
+}

package/src/plugin-inventory.ts

@@ -0,0 +1,47 @@
+/** Read-only projection of Cordis Loader entries for /plugin. */
+
+import type { Context, FiberState } from '@deepseek-ai/cordis'
+
+export type PluginPhase = 'pending' | 'loading' | 'active' | 'failed' | 'unloading' | null
+
+export interface PluginRow {
+  readonly entryId: string
+  readonly moduleName: string
+  readonly enabled: boolean
+  readonly phase: PluginPhase
+}
+
+const PHASES: Record<number, PluginPhase> = {
+  0: 'pending',
+  1: 'loading',
+  2: 'active',
+  3: 'failed',
+  4: null,
+  5: 'unloading',
+}
+
+interface LoaderEntry {
+  readonly id: string
+  readonly disabled: boolean
+  readonly options: { readonly group?: boolean; readonly name: string }
+  readonly fiber?: { readonly state: FiberState }
+}
+
+/** Snapshot the live Loader; group-only rows are composition containers, not plugins. */
+export function listPluginRows(ctx: Context): PluginRow[] {
+  const loader = (ctx as unknown as { get(name: string): unknown }).get('loader') as
+    | { entries(): Iterable<LoaderEntry> }
+    | undefined
+  if (loader === undefined) return []
+  const rows: PluginRow[] = []
+  for (const entry of loader.entries()) {
+    if (entry.options.group === true) continue
+    rows.push({
+      entryId: entry.id,
+      moduleName: entry.options.name,
+      enabled: !entry.disabled,
+      phase: entry.fiber === undefined ? null : PHASES[entry.fiber.state] ?? null,
+    })
+  }
+  return rows
+}

package/src/presets.ts

@@ -0,0 +1,64 @@
+/** Agent-preset policy kept independent from the Ink surface. */
+
+import type { Context } from '@deepseek-ai/cordis'
+import type { Agent, AgentHandle } from '@deepseek-ai/dsh-agent'
+import type { Session, SessionEvent } from '@deepseek-ai/dsh-session'
+
+/** One discoverable agent composition. */
+export interface PresetRow {
+  readonly id: string
+  readonly trust: 'system' | 'user'
+  readonly name?: string
+  readonly description?: string
+  readonly order?: number
+  readonly broken?: string
+}
+
+/** Structural boundary for the optional upstream AgentPresets service. */
+export interface AgentPresetsService {
+  readonly defaultId: string
+  list(): Promise<PresetRow[]>
+  resolve(id?: string): Promise<PresetRow>
+  mount(agentCtx: Context, id?: string): Promise<PresetRow>
+  recompose(agentCtx: Context, id: string): Promise<PresetRow>
+  composedPreset(agentCtx: Context): string | undefined
+}
+
+/** Read an optional Cordis service without requiring its package at build time. */
+export function agentPresetsFrom(ctx: Context): AgentPresetsService | undefined {
+  return (ctx as unknown as { get(name: string): unknown }).get('agentPresets') as AgentPresetsService | undefined
+}
+
+/** A preset may change only before the first durable turn begins. */
+export function isBlankSession(events: readonly SessionEvent[]): boolean {
+  return !events.some(event => event.type === 'turn/start')
+}
+
+/** Latest logged selection wins; legacy sessions deliberately fall back to standard. */
+export function resolvePreset(session: Pick<Session, 'header' | 'events'>): string {
+  for (let index = session.events.length - 1; index >= 0; index -= 1) {
+    const event = session.events[index] as unknown as { type: string; data?: { agentPreset?: string } }
+    if (event.type === 'agent-preset/selected' && event.data?.agentPreset !== undefined) {
+      return event.data.agentPreset
+    }
+  }
+  return session.header.agentPreset ?? 'standard'
+}
+
+/** Recompose atomically from the caller's perspective, logging only success. */
+export async function switchPreset(
+  service: AgentPresetsService,
+  agent: Agent,
+  presetId: string,
+): Promise<PresetRow> {
+  if (!isBlankSession(agent.session.events)) {
+    throw new Error('mode is locked after the first turn; use /new <mode>')
+  }
+  const preset = await service.recompose(agent.ctx, presetId)
+  const writable = agent.session as unknown as { append(type: string, data: unknown): void }
+  writable.append('agent-preset/selected', { agentPreset: preset.id })
+  return preset
+}
+
+/** Minimal handle shape used by lifecycle tests without exposing Agent internals. */
+export type OwnedAgent = Pick<AgentHandle, 'agent' | 'dispose'>

package/src/render/export.ts

@@ -0,0 +1,81 @@
+/**
+ * Markdown export of one transcript view: the /export command's pure
+ * formatter. Deterministic and side-effect free — the runner owns the file
+ * write, so tests drive the builder with folded views directly.
+ *
+ * @module @deepseek-ai/dsh-code/render/export
+ */
+
+import { assertNever } from '@deepseek-ai/dsh-llm'
+import type { TranscriptView } from './projection.ts'
+
+/**
+ * Render the transcript as a standalone markdown document.
+ * @param view - the folded transcript view to export.
+ * @param sessionId - the full session identity for the header.
+ * @returns the complete markdown text.
+ */
+export function buildExportMarkdown(view: TranscriptView, sessionId: string): string {
+  const out: string[] = [
+    view.title === ''
+      ? `# dsh session ${sessionId}`
+      : `# ${view.title}`,
+    `> session ${sessionId}`,
+    '',
+  ]
+  for (const entry of view.entries) {
+    switch (entry.kind) {
+      case 'user':
+        if (entry.notice) {
+          out.push(`> ⤷ context: ${entry.text}`, '')
+        } else {
+          out.push('## user', '', entry.text, '')
+        }
+        break
+      case 'assistant':
+        if (entry.reasoning !== '') {
+          out.push('<details><summary>thinking</summary>', '', entry.reasoning, '', '</details>', '')
+        }
+        out.push('## assistant', '', entry.text, '')
+        break
+      case 'tool':
+        out.push(`### tool \`${entry.name}\``, '')
+        if (entry.preview !== '') out.push(`- args: ${entry.preview}`)
+        if (entry.summary !== '') out.push(`- ${entry.state === 'error' ? 'error' : 'result'}: ${entry.summary}`)
+        out.push('')
+        break
+      case 'command':
+        out.push(`### /${entry.name}${entry.args === '' ? '' : ` ${entry.args}`}`, '')
+        if (entry.summary !== '') out.push(`- ${entry.state === 'error' ? 'error' : 'result'}: ${entry.summary}`)
+        out.push('')
+        break
+      case 'error':
+        out.push(`> ⨯ ${entry.text}`, '')
+        break
+      case 'turn-marker':
+        out.push(`> ${entry.text}`, '')
+        break
+      case 'compaction':
+        out.push(entry.ok
+          ? `> compacted ~${entry.tokens} tokens`
+          : `> compaction failed: ${entry.error}`, '')
+        break
+      case 'retry':
+        out.push(`> retry ${entry.attempt}/${entry.max} (${entry.code})`, '')
+        break
+      case 'files':
+        out.push(`> files changed: ${entry.paths.join(', ')}`, '')
+        break
+      default:
+        assertNever(entry, 'transcript entry kind')
+    }
+  }
+  if (view.streaming !== '') out.push('## assistant (streaming)', '', view.streaming, '')
+  const { stats } = view
+  out.push('---', '')
+  out.push(`- model: ${view.model === '' ? '(none yet)' : view.model}`)
+  out.push(`- turns: ${stats.turns} · steps: ${stats.steps}`)
+  out.push(`- tokens: ↑${stats.usage.inputTokens} ↓${stats.usage.outputTokens} · cache read ${stats.usage.cacheReadTokens}`)
+  out.push(`- todos: ${view.todos.length}`)
+  return out.join('\n')
+}

package/src/render/inspector.ts

@@ -0,0 +1,88 @@
+/** Pure viewport, selection, and scrolling rules for exclusive TUI panels. */
+
+/** Terminal-space allocation for the inspector's one dynamic screen. */
+export interface InspectorViewport {
+  /** Maximum dynamic rows, kept strictly below the terminal height. */
+  maxHeight: number
+  /** Rows available to the selected entry after border, title, and footer. */
+  bodyRows: number
+  /** Optional blank rows separating title/body/footer on roomy terminals. */
+  gapRows: 0 | 2
+  /** Columns available inside the horizontal border and padding. */
+  contentColumns: number
+  /** Tiny terminals use a borderless one-line close hint. */
+  compact: boolean
+}
+
+/** Composer/status chrome plus one optional, fixed-height local notice row. */
+const INSPECTOR_CHROME_ROWS = 5
+
+/** One transcript-to-composer gutter, collapsed on short terminals. */
+export function layoutGutterRows(rows: number): 0 | 1 {
+  return Math.max(1, Math.floor(rows)) >= 14 ? 1 : 0
+}
+
+/**
+ * Keep the inspector plus its persistent status/composer chrome below
+ * `stdout.rows`: at equality Ink clears the terminal and rewrites all
+ * accumulated `<Static>` output on every frame.
+ */
+export function panelViewport(columns: number, rows: number): InspectorViewport {
+  const safeColumns = Math.max(1, Math.floor(columns))
+  const safeRows = Math.max(1, Math.floor(rows))
+  // Two spare rows cover Ink's first-frame transition from existing Static
+  // scrollback into a tall dynamic panel. A one-row margin is insufficient:
+  // the transition can still take the full-terminal rewrite path at rows - 1.
+  const maxHeight = Math.max(0, Math.min(
+    safeRows - 2 - INSPECTOR_CHROME_ROWS - layoutGutterRows(safeRows),
+    Math.floor(safeRows / 2),
+  ))
+  const compact = maxHeight < 5 || safeColumns < 8
+  const gapRows = !compact && maxHeight >= 7 ? 2 : 0
+  return {
+    maxHeight,
+    bodyRows: compact ? 0 : maxHeight - 4 - gapRows,
+    gapRows,
+    contentColumns: compact ? Math.max(1, safeColumns - 1) : Math.max(1, safeColumns - 4),
+    compact,
+  }
+}
+
+/** Backward-compatible name for the Ctrl+O-specific caller and tests. */
+export function inspectorViewport(columns: number, rows: number): InspectorViewport {
+  return panelViewport(columns, rows)
+}
+
+/** Clamp a first-visible row to the range representable by one viewport. */
+export function clampScroll(offset: number, totalRows: number, visibleRows: number): number {
+  const total = Math.max(0, Math.floor(totalRows))
+  const size = Math.max(0, Math.floor(visibleRows))
+  const last = Math.max(0, total - size)
+  return Math.max(0, Math.min(Math.floor(offset), last))
+}
+
+/** Move a viewport by a signed row delta without escaping its content. */
+export function moveScroll(offset: number, delta: number, totalRows: number, visibleRows: number): number {
+  return clampScroll(offset + delta, totalRows, visibleRows)
+}
+
+/** Keep one focused row visible while preserving the current window when possible. */
+export function revealRow(offset: number, row: number, totalRows: number, visibleRows: number): number {
+  const size = Math.max(1, Math.floor(visibleRows))
+  const target = Math.max(0, Math.min(Math.floor(row), Math.max(0, totalRows - 1)))
+  if (target < offset) return clampScroll(target, totalRows, size)
+  if (target >= offset + size) return clampScroll(target - size + 1, totalRows, size)
+  return clampScroll(offset, totalRows, size)
+}
+
+/** Center a selected list row where possible, clamped at both ends. */
+export function selectionWindow(cursor: number, totalRows: number, visibleRows: number): number {
+  return clampScroll(cursor - Math.floor(Math.max(1, visibleRows) / 2), totalRows, visibleRows)
+}
+
+/** Follow appended history only while the inspector cursor was at the tail. */
+export function followInspectorCursor(cursor: number, previousLength: number, nextLength: number): number {
+  const nextLast = Math.max(0, nextLength - 1)
+  if (cursor >= Math.max(0, previousLength - 1)) return nextLast
+  return Math.min(cursor, nextLast)
+}