@carlesandres/house 0.4.0 → 0.4.2

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,8 +21,11 @@ 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 { openInEditor, resolveEditor } from "./io/editor.ts"
 import { readFileText } from "./io/readFile.ts"
 import { browserBindings, type BrowserCtx } from "./keymap/browser.ts"
 import { dispatch } from "./keymap/keymap.ts"
@@ -31,6 +35,8 @@ import {
 	initialShownForAuto,
 	resolveSidebarWidth,
 } from "./layout/resolve.ts"
+import { formatSidebarRow } from "./layout/sidebarRow.ts"
+import { PromptRow } from "./PromptRow.tsx"
 import { openInBrowser } from "./serve/openBrowser.ts"
 import { startServer, type ServerHandle } from "./serve/server.ts"
 import { colors, setActiveTheme } from "./theme/colors.ts"
@@ -41,7 +47,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 +59,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 +87,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()
@@ -130,11 +144,12 @@ export const Browser = ({
 	// otherwise still observe filterOpen=false through closure).
 	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.
-	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])
@@ -231,21 +261,31 @@ export const Browser = ({
 	// operate on what the user actually sees.
 	const ctx: BrowserCtx = {
 		files: displayedFiles,
+		hasSelected: selected != null,
 		focus,
 		sidebarShown: shown,
 		helpVisible,
 		filterOpen,
+		filterQuery,
 		paletteOpen,
 		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,11 +296,22 @@ 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.
-			priorFilterQueryRef.current = filterQueryRef.current
+			// 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`.
+			if (focus !== "sidebar") setFocus("sidebar")
+			filterOpenRef.current = true
+			setFilterOpen(true)
+		},
+		clearAndOpenFilter: () => {
+			// Reset both the ref and the state so the freshly-opened modal
+			// shows an empty input and selection lands on the first file in
+			// the (now unfiltered) list.
+			filterQueryRef.current = ""
+			setFilterQuery("")
+			setSelectedIndex(() => 0)
 			if (focus !== "sidebar") setFocus("sidebar")
 			filterOpenRef.current = true
 			setFilterOpen(true)
@@ -288,9 +339,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 +353,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) {
@@ -312,67 +363,100 @@ export const Browser = ({
 			renderer?.destroy()
 			process.exit(0)
 		},
+		editCurrent: () => {
+			const file = displayedFiles[selectedIndex]
+			if (!file) return
+			const editor = resolveEditor(process.env)
+			if (!editor) {
+				pushFooterNotice("set $EDITOR or $VISUAL to use e")
+				return
+			}
+			if (!renderer) {
+				// Test environments without a real renderer (e.g. testRender's
+				// host) don't expose suspend/resume. Nothing safe to do here.
+				pushFooterNotice("editor unavailable in this environment")
+				return
+			}
+			// Fire-and-forget: useKeyboard's run() is synchronous, but the
+			// editor session is naturally async. We always re-enter the
+			// renderer in the finally block so a thrown error never leaves
+			// the user staring at a dead terminal.
+			void (async () => {
+				renderer.suspend()
+				renderer.currentRenderBuffer.clear()
+				let result
+				try {
+					result = await openInEditor({ editor, filePath: file.path })
+				} finally {
+					renderer.currentRenderBuffer.clear()
+					renderer.resume()
+					renderer.requestRender()
+				}
+				// Only reload the in-memory cache when the edited file is the
+				// one currently displayed. Editing a sidebar-selected file that
+				// the reader hasn't caught up to (debounce in flight) is fine —
+				// the regular load path picks up the new mtime when renderedPath
+				// advances.
+				if (file.path === renderedPath) {
+					try {
+						const text = await readFile(file.path)
+						setLoaded({ path: file.path, content: text })
+						setError(null)
+					} catch (err) {
+						const message = String(err)
+						const enoent =
+							(err as { code?: string } | null)?.code === "ENOENT" || message.includes("ENOENT")
+						if (enoent) {
+							pushFooterNotice(`${file.relativePath} no longer exists`)
+							setError(`Cannot read ${file.path}: ${message}`)
+							setLoaded(null)
+						} else {
+							pushFooterNotice(`reload failed: ${message}`)
+						}
+					}
+				}
+				if (!result.ok) {
+					if (result.reason === "spawn-failed") {
+						pushFooterNotice(`editor not found: ${editor.cmd}`)
+					} else if (result.reason === "non-zero") {
+						pushFooterNotice(`editor exited ${result.detail}`)
+					}
+				}
+			})()
+		},
 	}
 
 	useKeyboard((key) => {
-		// Filter modal: capture keystrokes for the input. Esc closes and
-		// clears; Return closes, clears, and focuses the reader (open the
-		// match); Backspace edits; Up/Down navigate the filtered list;
-		// printable characters extend the query and reset selection to 0.
-		// Everything else is swallowed so normal bindings (j/k as nav,
-		// `s`, `t`, …) don't fire while the user is typing. This sits
-		// outside the data-driven keymap for the same reason the help
-		// branch does — see DESIGN.md §12.
+		// Filter modal: capture keystrokes for the input. Esc closes,
+		// leaving the typed query applied as the active filter; Return
+		// closes and focuses the reader (open the match); Ctrl+\ clears
+		// the input but stays in filter mode (same binding used from
+		// outside the modal — single chord, single mental model. Ctrl+U
+		// is deliberately not overloaded here; it stays reserved for its
+		// sidebar/reader half-page-up role); Backspace edits; Up/Down
+		// navigate the filtered list; printable characters extend the
+		// query and reset selection to 0. Everything else is swallowed
+		// so normal bindings (j/k as nav, `s`, `t`, …) don't fire while
+		// the user is typing. This sits outside the data-driven keymap
+		// for the same reason the help branch does — see DESIGN.md §12.
 		if (filterOpenRef.current) {
-			// One close path used by both Esc and Return. Closing the filter
-			// restores the full list; translating the highlighted match to
-			// its index in `files` keeps the cursor on whatever the user was
-			// looking at when they hit the key, instead of landing on a
-			// random file at the same numeric position in a now-different
-			// list. `focusReader=true` is the Return semantic (open the
-			// match); false is Esc (cancel, stay in sidebar).
-			//
-			// Centralized so the dual filterOpenRef / filterOpen invariant
-			// only has to be maintained in one place (plus `openFilter`).
+			// One close path used by both Esc and Return. `commit=true` is
+			// the Return semantic (open the match in the reader); false is
+			// Esc (stop typing, keep the applied filter, stay in sidebar).
 			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
 				setFilterOpen(false)
-				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 depends on layout intent (DESIGN.md §7.1):
-				//   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.
+				// Where focus lands after the filter closes:
+				//   commit (Return on a real pick) → reader. The user asked
+				//     to open the match; show them what they picked.
+				//   otherwise → sidebar if it's up so j/k keeps walking the
+				//     filtered list; reader if the sidebar was hidden.
 				if (effectiveCommit) {
 					setFocus("reader")
 				} else {
-					setFocus(shown && canFitInline(width) ? "sidebar" : "reader")
+					setFocus(shown ? "sidebar" : "reader")
 				}
 			}
 			if (key.name === "escape") {
@@ -383,11 +467,19 @@ export const Browser = ({
 				closeFilter(true)
 				return
 			}
+			if (key.ctrl && key.name === "\\") {
+				// Same action as the `filter.clearOrOpen` binding fires from
+				// outside the modal: clear the query, reset selection. The
+				// keymap doesn't see keys in filter mode, so this branch is
+				// the in-modal half of that single chord.
+				filterQueryRef.current = ""
+				setFilterQuery("")
+				setSelectedIndex(() => 0)
+				return
+			}
 			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).
+				// Backspace on empty input closes the modal — the leading `/`
+				// chevron is the last thing left to "delete."
 				if (filterQueryRef.current.length === 0) {
 					closeFilter(false)
 					return
@@ -516,42 +608,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,40 +647,17 @@ 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)
-	// Right-anchored truncation: keep the filename visible, lose the prefix
-	// with a leading ellipsis when the path is too long.
-	const truncatePath = useCallback(
-		(s: string): string =>
-			s.length <= sidebarTextWidth ? s : "…" + s.slice(s.length - sidebarTextWidth + 1),
+	// 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))
+	const layoutSidebarRow = useCallback(
+		(relativePath: string) => formatSidebarRow(relativePath, sidebarTextWidth),
 		[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
@@ -612,13 +672,17 @@ 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 && (
-				<text content={filterRowContent} wrapMode="none" style={{ fg: filterRowFg }} />
+				<PromptRow
+					query={filterQuery}
+					editing={filterOpen}
+					placeholder="/ to filter…"
+					width={sidebarTextWidth}
+				/>
 			)}
 			{displayedFiles.length === 0 ? (
 				<text
@@ -635,127 +699,168 @@ export const Browser = ({
 				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
+					const { basename, separator, parent } = layoutSidebarRow(file.relativePath)
+					const basenameFg = isSelected ? colors.textStrong : colors.text
+					const rowStyle = isSelected
+						? { bg: sidebarActive ? colors.selectedBg : colors.selectedBgInactive }
+						: {}
 					return (
-						<text
-							key={file.path}
-							content={display}
-							wrapMode="none"
-							style={{ fg: colors.textStrong, bg }}
-						/>
+						<text key={file.path} wrapMode="none" style={rowStyle}>
+							<span style={{ fg: basenameFg }}>{basename}</span>
+							{parent !== "" && (
+								<span style={{ fg: colors.textMuted }}>{`${separator}${parent}`}</span>
+							)}
+						</text>
 					)
 				})
 			)}
 		</>
 	)
 
+	// 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}
 			/>