@carlesandres/house 0.3.1 → 0.4.1

package/src/Browser.tsx

@@ -11,32 +11,59 @@
  */
 
 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"
 import { useCallback, useEffect, useMemo, useRef, useState } from "react"
+import { buildCommands } from "./commands/buildCommands.ts"
+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"
 import { dispatch } from "./keymap/keymap.ts"
+import {
+	canFitInline,
+	defaultPreferredWidth,
+	initialShownForAuto,
+	resolveSidebarWidth,
+} from "./layout/resolve.ts"
 import { openInBrowser } from "./serve/openBrowser.ts"
 import { startServer, type ServerHandle } from "./serve/server.ts"
 import { colors, setActiveTheme } from "./theme/colors.ts"
 import { themeAtom } from "./theme/atom.ts"
 import { themeDefinitions, getThemeDefinition } from "./theme/registry.ts"
 
+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
+	/** Persistent footer indicator (e.g. "indexing… 42"). Pass null/undefined
+	 *  when discovery has finished; the indicator clears. */
+	readonly discoveryStatus?: string | null
+	/** Initial sidebar visibility (`--sidebar` flag). `auto` consults the
+	 *  launch viewport bucket once; subsequent visibility goes through `s`. */
+	readonly sidebarMode?: SidebarMode
 	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))
