@carlesandres/house 0.4.4 → 0.4.6

package/CHANGELOG.md

@@ -6,13 +6,54 @@ The publish workflow (`.github/workflows/publish.yml`) runs on the `release: pub
 
 ## [Unreleased]
 
+## [0.4.6] — 2026-05-25
+
+### Added
+
+- Reader empty states now show one tip at a time and rotate through a relevance-ordered set of workflow hints.
+
+### Changed
+
+- Startup behavior now uses `--focus <sidebar|reader|filter>`, `HOUSE_FOCUS`, and TOML `focus = "..."`; the built-in startup default is now `filter`.
+- Active filter/status metadata now uses the secondary theme token, matching opencode's use of `secondary` for active contextual metadata.
+- UI theme consumers now use the opencode-aligned `primary` token directly for strong emphasis and selected foreground.
+- UI chrome no longer uses house-only aliases (`surface`, `selectedBg`, `selectedBgInactive`), and background/backgroundPanel are no longer reordered by luminance.
+- Sidebar filtering now ranks basename matches above folder-only matches and softly prefers current-folder files over deeper nested paths, while keeping empty-query tree order unchanged.
+
+### Fixed
+
+- Tabbing away from the sidebar filter now lands on the reader without dropping filter mode, and the next `Tab` restores focus to the filter input instead of the sidebar list.
+- Batched key input no longer clears active filter focus unexpectedly during tab cycling.
+
+### Docs
+
+- Added semantic token usage guidance for supported theme tokens.
+- DESIGN now documents the sidebar filter's basename-first, pure-function ranking model.
+
+### Tests
+
+- Added headless and PTY regression coverage for filter tab-cycle focus restoration.
+
+## [0.4.5] — 2026-05-24
+
+### Changed
+
+- npm install/upgrade runtime baseline is now explicit: Node `>=22.22.2` is required when installing `@carlesandres/house` via npm, matching transitive engine requirements.
+
+### Docs
+
+- README now calls out the Node `>=22.22.2` requirement for npm-based install/upgrade.
+
+### Tests
+
+- CI now includes an npm global-install smoke matrix on Node `22.22.2` and Node `24` with `engine-strict=true`, catching runtime-floor regressions before release.
+
 ## [0.4.4] — 2026-05-24
 
 ### Added
 
 - Discovery visibility controls: new `--show <list>` CLI flag, `HOUSE_SHOW` env var, and TOML `show = ["..."]` config, replacing boolean discovery toggles with explicit categories (`hidden`, `gitignored`).
 - Session visibility toggle: `shift+a` flips discovery between the configured visibility set and showing all categories, preserving selection across the re-walk.
-- Launch-in-filter option: `--start-in-filter` CLI flag, `HOUSE_START_IN_FILTER` env var, and TOML `start_in_filter = true` open the sidebar filter prompt focused at startup.
 
 ### Changed
 
@@ -189,7 +230,9 @@ The v1 MVP, published as `@carlesandres/openmdr` on npm.
 
 Search, stdin, URL fetching, cross-file link following, `$EDITOR` hand-off, syntax highlighting, persistent config, OS-appearance auto-detect, single-binary distribution (issue [#2](https://github.com/carlesandres/openmdr/issues/2)), Homebrew tap. All tracked.
 
-[Unreleased]: https://github.com/carlesandres/house/compare/v0.4.4...HEAD
+[Unreleased]: https://github.com/carlesandres/house/compare/v0.4.6...HEAD
+[0.4.6]: https://github.com/carlesandres/house/compare/v0.4.5...v0.4.6
+[0.4.5]: https://github.com/carlesandres/house/compare/v0.4.4...v0.4.5
 [0.4.4]: https://github.com/carlesandres/house/compare/v0.4.3...v0.4.4
 [0.4.3]: https://github.com/carlesandres/house/compare/v0.4.2...v0.4.3
 [0.4.2]: https://github.com/carlesandres/house/compare/v0.4.1...v0.4.2

package/README.md

@@ -14,7 +14,14 @@ A terminal markdown reader and navigator — themable and configurable, with a k
 - **Open in browser**
 - **Open in `$EDITOR`**
 
-Requires [Bun](https://bun.sh) on `PATH`. Supported on macOS and Linux; Windows is unsupported and unvalidated (see [#129](https://github.com/carlesandres/house/issues/129)).
+Requires [Bun](https://bun.sh) on `PATH`.
+
+## Runtime requirements
+
+- Bun: required to run `house`.
+- npm install/upgrade path: Node `>=22.22.2` (Node 24 LTS recommended).
+
+Supported on macOS and Linux; Windows is unsupported and unvalidated (see [#129](https://github.com/carlesandres/house/issues/129)).
 
 ## Install
 
@@ -50,10 +57,10 @@ house [options] <path>
 | `--show <list>` | `""` | Reveal normally-skipped entries; comma-separated subset of `hidden`, `gitignored`. Use `--show ""` to clear. |
 | `--sort <mode>` | `dirs-first` | Sidebar order: `dirs-first` or `files-first` |
 | `--sidebar <mode>` | `auto` | Initial sidebar visibility: `auto`, `on`, or `off` |
+| `--focus <mode>` | `filter` | Startup focus: `sidebar`, `reader`, or `filter`. `filter` opens the sidebar filter prompt immediately. |
 | `--serve` | off | Serve the given file as HTML in the browser (skips TUI) |
 | `--port <N>` | OS-assigned | Port for `--serve` |
 | `--no-mdx` | off | Exclude `.mdx` files from discovery |
-| `--start-in-filter` | off | Open the sidebar filter prompt on launch so you can type a query immediately. Press Esc to dismiss. |
 | `--no-update-check` | off | Suppress the "newer version available" check (also via `NO_UPDATE_NOTIFIER=1`) |
 | `--config-path` | — | Print the resolved config-file path and exit |
 | `-h`, `--help` | — | Show help and exit |
@@ -75,19 +82,19 @@ theme = "tokyonight"
 tone  = "dark"
 mdx   = true
 show  = ["hidden", "gitignored"]
-start_in_filter = false
+focus = "filter"
 ```
 
