@xp266/dshtui 0.1.0

package/src/ui/panels/question-model.ts

@@ -0,0 +1,424 @@
+import { inputLayout, moveCaretLine } from '../../core/composer-layout.ts'
+import { INPUT_WIDTH_OFFSET } from '../../core/metrics.ts'
+import { textWidth, wrapLines } from '../../core/text.ts'
+import { editInsert, editBackspace } from '../../core/edit.ts'
+import { caretNonceBold, caretNonceColor, caretNonceText } from '../../core/caret-nonce.ts'
+import type { EditState } from '../../core/edit.ts'
+import { mergeRuns } from '../../core/segments.ts'
+import type { MarkStyle, Segment } from '../../core/segments.ts'
+import { COLORS } from '../../theme.ts'
+import { glyphs } from '../../terminal/glyphs.ts'
+import { panelLegend } from './surface.tsx'
+import { answerSummary } from '../../chat/question-view.ts'
+import type { AskQuestionItemLike, AskUserQuestionAnswerItemLike, AskUserQuestionRequestLike } from '../../chat/interactions.ts'
+
+const questionStyle = (): MarkStyle => ({ color: COLORS.panelQuestionText, bold: true })
+const focusedLabelStyle = (): MarkStyle => ({ color: COLORS.workspaceWriteText })
+const descriptionStyle = (): MarkStyle => ({ color: COLORS.toolBodyText })
+const checkStyle = (): MarkStyle => ({ color: COLORS.success })
+const unansweredStyle = (): MarkStyle => ({ color: COLORS.errorText })
+
+function seg(text: string, style?: MarkStyle): Segment {
+  return { text, style: style ?? {} }
+}
+
+function lineOf(parts: Array<string | Segment>): Segment[] {
+  return mergeRuns(parts.map(part => typeof part === 'string' ? seg(part) : part))
+}
+
+function pushWrapped(target: Segment[][], text: string, indent: number, width: number, style?: MarkStyle): void {
+  const lines = wrapLines(text, Math.max(4, width - indent))
+  target.push(lineOf([' '.repeat(indent), seg(lines[0]!, style)]))
+  for (const line of lines.slice(1)) {
+    target.push(lineOf([' '.repeat(indent), seg(line, style)]))
+  }
+}
+
+export const NUMBER_COL = 2
+export const SINGLE_LABEL_COL = 5
+export const MULTI_LABEL_COL = 9
+export const MAX_FIELD_ROWS = 3
+export const MAX_BODY_ROWS = 14
+export const MAX_DETAIL_ROWS = 7
+
+export interface QuestionDraft {
+  selected: string[]
+  customText: string
+  customChecked: boolean
+}
+
+export interface QuestionPageState {
+  request: AskUserQuestionRequestLike
+  drafts: QuestionDraft[]
+  page: number
+  cursors: number[]
+  editing: boolean
+  editor: EditState
+  detailScroll: number[]
+}
+
+export function initialPageState(request: AskUserQuestionRequestLike): QuestionPageState {
+  return {
+    request,
+    drafts: request.questions.map(() => ({ selected: [], customText: '', customChecked: false })),
+    page: 0,
+    cursors: request.questions.map(() => 0),
+    editing: false,
+    editor: { value: '', cursor: 0 },
+    detailScroll: request.questions.map(() => 0),
+  }
+}
+
+export function scrollDetail(state: QuestionPageState, delta: number): QuestionPageState {
+  if (state.editing) return state
+  const next = Math.max(0, state.detailScroll[state.page]! + delta)
+  if (next === state.detailScroll[state.page]) return state
+  return {
+    ...state,
+    detailScroll: state.detailScroll.map((value, index) => index === state.page ? next : value),
+  }
+}
+
+export function interactiveRowCount(question: AskQuestionItemLike): number {
+  return (question.options?.length ?? 0) + 1
+}
+
+function labelCol(question: AskQuestionItemLike): number {
+  return question.multiSelect === true ? MULTI_LABEL_COL : SINGLE_LABEL_COL
+}
+
+function isCustomRow(question: AskQuestionItemLike, row: number): boolean {
+  return row >= (question.options?.length ?? 0)
+}
+
+export function beginEdit(state: QuestionPageState): QuestionPageState {
+  const draft = state.drafts[state.page]!
+  return {
+    ...state,
+    editing: true,
+    editor: { value: draft.customText, cursor: draft.customText.length },
+  }
+}
+
+export function commitEdit(state: QuestionPageState): QuestionPageState {
+  const question = state.request.questions[state.page]
+  if (question === undefined || !state.editing) return state
+  const text = state.editor.value.trim()
+  return {
+    ...state,
+    editing: false,
+    editor: { value: '', cursor: 0 },
+    drafts: state.drafts.map((draft, index) => index === state.page
+      ? {
+          ...draft,
+          customText: state.editor.value,
+          customChecked: text !== '',
+          ...(question.multiSelect !== true && text !== '' ? { selected: [] } : {}),
+        }
+      : draft),
+  }
+}
+
+export function cancelEdit(state: QuestionPageState): QuestionPageState {
+  return { ...state, editing: false, editor: { value: '', cursor: 0 } }
+}
+
+export function toggleCustomChecked(state: QuestionPageState): QuestionPageState {
+  return {
+    ...state,
+    drafts: state.drafts.map((draft, index) => index === state.page
+      ? { ...draft, customChecked: !draft.customChecked }
+      : draft),
+  }
+}
+
+export function toggleOption(state: QuestionPageState): QuestionPageState {
+  const question = state.request.questions[state.page]
+  if (question === undefined) return state
+  const row = state.cursors[state.page]!
+  if (isCustomRow(question, row)) return toggleCustomChecked(state)
+  const option = question.options![row]!
+  if (question.multiSelect === true) {
+    return {
+      ...state,
+      drafts: state.drafts.map((draft, index) => index === state.page
+        ? {
+            ...draft,
+            selected: draft.selected.includes(option.label)
+              ? draft.selected.filter(label => label !== option.label)
+              : [...draft.selected, option.label],
+          }
+        : draft),
+    }
+  }
+  return {
+    ...state,
+    drafts: state.drafts.map((draft, index) => index === state.page
+      ? { ...draft, selected: [option.label], customChecked: false }
+      : draft),
+  }
+}
+
+export function enterOnRow(state: QuestionPageState): QuestionPageState {
+  const question = state.request.questions[state.page]
+  if (question === undefined || state.editing) return commitEdit(state)
+  const draft = state.drafts[state.page]!
+  const row = state.cursors[state.page]!
+  if (!isCustomRow(question, row)) return toggleOption(state)
+  if (draft.customChecked) return toggleCustomChecked(state)
+  return beginEdit(state)
+}
+
+export function moveCursor(state: QuestionPageState, delta: -1 | 1): QuestionPageState {
+  const question = state.request.questions[state.page]
+  if (question === undefined || state.editing) return state
+  const count = interactiveRowCount(question)
+  if (count === 0) return state
+  const next = ((state.cursors[state.page]! + delta) % count + count) % count
+  return {
+    ...state,
+    cursors: state.cursors.map((value, index) => index === state.page ? next : value),
+  }
+}
+
+export function switchPage(state: QuestionPageState, delta: -1 | 1): QuestionPageState {
+  if (state.editing) return state
+  const total = state.request.questions.length + 1
+  return { ...state, page: Math.max(0, Math.min(total - 1, state.page + delta)) }
+}
+
+export function editorInsert(state: QuestionPageState, text: string): QuestionPageState {
+  if (!state.editing || text === '') return state
+  return { ...state, editor: editInsert(state.editor, text) }
+}
+
+export function editorBackspace(state: QuestionPageState): QuestionPageState {
+  if (!state.editing) return state
+  const next = editBackspace(state.editor)
+  return next === null ? state : { ...state, editor: next }
+}
+
+export function fieldWidthOf(question: AskQuestionItemLike, innerWidth: number): number {
+  return Math.max(8, innerWidth - labelCol(question))
+}
+
+export function editorCaret(state: QuestionPageState, deltaCol: number, deltaLine: number, fieldWidth: number): QuestionPageState {
+  if (!state.editing) return state
+  const value = state.editor.value
+  let cursor = state.editor.cursor
+  if (deltaCol !== 0) cursor = Math.max(0, Math.min(value.length, cursor + deltaCol))
+  if (deltaLine !== 0) cursor = moveCaretLine(value, cursor, fieldWidth, deltaLine === 1 ? 1 : -1)
+  return { ...state, editor: { value, cursor } }
+}
+
+export function buildAnswers(state: QuestionPageState): AskUserQuestionAnswerItemLike[] {
+  return state.request.questions.map((question, index) => {
+    const draft = state.drafts[index]!
+    const labels = (question.options ?? []).filter(option => draft.selected.includes(option.label)).map(option => option.label)
+    const custom = draft.customText.trim()
+    if (draft.customChecked && custom !== '') {
+      if (question.multiSelect === true) {
+        return { id: question.id, selected: labels, ...(custom === '' ? {} : { custom }) }
+      }
+      return { id: question.id, selected: [], custom }
+    }
+    return { id: question.id, selected: labels }
+  })
+}
+
+export function reviewAnswerOf(question: AskQuestionItemLike, draft: QuestionDraft): string {
+  const labels = (question.options ?? []).filter(option => draft.selected.includes(option.label)).map(option => option.label)
+  const custom = draft.customText.trim()
+  return answerSummary(question, labels, custom, draft.customChecked)
+}
+
+export interface PanelHitRow {
+  line: number
+  optionIndex: number
+}
+
+export interface PanelLayout {
+  lines: Segment[][]
+  focusLine: number
+  caret: { row: number; col: number } | null
+  height: number
+  hitRows: PanelHitRow[]
+}
+
+export function questionPanelLayout(state: QuestionPageState, innerWidth: number, scrollWindow: number = MAX_BODY_ROWS): PanelLayout {
+  const total = state.request.questions.length + 1
+  const isReview = state.page >= state.request.questions.length
+  const body: Segment[][] = []
+  const hitRows: PanelHitRow[] = []
+  let focusLine = 0
+  let caret: { row: number; col: number } | null = null
+
+  if (isReview) {
+    body.push(lineOf([seg('Confirm Selection', questionStyle())]))
+    body.push([])
+    for (const [index, question] of state.request.questions.entries()) {
+      pushWrapped(body, `${index + 1}. ${question.question}`, NUMBER_COL, innerWidth)
+      const answer = reviewAnswerOf(question, state.drafts[index]!)
+      const answerStyle = answer === '(Question not answered)' ? unansweredStyle() : descriptionStyle()
+      pushWrapped(body, answer, SINGLE_LABEL_COL, innerWidth, answerStyle)
+    }
+    body.push([])
+    body.push(questionLegend(state.page, total))
+  } else {
+    const question = state.request.questions[state.page]!
+    const multi = question.multiSelect === true
+    const editing = state.editing
+    const labX = labelCol(question)
+    const fieldWidth = Math.max(8, innerWidth - labX)
+    const above: Segment[][] = []
+    pushWrapped(above, question.question, 0, innerWidth, questionStyle())
+    above.push(lineOf([]))
+
+    const below: Segment[][] = []
+    let focusInBelow = -1
+    let caretInBelow: { row: number; col: number } | null = null
+    const hitsInBelow: PanelHitRow[] = []
+    const rows = interactiveRowCount(question)
+    const cursorRow = state.cursors[state.page]!
+    const draft = state.drafts[state.page]!
+    for (let i = 0; i < rows; i++) {
+      const focused = cursorRow === i
+      const marker = focused ? glyphs.focusMarker : ' '
+      const num = `${i + 1}.`
+      if (focused) focusInBelow = below.length
+      hitsInBelow.push({ line: below.length, optionIndex: i })
+      if (i === rows - 1) {
+        const checked = draft.customChecked
+        const box = multi ? (checked ? glyphs.checkboxOn : glyphs.checkboxOff) : ''
+        const tick = !multi && checked ? `  ${glyphs.tick}` : ''
+        const value = editing ? state.editor.value : draft.customText
+        const cursor = editing ? state.editor.cursor : value.length
+        below.push(lineOf([
+          seg(marker, focused ? checkStyle() : undefined),
+          ' ',
+          seg(num, focused ? focusedLabelStyle() : undefined),
+          ...(box === '' ? [] : [seg(' ' + box, focused ? focusedLabelStyle() : undefined)]),
+          ' ',
+          seg('Custom input content', focused ? focusedLabelStyle() : undefined),
+          ...(tick === '' ? [] : [seg(tick, checkStyle())]),
+          ...(editing && focused ? [seg(caretNonceText(cursor), { color: caretNonceColor(cursor), bold: caretNonceBold(cursor) })] : []),
+        ]))
+        const field = inputLayout(value, cursor, fieldWidth + INPUT_WIDTH_OFFSET)
+        const firstVisible = Math.min(
+          Math.max(0, field.cursorRow - (MAX_FIELD_ROWS - 1)),
+          Math.max(0, field.lines.length - MAX_FIELD_ROWS),
+        )
+        const visible = field.lines.slice(firstVisible, firstVisible + MAX_FIELD_ROWS)
+        const fieldStart = below.length
+        for (const [index, line] of visible.entries()) {
+          below.push(lineOf([' '.repeat(labX), seg(line, descriptionStyle()), ...(editing && index === visible.length - 1 ? [seg(' ', descriptionStyle())] : [])]))
+        }
+        if (editing) {
+          caretInBelow = {
+            row: fieldStart + field.cursorRow - firstVisible,
+            col: labX + field.cursorCol,
+          }
+        }
+      } else {
+        const option = question.options![i]!
+        const chosen = draft.selected.includes(option.label)
+        const box = multi ? (chosen ? glyphs.checkboxOn : glyphs.checkboxOff) : ''
+        const tick = !multi && chosen ? `  ${glyphs.tick}` : ''
+        below.push(lineOf([
+          seg(marker, focused ? checkStyle() : undefined),
+          ' ',
+          seg(num, focused ? focusedLabelStyle() : undefined),
+          ...(box === '' ? [] : [seg(' ' + box, focused ? focusedLabelStyle() : undefined)]),
+          ' ',
+          seg(option.label, focused ? focusedLabelStyle() : undefined),
+          ...(tick === '' ? [] : [seg(tick, checkStyle())]),
+        ]))
+        if (option.description !== undefined && option.description !== '') {
+          pushWrapped(below, option.description, labX, innerWidth, descriptionStyle())
+        }
+      }
+    }
+    below.push(lineOf([]))
+    below.push(questionLegend(state.page, total))
+
+    body.push(...above)
+    const detail = question.detail === undefined || question.detail === '' || isPlanReview(question)
+      ? []
+      : wrapLines(question.detail, Math.max(8, innerWidth - SINGLE_LABEL_COL))
+    if (detail.length > 0) {
+      const budget = Math.max(3, scrollWindow - body.length - below.length)
+      if (detail.length <= budget) {
+        for (const line of detail) {
+          body.push(lineOf(['  ', seg(line, descriptionStyle())]))
+        }
+      } else {
+        const contentRows = Math.max(1, budget - 2)
+        const maxStart = detail.length - contentRows
+        const start = Math.max(0, Math.min(state.detailScroll[state.page]!, maxStart))
+        if (start > 0) {
+          body.push(lineOf([seg(`${glyphs.ellipsis} ${start} lines above`, descriptionStyle())]))
+        }
+        for (const line of detail.slice(start, start + contentRows)) {
+          body.push(lineOf(['  ', seg(line, descriptionStyle())]))
+        }
+        if (start + contentRows < detail.length) {
+          body.push(lineOf([seg(`${glyphs.ellipsis} ${detail.length - start - contentRows} more lines`, descriptionStyle())]))
+        }
+      }
+    }
+    const base = body.length
+    body.push(...below)
+    if (focusInBelow >= 0) focusLine = base + focusInBelow
+    if (caretInBelow !== null) caret = { row: base + caretInBelow.row, col: caretInBelow.col }
+    for (const hit of hitsInBelow) {
+      hitRows.push({ line: base + hit.line, optionIndex: hit.optionIndex })
+    }
+  }
+
+  const window = Math.max(3, Math.min(scrollWindow, body.length))
+  if (body.length <= window) {
+    return { lines: body, focusLine, caret: finalizeCaret(caret, body), height: body.length, hitRows }
+  }
+  let start = Math.max(0, Math.min(focusLine - Math.floor(window / 2), body.length - window))
+  const lines = body.slice(start, start + window)
+  const shifted = hitRows
+    .map(hit => ({ line: hit.line - start, optionIndex: hit.optionIndex }))
+    .filter(hit => hit.line >= 0 && hit.line < lines.length)
+  return { lines, focusLine: focusLine - start, caret: finalizeCaret(caret, body, start), height: window, hitRows: shifted }
+}
+
+function finalizeCaret(
+  caret: { row: number; col: number } | null,
+  body: Segment[][],
+  start = 0,
+): { row: number; col: number } | null {
+  if (caret === null) return null
+  const row = Math.max(0, Math.min(body.length - 1, caret.row)) - start
+  return { row, col: caret.col }
+}
+
+function questionLegend(page: number, total: number): Segment[] {
+  const prefix = `${page + 1}/${total}`
+  const review = page + 1 === total
+  const hints = review
+    ? [
+        { key: glyphs.pageFlip, description: 'page' },
+        { key: 'enter', description: 'submit' },
+        { key: 'esc', description: 'close' },
+      ]
+    : [
+        { key: glyphs.pageFlip, description: 'page' },
+        { key: glyphs.wrapArrows, description: 'wrap' },
+        { key: 'enter', description: 'select' },
+        { key: 'esc', description: 'close' },
+      ]
+  return panelLegend(hints, { prefix })
+}
+
+interface QuestionLike {
+  intent?: { kind?: string }
+}
+
+export function isPlanReview(question: QuestionLike): boolean {
+  return question.intent?.kind === 'plan-review'
+}

