@carlesandres/house 0.4.0 → 0.4.1

package/src/Browser.tsx

@@ -11,6 +11,7 @@
  */
 
 import { SyntaxStyle } from "@opentui/core"
+import type { BorderSides } from "@opentui/core"
 import { useKeyboard, useRenderer, useTerminalDimensions } from "@opentui/react"
 import { useAtomValue, useAtomSet } from "@effect/atom-react"
 import { Effect } from "effect"
@@ -20,7 +21,9 @@ import { clampSelectedIndex, filterCommands } from "./commands/score.ts"
 import { CommandPalette } from "./CommandPalette.tsx"
 import { filterFiles } from "./discovery/filter.ts"
 import { type FileEntry } from "./discovery/walk.ts"
+import { BRAND, BRAND_NAME } from "./brand.ts"
 import { Footer, FOOTER_HEIGHT } from "./Footer.tsx"
+import { Header, HEADER_HEIGHT } from "./Header.tsx"
 import { HelpOverlay } from "./HelpOverlay.tsx"
 import { readFileText } from "./io/readFile.ts"
 import { browserBindings, type BrowserCtx } from "./keymap/browser.ts"
@@ -41,7 +44,6 @@ export type SidebarMode = "auto" | "on" | "off"
 
 export interface BrowserProps {
 	readonly files: readonly FileEntry[]
-	readonly title?: string
 	readonly initialIndex?: number
 	/** Cap the rendered markdown's width at N columns. Null = fill the pane. */
 	readonly maxWidth?: number | null
@@ -54,6 +56,14 @@ export interface BrowserProps {
 	readonly onQuit?: () => void
 	/** Test seam: replaces the file reader. */
 	readonly readFile?: (path: string) => Promise<string>
+	/** Optional one-shot footer toast surfaced on first appearance (e.g. the
+	 *  "update available" nudge). Shown with an extended TTL so the user has
+	 *  time to read it; subsequent transient toasts (theme cycle, etc.)
+	 *  preempt it via the same single-slot channel. Null disables. */
+	readonly updateNotice?: string | null
+	/** TTL (ms) for the update-notice toast. Exposed so tests can use a small
+	 *  value instead of sleeping for the production 10s window. */
+	readonly updateNoticeTtlMs?: number
 }
 
 const defaultReadFile = (path: string): Promise<string> => Effect.runPromise(readFileText(path))
@@ -74,13 +84,14 @@ const HELP_ALLOWED_IDS: ReadonlySet<string> = new Set([
 
 export const Browser = ({
 	files,
-	title = "house",
 	initialIndex = 0,
 	maxWidth = null,
 	discoveryStatus = null,
 	sidebarMode = "auto",
 	onQuit,
 	readFile = defaultReadFile,
+	updateNotice = null,
+	updateNoticeTtlMs = 10000,
 }: BrowserProps) => {
 	const renderer = useRenderer()
 	const { width, height } = useTerminalDimensions()
@@ -131,10 +142,14 @@ export const Browser = ({
 	const filterOpenRef = useRef(false)
 	const filterQueryRef = useRef("")
 	// Snapshot the query at filter-open so Esc reverts edits but commit (Return)
-	// keeps them. Layout snapshots are no longer needed — focus drives drawer
-	// dismissal under the §7.1 visibility rule.
+	// keeps them.
 	const priorFilterQueryRef = useRef("")
-	const [footerNotice, setFooterNotice] = useState<string | null>(null)
+	const [footerNotice, setFooterNoticeState] = useState<{
+		readonly text: string
+		readonly ttlMs: number
+	} | null>(null)
+	const pushFooterNotice = (text: string, ttlMs = 2000): void =>
+		setFooterNoticeState({ text, ttlMs })
 	const serverRef = useRef<ServerHandle | null>(null)
 
 	// Stop the preview server on unmount so re-mounts (tests) and clean
@@ -146,21 +161,36 @@ export const Browser = ({
 		}
 	}, [])
 
-	// Single-slot notice with a 2s TTL. A new notice cancels the pending
-	// timer so the latest message gets its own full window.
+	// Single-slot notice with a per-message TTL. A new notice cancels the
+	// pending timer so the latest message gets its own full window. The TTL
+	// travels with the message so a long-lived nudge (update available) and a
+	// transient toast (theme cycle) can share one slot without one stealing
+	// the other's display window.
 	useEffect(() => {
 		if (footerNotice === null) return
-		const timer = setTimeout(() => setFooterNotice(null), 2000)
+		const timer = setTimeout(() => setFooterNoticeState(null), footerNotice.ttlMs)
 		return () => clearTimeout(timer)
 	}, [footerNotice])
 
+	// Push the update-available nudge once, when it arrives from the parent
+	// (the registry probe resolves asynchronously after boot). 10s gives the
+	// user time to read it before it auto-clears; the quit-time stderr print
+	// is the durable record they can copy from scrollback.
+	const updateNoticeSeenRef = useRef<string | null>(null)
+	useEffect(() => {
+		if (!updateNotice) return
+		if (updateNoticeSeenRef.current === updateNotice) return
+		updateNoticeSeenRef.current = updateNotice
+		pushFooterNotice(updateNotice, updateNoticeTtlMs)
+	}, [updateNotice, updateNoticeTtlMs])
+
 	const cycleTheme = (delta: 1 | -1) => {
 		const idx = themeDefinitions.findIndex((d) => d.id === theme.id)
 		const next = themeDefinitions[(idx + delta + themeDefinitions.length) % themeDefinitions.length]
 		if (!next) return
 		setActiveTheme(next, theme.tone)
 		setTheme({ id: next.id, tone: theme.tone })
-		setFooterNotice(`theme: ${next.name}`)
+		pushFooterNotice(`theme: ${next.name}`)
 	}
 
 	const toggleTone = () => {
@@ -168,7 +198,7 @@ export const Browser = ({
 		const def = getThemeDefinition(theme.id)
 		if (def) setActiveTheme(def, nextTone)
 		setTheme({ id: theme.id, tone: nextTone })
-		setFooterNotice(`tone: ${nextTone}`)
+		pushFooterNotice(`tone: ${nextTone}`)
 	}
 
 	const displayedFiles = useMemo(() => filterFiles(files, filterQuery), [files, filterQuery])
@@ -239,13 +269,21 @@ export const Browser = ({
 		setFocus,
 		setSelectedIndex,
 		toggleShown: () => {
-			// Per DESIGN.md §7.1 s-behavior table:
-			//   shown=true,  focus=sidebar → shown=false, focus=reader
-			//                                (otherwise the drawer would
-			//                                 immediately re-appear)
-			//   shown=true,  focus=reader  → shown=false, focus=reader
-			//   shown=false, focus=reader  → shown=true,  focus=sidebar
-			//   shown=false, focus=sidebar → shown=true,  focus=sidebar
+			// Two layout shapes, two behaviors:
+			//   wide  → flip the sticky `shown` preference. Per DESIGN.md §7.1
+			//           s-behavior table: also nudge focus so the visibility
+			//           rule (`visible = shown || focus==="sidebar"`) reflects
+			//           the user's intent instead of forcing the sidebar back
+			//           on via focus.
+			//   narrow → swap which screen is up (focus is the source of truth
+			//           for render). Sync `shown` to the new screen so a later
+			//           resize to wide opens with the right pane visible.
+			if (!canFitInline(width)) {
+				const next = focus === "sidebar" ? "reader" : "sidebar"
+				setFocus(next)
+				setShown(next === "sidebar")
+				return
+			}
 			if (shown) {
 				setShown(false)
 				if (focus === "sidebar") setFocus("reader")
@@ -256,10 +294,11 @@ export const Browser = ({
 		},
 		setHelpVisible,
 		openFilter: () => {
-			// Focus the sidebar so the filter input has a home. Under §7.1's
-			// `visible = shown || focus==="sidebar"` rule, focus alone makes
-			// the sidebar visible (as a drawer when `shown=false`), so we no
-			// longer need to mutate `shown` here.
+			// Focus the sidebar so the filter input has a home. In wide,
+			// §7.1's visibility rule (`shown || focus === "sidebar"`) brings
+			// the inline sidebar back on screen if it was hidden. In narrow,
+			// focusing the sidebar swaps to the sidebar screen. Either way
+			// no need to mutate `shown`.
 			priorFilterQueryRef.current = filterQueryRef.current
 			if (focus !== "sidebar") setFocus("sidebar")
 			filterOpenRef.current = true
@@ -288,9 +327,9 @@ export const Browser = ({
 					handle = startServer({ path: file.path })
 					serverRef.current = handle
 					openInBrowser(handle.url)
-					setFooterNotice(`serving at ${handle.url}`)
+					pushFooterNotice(`serving at ${handle.url}`)
 				} catch (err) {
-					setFooterNotice(`serve failed: ${String(err)}`)
+					pushFooterNotice(`serve failed: ${String(err)}`)
 				}
 				return
 			}
@@ -302,7 +341,7 @@ export const Browser = ({
 			// an existing tab on the same URL when one is open, so this is
 			// idempotent for the common case.
 			openInBrowser(handle.url)
-			setFooterNotice(`serving ${file.relativePath} at ${handle.url}`)
+			pushFooterNotice(`serving ${file.relativePath} at ${handle.url}`)
 		},
 		quit: () => {
 			if (onQuit) {
@@ -361,18 +400,20 @@ export const Browser = ({
 						if (idx >= 0) setSelectedIndex(() => idx)
 					}
 				}
-				// Where focus lands depends on layout intent (DESIGN.md §7.1):
+				// Where focus lands after the filter closes:
 				//   commit (Return on a real pick) → reader, always. The user
 				//     asked to open the match; show them what they picked.
-				//   cancel (Esc, or Return with no pick) → if the sidebar is
-				//     inline (shown && fits), keep focus there so j/k keeps
-				//     walking the list; if the sidebar was only up as a drawer
-				//     (shown=false), dismiss focus to the reader so the drawer
-				//     disappears under the §7.1 visibility rule.
+				//   cancel (Esc, or Return with no pick) → restore the user's
+				//     pre-filter intent. If the sidebar was up before the
+				//     filter opened (shown=true), stay in it so j/k keeps
+				//     walking. If the sidebar was hidden (shown=false), go
+				//     back to the reader so the sidebar dismisses — in narrow
+				//     that swaps screens; in wide that drops the focus-driven
+				//     sidebar revival.
 				if (effectiveCommit) {
 					setFocus("reader")
 				} else {
-					setFocus(shown && canFitInline(width) ? "sidebar" : "reader")
+					setFocus(shown ? "sidebar" : "reader")
 				}
 			}
 			if (key.name === "escape") {
@@ -516,42 +557,33 @@ export const Browser = ({
 	const sidebarWidth = resolveSidebarWidth(width, defaultPreferredWidth(width))
 	const sidebarActive = focus === "sidebar"
 	const readerActive = focus === "reader"
-	// Visibility = shown OR sidebar-focused. When visible-because-focused
-	// only, render as a drawer (absolute) on top of the reader. We also
-	// fall back to drawer rendering when the viewport is too narrow for
-	// the inline two-pane layout even with `shown=true` (Q2 in DESIGN.md
-	// §7.1) — preserves the user's preference without squeezing the reader
-	// below READER_MIN_WIDTH.
-	const sidebarVisible = shown || sidebarActive
-	const sidebarAsDrawer = sidebarVisible && (!shown || !canFitInline(width))
-	const sidebarInline = sidebarVisible && !sidebarAsDrawer
-	// Drawer is offset 1 row from the top so the reader's title stays visible.
-	// That row comes off the drawer's own height, so the body has one fewer
-	// usable row than the inline sidebar. Tracked here so the virtualization
-	// slice matches the wrapper that actually paints it.
-	const drawerTopOffset = 1
-	const sidebarTitle = sidebarActive ? " ▸ files " : "   files "
-	const readerLabel = selected?.relativePath ?? title
-	const readerTitle = readerActive ? ` ▸ ${readerLabel} ` : `   ${readerLabel} `
+	// Wide vs narrow drives the entire layout shape.
+	//   wide   → inline two-pane (today). visible = shown || focus==="sidebar".
+	//   narrow → single-pane stack: whichever pane has focus fills the area.
+	//            `shown` is silently ignored for render in narrow; `focus`
+	//            is the single source of truth.
+	// See DESIGN.md §7.1.
+	const isNarrow = !canFitInline(width)
+	const sidebarInline = isNarrow ? sidebarActive : shown || sidebarActive
+	const readerVisible = isNarrow ? readerActive : true
+	// Currently-selected file shown in the Header (which replaced the
+	// per-pane border title that used to carry this information).
+	const currentFile = selected?.relativePath ?? null
 	const content = loaded?.path === renderedPath ? loaded.content : ""
 
 	// Sidebar virtualization: render only the visible window. Without this,
 	// every keystroke re-renders all N file rows even though only the bg of
 	// two of them changed (old + new selected). On a 195-file vault that
 	// dominates the per-keystroke cost.
-	// Sidebar box adds top/bottom borders (2); footer eats FOOTER_HEIGHT;
-	// the filter row eats one more cell when files are present *or* while
+	// Chrome budget: header + pane top border + pane bottom border + footer.
+	// The filter row eats one more cell when files are present *or* while
 	// discovery is in flight (allocates the row up front so it doesn't pop
 	// in when the first file arrives).
 	const discoveryActive = discoveryStatus !== null && discoveryStatus.length > 0
 	const filterRowVisible = files.length > 0 || discoveryActive
 	const sidebarBodyHeight = Math.max(
 		1,
-		height -
-			2 -
-			FOOTER_HEIGHT -
-			(filterRowVisible ? 1 : 0) -
-			(sidebarAsDrawer ? drawerTopOffset : 0),
+		height - FOOTER_HEIGHT - HEADER_HEIGHT - 2 - (filterRowVisible ? 1 : 0),
 	)
 	const maxScroll = Math.max(0, displayedFiles.length - sidebarBodyHeight)
 	const desiredScroll = (() => {
@@ -564,8 +596,12 @@ export const Browser = ({
 		if (desiredScroll !== sidebarScroll) setSidebarScroll(desiredScroll)
 	}, [desiredScroll, sidebarScroll])
 	const visibleFiles = displayedFiles.slice(desiredScroll, desiredScroll + sidebarBodyHeight)
-	// Available width for sidebar text rows: box width minus 1-cell border on each side.
-	const sidebarTextWidth = Math.max(4, sidebarWidth - 2)
+	// Available width for sidebar text rows. Wide-inline: sidebarWidth minus
+	// 1-cell left padding and 1-cell right divider border. Narrow-stack: the
+	// sidebar flex-grows to fill the viewport with no right divider, so the
+	// budget is the viewport minus the 1-cell left padding only.
+	const sidebarPaneWidth = isNarrow ? width : sidebarWidth
+	const sidebarTextWidth = Math.max(4, sidebarPaneWidth - (isNarrow ? 1 : 2))
 	// Right-anchored truncation: keep the filename visible, lose the prefix
 	// with a leading ellipsis when the path is too long.
 	const truncatePath = useCallback(
@@ -612,9 +648,8 @@ export const Browser = ({
 		[helpVisible],
 	)
 
-	// One sidebar element is reused for inline and drawer rendering; only
-	// the wrapper differs (flex sibling vs absolute-positioned). The body is
-	// identical so file rows / filter row don't drift between modes.
+	// One sidebar body for both wide-inline and narrow-stack rendering; only
+	// the wrapper differs (fixed-width sibling vs flex-grow full-pane).
 	const sidebarBody = (
 		<>
 			{filterRowVisible && (
@@ -655,107 +690,150 @@ export const Browser = ({
 		</>
 	)
 
+	// Pane borders draw a connected frame: each pane's top/bottom edges
+	// (the horizontal rules) and the sidebar's right edge (the vertical
+	// divider) are rendered by opentui in one pass, so the junctions
+	// never get painted over by sibling elements. customBorderChars on
+	// the sidebar turns its right-side corners from `┐ ┘` into `┬ ┴` so
+	// they connect cleanly with the reader's top/bottom rules.
+	const sidebarBorderSides: BorderSides[] = ["top", "bottom", "right"]
+	const readerBorderSides: BorderSides[] = ["top", "bottom"]
+	const SIDEBAR_BORDER_CHARS = {
+		topLeft: "┌",
+		topRight: "┬",
+		bottomLeft: "└",
+		bottomRight: "┴",
+		horizontal: "─",
+		vertical: "│",
+		topT: "┬",
+		bottomT: "┴",
+		leftT: "├",
+		rightT: "┤",
+		cross: "┼",
+	} as const
+
 	return (
-		<box style={{ width, height, flexDirection: "column", backgroundColor: colors.background }}>
+		<box style={{ width, height, flexDirection: "column", backgroundColor: colors.surface }}>
+			<Header width={width} currentFile={currentFile} />
 			<box
 				style={{
 					flexDirection: "row",
 					flexGrow: 1,
 					flexShrink: 1,
-					backgroundColor: colors.background,
+					backgroundColor: colors.surface,
 				}}
 			>
 				{sidebarInline && (
 					<box
-						title={sidebarTitle}
-						titleAlignment="left"
 						style={{
-							border: true,
-							borderColor: sidebarActive ? colors.borderActive : colors.border,
-							width: sidebarWidth,
-							flexShrink: 0,
+							// Narrow mode runs single-pane: the sidebar fills the area
+							// and drops its right divider (no neighbour to abut).
+							border: isNarrow ? readerBorderSides : sidebarBorderSides,
+							borderColor: colors.textMuted,
+							...(isNarrow
+								? { flexGrow: 1, flexShrink: 1 }
+								: { width: sidebarWidth, flexShrink: 0 }),
 							flexDirection: "column",
+							// Dim by default. Borders/separators ride on this so they read
+							// as a single connected frame regardless of focus; only the
+							// active pane's inner body overrides to the raised tint below.
 							backgroundColor: colors.surface,
 						}}
+						{...(isNarrow ? {} : { customBorderChars: SIDEBAR_BORDER_CHARS })}
 					>
-						{sidebarBody}
+						<box
+							style={{
+								flexGrow: 1,
+								flexShrink: 1,
+								flexDirection: "column",
+								paddingLeft: 1,
+								backgroundColor: sidebarActive ? colors.background : colors.surface,
+							}}
+						>
+							{sidebarBody}
+						</box>
 					</box>
 				)}
-				<box
-					title={readerTitle}
-					titleAlignment="left"
-					style={{
-						border: true,
-						borderColor: readerActive ? colors.borderActive : colors.border,
-						padding: 1,
-						flexGrow: 1,
-						flexShrink: 1,
-						backgroundColor: colors.background,
-					}}
-				>
-					{error ? (
-						<text content={error} style={{ fg: colors.error }} />
-					) : (
-						<scrollbox
+				{readerVisible && (
+					<box
+						style={{
+							border: readerBorderSides,
+							borderColor: colors.textMuted,
+							flexGrow: 1,
+							flexShrink: 1,
+							flexDirection: "column",
+							// Dim by default (see sidebar note); inner body overrides when active.
+							backgroundColor: colors.surface,
+						}}
+					>
+						<box
 							style={{
-								scrollY: true,
-								scrollX: false,
 								flexGrow: 1,
 								flexShrink: 1,
-								backgroundColor: colors.background,
+								flexDirection: "column",
+								padding: 1,
+								backgroundColor: readerActive ? colors.background : colors.surface,
 							}}
-							// opentui's scrollbox consumes arrow keys at the focused-element
-							// level *before* useKeyboard fires, so a modal that handles
-							// arrow keys itself (palette nav, help dismissal) would still
-							// see the reader scroll alongside its own action. Unfocus the
-							// scrollbox while any blocking modal is up — useKeyboard's
-							// modal branches own the keys in that state. Filter is not
-							// listed because it force-focuses the sidebar (readerActive
-							// is already false).
-							focused={readerActive && !paletteOpen && !helpVisible}
 						>
-							<markdown
-								key={renderedPath ?? "empty"}
-								content={content}
-								syntaxStyle={syntaxStyle}
-								fg={colors.text}
-								bg={colors.background}
-								conceal
-								style={{ width: maxWidth ?? "100%" }}
-							/>
-						</scrollbox>
-					)}
-				</box>
+							{error ? (
+								<text content={error} style={{ fg: colors.error }} />
+							) : !renderedPath ? (
+								// Reader empty state — no file selected. Brand mark centered as a
+								// welcome anchor; in-app tips (#47) will live here too.
+								<box
+									style={{
+										flexGrow: 1,
+										flexShrink: 1,
+										alignItems: "center",
+										justifyContent: "center",
+										backgroundColor: readerActive ? colors.background : colors.surface,
+									}}
+								>
+									<text
+										content={`${BRAND} ${BRAND_NAME}`}
+										wrapMode="none"
+										style={{ fg: colors.textMuted }}
+									/>
+								</box>
+							) : (
+								<scrollbox
+									style={{
+										scrollY: true,
+										scrollX: false,
+										flexGrow: 1,
+										flexShrink: 1,
+										backgroundColor: readerActive ? colors.background : colors.surface,
+									}}
+									// opentui's scrollbox consumes arrow keys at the focused-element
+									// level *before* useKeyboard fires, so a modal that handles
+									// arrow keys itself (palette nav, help dismissal) would still
+									// see the reader scroll alongside its own action. Unfocus the
+									// scrollbox while any blocking modal is up — useKeyboard's
+									// modal branches own the keys in that state. Filter is not
+									// listed because it force-focuses the sidebar (readerActive
+									// is already false).
+									focused={readerActive && !paletteOpen && !helpVisible}
+								>
+									<markdown
+										key={renderedPath ?? "empty"}
+										content={content}
+										syntaxStyle={syntaxStyle}
+										fg={colors.text}
+										bg={readerActive ? colors.background : colors.surface}
+										conceal
+										style={{ width: maxWidth ?? "100%" }}
+									/>
+								</scrollbox>
+							)}
+						</box>
+					</box>
+				)}
 			</box>
-			{sidebarAsDrawer && (
-				// Offset by 1 row so the reader pane's top border (which carries
-				// the current file name) stays visible above the drawer. Without
-				// this, the user loses the only on-screen indicator of which
-				// file they're reading whenever the drawer is up.
-				<box
-					position="absolute"
-					left={0}
-					top={drawerTopOffset}
-					width={sidebarWidth}
-					height={Math.max(1, height - FOOTER_HEIGHT - drawerTopOffset)}
-					zIndex={5}
-					title={sidebarTitle}
-					titleAlignment="left"
-					style={{
-						border: true,
-						borderColor: sidebarActive ? colors.borderActive : colors.border,
-						flexDirection: "column",
-						backgroundColor: colors.surface,
-					}}
-				>
-					{sidebarBody}
-				</box>
-			)}
 			<Footer
 				bindings={footerBindings}
 				ctx={ctx}
 				width={width}
-				notice={footerNotice}
+				notice={footerNotice?.text ?? null}
 				discoveryStatus={discoveryStatus}
 				filterQuery={!filterOpen && filterQuery.length > 0 ? filterQuery : null}
 			/>

package/src/CommandPalette.tsx

@@ -9,9 +9,16 @@
  * no mouse, no recency. See #91/#93/#94/#95/#96 for the follow-ups.
  */
 
+import { RGBA } from "@opentui/core"
 import { colors } from "./theme/colors.ts"
 import type { AppCommand } from "./commands/types.ts"
 
+// Semi-transparent black scrim painted across the viewport behind the modal.
+// Opentui composites it over the chrome underneath, so the rest of the UI
+// reads as darkened while the modal stays fully opaque. Mirrors opencode's
+// dialog backdrop (cli/cmd/tui/ui/dialog.tsx).
+const SCRIM = RGBA.fromInts(0, 0, 0, 150)
+
 export interface CommandPaletteProps {
 	readonly commands: readonly AppCommand[]
 	readonly query: string
@@ -73,54 +80,71 @@ export const CommandPalette = ({
 	return (
 		<box
 			position="absolute"
-			left={left}
-			top={top}
-			width={overlayWidth}
-			height={overlayHeight}
+			left={0}
+			top={0}
+			width={viewportWidth}
+			height={viewportHeight}
 			zIndex={20}
-			title=" Commands "
-			titleAlignment="left"
-			paddingLeft={1}
-			paddingRight={1}
-			style={{
-				border: true,
-				borderColor: colors.borderActive,
-				flexDirection: "column",
-				backgroundColor: colors.surface,
-			}}
+			style={{ backgroundColor: SCRIM }}
 		>
-			<text
-				wrapMode="none"
-				content={fit(`> ${query}▏`, rowWidth)}
-				style={{ fg: colors.textStrong }}
-			/>
-			<text content=" " />
-			{commands.length === 0 ? (
-				<text wrapMode="none" content="  (no matches)" style={{ fg: colors.textMuted }} />
-			) : (
-				visible.map((cmd, i) => {
-					const realIdx = scrollTop + i
-					const isSelected = realIdx === selectedIndex
-					const selector = isSelected ? "▸ " : "  "
-					const titleText = fit(cmd.title, titleWidth)
-					const shortcutText = cmd.shortcut
-						? fitRight(cmd.shortcut, SHORTCUT_WIDTH)
-						: " ".repeat(SHORTCUT_WIDTH)
-					// Title and shortcut render as separate spans so the shortcut
-					// can use `textMuted` while the title uses `text`/`textStrong`.
-					// Same trick opencode pulls with `--text-weak` — the theme
-					// guarantees the contrast, we just pick the right role.
-					const titleFg = isSelected ? colors.textStrong : colors.text
-					return (
-						<text key={cmd.id} wrapMode="none" style={isSelected ? { bg: colors.selectedBg } : {}}>
-							<span style={{ fg: titleFg }}>{`${selector}${titleText} `}</span>
-							<span style={{ fg: colors.textMuted }}>{shortcutText}</span>
-						</text>
-					)
-				})
-			)}
-			<text content=" " />
-			<text wrapMode="none" content={fit(FOOTER_HINT, rowWidth)} style={{ fg: colors.textMuted }} />
+			<box
+				position="absolute"
+				left={left}
+				top={top}
+				width={overlayWidth}
+				height={overlayHeight}
+				title=" Commands "
+				titleAlignment="left"
+				paddingLeft={1}
+				paddingRight={1}
+				style={{
+					border: true,
+					borderColor: colors.textMuted,
+					flexDirection: "column",
+					backgroundColor: colors.surface,
+				}}
+			>
+				<text
+					wrapMode="none"
+					content={fit(`> ${query}▏`, rowWidth)}
+					style={{ fg: colors.textStrong }}
+				/>
+				<text content=" " />
+				{commands.length === 0 ? (
+					<text wrapMode="none" content="  (no matches)" style={{ fg: colors.textMuted }} />
+				) : (
+					visible.map((cmd, i) => {
+						const realIdx = scrollTop + i
+						const isSelected = realIdx === selectedIndex
+						const selector = isSelected ? "▸ " : "  "
+						const titleText = fit(cmd.title, titleWidth)
+						const shortcutText = cmd.shortcut
+							? fitRight(cmd.shortcut, SHORTCUT_WIDTH)
+							: " ".repeat(SHORTCUT_WIDTH)
+						// Title and shortcut render as separate spans so the shortcut
+						// can use `textMuted` while the title uses `text`/`textStrong`.
+						// Same trick opencode pulls with `--text-weak` — the theme
+						// guarantees the contrast, we just pick the right role.
+						const titleFg = isSelected ? colors.textStrong : colors.text
+						return (
+							<text
+								key={cmd.id}
+								wrapMode="none"
+								style={isSelected ? { bg: colors.selectedBg } : {}}
+							>
+								<span style={{ fg: titleFg }}>{`${selector}${titleText} `}</span>
+								<span style={{ fg: colors.textMuted }}>{shortcutText}</span>
+							</text>
+						)
+					})
+				)}
+				<text content=" " />
+				<text
+					wrapMode="none"
+					content={fit(FOOTER_HINT, rowWidth)}
+					style={{ fg: colors.textMuted }}
+				/>
+			</box>
 		</box>
 	)
 }