-Supported keys: `theme`, `tone`, `mdx`, `show`, `start_in_filter`.
+Supported keys: `theme`, `tone`, `mdx`, `show`, `focus`.
 
 `show` is a list of normally-skipped categories to opt into. Known categories: `hidden` (dot-prefixed entries), `gitignored` (entries matched by a `.gitignore`). Default is the empty list. Hard skips (`node_modules`, `.git`, `.venv`) always apply.
 
 Precedence, highest to lowest:
 
-1. CLI flags (`--theme`, `--tone`, `--no-mdx`, `--show`, `--start-in-filter`)
-2. Env vars (`HOUSE_THEME`, `HOUSE_TONE`, `HOUSE_MDX`, `HOUSE_SHOW`, `HOUSE_START_IN_FILTER`)
+1. CLI flags (`--theme`, `--tone`, `--no-mdx`, `--show`, `--focus`)
+2. Env vars (`HOUSE_THEME`, `HOUSE_TONE`, `HOUSE_MDX`, `HOUSE_SHOW`, `HOUSE_FOCUS`)
 3. Config file
-4. Built-in defaults (`opencode` / `dark` / `mdx = true` / `show = []` / `start_in_filter = false`)
+4. Built-in defaults (`opencode` / `dark` / `mdx = true` / `show = []` / `focus = "filter"`)
 
 `HOUSE_SHOW` takes a comma-separated list (`HOUSE_SHOW=hidden,gitignored`). For `show` specifically, each source completely replaces the next — categories don't merge across layers. Press `shift+a` in the TUI to round-trip between the configured set and the full vocabulary without editing config.
 
@@ -142,6 +149,9 @@ The file is optional — a missing file is fine. Invalid keys, unknown themes, o
 
 Each theme supports dark and light tones. Cycle with `t` / `T`; toggle tone with `L`.
 
