@carlesandres/house 0.4.6 → 0.4.8

package/src/Browser.tsx

@@ -7,7 +7,7 @@
  *  - q / ctrl+c quit.
  *
  * Deferred to next iteration: focus model, reader scrolling via j/k,
- * sidebar collapse with `\`, help overlay.
+ * sidebar collapse with `\`.
  */
 
 import { SyntaxStyle } from "@opentui/core"
@@ -15,16 +15,16 @@ 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 { useCallback, useEffect, useMemo, useReducer, useRef, useState } from "react"
 import { buildCommands } from "./commands/buildCommands.ts"
 import { clampSelectedIndex, filterCommands } from "./commands/score.ts"
-import { CommandPalette } from "./CommandPalette.tsx"
+import { CommandPalette, orderCommandsForPalette } from "./CommandPalette.tsx"
 import { filterFiles } from "./discovery/filter.ts"
 import { type FileEntry } from "./discovery/walk.ts"
+import { parseFrontmatter } from "./markdown/frontmatter.ts"
 import { BRAND, BRAND_NAME } from "./brand.ts"
-import { Footer, FOOTER_HEIGHT } from "./Footer.tsx"
+import { Footer, FOOTER_HEIGHT, type FooterProps } 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"
@@ -35,8 +35,10 @@ import {
 	initialShownForAuto,
 	resolveSidebarWidth,
 } from "./layout/resolve.ts"
+import { fitSidebarEmptyValue } from "./layout/sidebarEmptyState.ts"
 import { formatSidebarRow } from "./layout/sidebarRow.ts"
 import { PromptRow } from "./PromptRow.tsx"
+import { StatusPopoverPanel } from "./StatusPopover.tsx"
 import { buildReaderEmptyStateTips, pickTipByRotation } from "./tips.ts"
 import { openInBrowser } from "./serve/openBrowser.ts"
 import { startServer, type ServerHandle } from "./serve/server.ts"
@@ -50,11 +52,26 @@ export type StartupFocus = "sidebar" | "reader" | "filter"
 export interface BrowserProps {
 	readonly files: readonly FileEntry[]
 	readonly initialIndex?: number
+	/** Initial applied filter query seeded from the CLI positional. */
+	readonly initialQuery?: string
 	/** Cap the rendered markdown's width at N columns. Null = fill the pane. */
 	readonly maxWidth?: number | null
+	/** Discovery root label used in the post-discovery empty-vault sidebar row. */
+	readonly emptyRootLabel?: string
 	/** Persistent footer indicator (e.g. "indexing… 42"). Pass null/undefined
 	 *  when discovery has finished; the indicator clears. */
 	readonly discoveryStatus?: string | null
+	/** Test seam: override the footer discovery spinner speed. */
+	readonly discoverySpinnerIntervalMs?: number
+	readonly discoverySpinnerInitialFrameIndex?: number
+	/** Test seam: deterministic footer spinner driver. */
+	readonly discoverySpinnerRegisterTick?: ((tick: () => void) => void) | null
+	/** Test seam: override filter debounce timing. */
+	readonly filterDebounceMs?: number
+	/** Test seam: override rendered-path debounce timing. */
+	readonly renderedPathDebounceMs?: number
+	/** Test seam: disable reader-empty-state tip rotation effect. */
+	readonly disableReaderEmptyStateRotation?: boolean
 	/** Initial sidebar visibility (`--sidebar` flag). `auto` consults the
 	 *  launch viewport bucket once; subsequent visibility goes through `s`. */
 	readonly sidebarMode?: SidebarMode
@@ -69,6 +86,8 @@ export interface BrowserProps {
 	/** 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
+	/** Test seam: disable footer-notice auto-clear timers. */
+	readonly disableFooterNoticeAutoClear?: boolean
 	/** Flip the parent's discovery vocabulary (#145). Browser doesn't need
 	 *  to know which categories are currently on — the toggle is opaque
 	 *  from this side; we just snapshot the selected path so it can be
@@ -83,18 +102,6 @@ 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. `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",
-])
-
 let nextReaderEmptyStateTipRotation = 0
 
 export const resetReaderEmptyStateTipRotationForTests = () => {
@@ -105,16 +112,96 @@ export const setReaderEmptyStateTipRotationForTests = (next: number) => {
 	nextReaderEmptyStateTipRotation = next
 }
 
+const FILTER_DEBOUNCE_MS = 50
+const RENDERED_PATH_DEBOUNCE_MS = 80
+
+const isPartialDiscoveryWarning = (status: string | null | undefined): boolean =>
+	status?.trimStart().startsWith("scan incomplete:") ?? false
+
+type FloatingOverlay =
+	| { readonly kind: "none" }
+	| { readonly kind: "command-palette" }
+	| { readonly kind: "status-popover"; readonly content: string }
+
+type FloatingOverlayAction =
+	| { readonly type: "close" }
+	| { readonly type: "open-command-palette" }
+	| { readonly type: "toggle-status-popover"; readonly content: string }
+	| { readonly type: "update-status-popover"; readonly content: string }
+
+const noFloatingOverlay: FloatingOverlay = { kind: "none" }
+
+const floatingOverlayReducer = (
+	state: FloatingOverlay,
+	action: FloatingOverlayAction,
+): FloatingOverlay => {
+	switch (action.type) {
+		case "close":
+			return noFloatingOverlay
+		case "open-command-palette":
+			return { kind: "command-palette" }
+		case "toggle-status-popover":
+			return state.kind === "status-popover"
+				? noFloatingOverlay
+				: { kind: "status-popover", content: action.content }
+		case "update-status-popover":
+			return state.kind === "status-popover"
+				? { kind: "status-popover", content: action.content }
+				: state
+	}
+}
+
+const SidebarEmptyMessage = ({
+	label,
+	value,
+	width,
+	withTopSpacer,
+}: {
+	readonly label: string
+	readonly value: string
+	readonly width: number
+	readonly withTopSpacer: boolean
+}) => (
+	<>
+		{withTopSpacer && <text content="" />}
+		<box
+			style={{
+				width,
+				flexDirection: "row",
+				flexWrap: "wrap",
+				justifyContent: "center",
+				gap: 1,
+			}}
+		>
+			<text wrapMode="none">
+				<span style={{ fg: colors.textMuted }}>{label}</span>
+			</text>
+			<text wrapMode="none">
+				<span style={{ fg: colors.textMuted }}>{`"${fitSidebarEmptyValue(value, width)}"`}</span>
+			</text>
+		</box>
+	</>
+)
+
 export const Browser = ({
 	files,
 	initialIndex = 0,
+	initialQuery = "",
 	maxWidth = null,
+	emptyRootLabel = "current root",
 	discoveryStatus = null,
+	discoverySpinnerIntervalMs,
+	discoverySpinnerInitialFrameIndex,
+	discoverySpinnerRegisterTick = null,
+	filterDebounceMs = FILTER_DEBOUNCE_MS,
+	renderedPathDebounceMs = RENDERED_PATH_DEBOUNCE_MS,
+	disableReaderEmptyStateRotation = false,
 	sidebarMode = "auto",
 	onQuit,
 	readFile = defaultReadFile,
 	updateNotice = null,
 	updateNoticeTtlMs = 10000,
+	disableFooterNoticeAutoClear = false,
 	onToggleAll,
 	startupFocus = null,
 }: BrowserProps) => {
@@ -164,17 +251,29 @@ export const Browser = ({
 		shown || initialFocus === "sidebar" ? "sidebar" : "reader",
 	)
 	const [sidebarScroll, setSidebarScroll] = useState<number>(0)
-	const [helpVisible, setHelpVisible] = useState<boolean>(false)
 	const [filterOpen, setFilterOpen] = useState<boolean>(startInFilter)
-	const [filterQuery, setFilterQuery] = useState<string>("")
-	const [paletteOpen, setPaletteOpen] = useState<boolean>(false)
+	const [filterInput, setFilterInput] = useState<string>(initialQuery)
+	const [filterApplied, setFilterApplied] = useState<string>(initialQuery)
+	const [floatingOverlay, dispatchFloatingOverlayState] = useReducer(
+		floatingOverlayReducer,
+		noFloatingOverlay,
+	)
+	const floatingOverlayRef = useRef<FloatingOverlay>(noFloatingOverlay)
+	const dispatchFloatingOverlay = (action: FloatingOverlayAction): void => {
+		const next = floatingOverlayReducer(floatingOverlayRef.current, action)
+		floatingOverlayRef.current = next
+		dispatchFloatingOverlayState(action)
+	}
+	const closeFloatingOverlay = (): void => dispatchFloatingOverlay({ type: "close" })
+	const paletteOpen = floatingOverlay.kind === "command-palette"
+	const activeStatusPopover = floatingOverlay.kind === "status-popover" ? floatingOverlay : null
+	const discoveryWarningStatus = isPartialDiscoveryWarning(discoveryStatus) ? discoveryStatus : null
 	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)
 	const [readerEmptyStateTipRotation, setReaderEmptyStateTipRotation] = useState(
@@ -186,7 +285,9 @@ export const Browser = ({
 	// first key opens the filter; subsequent keys in the same tick would
 	// otherwise still observe filterOpen=false through closure).
 	const filterOpenRef = useRef(startInFilter)
-	const filterQueryRef = useRef("")
+	const filterInputRef = useRef(initialQuery)
+	const filterAppliedRef = useRef(initialQuery)
+	const autoSelectForAppliedFilterRef = useRef(true)
 	const focusRef = useRef<"sidebar" | "reader">(focus)
 	const restoreFilterOnSidebarFocusRef = useRef(startInFilter)
 	const [footerNotice, setFooterNoticeState] = useState<{
@@ -220,9 +321,24 @@ export const Browser = ({
 	// the other's display window.
 	useEffect(() => {
 		if (footerNotice === null) return
+		closeFloatingOverlay()
+		if (disableFooterNoticeAutoClear) return
 		const timer = setTimeout(() => setFooterNoticeState(null), footerNotice.ttlMs)
 		return () => clearTimeout(timer)
-	}, [footerNotice])
+	}, [disableFooterNoticeAutoClear, footerNotice])
+
+	useEffect(() => {
+		if (discoveryWarningStatus === null) {
+			if (floatingOverlay.kind === "status-popover") closeFloatingOverlay()
+			return
+		}
+		if (
+			floatingOverlay.kind === "status-popover" &&
+			floatingOverlay.content !== discoveryWarningStatus
+		) {
+			dispatchFloatingOverlay({ type: "update-status-popover", content: discoveryWarningStatus })
+		}
+	}, [discoveryWarningStatus, floatingOverlay])
 
 	// Push the update-available nudge once, when it arrives from the parent
 	// (the registry probe resolves asynchronously after boot). 10s gives the
@@ -257,8 +373,29 @@ export const Browser = ({
 		pushFooterNotice(`tone: ${nextTone}`)
 	}
 
-	const displayedFiles = useMemo(() => filterFiles(files, filterQuery), [files, filterQuery])
-	const filterHasNoMatches = filterQuery.length > 0 && displayedFiles.length === 0
+	useEffect(() => {
+		if (filterInput === filterApplied) return
+		const timer = setTimeout(() => {
+			filterAppliedRef.current = filterInput
+			setFilterApplied(filterInput)
+		}, filterDebounceMs)
+		return () => clearTimeout(timer)
+	}, [filterApplied, filterDebounceMs, filterInput])
+
+	useEffect(() => {
+		autoSelectForAppliedFilterRef.current = true
+	}, [filterApplied])
+
+	const displayedFiles = useMemo(() => filterFiles(files, filterApplied), [files, filterApplied])
+	const filterHasNoMatches = filterInput.length > 0 && displayedFiles.length === 0
+
+	useEffect(() => {
+		if (filterApplied.length === 0) return
+		if (!autoSelectForAppliedFilterRef.current) return
+		if (displayedFiles.length === 0) return
+		setSelectedIndex(0)
+		autoSelectForAppliedFilterRef.current = false
+	}, [displayedFiles, filterApplied])
 	// When the filtered list shrinks, keep selectedIndex valid. The reset to 0
 	// on every query change happens in the keystroke handler, not here, so a
 	// no-op rerender doesn't snap the cursor back to the top.
@@ -296,9 +433,9 @@ export const Browser = ({
 	useEffect(() => {
 		const target = selected?.path ?? null
 		if (target === renderedPath) return
-		const timer = setTimeout(() => setRenderedPath(target), 80)
+		const timer = setTimeout(() => setRenderedPath(target), renderedPathDebounceMs)
 		return () => clearTimeout(timer)
-	}, [selected?.path, renderedPath])
+	}, [selected?.path, renderedPath, renderedPathDebounceMs])
 
 	useEffect(() => {
 		if (!renderedPath) {
@@ -337,10 +474,9 @@ export const Browser = ({
 		hasSelected: selected != null,
 		focus,
 		sidebarShown: shown,
-		helpVisible,
 		filterOpen,
 		restoreFilterOnSidebarFocus: restoreFilterOnSidebarFocusRef.current,
-		filterQuery,
+		filterQuery: filterInput,
 		paletteOpen,
 		setFocus,
 		// Wrapped so any keymap-driven selection move (j/k/g/G/[/], reader
@@ -350,6 +486,7 @@ export const Browser = ({
 		// itself) deliberately use the raw `setSelectedIndex` setter.
 		setSelectedIndex: (updater) => {
 			pendingSelectionPathRef.current = null
+			autoSelectForAppliedFilterRef.current = false
 			setSelectedIndex(updater)
 		},
 		toggleShown: () => {
@@ -376,8 +513,8 @@ export const Browser = ({
 				if (focus === "reader") setFocus("sidebar")
 			}
 		},
-		setHelpVisible,
 		openFilter: () => {
+			closeFloatingOverlay()
 			// 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,
@@ -390,11 +527,14 @@ export const Browser = ({
 			setFilterOpen(true)
 		},
 		clearAndOpenFilter: () => {
+			closeFloatingOverlay()
 			// 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("")
+			filterInputRef.current = ""
+			filterAppliedRef.current = ""
+			setFilterInput("")
+			setFilterApplied("")
 			setSelectedIndex(() => 0)
 			focusRef.current = "sidebar"
 			if (focus !== "sidebar") setFocus("sidebar")
@@ -403,16 +543,13 @@ export const Browser = ({
 			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)
+			dispatchFloatingOverlay({ type: "open-command-palette" })
 		},
 		cycleTheme,
 		toggleTone,
@@ -467,7 +604,7 @@ export const Browser = ({
 			if (!file) return
 			const editor = resolveEditor(process.env)
 			if (!editor) {
-				pushFooterNotice("set $EDITOR or $VISUAL to use e")
+				pushFooterNotice("set $EDITOR or $VISUAL to use E")
 				return
 			}
 			if (!renderer) {
@@ -526,6 +663,68 @@ export const Browser = ({
 	}
 
 	useKeyboard((key) => {
+		// Command palette modal: capture keystrokes for the query input and
+		// list navigation. This branch intentionally runs before the filter
+		// branch so ctrl+p can open the palette from filter mode while the
+		// palette still owns Esc/arrows/Return until it closes.
+		if (floatingOverlayRef.current.kind === "command-palette") {
+			const closePalette = () => {
+				paletteQueryRef.current = ""
+				paletteIndexRef.current = 0
+				closeFloatingOverlay()
+				setPaletteQuery("")
+				setPaletteIndex(0)
+			}
+			const setPaletteIndexSync = (next: number) => {
+				paletteIndexRef.current = next
+				setPaletteIndex(next)
+			}
+			const allCommands = buildCommands(ctx)
+			const filtered = orderCommandsForPalette(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.
+			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
+		}
+
 		// 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
@@ -543,6 +742,8 @@ export const Browser = ({
 			// 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) => {
+				filterAppliedRef.current = filterInputRef.current
+				setFilterApplied(filterInputRef.current)
 				const picked = displayedFiles[selectedIndex] ?? null
 				const effectiveCommit = commit && picked !== null
 				restoreFilterOnSidebarFocusRef.current = false
@@ -578,25 +779,31 @@ export const Browser = ({
 				setFocus("reader")
 				return
 			}
+			if (key.ctrl && !key.meta && key.name === "p") {
+				ctx.openPalette()
+				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("")
+				filterInputRef.current = ""
+				filterAppliedRef.current = ""
+				setFilterInput("")
+				setFilterApplied("")
 				setSelectedIndex(() => 0)
 				return
 			}
 			if (key.name === "backspace" || key.name === "delete") {
 				// Backspace on empty input closes the modal — the leading `/`
 				// chevron is the last thing left to "delete."
-				if (filterQueryRef.current.length === 0) {
+				if (filterInputRef.current.length === 0) {
 					closeFilter(false)
 					return
 				}
-				filterQueryRef.current = filterQueryRef.current.slice(0, -1)
-				setFilterQuery(filterQueryRef.current)
+				filterInputRef.current = filterInputRef.current.slice(0, -1)
+				setFilterInput(filterInputRef.current)
 				setSelectedIndex(() => 0)
 				return
 			}
@@ -615,101 +822,12 @@ export const Browser = ({
 				char = key.shift ? key.name.toUpperCase() : key.name
 			}
 			if (char !== null) {
-				filterQueryRef.current = filterQueryRef.current + char
-				setFilterQuery(filterQueryRef.current)
+				filterInputRef.current = filterInputRef.current + char
+				setFilterInput(filterInputRef.current)
 				setSelectedIndex(() => 0)
 			}
 			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 —
-		// it is the largest theme-painted surface in the app. Everything else
-		// is suppressed so the user can read without driving the UI behind.
-		// This is the one place we step outside the data-driven keymap; the
-		// alternative — adding `when: !c.helpVisible` to every other binding
-		// — would clutter the array. See DESIGN.md §12 (keymap composition).
-		if (helpVisible) {
-			if (key.name === "escape") {
-				setHelpVisible(() => false)
-				return
-			}
-			const allowed = browserBindings.filter((b) => HELP_ALLOWED_IDS.has(b.id))
-			// Defensive: stub quit even though no allowed binding currently
-			// calls it. Keeps the invariant local to this branch instead of
-			// relying on a future maintainer remembering not to add quit-ish
-			// bindings to HELP_ALLOWED_IDS.
-			dispatch(allowed, { ...ctx, quit: () => {} }, key)
-			return
-		}
 		dispatch(browserBindings, ctx, key)
 	})
 
@@ -732,12 +850,14 @@ export const Browser = ({
 	// per-pane border title that used to carry this information).
 	const currentFile = selected?.relativePath ?? null
 	const content = loaded?.path === renderedPath ? loaded.content : ""
+	const parsedContent = useMemo(() => parseFrontmatter(content), [content])
 	const readerEmptyStateTitle = filterHasNoMatches
-		? `No files match: ${filterQuery}`
+		? `No files match: ${filterInput}`
 		: `${BRAND} ${BRAND_NAME}`
 	const readerEmptyStateVisible = error == null && renderedPath == null
 
 	useEffect(() => {
+		if (disableReaderEmptyStateRotation) return
 		if (readerEmptyStateVisible) {
 			if (!readerEmptyStateVisibleRef.current) {
 				readerEmptyStateVisibleRef.current = true
@@ -746,7 +866,7 @@ export const Browser = ({
 			return
 		}
 		readerEmptyStateVisibleRef.current = false
-	}, [readerEmptyStateVisible])
+	}, [disableReaderEmptyStateRotation, readerEmptyStateVisible])
 
 	// Sidebar virtualization: render only the visible window. Without this,
 	// every keystroke re-renders all N file rows even though only the bg of
@@ -784,19 +904,27 @@ export const Browser = ({
 		[sidebarTextWidth],
 	)
 
-	// 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
-	// `HELP_ALLOWED_IDS` are module-level constants.
-	const footerBindings = useMemo(
-		() =>
-			helpVisible
-				? browserBindings
-						.filter((b) => HELP_ALLOWED_IDS.has(b.id))
-						.map((b) => (b.id === "help.toggle" ? { ...b, hint: "close" } : b))
-				: browserBindings,
-		[helpVisible],
-	)
+	const footerProps = {
+		bindings: browserBindings,
+		ctx,
+		width,
+		notice: footerNotice?.text ?? null,
+		discoveryStatus,
+		...(discoverySpinnerIntervalMs === undefined ? {} : { discoverySpinnerIntervalMs }),
+		...(discoverySpinnerInitialFrameIndex === undefined
+			? {}
+			: { discoverySpinnerInitialFrameIndex }),
+		...(discoverySpinnerRegisterTick === undefined ? {} : { discoverySpinnerRegisterTick }),
+		...(discoveryWarningStatus === null
+			? {}
+			: {
+					onDiscoveryWarningToggle: () =>
+						dispatchFloatingOverlay({
+							type: "toggle-status-popover",
+							content: discoveryWarningStatus,
+						}),
+				}),
+	} satisfies FooterProps<BrowserCtx>
 	const readerEmptyStateTips = useMemo(() => buildReaderEmptyStateTips(browserBindings, ctx), [ctx])
 	const readerEmptyStateTip = useMemo(
 		() => pickTipByRotation(readerEmptyStateTips, readerEmptyStateTipRotation),
@@ -809,40 +937,32 @@ export const Browser = ({
 		<>
 			{filterRowVisible && (
 				<PromptRow
-					query={filterQuery}
+					query={filterInput}
 					editing={filterOpen}
 					placeholder="/ to filter…"
 					width={sidebarTextWidth}
 				/>
 			)}
 			{displayedFiles.length === 0 ? (
-				<text
-					content={
+				<SidebarEmptyMessage
+					withTopSpacer={filterRowVisible}
+					width={sidebarTextWidth}
+					label={
 						files.length === 0
 							? discoveryActive
-								? "(scanning…)"
-								: "(no markdown files)"
-							: "(no matches)"
+								? "Scanning"
+								: "No markdown files in"
+							: "No files match"
 					}
-					style={{ fg: colors.textMuted }}
+					value={files.length === 0 ? (discoveryActive ? "…" : emptyRootLabel) : filterApplied}
 				/>
 			) : (
 				visibleFiles.map((file, idx) => {
 					const realIdx = desiredScroll + idx
 					const isSelected = realIdx === selectedIndex
 					const { basename, separator, parent } = layoutSidebarRow(file.relativePath)
-					const selectedFg =
-						colors.selectedListItemText === colors.background
-							? colors.primary
-							: colors.selectedListItemText
-					const basenameFg = isSelected
-						? sidebarActive
-							? selectedFg
-							: colors.primary
-						: colors.text
-					const rowStyle = isSelected
-						? { bg: sidebarActive ? colors.backgroundElement : colors.borderSubtle }
-						: {}
+					const basenameFg = isSelected ? colors.selectedListItemText : colors.text
+					const rowStyle = isSelected ? { bg: colors.backgroundElement } : {}
 					return (
 						<text key={file.path} wrapMode="none" style={rowStyle}>
 							<span style={{ fg: basenameFg }}>{basename}</span>
@@ -877,6 +997,7 @@ export const Browser = ({
 		rightT: "┤",
 		cross: "┼",
 	} as const
+	const INACTIVE_PANE_OPACITY = 0.62
 
 	return (
 		<box
@@ -897,7 +1018,7 @@ export const Browser = ({
 							// 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,
+							borderColor: colors.border,
 							...(isNarrow
 								? { flexGrow: 1, flexShrink: 1 }
 								: { width: sidebarWidth, flexShrink: 0 }),
@@ -916,6 +1037,7 @@ export const Browser = ({
 								flexDirection: "column",
 								paddingLeft: 1,
 								backgroundColor: sidebarActive ? colors.background : colors.backgroundPanel,
+								opacity: sidebarActive ? 1 : INACTIVE_PANE_OPACITY,
 							}}
 						>
 							{sidebarBody}
@@ -926,7 +1048,7 @@ export const Browser = ({
 					<box
 						style={{
 							border: readerBorderSides,
-							borderColor: colors.textMuted,
+							borderColor: colors.border,
 							flexGrow: 1,
 							flexShrink: 1,
 							flexDirection: "column",
@@ -941,6 +1063,7 @@ export const Browser = ({
 								flexDirection: "column",
 								padding: 1,
 								backgroundColor: readerActive ? colors.background : colors.backgroundPanel,
+								opacity: readerActive ? 1 : INACTIVE_PANE_OPACITY,
 							}}
 						>
 							{error ? (
@@ -984,17 +1107,38 @@ export const Browser = ({
 									}}
 									// 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
+									// arrow keys itself (palette nav) 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}
+									focused={readerActive && !paletteOpen}
 								>
+									{parsedContent.fields.length > 0 && (
+										<box style={{ flexDirection: "column", marginBottom: 1 }}>
+											{parsedContent.fields.map((field) => (
+												<box
+													key={field.key}
+													style={{ flexDirection: "row", gap: 1, flexWrap: "wrap" }}
+												>
+													<text
+														content={`${field.key}:`}
+														wrapMode="word"
+														style={{ fg: colors.secondary }}
+													/>
+													<text
+														content={field.value}
+														wrapMode="word"
+														style={{ fg: colors.textMuted }}
+													/>
+												</box>
+											))}
+										</box>
+									)}
 									<markdown
 										key={renderedPath ?? "empty"}
-										content={content}
+										content={parsedContent.body}
 										syntaxStyle={syntaxStyle}
 										fg={colors.text}
 										bg={readerActive ? colors.background : colors.backgroundPanel}
@@ -1007,26 +1151,19 @@ export const Browser = ({
 					</box>
 				)}
 			</box>
-			<Footer
-				bindings={footerBindings}
-				ctx={ctx}
-				width={width}
-				notice={footerNotice?.text ?? null}
-				discoveryStatus={discoveryStatus}
-				filterQuery={!filterOpen && filterQuery.length > 0 ? filterQuery : null}
-			/>
-			{helpVisible && (
-				<HelpOverlay bindings={browserBindings} viewportWidth={width} viewportHeight={height} />
-			)}
+			<Footer {...footerProps} />
 			{paletteOpen && (
 				<CommandPalette
-					commands={filterCommands(buildCommands(ctx), paletteQuery)}
+					commands={orderCommandsForPalette(filterCommands(buildCommands(ctx), paletteQuery))}
 					query={paletteQuery}
 					selectedIndex={paletteIndex}
 					viewportWidth={width}
 					viewportHeight={height}
 				/>
 			)}
+			{activeStatusPopover && (
+				<StatusPopoverPanel content={activeStatusPopover.content} variant="warning" />
+			)}
 		</box>
 	)
 }