@carlesandres/house 0.4.1 → 0.4.3

package/CHANGELOG.md

@@ -6,6 +6,40 @@ The publish workflow (`.github/workflows/publish.yml`) runs on the `release: pub
 
 ## [Unreleased]
 
+## [0.4.3] — 2026-05-23
+
+### Fixed
+
+- Dependency alignment: bumped `effect` to `4.0.0-beta.70` to match `@effect/atom-react@4.0.0-beta.70`, removing npm `ERESOLVE overriding peer dependency` warnings during global installs.
+
+## [0.4.2] — 2026-05-23
+
+### Added
+
+- Editor hand-off: press `e` to open the selected file in `$EDITOR`/`$VISUAL` (`#19`).
+- Sidebar rows now render basename-first with segment-aware parent-path elision, improving scanability in deep trees.
+- `ctrl+\\` clears an active sidebar filter query without leaving filter mode.
+
+### Changed
+
+- Sidebar filter input and command palette input now share a single `PromptRow` UI path for consistent rendering and behavior.
+
+### Fixed
+
+- Dev server SSE stream (`/__reload`) now stays open past Bun's 10s idle timeout.
+- Filter Escape behavior no longer reverts to the pre-filter selection; Escape now closes/clears filter predictably.
+
+### Docs
+
+- README synced with current features, options, keys, and config behavior.
+- Windows support is now documented as POSIX-only for this release line, with tracking issues linked.
+- ROADMAP docs updated for release tooling and standalone-binary epic breakdown.
+
+### Tests
+
+- Added PTY regression coverage for selection background behavior.
+- Added sidebar coverage for basename+parent rendering and `fitTail` behavior at very narrow widths.
+
 ## [0.4.1] — 2026-05-22
 
 ### Added
@@ -139,4 +173,13 @@ 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.1...HEAD [0.4.1]: https://github.com/carlesandres/house/compare/v0.4.0...v0.4.1 [0.4.0]: https://github.com/carlesandres/house/compare/v0.3.1...v0.4.0 [0.3.1]: https://github.com/carlesandres/house/compare/v0.3.0...v0.3.1 [0.3.0]: https://github.com/carlesandres/house/compare/v0.2.1...v0.3.0 [0.2.1]: https://github.com/carlesandres/house/compare/v0.2.0...v0.2.1 [0.2.0]: https://github.com/carlesandres/house/compare/v0.1.0...v0.2.0 [0.1.0]: https://github.com/carlesandres/house/releases/tag/v0.1.0
+[Unreleased]: https://github.com/carlesandres/house/compare/v0.4.3...HEAD
+[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
+[0.4.1]: https://github.com/carlesandres/house/compare/v0.4.0...v0.4.1
+[0.4.0]: https://github.com/carlesandres/house/compare/v0.3.1...v0.4.0
+[0.3.1]: https://github.com/carlesandres/house/compare/v0.3.0...v0.3.1
+[0.3.0]: https://github.com/carlesandres/house/compare/v0.2.1...v0.3.0
+[0.2.1]: https://github.com/carlesandres/house/compare/v0.2.0...v0.2.1
+[0.2.0]: https://github.com/carlesandres/house/compare/v0.1.0...v0.2.0
+[0.1.0]: https://github.com/carlesandres/house/releases/tag/v0.1.0

package/README.md

@@ -12,8 +12,9 @@ A terminal markdown reader and navigator — themable and configurable, with a k
 - **Command palette**
 - **Keyboard-driven**
 - **Open in browser**
+- **Open in `$EDITOR`**
 
-Requires [Bun](https://bun.sh) on `PATH`.
+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)).
 
 ## Install
 