package/src/ui/panels/question-panel.tsx

@@ -0,0 +1,154 @@
+import { Box, Text, useInput } from 'ink'
+import { panelAnchorRow } from '../layout-service.ts'
+import { isKeyConsumed } from '../key-arbiter.ts'
+import { useEffect, useState } from 'react'
+import { useCaret } from '../hooks/use-caret.ts'
+import type { Ref } from 'react'
+import { useImperativeHandle } from 'react'
+import { isMouseResidue } from '../../terminal/mouse.ts'
+import { writeCursorShape } from '../../terminal/cursor-shape.ts'
+import { CHROME_MARGIN_X, CHROME_TEXT_X } from '../../core/metrics.ts'
+import type { AskUserQuestionAnswerLike, QuestionPanelRequest } from '../../chat/interactions.ts'
+import {
+  buildAnswers,
+  cancelEdit,
+  commitEdit,
+  editorBackspace,
+  editorCaret,
+  fieldWidthOf,
+  editorInsert,
+  enterOnRow,
+  initialPageState,
+  MAX_BODY_ROWS,
+  MAX_DETAIL_ROWS,
+  moveCursor,
+  questionPanelLayout,
+  scrollDetail,
+  switchPage,
+} from './question-model.ts'
+import type { QuestionPageState } from './question-model.ts'
+import { PanelSurface } from './surface.tsx'
+import type { PanelPointerHandle } from './surface.tsx'
+
+export interface QuestionPanelProps {
+  handleRef?: Ref<PanelPointerHandle>
+  question: QuestionPanelRequest
+  background: string
+  active: boolean
+  columns: number
+  innerWidth: number
+  blockWidth: number
+  rows: number
+  onSubmit(answer: AskUserQuestionAnswerLike): void
+  onCancel(): void
+  onResize(height: number): void
+}
+
+export function QuestionPanel({ handleRef, question: panel, background, active, columns, innerWidth, blockWidth, rows, onSubmit, onCancel, onResize }: QuestionPanelProps) {
+  const [state, setState] = useState<QuestionPageState>(() => initialPageState(panel.request))
+  const { setCursorPosition } = useCaret()
+  const layout = questionPanelLayout(state, innerWidth, Math.min(MAX_BODY_ROWS, Math.max(3, rows - 6)))
+  const totalHeight = layout.height + 2
+  const bodyStart = panelAnchorRow(rows, layout.height)
+  useImperativeHandle(handleRef, () => ({
+    clickAt(y) {
+      if (!active || state.editing) return
+      const rel = y - bodyStart
+      const hit = layout.hitRows.find(entry => entry.line === rel)
+      if (hit === undefined) return
+      setState(current => {
+        if (current.cursors[current.page] === hit.optionIndex) return enterOnRow(current)
+        return {
+          ...current,
+          cursors: current.cursors.map((value, index) => index === current.page ? hit.optionIndex : value),
+        }
+      })
+    },
+    wheel(dir: -1 | 1) {
+      if (!active || state.editing) return false
+      setState(current => scrollDetail(current, dir === -1 ? -3 : 3))
+      return true
+    },
+  }))
+  if (active && state.editing && layout.caret !== null) {
+    setCursorPosition({
+      x: CHROME_TEXT_X + layout.caret.col,
+      y: bodyStart + layout.caret.row,
+    })
+  } else {
+    setCursorPosition(undefined)
+  }
+  useEffect(() => {
+    if (state.editing) {
+      writeCursorShape('show')
+      writeCursorShape('beam')
+    } else {
+      writeCursorShape('hide')
+    }
+  }, [state.editing])
+  useEffect(() => {
+    return () => {
+      writeCursorShape('show')
+      writeCursorShape('reset')
+    }
+  }, [])
+  useEffect(() => {
+    setState(initialPageState(panel.request))
+  }, [panel.id])
+  useEffect(() => {
+    onResize(totalHeight)
+  }, [totalHeight])
+  useInput((input, key) => {
+    if (!active || isKeyConsumed()) return
+    if (isMouseResidue(input)) return
+    if (state.editing) {
+      if (key.return) {
+        setState(current => commitEdit(current))
+        return
+      }
+      if (key.escape) {
+        setState(current => cancelEdit(current))
+        return
+      }
+      const fieldWidth = fieldWidthOf(state.request.questions[state.page]!, innerWidth)
+      if (key.upArrow) return setState(current => editorCaret(current, 0, -1, fieldWidth))
+      if (key.downArrow) return setState(current => editorCaret(current, 0, 1, fieldWidth))
+      if (key.leftArrow) return setState(current => editorCaret(current, -1, 0, fieldWidth))
+      if (key.rightArrow) return setState(current => editorCaret(current, 1, 0, fieldWidth))
+      if (key.home) return setState(current => ({ ...current, editor: { value: current.editor.value, cursor: 0 } }))
+      if (key.end) return setState(current => ({ ...current, editor: { value: current.editor.value, cursor: current.editor.value.length } }))
+      if (key.backspace || key.delete) return setState(current => editorBackspace(current))
+      if (key.ctrl && input === 'j') return setState(current => editorInsert(current, '\n'))
+      if (!key.ctrl && !key.meta && input.length > 0) return setState(current => editorInsert(current, input))
+      return
+    }
+    if (key.escape) {
+      onCancel()
+      return
+    }
+    if (key.leftArrow) return setState(current => switchPage(current, -1))
+    if (key.rightArrow) return setState(current => switchPage(current, 1))
+    if (key.pageUp) return setState(current => scrollDetail(current, -MAX_DETAIL_ROWS))
+    if (key.pageDown) return setState(current => scrollDetail(current, MAX_DETAIL_ROWS))
+    if (key.upArrow) return setState(current => moveCursor(current, -1))
+    if (key.downArrow) return setState(current => moveCursor(current, 1))
+    const isReview = state.page >= state.request.questions.length
+    if (key.return) {
+      if (isReview) {
+        onSubmit({ answers: buildAnswers(state) })
+        return
+      }
+      setState(current => enterOnRow(current))
+    }
+  })
+  return (
+    <PanelSurface
+      columns={columns}
+      rows={rows}
+      body={layout.lines.map(segments => ({ segments }))}
+      bodyStart={bodyStart}
+      background={background}
+      blockWidth={blockWidth}
+    />
+  )
+}