+For the supported semantic theme tokens and their intended usage, see
+[DESIGN.md §7.5](https://github.com/carlesandres/house/blob/main/DESIGN.md#75-theming).
+
 ## Inspiration
 
 - [glow](https://github.com/charmbracelet/glow) — render markdown on the CLI, with pizzazz

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@carlesandres/house",
-	"version": "0.4.4",
+	"version": "0.4.6",
 	"description": "TUI-first markdown reader on opentui",
 	"type": "module",
 	"license": "MIT",
@@ -12,6 +12,9 @@
 		"url": "https://github.com/carlesandres/house/issues"
 	},
 	"homepage": "https://github.com/carlesandres/house#readme",
+	"engines": {
+		"node": ">=22.22.2"
+	},
 	"keywords": [
 		"markdown",
 		"reader",
@@ -53,6 +56,7 @@
 		"@effect/atom-react": "4.0.0-beta.70",
 		"@opentui/core": "0.2.15",
 		"@opentui/react": "0.2.15",
+		"commander": "^14.0.3",
 		"effect": "4.0.0-beta.70",
 		"ignore": "^7.0.5",
 		"marked": "^18.0.4",

package/src/Browser.tsx

@@ -37,6 +37,7 @@ import {
 } from "./layout/resolve.ts"
 import { formatSidebarRow } from "./layout/sidebarRow.ts"
 import { PromptRow } from "./PromptRow.tsx"
+import { buildReaderEmptyStateTips, pickTipByRotation } from "./tips.ts"
 import { openInBrowser } from "./serve/openBrowser.ts"
 import { startServer, type ServerHandle } from "./serve/server.ts"
 import { colors, setActiveTheme } from "./theme/colors.ts"
@@ -44,6 +45,7 @@ import { themeAtom } from "./theme/atom.ts"
 import { themeDefinitions, getThemeDefinition } from "./theme/registry.ts"
 
 export type SidebarMode = "auto" | "on" | "off"
+export type StartupFocus = "sidebar" | "reader" | "filter"
 
 export interface BrowserProps {
 	readonly files: readonly FileEntry[]
@@ -72,10 +74,9 @@ export interface BrowserProps {
 	 *  from this side; we just snapshot the selected path so it can be
 	 *  restored across the re-walk the parent triggers. */
 	readonly onToggleAll?: () => void
-	/** Open the sidebar filter prompt on mount so the user can type
-	 *  immediately. Esc closes it through the normal close path — no
-	 *  special "first close" behavior. */
-	readonly startInFilter?: boolean
+	/** Startup pane/input target. `filter` opens the sidebar filter prompt on
+	 *  mount so the user can type immediately. */
+	readonly startupFocus?: StartupFocus | null
 }
 
 const defaultReadFile = (path: string): Promise<string> => Effect.runPromise(readFileText(path))
@@ -94,6 +95,16 @@ const HELP_ALLOWED_IDS: ReadonlySet<string> = new Set([
 	"palette.open",
 ])
 
+let nextReaderEmptyStateTipRotation = 0
+
+export const resetReaderEmptyStateTipRotationForTests = () => {
+	nextReaderEmptyStateTipRotation = 0
+}
+
+export const setReaderEmptyStateTipRotationForTests = (next: number) => {
+	nextReaderEmptyStateTipRotation = next
+}
+
 export const Browser = ({
 	files,
 	initialIndex = 0,
@@ -105,7 +116,7 @@ export const Browser = ({
 	updateNotice = null,
 	updateNoticeTtlMs = 10000,
 	onToggleAll,
-	startInFilter = false,
+	startupFocus = null,
 }: BrowserProps) => {
 	const renderer = useRenderer()
 	const { width, height } = useTerminalDimensions()
@@ -134,12 +145,23 @@ export const Browser = ({
 				return initialShownForAuto(width)
 		}
 	})
-	// startInFilter mirrors `openFilter`'s focus rule: the filter input lives
-	// in the sidebar, so opening it on mount also forces sidebar focus
-	// regardless of `--sidebar=off` (§7.1's visibility derivation surfaces
-	// the sidebar via focus even when `shown` is false).
+	const startInFilter = startupFocus === "filter"
+	const initialFocus: "sidebar" | "reader" =
+		startupFocus === null
+			? shown
+				? "sidebar"
+				: "reader"
+			: startupFocus === "reader"
+				? "reader"
+				: "sidebar"
+	// `filter` mirrors `openFilter`'s focus rule: the filter input lives in
+	// the sidebar, so opening it on mount also forces sidebar focus regardless
+	// of `--sidebar=off` (§7.1's visibility derivation surfaces the sidebar via
+	// focus even when `shown` is false). Plain `sidebar` startup shares the
+	// same pane focus without opening the prompt. When omitted, preserve the
+	// legacy Browser behavior: initial focus follows visibility.
 	const [focus, setFocus] = useState<"sidebar" | "reader">(() =>
-		shown || startInFilter ? "sidebar" : "reader",
+		shown || initialFocus === "sidebar" ? "sidebar" : "reader",
 	)
 	const [sidebarScroll, setSidebarScroll] = useState<number>(0)
 	const [helpVisible, setHelpVisible] = useState<boolean>(false)
@@ -155,12 +177,18 @@ export const Browser = ({
 	const paletteOpenRef = useRef(false)
 	const paletteQueryRef = useRef("")
 	const paletteIndexRef = useRef(0)
+	const [readerEmptyStateTipRotation, setReaderEmptyStateTipRotation] = useState(
+		() => nextReaderEmptyStateTipRotation,
+	)
+	const readerEmptyStateVisibleRef = useRef(false)
 	// 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(startInFilter)
 	const filterQueryRef = useRef("")
+	const focusRef = useRef<"sidebar" | "reader">(focus)
+	const restoreFilterOnSidebarFocusRef = useRef(startInFilter)
 	const [footerNotice, setFooterNoticeState] = useState<{
 		readonly text: string
 		readonly ttlMs: number
@@ -201,6 +229,10 @@ export const Browser = ({
 	// 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(() => {
+		focusRef.current = focus
+	}, [focus])
+
 	useEffect(() => {
 		if (!updateNotice) return
 		if (updateNoticeSeenRef.current === updateNotice) return
@@ -226,6 +258,7 @@ export const Browser = ({
 	}
 
 	const displayedFiles = useMemo(() => filterFiles(files, filterQuery), [files, filterQuery])
+	const filterHasNoMatches = filterQuery.length > 0 && displayedFiles.length === 0
 	// 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.
@@ -306,6 +339,7 @@ export const Browser = ({
 		sidebarShown: shown,
 		helpVisible,
 		filterOpen,
+		restoreFilterOnSidebarFocus: restoreFilterOnSidebarFocusRef.current,
 		filterQuery,
 		paletteOpen,
 		setFocus,
@@ -349,7 +383,9 @@ export const Browser = ({
 			// 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`.
+			focusRef.current = "sidebar"
 			if (focus !== "sidebar") setFocus("sidebar")
+			restoreFilterOnSidebarFocusRef.current = true
 			filterOpenRef.current = true
 			setFilterOpen(true)
 		},
@@ -360,7 +396,9 @@ export const Browser = ({
 			filterQueryRef.current = ""
 			setFilterQuery("")
 			setSelectedIndex(() => 0)
+			focusRef.current = "sidebar"
 			if (focus !== "sidebar") setFocus("sidebar")
+			restoreFilterOnSidebarFocusRef.current = true
 			filterOpenRef.current = true
 			setFilterOpen(true)
 		},
@@ -500,13 +538,14 @@ export const Browser = ({
 		// 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) {
+		if (filterOpenRef.current && focusRef.current === "sidebar") {
 			// 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
 				const effectiveCommit = commit && picked !== null
+				restoreFilterOnSidebarFocusRef.current = false
 				filterOpenRef.current = false
 				setFilterOpen(false)
 				// Where focus lands after the filter closes:
@@ -515,9 +554,12 @@ export const Browser = ({
 				//   otherwise → sidebar if it's up so j/k keeps walking the
 				//     filtered list; reader if the sidebar was hidden.
 				if (effectiveCommit) {
+					focusRef.current = "reader"
 					setFocus("reader")
 				} else {
-					setFocus(shown ? "sidebar" : "reader")
+					const nextFocus = shown ? "sidebar" : "reader"
+					focusRef.current = nextFocus
+					setFocus(nextFocus)
 				}
 			}
 			if (key.name === "escape") {
@@ -528,6 +570,14 @@ export const Browser = ({
 				closeFilter(true)
 				return
 			}
+			if (key.name === "tab" || (key.ctrl && key.name === "i" && !key.shift && !key.meta)) {
+				focusRef.current = "reader"
+				restoreFilterOnSidebarFocusRef.current = true
+				filterOpenRef.current = false
+				setFilterOpen(false)
+				setFocus("reader")
+				return
+			}
 			if (key.ctrl && key.name === "\\") {
 				// Same action as the `filter.clearOrOpen` binding fires from
 				// outside the modal: clear the query, reset selection. The
@@ -682,6 +732,21 @@ 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 readerEmptyStateTitle = filterHasNoMatches
+		? `No files match: ${filterQuery}`
+		: `${BRAND} ${BRAND_NAME}`
+	const readerEmptyStateVisible = error == null && renderedPath == null
+
+	useEffect(() => {
+		if (readerEmptyStateVisible) {
+			if (!readerEmptyStateVisibleRef.current) {
+				readerEmptyStateVisibleRef.current = true
+				setReaderEmptyStateTipRotation(nextReaderEmptyStateTipRotation++)
+			}
+			return
+		}
+		readerEmptyStateVisibleRef.current = false
+	}, [readerEmptyStateVisible])
 
 	// Sidebar virtualization: render only the visible window. Without this,
 	// every keystroke re-renders all N file rows even though only the bg of
@@ -732,6 +797,11 @@ export const Browser = ({
 				: browserBindings,
 		[helpVisible],
 	)
+	const readerEmptyStateTips = useMemo(() => buildReaderEmptyStateTips(browserBindings, ctx), [ctx])
+	const readerEmptyStateTip = useMemo(
+		() => pickTipByRotation(readerEmptyStateTips, readerEmptyStateTipRotation),
+		[readerEmptyStateTipRotation, readerEmptyStateTips],
+	)
 
 	// One sidebar body for both wide-inline and narrow-stack rendering; only
 	// the wrapper differs (fixed-width sibling vs flex-grow full-pane).
@@ -761,9 +831,17 @@ export const Browser = ({
 					const realIdx = desiredScroll + idx
 					const isSelected = realIdx === selectedIndex
 					const { basename, separator, parent } = layoutSidebarRow(file.relativePath)
-					const basenameFg = isSelected ? colors.textStrong : colors.text
+					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.selectedBg : colors.selectedBgInactive }
+						? { bg: sidebarActive ? colors.backgroundElement : colors.borderSubtle }
 						: {}
 					return (
 						<text key={file.path} wrapMode="none" style={rowStyle}>
@@ -801,14 +879,16 @@ export const Browser = ({
 	} as const
 
 	return (
-		<box style={{ width, height, flexDirection: "column", backgroundColor: colors.surface }}>
+		<box
+			style={{ width, height, flexDirection: "column", backgroundColor: colors.backgroundPanel }}
+		>
 			<Header width={width} currentFile={currentFile} />
 			<box
 				style={{
 					flexDirection: "row",
 					flexGrow: 1,
 					flexShrink: 1,
-					backgroundColor: colors.surface,
+					backgroundColor: colors.backgroundPanel,
 				}}
 			>
 				{sidebarInline && (
@@ -825,7 +905,7 @@ export const Browser = ({
 							// 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,
+							backgroundColor: colors.backgroundPanel,
 						}}
 						{...(isNarrow ? {} : { customBorderChars: SIDEBAR_BORDER_CHARS })}
 					>
@@ -835,7 +915,7 @@ export const Browser = ({
 								flexShrink: 1,
 								flexDirection: "column",
 								paddingLeft: 1,
-								backgroundColor: sidebarActive ? colors.background : colors.surface,
+								backgroundColor: sidebarActive ? colors.background : colors.backgroundPanel,
 							}}
 						>
 							{sidebarBody}
@@ -851,7 +931,7 @@ export const Browser = ({
 							flexShrink: 1,
 							flexDirection: "column",
 							// Dim by default (see sidebar note); inner body overrides when active.
-							backgroundColor: colors.surface,
+							backgroundColor: colors.backgroundPanel,
 						}}
 					>
 						<box
@@ -860,28 +940,38 @@ export const Browser = ({
 								flexShrink: 1,
 								flexDirection: "column",
 								padding: 1,
-								backgroundColor: readerActive ? colors.background : colors.surface,
+								backgroundColor: readerActive ? colors.background : colors.backgroundPanel,
 							}}
 						>
 							{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.
+								// welcome anchor; reusable tips live here too.
 								<box
 									style={{
 										flexGrow: 1,
 										flexShrink: 1,
 										alignItems: "center",
 										justifyContent: "center",
-										backgroundColor: readerActive ? colors.background : colors.surface,
+										backgroundColor: readerActive ? colors.background : colors.backgroundPanel,
 									}}
 								>
-									<text
-										content={`${BRAND} ${BRAND_NAME}`}
-										wrapMode="none"
-										style={{ fg: colors.textMuted }}
-									/>
+									<box style={{ flexDirection: "column", gap: 1, alignItems: "center" }}>
+										<text
+											content={readerEmptyStateTitle}
+											wrapMode="none"
+											style={{ fg: colors.textMuted }}
+										/>
+										{readerEmptyStateTip && (
+											<text
+												key={readerEmptyStateTip.id}
+												content={readerEmptyStateTip.text}
+												wrapMode="none"
+												style={{ fg: colors.textMuted }}
+											/>
+										)}
+									</box>
 								</box>
 							) : (
 								<scrollbox
@@ -890,7 +980,7 @@ export const Browser = ({
 										scrollX: false,
 										flexGrow: 1,
 										flexShrink: 1,
-										backgroundColor: readerActive ? colors.background : colors.surface,
+										backgroundColor: readerActive ? colors.background : colors.backgroundPanel,
 									}}
 									// opentui's scrollbox consumes arrow keys at the focused-element
 									// level *before* useKeyboard fires, so a modal that handles
@@ -907,7 +997,7 @@ export const Browser = ({
 										content={content}
 										syntaxStyle={syntaxStyle}
 										fg={colors.text}
-										bg={readerActive ? colors.background : colors.surface}
+										bg={readerActive ? colors.background : colors.backgroundPanel}
 										conceal
 										style={{ width: maxWidth ?? "100%" }}
 									/>

package/src/CommandPalette.tsx

@@ -102,7 +102,7 @@ export const CommandPalette = ({
 					border: true,
 					borderColor: colors.textMuted,
 					flexDirection: "column",
-					backgroundColor: colors.surface,
+					backgroundColor: colors.backgroundPanel,
 				}}
 			>
 				<PromptRow query={query} editing={true} width={rowWidth} />
@@ -119,15 +119,15 @@ export const CommandPalette = ({
 							? fitRight(cmd.shortcut, SHORTCUT_WIDTH)
 							: " ".repeat(SHORTCUT_WIDTH)
 						// Title and shortcut render as separate spans so the shortcut
-						// can use `textMuted` while the title uses `text`/`textStrong`.
+						// can use `textMuted` while the title uses `text`/`primary`.
 						// Same trick opencode pulls with `--text-weak` — the theme
 						// guarantees the contrast, we just pick the right role.
-						const titleFg = isSelected ? colors.textStrong : colors.text
+						const titleFg = isSelected ? colors.primary : colors.text
 						return (
 							<text
 								key={cmd.id}
 								wrapMode="none"
-								style={isSelected ? { bg: colors.selectedBg } : {}}
+								style={isSelected ? { bg: colors.backgroundElement } : {}}
 							>
 								<span style={{ fg: titleFg }}>{`${selector}${titleText} `}</span>
 								<span style={{ fg: colors.textMuted }}>{shortcutText}</span>

package/src/Footer.tsx

@@ -22,6 +22,7 @@
  */
 
 import type { KeyBinding } from "./keymap/keymap.ts"
+import { displayKey } from "./keymap/displayKey.ts"
 import { colors } from "./theme/colors.ts"
 
 /** Rows the Footer occupies. Importers use it for layout math so a future
@@ -46,31 +47,6 @@ export interface FooterProps<C> {
 
 const HINT_SEPARATOR = "  "
 
-/** Display form for the first key of a binding. Picks the first chord and
- *  rewrites a few names to terminal-friendly shorthands.
- *
- *  Footer policy: only the first key is shown, even when a binding has
- *  aliases (e.g. `sidebar.open` accepts `return`/`right`/`l`). The footer
- *  is a narrow real-estate budget, and listing every alias would push out
- *  other bindings on tight viewports. The full alias list lives in the
- *  help overlay (`?`). */
-const displayKey = (raw: string): string => {
-	switch (raw) {
-		case "return":
-			return "↵"
-		case "escape":
-			return "esc"
-		case "space":
-			return "␣"
-		case "pageup":
-			return "pgup"
-		case "pagedown":
-			return "pgdn"
-		default:
-			return raw
-	}
-}
-
 /** Hint row entries. `key === null` is a standalone chip (e.g. the filter
  *  chip) and renders as muted text without the key/label split. */
 interface Hint {
@@ -126,7 +102,7 @@ export const Footer = <C,>({
 		flexDirection: "row",
 		paddingLeft: 1,
 		paddingRight: 1,
-		backgroundColor: colors.surface,
+		backgroundColor: colors.backgroundPanel,
 	} as const
 
 	const hints: Hint[] = []
@@ -183,7 +159,7 @@ export const Footer = <C,>({
 			if (h.key === null) {
 				return [
 					...sep,
-					<text key={`l${i}`} content={h.label} wrapMode="none" style={{ fg: colors.textMuted }} />,
+					<text key={`l${i}`} content={h.label} wrapMode="none" style={{ fg: colors.secondary }} />,
 				]
 			}
 			return [
@@ -198,12 +174,12 @@ export const Footer = <C,>({
 			]
 		})
 
-	// Priority: notice > (status + hints). Notice fg is strong; status sits
-	// at the muted level so it reads as ambient state, not an event.
+	// Priority: notice > (status + hints). Discovery status uses the secondary
+	// token: active metadata, but not a warning/error event.
 	if (noticeContent !== null) {
 		return (
 			<box style={rowStyle}>
-				<text content={noticeContent} wrapMode="none" style={{ fg: colors.textStrong }} />
+				<text content={noticeContent} wrapMode="none" style={{ fg: colors.primary }} />
 			</box>
 		)
 	}
@@ -211,7 +187,7 @@ export const Footer = <C,>({
 	if (status !== null) {
 		return (
 			<box style={rowStyle}>
-				<text content={statusContent} wrapMode="none" style={{ fg: colors.textMuted }} />
+				<text content={statusContent} wrapMode="none" style={{ fg: colors.secondary }} />
 				<text content={STATUS_SEPARATOR} wrapMode="none" style={{ fg: colors.textMuted }} />
 				{renderHints()}
 			</box>

package/src/Header.tsx

@@ -58,7 +58,7 @@ export const Header = ({ width, currentFile, version = pkg.version }: HeaderProp
 				justifyContent: "space-between",
 				paddingLeft: 1,
 				paddingRight: 1,
-				backgroundColor: colors.surface,
+				backgroundColor: colors.backgroundPanel,
 			}}
 		>
 			<text content={left} wrapMode="none" style={{ fg: colors.text }} />

package/src/HelpOverlay.tsx

@@ -106,7 +106,7 @@ export const HelpOverlay = <C,>({
 					borderColor: colors.textMuted,
 					padding: 1,
 					flexDirection: "column",
-					backgroundColor: colors.surface,
+					backgroundColor: colors.backgroundPanel,
 				}}
 			>
 				{rows.map((row) => {