@@ -37,7 +38,7 @@ bun add -g @carlesandres/house
 house [options] <path>
 ```
 
-`<path>` can be a directory (walks for `.md` files) or a single `.md` file.
+`<path>` can be a directory (walks for `.md`, `.markdown`, and `.mdx` files) or a single markdown file. Defaults to the current directory if omitted.
 
 ### Options
 
@@ -45,7 +46,17 @@ house [options] <path>
 |------|---------|-------------|
 | `--theme <name>` | `opencode` | Starting theme (see list below) |
 | `--tone dark\|light` | `dark` | Starting tone |
+| `--width <N>` | — | Cap rendered markdown width at N columns |
+| `--all` | off | Include hidden and gitignored files in discovery |
+| `--sort <mode>` | `dirs-first` | Sidebar order: `dirs-first` or `files-first` |
+| `--sidebar <mode>` | `auto` | Initial sidebar visibility: `auto`, `on`, or `off` |
+| `--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 |
+| `--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 |
+| `-v`, `--version` | — | Print version and exit |
 
 ## Configuration
 
@@ -61,14 +72,17 @@ Run `house --config-path` to print the exact location.
 # ~/.config/house/config.toml
 theme = "tokyonight"
 tone  = "dark"
+mdx   = true
 ```
 
+Supported keys: `theme`, `tone`, `mdx`.
+
 Precedence, highest to lowest:
 
-1. CLI flags (`--theme`, `--tone`)
-2. Env vars (`HOUSE_THEME`, `HOUSE_TONE`)
+1. CLI flags (`--theme`, `--tone`, `--no-mdx`)
+2. Env vars (`HOUSE_THEME`, `HOUSE_TONE`, `HOUSE_MDX`)
 3. Config file
-4. Built-in defaults (`opencode` / `dark`)
+4. Built-in defaults (`opencode` / `dark` / `mdx = true`)
 
 The file is optional — a missing file is fine. Invalid keys, unknown themes, or malformed TOML fail loudly with a one-line error. Per-project config (`.house/config.toml`) and additional keys are deferred.
 
@@ -82,7 +96,9 @@ The file is optional — a missing file is fine. Invalid keys, unknown themes, o
 | `tab` | Toggle focus (sidebar ↔ reader) |
 | `s` | Toggle sidebar visibility |
 | `?` | Show / dismiss help overlay |
+| `ctrl+p` | Command palette |
 | `o` | Open current file in browser as HTML |
+| `e` | Open current file in `$EDITOR` (`$VISUAL` takes precedence) |
 | `t` | Next theme |
 | `T` | Previous theme |
 | `L` | Toggle dark / light tone |