package/src/ui/panels/surface.tsx

@@ -0,0 +1,106 @@
+import { Box, Text } from 'ink'
+import type { ReactNode } from 'react'
+import { mergeRuns } from '../../core/segments.ts'
+import type { Segment } from '../../core/segments.ts'
+import { COLORS } from '../../theme.ts'
+import { CHROME_MARGIN_X, CHROME_PAD_X, CHROME_TEXT_X } from '../../core/metrics.ts'
+import { SelectableText } from '../selection.tsx'
+import { Region } from '../region.tsx'
+import { CapText } from '../chrome/caps.tsx'
+
+export interface PanelPointerHandle {
+  clickAt(y: number, x: number): void
+  wheel(dir: -1 | 1): boolean
+}
+
+export interface PanelRow {
+  segments: Segment[]
+  /** Replaces the text row with an interactive node (e.g. a button row). */
+  content?: ReactNode
+}
+
+export interface PanelHint {
+  /** Key token, rendered with the key color (e.g. "enter", an arrow glyph). */
+  key: string
+  /** Action word, rendered with the description color. */
+  description: string
+}
+
+export interface PanelLegendOptions {
+  /** Leading counter text (e.g. "1/2"), rendered with the description color. */
+  prefix?: string
+  keyColor?: string
+  descriptionColor?: string
+}
+
+/**
+ * Build a key-hint row: keys in the panel key color, action words in the
+ * muted description color ("enter select  esc close").
+ */
+export function panelLegend(hints: readonly PanelHint[], options: PanelLegendOptions = {}): Segment[] {
+  const keyStyle = { color: options.keyColor ?? COLORS.panelKeyText }
+  const descriptionStyle = { color: options.descriptionColor ?? COLORS.toolBodyText }
+  const parts: Array<Segment> = []
+  if (options.prefix !== undefined && options.prefix !== '') {
+    parts.push({ text: options.prefix, style: descriptionStyle })
+  }
+  for (const [index, hint] of hints.entries()) {
+    if (index > 0 || parts.length > 0) parts.push({ text: '  ', style: descriptionStyle })
+    parts.push({ text: hint.key, style: keyStyle })
+    parts.push({ text: ' ', style: descriptionStyle })
+    parts.push({ text: hint.description, style: descriptionStyle })
+  }
+  return mergeRuns(parts)
+}
+
+/**
+ * Shared panel chrome: a floating block anchored above the status line with
+ * half-block caps, the panel background, and per-row text or interactive
+ * content. Builtin panels and plugin panels built through dshtui/dialog
+ * share this shell so every interaction panel looks the same.
+ *
+ * Selection pieces span the row text only, never the pill padding, so
+ * dragging over blank panel area selects nothing (same rule as messages).
+ */
+export function PanelSurface({ columns, rows, body, bodyStart, background, blockWidth }: {
+  columns: number
+  rows: number
+  body: PanelRow[]
+  bodyStart: number
+  background: string
+  blockWidth: number
+}) {
+  return (
+    <Region>
+      <Box position="absolute" top={0} left={0} width={columns} height={rows}>
+        <Box position="absolute" top={bodyStart - 1} left={CHROME_MARGIN_X} width={blockWidth}>
+          <CapText background={background} top width={blockWidth} />
+        </Box>
+        {body.map((row, index) => {
+          const isEmpty = row.segments.every(segment => segment.text.trim() === '')
+          return (
+            <Box
+              key={`panel-row-${index}`}
+              position="absolute"
+              top={bodyStart + index}
+              left={CHROME_MARGIN_X}
+              width={blockWidth}
+              paddingLeft={CHROME_PAD_X}
+              paddingRight={CHROME_PAD_X}
+              backgroundColor={background}
+            >
+              {row.content !== undefined
+                ? row.content
+                : isEmpty
+                  ? <Text>{' '}</Text>
+                  : <SelectableText y={bodyStart + index} col={CHROME_TEXT_X} segments={row.segments} />}
+            </Box>
+          )
+        })}
+        <Box position="absolute" top={bodyStart + body.length} left={CHROME_MARGIN_X} width={blockWidth}>
+          <CapText background={background} top={false} width={blockWidth} />
+        </Box>
+      </Box>
+    </Region>
+  )
+}