@@ -44,21 +71,27 @@ const defaultReadFile = (path: string): Promise<string> => Effect.runPromise(rea
 const clamp = (n: number, min: number, max: number) => Math.max(min, Math.min(max, n))
 
 /** Bindings the help overlay lets through. Single source of truth for both
- *  the keyboard early-return and the footer hint filter. */
+ *  the keyboard early-return and the footer hint filter. `palette.open`
+ *  passes through so users can jump from help into the palette in one
+ *  keystroke — `openPalette` closes help on its way in. */
 const HELP_ALLOWED_IDS: ReadonlySet<string> = new Set([
 	"help.toggle",
 	"theme.next",
 	"theme.prev",
 	"theme.toneToggle",
+	"palette.open",
 ])
 
 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()
@@ -71,19 +104,52 @@ export const Browser = ({
 	)
 	const [loaded, setLoaded] = useState<{ path: string; content: string } | null>(null)
 	const [error, setError] = useState<string | null>(null)
-	const [focus, setFocus] = useState<"sidebar" | "reader">("sidebar")
-	const [sidebarVisible, setSidebarVisible] = useState<boolean>(true)
+	// `shown` is the user's sticky preference. Visibility is derived:
+	// `visible = shown || focus === "sidebar"`. See DESIGN.md §7.1.
+	//
+	// Launch consults the viewport bucket once for `--sidebar=auto`. The
+	// useState initializer pins this to the first render — buckets are
+	// launch-only by design, so resize must NOT re-evaluate.
+	const [shown, setShown] = useState<boolean>(() => {
+		switch (sidebarMode) {
+			case "on":
+				return true
+			case "off":
+				return false
+			case "auto":
+				return initialShownForAuto(width)
+		}
+	})
+	const [focus, setFocus] = useState<"sidebar" | "reader">(() => (shown ? "sidebar" : "reader"))
 	const [sidebarScroll, setSidebarScroll] = useState<number>(0)
 	const [helpVisible, setHelpVisible] = useState<boolean>(false)
 	const [filterOpen, setFilterOpen] = useState<boolean>(false)
 	const [filterQuery, setFilterQuery] = useState<string>("")
+	const [paletteOpen, setPaletteOpen] = useState<boolean>(false)
+	const [paletteQuery, setPaletteQuery] = useState<string>("")
+	const [paletteIndex, setPaletteIndex] = useState<number>(0)
+	// Synchronous mirrors for the keyboard handler — same reason filterOpenRef
+	// exists. Modal input can arrive in one React batch (e.g. ctrl+p, Down,
+	// Return), so every palette field read by later keys must update its ref
+	// before React state commits.
+	const paletteOpenRef = useRef(false)
+	const paletteQueryRef = useRef("")
+	const paletteIndexRef = useRef(0)
 	// Mirror filter state into refs so the keyboard handler sees synchronous
 	// updates even when multiple keys arrive in a single React batch (the
 	// first key opens the filter; subsequent keys in the same tick would
 	// otherwise still observe filterOpen=false through closure).
 	const filterOpenRef = useRef(false)
 	const filterQueryRef = useRef("")
-	const [footerNotice, setFooterNotice] = useState<string | null>(null)
+	// Snapshot the query at filter-open so Esc reverts edits but commit (Return)
+	// keeps them.
+	const priorFilterQueryRef = useRef("")
+	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
@@ -95,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 = () => {
@@ -117,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])
@@ -181,17 +262,60 @@ export const Browser = ({
 	const ctx: BrowserCtx = {
 		files: displayedFiles,
 		focus,
-		sidebarVisible,
+		sidebarShown: shown,
 		helpVisible,
 		filterOpen,
+		paletteOpen,
 		setFocus,
 		setSelectedIndex,
-		setSidebarVisible,
+		toggleShown: () => {
+			// 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")
+			} else {
+				setShown(true)
+				if (focus === "reader") setFocus("sidebar")
+			}
+		},
 		setHelpVisible,
 		openFilter: () => {
+			// 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
 			setFilterOpen(true)
 		},
+		openPalette: () => {
+			// Close help if it was open — palette is the active modal now.
+			// Reset query/index so each open starts fresh (no stale state from
+			// the previous session).
+			if (helpVisible) setHelpVisible(() => false)
+			paletteQueryRef.current = ""
+			setPaletteQuery("")
+			paletteIndexRef.current = 0
+			setPaletteIndex(0)
+			paletteOpenRef.current = true
+			setPaletteOpen(true)
+		},
 		cycleTheme,
 		toggleTone,
 		serveCurrent: () => {
@@ -203,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
 			}
@@ -217,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) {
@@ -249,17 +373,48 @@ export const Browser = ({
 			//
 			// Centralized so the dual filterOpenRef / filterOpen invariant
 			// only has to be maintained in one place (plus `openFilter`).
-			const closeFilter = (focusReader: boolean) => {
+			const closeFilter = (commit: boolean) => {
 				const picked = displayedFiles[selectedIndex] ?? null
+				// Return on a zero-match list has nothing to commit. Treat it
+				// as Esc so the user isn't stranded in an "applied filter with
+				// no visible files" state they'd have to back out of manually.
+				const effectiveCommit = commit && picked !== null
 				filterOpenRef.current = false
-				filterQueryRef.current = ""
 				setFilterOpen(false)
-				setFilterQuery("")
-				if (picked) {
-					const fullIdx = files.findIndex((f) => f.path === picked.path)
-					if (fullIdx >= 0) setSelectedIndex(() => fullIdx)
+				if (effectiveCommit) {
+					// Return keeps the query. selectedIndex is already a valid
+					// position in the (still-filtered) displayedFiles list, so
+					// no translation is needed.
+				} else {
+					// Esc reverts the query to its pre-session value. After the
+					// revert, displayedFiles may change shape — translate the
+					// cursor by path so it stays on whatever the user was
+					// looking at, instead of snapping to a numerically-equivalent
+					// row in the restored list.
+					const before = priorFilterQueryRef.current
+					filterQueryRef.current = before
+					setFilterQuery(before)
+					if (picked) {
+						const restored = before === "" ? files : filterFiles(files, before)
+						const idx = restored.findIndex((f) => f.path === picked.path)
+						if (idx >= 0) setSelectedIndex(() => idx)
+					}
+				}
+				// 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) → 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 ? "sidebar" : "reader")
 				}
-				if (focusReader && picked) setFocus("reader")
 			}
 			if (key.name === "escape") {
 				closeFilter(false)
@@ -269,7 +424,15 @@ export const Browser = ({
 				closeFilter(true)
 				return
 			}
-			if (key.name === "backspace") {
+			if (key.name === "backspace" || key.name === "delete") {
+				// Pressing backspace/delete with no query left removes the
+				// leading `/` — i.e. closes the modal. Equivalent to Esc:
+				// reverts to the pre-session query (so an applied filter
+				// survives a "I changed my mind" tap).
+				if (filterQueryRef.current.length === 0) {
+					closeFilter(false)
+					return
+				}
 				filterQueryRef.current = filterQueryRef.current.slice(0, -1)
 				setFilterQuery(filterQueryRef.current)
 				setSelectedIndex(() => 0)
@@ -296,6 +459,74 @@ export const Browser = ({
 			}
 			return
 		}
+		// Command palette modal: capture keystrokes for the query input and
+		// list navigation. Esc closes (single press, regardless of query —
+		// #70 Q7a). Return runs the selected command. Up/Down navigate.
+		// Backspace edits the query and is a no-op on empty (#70 Q7b —
+		// intentionally diverges from the filter modal, which closes on
+		// empty-backspace, because accidental close feels worse in the
+		// palette). Printable characters extend the query and snap selection
+		// to 0 (#70 Q7c). Ctrl/Meta-modified keys are swallowed except
+		// ctrl+p, which toggles the palette closed (matches help-toggle's
+		// re-press-to-close behavior).
+		if (paletteOpenRef.current) {
+			const closePalette = () => {
+				paletteOpenRef.current = false
+				paletteQueryRef.current = ""
+				paletteIndexRef.current = 0
+				setPaletteOpen(false)
+				setPaletteQuery("")
+				setPaletteIndex(0)
+			}
+			const setPaletteIndexSync = (next: number) => {
+				paletteIndexRef.current = next
+				setPaletteIndex(next)
+			}
+			const allCommands = buildCommands(ctx)
+			const filtered = filterCommands(allCommands, paletteQueryRef.current)
+			if (key.name === "escape") {
+				closePalette()
+				return
+			}
+			if (key.name === "return") {
+				const picked = filtered[clampSelectedIndex(paletteIndexRef.current, filtered)]
+				closePalette()
+				picked?.run()
+				return
+			}
+			if (key.name === "up") {
+				setPaletteIndexSync(Math.max(0, paletteIndexRef.current - 1))
+				return
+			}
+			if (key.name === "down") {
+				setPaletteIndexSync(Math.min(Math.max(0, filtered.length - 1), paletteIndexRef.current + 1))
+				return
+			}
+			if (key.name === "backspace" || key.name === "delete") {
+				if (paletteQueryRef.current.length === 0) return
+				paletteQueryRef.current = paletteQueryRef.current.slice(0, -1)
+				setPaletteQuery(paletteQueryRef.current)
+				setPaletteIndexSync(0)
+				return
+			}
+			// ctrl+p again closes — matches help-toggle behavior.
+			if (key.ctrl && !key.meta && key.name === "p") {
+				closePalette()
+				return
+			}
+			if (key.ctrl || key.meta) return
+			let char: string | null = null
+			if (key.name === "space") char = " "
+			else if (typeof key.name === "string" && key.name.length === 1) {
+				char = key.shift ? key.name.toUpperCase() : key.name
+			}
+			if (char !== null) {
+				paletteQueryRef.current = paletteQueryRef.current + char
+				setPaletteQuery(paletteQueryRef.current)
+				setPaletteIndexSync(0)
+			}
+			return
+		}
 		// While help is open, swallow most keys: only ? (toggle), esc
 		// (close), and the theme bindings pass through. Theme keys stay live
 		// so users can preview palette changes against the overlay itself —
@@ -320,23 +551,40 @@ export const Browser = ({
 		dispatch(browserBindings, ctx, key)
 	})
 
-	// Min/max-clamped percentage of viewport: narrow terminals stay readable,
-	// wide terminals get more room without wasting space at extremes.
-	// User-configurable width is deferred — see DESIGN.md §12.
-	const sidebarWidth = Math.max(28, Math.min(60, Math.floor(width * 0.25)))
+	// Sidebar width is a pure function of viewport (DESIGN.md §7.1). Until
+	// persistent config (#13) lands, `preferred` is derived from viewport,
+	// matching the pre-#22 inline math.
+	const sidebarWidth = resolveSidebarWidth(width, defaultPreferredWidth(width))
 	const sidebarActive = focus === "sidebar"
 	const readerActive = focus === "reader"
-	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.
-	const sidebarBodyHeight = Math.max(1, height - 2 - FOOTER_HEIGHT)
+	// 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 - FOOTER_HEIGHT - HEADER_HEIGHT - 2 - (filterRowVisible ? 1 : 0),
+	)
 	const maxScroll = Math.max(0, displayedFiles.length - sidebarBodyHeight)
 	const desiredScroll = (() => {
 		let s = sidebarScroll
@@ -348,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(
@@ -358,6 +610,30 @@ export const Browser = ({
 		[sidebarTextWidth],
 	)
 
+	// Filter row content + color. Three reachable states:
+	//   editing  — filterOpen=true              → /<query>▏  in textStrong
+	//   applied  — !filterOpen && query !== ""  → /<query>   in text
+	//   idle     — !filterOpen && query === ""  → "/ filter…" in textMuted
+	const filterRowFg = filterOpen
+		? colors.textStrong
+		: filterQuery.length > 0
+			? colors.text
+			: colors.textMuted
+	const filterRowRaw = filterOpen
+		? `/${filterQuery}▏`
+		: filterQuery.length > 0
+			? `/${filterQuery}`
+			: "/ filter…"
+	// Editing keeps the cursor visible — anchor the right edge with a leading
+	// ellipsis when the query overflows. Applied/idle anchor the left edge
+	// (lose the tail) so the leading `/` always reads as a filter marker.
+	const filterRowContent =
+		filterRowRaw.length <= sidebarTextWidth
+			? filterRowRaw
+			: filterOpen
+				? "…" + filterRowRaw.slice(filterRowRaw.length - sidebarTextWidth + 1)
+				: filterRowRaw.slice(0, sidebarTextWidth - 1) + "…"
+
 	// While help is open, the `?` key closes the overlay — relabel its hint
 	// so the footer accurately describes what pressing the key will do.
 	// Memoized: `helpVisible` changes rarely; `browserBindings` and
@@ -372,110 +648,207 @@ export const Browser = ({
 		[helpVisible],
 	)
 
+	// 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 && (
+				<text content={filterRowContent} wrapMode="none" style={{ fg: filterRowFg }} />
+			)}
+			{displayedFiles.length === 0 ? (
+				<text
+					content={
+						files.length === 0
+							? discoveryActive
+								? "(scanning…)"
+								: "(no markdown files)"
+							: "(no matches)"
+					}
+					style={{ fg: colors.textMuted }}
+				/>
+			) : (
+				visibleFiles.map((file, idx) => {
+					const realIdx = desiredScroll + idx
+					const isSelected = realIdx === selectedIndex
+					const display = truncatePath(file.relativePath)
+					if (!isSelected) {
+						return (
+							<text key={file.path} content={display} wrapMode="none" style={{ fg: colors.text }} />
+						)
+					}
+					const bg = sidebarActive ? colors.selectedBg : colors.selectedBgInactive
+					return (
+						<text
+							key={file.path}
+							content={display}
+							wrapMode="none"
+							style={{ fg: colors.textStrong, bg }}
+						/>
+					)
+				})
+			)}
+		</>
+	)
+
+	// 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,
 				}}
 			>
-				{sidebarVisible && (
+				{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 })}
 					>
-						{displayedFiles.length === 0 ? (
-							<text
-								content={files.length === 0 ? "(no markdown files)" : "(no matches)"}
-								style={{ fg: colors.textMuted }}
-							/>
-						) : (
-							visibleFiles.map((file, idx) => {
-								const realIdx = desiredScroll + idx
-								const isSelected = realIdx === selectedIndex
-								const display = truncatePath(file.relativePath)
-								if (!isSelected) {
-									return (
-										<text
-											key={file.path}
-											content={display}
-											wrapMode="none"
-											style={{ fg: colors.text }}
-										/>
-									)
-								}
-								const bg = sidebarActive ? colors.selectedBg : colors.selectedBgInactive
-								return (
-									<text
-										key={file.path}
-										content={display}
-										wrapMode="none"
-										style={{ fg: colors.textStrong, bg }}
-									/>
-								)
-							})
-						)}
+						<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,
 							}}
-							focused={readerActive}
 						>
-							<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>
 			<Footer
 				bindings={footerBindings}
 				ctx={ctx}
 				width={width}
-				notice={footerNotice}
-				filter={filterOpen ? { query: filterQuery } : null}
+				notice={footerNotice?.text ?? null}
+				discoveryStatus={discoveryStatus}
+				filterQuery={!filterOpen && filterQuery.length > 0 ? filterQuery : null}
 			/>
 			{helpVisible && (
 				<HelpOverlay bindings={browserBindings} viewportWidth={width} viewportHeight={height} />
 			)}
+			{paletteOpen && (
+				<CommandPalette
+					commands={filterCommands(buildCommands(ctx), paletteQuery)}
+					query={paletteQuery}
+					selectedIndex={paletteIndex}
+					viewportWidth={width}
+					viewportHeight={height}
+				/>
+			)}
 		</box>
 	)
 }