@@ -123,6 +139,7 @@ Each theme supports dark and light tones. Cycle with `t` / `T`; toggle tone with
 - [glow](https://github.com/charmbracelet/glow) — render markdown on the CLI, with pizzazz
 - [ghui](https://github.com/kitlangton/ghui) — keyboard-driven terminal UI for GitHub pull requests
 - [hunk](https://github.com/modem-dev/hunk) — review-first terminal diff viewer for agent-authored changesets
+- [opencode](https://github.com/anomalyco/opencode) — terminal UI whose palette inspired house's themes
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@carlesandres/house",
-	"version": "0.4.1",
+	"version": "0.4.3",
 	"description": "TUI-first markdown reader on opentui",
 	"type": "module",
 	"license": "MIT",
@@ -44,26 +44,28 @@
 		"format": "oxfmt src/",
 		"format:check": "oxfmt --check src/",
 		"test": "bun test",
+		"test:pty": "HOUSE_PTY=1 bun test test/pty/",
 		"build:themes": "bun run dev/build-themes.ts",
 		"repro:pty-codeblocks": "bun run dev/repro-pty-codeblocks.ts",
 		"prepare": "git config core.hooksPath .githooks 2>/dev/null || true"
 	},
 	"dependencies": {
-		"@effect/atom-react": "4.0.0-beta.59",
-		"@opentui/core": "0.2.12",
-		"@opentui/react": "0.2.12",
-		"effect": "4.0.0-beta.59",
+		"@effect/atom-react": "4.0.0-beta.70",
+		"@opentui/core": "0.2.15",
+		"@opentui/react": "0.2.15",
+		"effect": "4.0.0-beta.70",
 		"ignore": "^7.0.5",
-		"marked": "^18.0.3",
-		"react": "19.2.5",
+		"marked": "^18.0.4",
+		"react": "19.2.6",
 		"scheduler": "0.27.0"
 	},
 	"devDependencies": {
-		"@effect/language-service": "0.85.1",
-		"@types/bun": "1.3.12",
-		"@types/react": "19.2.14",
-		"oxfmt": "0.47.0",
-		"oxlint": "1.62.0",
-		"typescript": "6.0.2"
+		"@effect/language-service": "0.86.2",
+		"@types/bun": "1.3.14",
+		"@types/react": "19.2.15",
+		"oxfmt": "0.51.0",
+		"oxlint": "1.66.0",
+		"tuistory": "^0.8.0",
+		"typescript": "6.0.3"
 	}
 }

package/src/Browser.tsx

@@ -25,6 +25,7 @@ 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"
@@ -34,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"
@@ -141,9 +144,6 @@ 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.
-	const priorFilterQueryRef = useRef("")
 	const [footerNotice, setFooterNoticeState] = useState<{
 		readonly text: string
 		readonly ttlMs: number
@@ -261,10 +261,12 @@ 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,
@@ -299,7 +301,17 @@ 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`.
-			priorFilterQueryRef.current = filterQueryRef.current
+			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)
@@ -351,65 +363,96 @@ 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 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.
+				//   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 {
@@ -424,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
@@ -602,38 +653,11 @@ export const Browser = ({
 	// 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(
-		(s: string): string =>
-			s.length <= sidebarTextWidth ? s : "…" + s.slice(s.length - sidebarTextWidth + 1),
+	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
@@ -653,7 +677,12 @@ export const Browser = ({
 	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
@@ -670,20 +699,18 @@ 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>
 					)
 				})
 			)}

package/src/CommandPalette.tsx

@@ -11,6 +11,7 @@
 
 import { RGBA } from "@opentui/core"
 import { colors } from "./theme/colors.ts"
+import { PromptRow } from "./PromptRow.tsx"
 import type { AppCommand } from "./commands/types.ts"
 
 // Semi-transparent black scrim painted across the viewport behind the modal.
@@ -104,11 +105,7 @@ export const CommandPalette = ({
 					backgroundColor: colors.surface,
 				}}
 			>
-				<text
-					wrapMode="none"
-					content={fit(`> ${query}▏`, rowWidth)}
-					style={{ fg: colors.textStrong }}
-				/>
+				<PromptRow query={query} editing={true} width={rowWidth} />
 				<text content=" " />
 				{commands.length === 0 ? (
 					<text wrapMode="none" content="  (no matches)" style={{ fg: colors.textMuted }} />

package/src/Footer.tsx

@@ -138,7 +138,11 @@ export const Footer = <C,>({
 		hints.push({ key: null, label: `[filter: ${filterQuery}]` })
 	}
 	for (const b of bindings) {
-		if (b.when && !b.when(ctx)) continue
+		// Hint visibility prefers `hintWhen` (binding-specific) over `when`
+		// (dispatch gate). Falling back to `when` keeps the original
+		// "hint shows when binding is enabled" behavior for the common case.
+		const visibleGate = b.hintWhen ?? b.when
+		if (visibleGate && !visibleGate(ctx)) continue
 		const h = formatHint(b)
 		if (h !== null) hints.push(h)
 	}

package/src/PromptRow.tsx

@@ -0,0 +1,49 @@
+/**
+ * PromptRow — single-line `> query` row shared by the sidebar filter and
+ * the command palette query input.
+ *
+ * Render-only: the parent owns query state and the focus/editing flag.
+ * The `> ` prefix always renders in `textStrong` regardless of state so it
+ * reads as chrome, not placeholder text — only the body span shifts color
+ * (textStrong while editing, text when applied, textMuted as placeholder).
+ *
+ * Overflow: when editing, an overflowing body anchors its right edge with a
+ * leading `…` so the cursor stays on screen; otherwise it anchors the left
+ * edge with a trailing `…`.
+ */
+
+import { colors } from "./theme/colors.ts"
+
+export interface PromptRowProps {
+	readonly query: string
+	/** True while the input is focused — shows a cursor and uses textStrong fg. */
+	readonly editing: boolean
+	/** Body fallback when !editing && query === "". Pass without the `> ` prefix. */
+	readonly placeholder?: string
+	/** Total cell width available for the row (prefix + body). */
+	readonly width: number
+}
+
+const PREFIX = "> "
+const CURSOR = "▏"
+
+export const PromptRow = ({ query, editing, placeholder = "", width }: PromptRowProps) => {
+	const bodyBudget = Math.max(1, width - PREFIX.length)
+
+	const rawBody = editing ? `${query}${CURSOR}` : query.length > 0 ? query : placeholder
+	const bodyFg = editing ? colors.textStrong : query.length > 0 ? colors.text : colors.textMuted
+
+	const body =
+		rawBody.length <= bodyBudget
+			? rawBody
+			: editing
+				? "…" + rawBody.slice(rawBody.length - bodyBudget + 1)
+				: rawBody.slice(0, bodyBudget - 1) + "…"
+
+	return (
+		<text wrapMode="none">
+			<span style={{ fg: colors.textStrong }}>{PREFIX}</span>
+			<span style={{ fg: bodyFg }}>{body}</span>
+		</text>
+	)
+}

package/src/commands/buildCommands.ts

@@ -45,6 +45,7 @@ const annotations: Record<string, Annotation> = {
 	"help.toggle": { title: "Show help", category: "App" },
 	"filter.open": { title: "Filter files…", category: "Navigation" },
 	"serve.current": { title: "Open in browser", category: "File" },
+	"file.edit": { title: "Open in editor", category: "File", keywords: ["editor", "vim", "vscode"] },
 	"theme.next": { category: "Appearance" },
 	"theme.prev": { category: "Appearance" },
 	"theme.toneToggle": { title: "Toggle dark/light tone", category: "Appearance" },

package/src/io/editor.ts

@@ -0,0 +1,162 @@
+/**
+ * Resolve `$VISUAL` / `$EDITOR` into a spawnable `{ cmd, args }`.
+ *
+ * The string is POSIX shell-split so users with values like
+ * `code --wait` or `"/Applications/Sublime Text/subl" --wait` get the
+ * expected argv. We deliberately do *not* shell out via `sh -c`: the
+ * caller appends the file path as a separate argv element, which avoids
+ * command-injection risk for paths containing shell metacharacters.
+ *
+ * Resolution order: `$VISUAL` → `$EDITOR` → `null`. No silent fallback to
+ * `vi`; the caller surfaces a footer notice when neither is set.
+ */
+
+export interface ResolvedEditor {
+	readonly cmd: string
+	readonly args: readonly string[]
+}
+
+/**
+ * Split a command string the way `sh` would for the simple cases users
+ * actually put in `$EDITOR`: single quotes (literal), double quotes
+ * (with `\"`, `\\` escapes), backslash escapes outside quotes, and
+ * whitespace separation. No variable expansion, no globbing, no command
+ * substitution — by design. If the input is unbalanced (an unclosed
+ * quote), the partial token is emitted as-is so the caller's spawn
+ * surfaces a real error instead of us throwing.
+ */
+export const splitEditorString = (input: string): string[] => {
+	const tokens: string[] = []
+	let buf = ""
+	let inSingle = false
+	let inDouble = false
+	let pendingToken = false
+
+	for (let i = 0; i < input.length; i++) {
+		const ch = input[i]!
+		if (inSingle) {
+			if (ch === "'") inSingle = false
+			else buf += ch
+			continue
+		}
+		if (inDouble) {
+			if (ch === "\\" && i + 1 < input.length) {
+				const next = input[i + 1]!
+				// In double quotes, `sh` only treats `\` as an escape before
+				// `$`, `` ` ``, `"`, `\`, or newline. Otherwise the backslash
+				// is literal. We collapse it for `"` and `\` (the cases users
+				// hit with Windows-style paths in double quotes) and keep it
+				// literal otherwise.
+				if (next === '"' || next === "\\") {
+					buf += next
+					i++
+					continue
+				}
+			}
+			if (ch === '"') {
+				inDouble = false
+				continue
+			}
+			buf += ch
+			continue
+		}
+		if (ch === "'") {
+			inSingle = true
+			pendingToken = true
+			continue
+		}
+		if (ch === '"') {
+			inDouble = true
+			pendingToken = true
+			continue
+		}
+		if (ch === "\\" && i + 1 < input.length) {
+			buf += input[i + 1]!
+			i++
+			pendingToken = true
+			continue
+		}
+		if (ch === " " || ch === "\t") {
+			if (pendingToken) {
+				tokens.push(buf)
+				buf = ""
+				pendingToken = false
+			}
+			continue
+		}
+		buf += ch
+		pendingToken = true
+	}
+	if (pendingToken) tokens.push(buf)
+	return tokens
+}
+
+/**
+ * Pick the user's editor from env vars. Returns `null` when neither
+ * `$VISUAL` nor `$EDITOR` is set to a non-empty, non-whitespace value.
+ *
+ * `env` is parameterised so tests don't need to mutate `process.env`.
+ */
+export const resolveEditor = (
+	env: Readonly<Record<string, string | undefined>>,
+): ResolvedEditor | null => {
+	const raw = pickEnv(env["VISUAL"]) ?? pickEnv(env["EDITOR"])
+	if (raw == null) return null
+	const parts = splitEditorString(raw)
+	if (parts.length === 0) return null
+	const [cmd, ...args] = parts
+	if (!cmd) return null
+	return { cmd, args }
+}
+
+const pickEnv = (value: string | undefined): string | null => {
+	if (value == null) return null
+	const trimmed = value.trim()
+	return trimmed.length === 0 ? null : trimmed
+}
+
+/** Result of a launched editor session. Never throws — every failure is
+ *  surfaced as a tagged value so the caller can decide UX. */
+export type EditorRunResult =
+	| { readonly ok: true; readonly exitCode: number }
+	| {
+			readonly ok: false
+			readonly reason: "spawn-failed" | "non-zero"
+			readonly detail?: string
+	  }
+
+export interface OpenInEditorOptions {
+	readonly editor: ResolvedEditor
+	readonly filePath: string
+}
+
+/**
+ * Launch the resolved editor on `filePath`, inheriting stdio so the
+ * editor takes over the TTY. Caller is responsible for suspending /
+ * resuming the renderer around this call (see Browser.tsx).
+ *
+ * The file path is passed as a separate argv element — never interpolated
+ * into a shell string — so paths with shell metacharacters can't be
+ * misinterpreted.
+ *
+ * Windows is unsupported (see #129). The PATHEXT gap that breaks `.cmd`
+ * shims (`code.cmd`, `nvim.cmd`) is tracked specifically in #128.
+ */
+export const openInEditor = async ({
+	editor,
+	filePath,
+}: OpenInEditorOptions): Promise<EditorRunResult> => {
+	const argv = [editor.cmd, ...editor.args, filePath]
+	try {
+		const proc = Bun.spawn(argv, {
+			stdin: "inherit",
+			stdout: "inherit",
+			stderr: "inherit",
+		})
+		const exitCode = await proc.exited
+		if (exitCode === 0) return { ok: true, exitCode }
+		return { ok: false, reason: "non-zero", detail: String(exitCode) }
+	} catch (err) {
+		return { ok: false, reason: "spawn-failed", detail: String(err) }
+	}
+}

package/src/keymap/browser.ts

@@ -10,11 +10,19 @@ export type BrowserFocus = "sidebar" | "reader"
 
 export interface BrowserCtx {
 	readonly files: readonly FileEntry[]
+	/** True iff `files[selectedIndex]` resolves to an entry. The honest
+	 *  predicate for File-group actions (`o`, `e`, `[`, `]`): with debounced
+	 *  filter and sticky auto-select, `files.length > 0` can be true while
+	 *  `selectedIndex` is invalid for the displayed list. See #115. */
+	readonly hasSelected: boolean
 	readonly focus: BrowserFocus
 	/** User's sticky sidebar preference. Visibility is `shown || focus==="sidebar"`. */
 	readonly sidebarShown: boolean
 	readonly helpVisible: boolean
 	readonly filterOpen: boolean
+	/** Current applied/edited filter query. Used by `filter.clearOrOpen`'s
+	 *  hint gate so the hint only appears when there is something to clear. */
+	readonly filterQuery: string
 	readonly paletteOpen: boolean
 	readonly setFocus: (next: BrowserFocus | ((prev: BrowserFocus) => BrowserFocus)) => void
 	readonly setSelectedIndex: (updater: (prev: number) => number) => void
@@ -22,12 +30,19 @@ export interface BrowserCtx {
 	readonly toggleShown: () => void
 	readonly setHelpVisible: (updater: (prev: boolean) => boolean) => void
 	readonly openFilter: () => void
+	/** Clear the current filter query and open the filter modal in a single
+	 *  action. Bound to `\` so users can reset a stranded zero-match filter
+	 *  without first reopening with `/` and backspacing. */
+	readonly clearAndOpenFilter: () => void
 	readonly openPalette: () => void
 	readonly cycleTheme: (delta: 1 | -1) => void
 	readonly toggleTone: () => void
 	readonly quit: () => void
 	/** Start (or retarget) the HTML preview server on the focused file. */
 	readonly serveCurrent: () => void
+	/** Suspend the TUI, hand the TTY to `$EDITOR`, resume and re-read on
+	 *  exit. No-op when nothing is selected; gating is the binding's job. */
+	readonly editCurrent: () => void
 }
 
 /** Step size for shift+j/k and the space/b/page keys. Constant for v1; could
@@ -37,6 +52,7 @@ const JUMP = 8
 const clamp = (n: number, min: number, max: number) => Math.max(min, Math.min(max, n))
 const lastIndex = (c: BrowserCtx) => Math.max(0, c.files.length - 1)
 const haveFiles = (c: BrowserCtx) => c.files.length > 0
+const hasSelected = (c: BrowserCtx) => c.hasSelected
 const stepBy = (c: BrowserCtx, delta: number) =>
 	c.setSelectedIndex((i) => clamp(i + delta, 0, lastIndex(c)))
 
@@ -45,7 +61,10 @@ const filterClosed = (c: BrowserCtx) => !c.filterOpen
 const paletteClosed = (c: BrowserCtx) => !c.paletteOpen
 const inReader = (c: BrowserCtx) => c.focus === "reader"
 const inSidebarWithFiles = (c: BrowserCtx) => inSidebar(c) && haveFiles(c)
-const inReaderWithFiles = (c: BrowserCtx) => inReader(c) && haveFiles(c)
+/** Reader-only sibling-step gate: needs a current selection plus a sibling
+ *  to step to. `hasSelected` implies `files.length >= 1`, so `>= 2` is the
+ *  meaningful extra condition. */
+const inReaderWithSibling = (c: BrowserCtx) => inReader(c) && hasSelected(c) && c.files.length >= 2
 
 export const browserBindings: readonly KeyBinding<BrowserCtx>[] = [
 	// Global
@@ -93,6 +112,28 @@ export const browserBindings: readonly KeyBinding<BrowserCtx>[] = [
 		when: filterClosed,
 		run: (c) => c.openFilter(),
 	},
+	{
+		id: "filter.clearOrOpen",
+		group: "Sidebar",
+		description: "Clear filter",
+		hint: "clear",
+		keys: ["ctrl+\\"],
+		// Fires from anywhere outside the filter modal via the keymap.
+		// Inside the filter modal it's intercepted directly in Browser.tsx
+		// (the filter mode owns key handling), but the action is the same —
+		// clear input, keep modal open. Palette/help branches short-circuit
+		// dispatch in Browser.tsx, so we don't need to gate on them for
+		// behavior; the `hintWhen` gate keeps the footer chip from showing
+		// when there's nothing to clear or when a modal owns the input.
+		// Chord chosen over single `\` so the binding works inside the
+		// filter input without colliding with the typed character; ctrl+u
+		// is deliberately left to its reader/sidebar half-page-up role to
+		// avoid overload.
+		when: filterClosed,
+		hintWhen: (c) =>
+			filterClosed(c) && !c.paletteOpen && !c.helpVisible && c.filterQuery.length > 0,
+		run: (c) => c.clearAndOpenFilter(),
+	},
 	{
 		id: "palette.open",
 		group: "Global",
@@ -106,15 +147,6 @@ export const browserBindings: readonly KeyBinding<BrowserCtx>[] = [
 		when: paletteClosed,
 		run: (c) => c.openPalette(),
 	},
-	{
-		id: "serve.current",
-		group: "Global",
-		description: "Open current file in browser as HTML",
-		hint: "html",
-		keys: ["o"],
-		when: haveFiles,
-		run: (c) => c.serveCurrent(),
-	},
 	{
 		id: "theme.next",
 		group: "Global",
@@ -213,32 +245,57 @@ export const browserBindings: readonly KeyBinding<BrowserCtx>[] = [
 		run: (c) => c.setFocus("reader"),
 	},
 
-	// Reader
+	// File — actions on the currently-selected file. Gated on `hasSelected`
+	// (per #115) so they're available exactly when the reader has something
+	// to act on, regardless of focus or filter state.
 	{
-		id: "reader.back",
-		group: "Reader",
-		description: "Back to sidebar",
-		hint: "back",
-		keys: ["escape", "left", "h"],
-		when: inReader,
-		run: (c) => c.setFocus("sidebar"),
+		id: "serve.current",
+		group: "File",
+		description: "Open current file in browser as HTML",
+		hint: "html",
+		keys: ["o"],
+		when: hasSelected,
+		run: (c) => c.serveCurrent(),
 	},
 	{
+		id: "file.edit",
+		group: "File",
+		description: "Open current file in $EDITOR",
+		hint: "edit",
+		keys: ["e"],
+		when: hasSelected,
+		run: (c) => c.editCurrent(),
+	},
+	{
+		// `[`/`]` keep the `inReader` clause so they're only typed from the
+		// reader (sidebar uses j/k for stepping). The File-group predicate is
+		// additive: needs a selection *and* a sibling to step to.
 		id: "reader.prevFile",
-		group: "Reader",
+		group: "File",
 		description: "Prev file",
 		hint: "prev",
 		keys: ["["],
-		when: inReaderWithFiles,
+		when: inReaderWithSibling,
 		run: (c) => stepBy(c, -1),
 	},
 	{
 		id: "reader.nextFile",
-		group: "Reader",
+		group: "File",
 		description: "Next file",
 		hint: "next",
 		keys: ["]"],
-		when: inReaderWithFiles,
+		when: inReaderWithSibling,
 		run: (c) => stepBy(c, 1),
 	},
+
+	// Reader
+	{
+		id: "reader.back",
+		group: "Reader",
+		description: "Back to sidebar",
+		hint: "back",
+		keys: ["escape", "left", "h"],
+		when: inReader,
+		run: (c) => c.setFocus("sidebar"),
+	},
 ]

package/src/keymap/keymap.ts

@@ -34,6 +34,12 @@ export interface KeyBinding<C> {
 	readonly hint?: string
 	/** If present, the binding only fires when this returns true. */
 	readonly when?: (ctx: C) => boolean
+	/** If present, the footer hint is shown only when this returns true. When
+	 *  absent, hint visibility falls back to `when`. Use when a binding's
+	 *  dispatch gate is broader than the situations where the hint is useful
+	 *  (e.g. "clear filter" fires from anywhere but only deserves a hint when
+	 *  there is actually a filter to clear). */
+	readonly hintWhen?: (ctx: C) => boolean
 	readonly run: (ctx: C) => void
 }
 

package/src/layout/sidebarRow.ts

@@ -0,0 +1,85 @@
+/**
+ * Sidebar row layout — basename-first with a dim parent suffix sized to the
+ * available width.
+ *
+ * Pure per-row formatting: a row's rendered shape depends only on its own
+ * path and the column budget — never on neighboring rows. That keeps the
+ * sidebar stable as filters change and the file set grows, and keeps the
+ * function trivially predictable. Disambiguation against same-basename
+ * siblings is the header's job (it shows the full relative path of the
+ * selected row); a future auto-scroll on the selected sidebar row can carry
+ * the same information without altering layout for the rest.
+ *
+ * Truncation policy (head-elide, segment-aware):
+ *   - Full parent fits → render whole.
+ *   - Else drop leading segments one at a time, prefixed with `…/`, until
+ *     the remainder fits — never chops a segment mid-character.
+ *   - When even the tail segment with `…/` overflows, drop the marker.
+ *   - When the tail segment alone overflows, hard-truncate it from its head
+ *     (leading `…`) as a last resort.
+ *
+ * Why head-elide: the immediate parent is the segment closest to the file
+ * and the most universally meaningful one when context shrinks.
+ */
+
+export const SIDEBAR_ROW_SEPARATOR = "  ·  "
+const ELISION_PREFIX = "…/"
+const MIN_PARENT_BUDGET = 3
+
+export interface SidebarRowParts {
+	readonly basename: string
+	readonly separator: string
+	readonly parent: string
+}
+
+export const formatSidebarRow = (relativePath: string, totalWidth: number): SidebarRowParts => {
+	const slash = relativePath.lastIndexOf("/")
+	if (slash < 0) {
+		return { basename: fitTail(relativePath, totalWidth), separator: "", parent: "" }
+	}
+
+	const basename = relativePath.slice(slash + 1)
+	const parentFull = relativePath.slice(0, slash)
+
+	if (basename.length >= totalWidth) {
+		return { basename: fitTail(basename, totalWidth), separator: "", parent: "" }
+	}
+
+	const remaining = totalWidth - basename.length - SIDEBAR_ROW_SEPARATOR.length
+	if (remaining < MIN_PARENT_BUDGET || parentFull.length === 0) {
+		return { basename, separator: "", parent: "" }
+	}
+
+	if (parentFull.length <= remaining) {
+		return row(basename, parentFull)
+	}
+
+	const segments = parentFull.split("/")
+	for (let k = segments.length - 1; k >= 1; k--) {
+		const candidate = ELISION_PREFIX + segments.slice(segments.length - k).join("/")
+		if (candidate.length <= remaining) return row(basename, candidate)
+	}
+
+	// Even one segment with the `…/` marker doesn't fit. Try without the marker.
+	const tail = segments[segments.length - 1]!
+	if (tail.length <= remaining) return row(basename, tail)
+
+	// Hard-chop the tail segment from its head as a last resort.
+	return row(basename, "…" + tail.slice(tail.length - remaining + 1))
+}
+
+const row = (basename: string, parent: string): SidebarRowParts => ({
+	basename,
+	separator: SIDEBAR_ROW_SEPARATOR,
+	parent,
+})
+
+const fitTail = (s: string, width: number): string => {
+	if (s.length <= width) return s
+	// At width ≤ 1 there's no room for both a character and the ellipsis; emit
+	// a single char so the result respects the budget. Callers currently clamp
+	// width to ≥ 4, but the helper carries its own floor so a tighter future
+	// caller can't silently overflow the column.
+	if (width <= 1) return s.slice(0, 1)
+	return s.slice(0, width - 1) + "…"
+}

package/src/serve/server.ts

@@ -86,9 +86,12 @@ export const startServer = ({ path, port = 0 }: StartOptions): ServerHandle => {
 		// user's local files, so leaking them to the network would be a
 		// surprise. URL strings are localhost-only by construction below.
 		hostname: "127.0.0.1",
-		async fetch(req) {
+		async fetch(req, server) {
 			const url = new URL(req.url)
 			if (url.pathname === "/__reload") {
+				// SSE stream is silent between file changes; without this Bun
+				// closes the request at the default 10s idleTimeout and warns.
+				server.timeout(req, 0)
 				// `cancel` receives a reason, not the controller — capture
 				// the controller in `start` so we can remove it from the set
 				// on disconnect. Without this, dead clients accumulate.