@carlesandres/house 0.4.8 → 0.4.10

package/CHANGELOG.md

@@ -6,6 +6,31 @@ The publish workflow (`.github/workflows/publish.yml`) runs on the `release: pub
 
 ## [Unreleased]
 
+## [0.4.10] — 2026-06-14
+
+### Added
+
+- Active theme selection is now persisted globally, with hardened config saving that preserves symlinked config files.
+
+### Changed
+
+- Sidebar parent paths now middle-truncate in deep trees to keep filenames scannable.
+- Markdown discovery now uses an extension allow-list for supported markdown file types.
+
+## [0.4.9] — 2026-06-09
+
+### Fixed
+
+- Sidebar rows now keep a tighter single-space filename/path gap, and footer hint width calculation better handles wide glyphs.
+
+### Changed
+
+- Removed the experimental `--sort` option. The sidebar now consistently lists files before directories, so current-directory files appear before nested subtrees in the base list. This makes less-nested files naturally rank higher even without a search term. When a filter query is active the existing `filterFiles` / `rankFile` scoring (filename bias + strengthened depth penalties) still applies on top.
+
+### Docs
+
+- Demo recording now lives in `recordings/record-demo.sh`, with docs and recorded assets updated to match the new capture flow.
+
 ## [0.4.8] — 2026-06-02
 
 ### Fixed
@@ -18,7 +43,7 @@ The publish workflow (`.github/workflows/publish.yml`) runs on the `release: pub
 ### Docs
 
 - Corrected usage docs and `--help` text: directory browsing is controlled by `--root` / `defaultRoot`; the positional path now seeds the initial browser filter query.
-- Refreshed unified-browser docs, roadmap state, and demo tapes after the single Browser model landed.
+- Refreshed unified-browser docs, pruned shipped roadmap items, and updated demo tapes after the single Browser model landed.
 - Added ADR 0001 documenting the decision to keep the current `marked`-based browser preview instead of adopting Streamdown for now.
 
 ### Changed
@@ -184,7 +209,7 @@ Beta release gates (DESIGN §10.2) closed.
 
 ### Docs
 
-- README embeds a VHS-generated demo gif; `tape/` holds the source scripts.
+- README embeds the recorded demo asset; `recordings/` holds the capture workflow.
 - `CONTRIBUTING.md` documents the `captureSpans()` / `MockTreeSitterClient` / `TestRecorder` testing patterns and the "before blaming `<markdown>`" stale-watcher debugging checklist.
 
 ## [0.3.0] — 2026-05-16
@@ -245,7 +270,7 @@ The v1 MVP, published as `@carlesandres/openmdr` on npm.
 
 ### Added — discovery
 
-- Recursive walk from the path argument (or cwd), `.md` / `.markdown` / `.mdx` only.
+- Recursive walk from the path argument (or cwd), limited to markdown extensions.
 - Honors `.gitignore` (root + nested).
 - Hard-skips `node_modules`, `.git`, `.venv` (always, even with `--all`).
 - Does not follow symlinks.
@@ -280,7 +305,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.8...HEAD
+[Unreleased]: https://github.com/carlesandres/house/compare/v0.4.10...HEAD
+[0.4.10]: https://github.com/carlesandres/house/compare/v0.4.9...v0.4.10
+[0.4.9]: https://github.com/carlesandres/house/compare/v0.4.8...v0.4.9
 [0.4.8]: https://github.com/carlesandres/house/compare/v0.4.7...v0.4.8
 [0.4.7]: https://github.com/carlesandres/house/compare/v0.4.6...v0.4.7
 [0.4.6]: https://github.com/carlesandres/house/compare/v0.4.5...v0.4.6

package/README.md

@@ -2,7 +2,7 @@
 
 A terminal markdown reader and navigator — themable and configurable, with a keyboard-driven modern UI. Browse a directory of `.md` files without leaving the terminal.
 
-![house demo](tape/house.gif)
+<video src="recordings/house-demo.mp4" controls muted loop playsinline></video>
 
 ## Features
 
@@ -60,23 +60,22 @@ house --serve README.md
 
 ### Options
 
-| Flag | Default | Description |
-|------|---------|-------------|
-| `--theme <name>` | `opencode` | Starting theme (see list below) |
-| `--tone dark\|light` | `dark` | Starting tone |
-| `--width <N>` | — | Cap rendered markdown width at N columns |
-| `--show <list>` | `""` | Reveal normally-skipped entries; comma-separated subset of `hidden`, `gitignored`. Use `--show ""` to clear. |
-| `--root <dir>` | current directory | Discovery root to walk; overrides `defaultRoot` config/env |
-| `--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 positional path 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 |
+| Flag                 | Default           | Description                                                                                                  |
+| -------------------- | ----------------- | ------------------------------------------------------------------------------------------------------------ |
+| `--theme <name>`     | `opencode`        | Starting theme (see list below)                                                                              |
+| `--tone dark\|light` | `dark`            | Starting tone                                                                                                |
+| `--width <N>`        | —                 | Cap rendered markdown width at N columns                                                                     |
+| `--show <list>`      | `""`              | Reveal normally-skipped entries; comma-separated subset of `hidden`, `gitignored`. Use `--show ""` to clear. |
+| `--root <dir>`       | current directory | Discovery root to walk; overrides `defaultRoot` config/env                                                   |
+| `--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 positional path as HTML in the browser (skips TUI)                                                 |
+| `--port <N>`         | OS-assigned       | Port for `--serve`                                                                                           |
+| `--ext <list>`       | none              | Include extra file extensions (comma-separated)                                                               |
+| `--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
 
@@ -92,22 +91,22 @@ Run `house --config-path` to print the exact location.
 # ~/.config/house/config.toml
 theme = "tokyonight"
 tone  = "dark"
-mdx   = true
+extensions = []
 show  = ["hidden", "gitignored"]
 focus = "filter"
 defaultRoot = "cwd" # or "git"
 ```
 
-Supported keys: `theme`, `tone`, `mdx`, `show`, `focus`, `defaultRoot`.
+Supported keys: `theme`, `tone`, `extensions`, `show`, `focus`, `defaultRoot`.
 
 `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`, `--focus`, `--root`)
-2. Env vars (`HOUSE_THEME`, `HOUSE_TONE`, `HOUSE_MDX`, `HOUSE_SHOW`, `HOUSE_FOCUS`, `HOUSE_DEFAULT_ROOT`)
+1. CLI flags (`--theme`, `--tone`, `--ext`, `--show`, `--focus`, `--root`)
+2. Env vars (`HOUSE_THEME`, `HOUSE_TONE`, `HOUSE_EXTENSIONS`, `HOUSE_SHOW`, `HOUSE_FOCUS`, `HOUSE_DEFAULT_ROOT`)
 3. Config file
-4. Built-in defaults (`opencode` / `dark` / `mdx = true` / `show = []` / `focus = "filter"` / `defaultRoot = "cwd"`)
+4. Built-in defaults (`opencode` / `dark` / `extensions = []` / `show = []` / `focus = "filter"` / `defaultRoot = "cwd"`)
 
 `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.
 
@@ -117,41 +116,41 @@ The file is optional — a missing file is fine. Invalid keys, unknown themes, o
 
 ### Global
 
-| Key | Action |
-|-----|--------|
-| `q` / `ctrl+c` | Quit |
-| `tab` | Toggle focus (sidebar ↔ reader) |
-| `s` | Toggle sidebar visibility |
-| `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 |
+| Key            | Action                                                      |
+| -------------- | ----------------------------------------------------------- |
+| `q` / `ctrl+c` | Quit                                                        |
+| `tab`          | Toggle focus (sidebar ↔ reader)                             |
+| `s`            | Toggle sidebar visibility                                   |
+| `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                                    |
 
 ### Sidebar
 
-| Key | Action |
-|-----|--------|
-| `j` / `↓` | Move selection down |
-| `k` / `↑` | Move selection up |
-| `J` | Jump down 8 |
-| `K` | Jump up 8 |
-| `space` / `pagedown` / `ctrl+d` | Page down |
-| `b` / `pageup` / `ctrl+u` | Page up |
-| `g` | First file |
-| `G` | Last file |
-| `/` | Filter files (fuzzy match on path) |
-| `A` | Toggle hidden + gitignored entries (session-only; round-trips with the configured `show`) |
-| `↵` / `→` / `l` | Open file (focus reader) |
+| Key                             | Action                                                                                    |
+| ------------------------------- | ----------------------------------------------------------------------------------------- |
+| `j` / `↓`                       | Move selection down                                                                       |
+| `k` / `↑`                       | Move selection up                                                                         |
+| `J`                             | Jump down 8                                                                               |
+| `K`                             | Jump up 8                                                                                 |
+| `space` / `pagedown` / `ctrl+d` | Page down                                                                                 |
+| `b` / `pageup` / `ctrl+u`       | Page up                                                                                   |
+| `g`                             | First file                                                                                |
+| `G`                             | Last file                                                                                 |
+| `/`                             | Filter files (fuzzy match on path)                                                        |
+| `A`                             | Toggle hidden + gitignored entries (session-only; round-trips with the configured `show`) |
+| `↵` / `→` / `l`                 | Open file (focus reader)                                                                  |
 
 ### Reader
 
-| Key | Action |
-|-----|--------|
+| Key               | Action          |
+| ----------------- | --------------- |
 | `esc` / `←` / `h` | Back to sidebar |
-| `[` | Previous file |
-| `]` | Next file |
+| `[`               | Previous file   |
+| `]`               | Next file       |
 
 ## Themes
 

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@carlesandres/house",
-		"version": "0.4.8",
+	"version": "0.4.10",
 	"description": "TUI-first markdown reader on opentui",
 	"type": "module",
 	"license": "MIT",
@@ -42,6 +42,7 @@
 	"scripts": {
 		"dev": "bun --watch src/index.tsx",
 		"start": "bun run src/index.tsx",
+		"record-demo": "bash recordings/record-demo.sh",
 		"typecheck": "tsc --noEmit",
 		"lint": "oxlint --tsconfig tsconfig.json src/",
 		"format": "oxfmt src/",

package/src/Browser.tsx

@@ -45,6 +45,8 @@ import { startServer, type ServerHandle } from "./serve/server.ts"
 import { colors, setActiveTheme } from "./theme/colors.ts"
 import { themeAtom } from "./theme/atom.ts"
 import { themeDefinitions, getThemeDefinition } from "./theme/registry.ts"
+import { saveThemePreference } from "./config/save.ts"
+import { middleTruncate } from "./ui/middleTruncate.ts"
 
 export type SidebarMode = "auto" | "on" | "off"
 export type StartupFocus = "sidebar" | "reader" | "filter"
@@ -362,6 +364,12 @@ export const Browser = ({
 		if (!next) return
 		setActiveTheme(next, theme.tone)
 		setTheme({ id: next.id, tone: theme.tone })
+		void saveThemePreference({ theme: next.id, tone: theme.tone }).catch((err) => {
+			pushFooterNotice("theme not saved")
+			process.stderr.write(
+				`house: failed to save theme preference: ${err instanceof Error ? err.message : String(err)}\n`,
+			)
+		})
 		pushFooterNotice(`theme: ${next.name}`)
 	}
 
@@ -370,6 +378,12 @@ export const Browser = ({
 		const def = getThemeDefinition(theme.id)
 		if (def) setActiveTheme(def, nextTone)
 		setTheme({ id: theme.id, tone: nextTone })
+		void saveThemePreference({ theme: theme.id, tone: nextTone }).catch((err) => {
+			pushFooterNotice("theme not saved")
+			process.stderr.write(
+				`house: failed to save theme preference: ${err instanceof Error ? err.message : String(err)}\n`,
+			)
+		})
 		pushFooterNotice(`tone: ${nextTone}`)
 	}
 
@@ -967,7 +981,12 @@ export const Browser = ({
 						<text key={file.path} wrapMode="none" style={rowStyle}>
 							<span style={{ fg: basenameFg }}>{basename}</span>
 							{parent !== "" && (
-								<span style={{ fg: colors.textMuted }}>{`${separator}${parent}`}</span>
+								<span style={{ fg: colors.textMuted }}>
+									{middleTruncate(
+										`${separator}${parent}`,
+										Math.max(0, sidebarTextWidth - basename.length),
+									)}
+								</span>
 							)}
 						</text>
 					)

package/src/Footer.tsx

@@ -15,12 +15,11 @@
  * sidebar (see Browser.tsx). The pattern mirrors ghui's PR list, where the
  * filter is part of the list it filters.
  *
- * Width math assumes hint labels are ASCII plus a small set of single-cell
- * BMP glyphs (see `displayKey`). `fitHints` and notice clipping use string
- * length as a proxy for cell count; introducing a CJK or emoji label would
- * require a real cell-width counter (e.g. East Asian Width).
+ * Width math uses terminal-style string width instead of raw string length so
+ * ambiguous glyphs such as `↵` don't steal spacing from the label beside them.
  */
 
+import stringWidth from "string-width"
 import type React from "react"
 import type { KeyBinding } from "./keymap/keymap.ts"
 import { displayKey } from "./keymap/displayKey.ts"
@@ -59,7 +58,7 @@ interface Hint {
 	readonly label: string
 }
 
-const hintWidth = (h: Hint): number => h.key.length + 1 + h.label.length // key + " " + label
+const hintWidth = (h: Hint): number => stringWidth(h.key) + 1 + stringWidth(h.label) // key + " " + label
 
 const formatHint = <C,>(b: KeyBinding<C>): Hint | null => {
 	if (!b.hint) return null

package/src/cli/argv.ts

@@ -12,8 +12,6 @@ export interface ParsedArgs {
 	readonly tone: string | null
 	/** Value of `--width <N>`, or null. Validated by the boot layer (must be a positive integer). */
 	readonly width: string | null
-	/** Value of `--sort <mode>` (`dirs-first` or `files-first`), or null. Validated by the boot layer. */
-	readonly sort: string | null
 	/** True when `--serve` was passed: serve the positional path as HTML, skip TUI. */
 	readonly serve: boolean
 	/** Value of `--port <N>`, or null. Validated by the boot layer. */
@@ -30,8 +28,8 @@ export interface ParsedArgs {
 	 *  probe and the "update available" notice. Mirrors the
 	 *  `NO_UPDATE_NOTIFIER` env var so opt-out is reachable without env state. */
 	readonly noUpdateCheck: boolean
-	/** True when `--no-mdx` was passed: exclude `.mdx` files from discovery. */
-	readonly noMdx: boolean
+	/** Raw value of `--ext [list]`, or null if absent. Comma-separated list. */
+	readonly extensions: string | null
 	/** Value of `--focus <mode>` (`sidebar`, `reader`, `filter`), or null.
 	 *  Validated by the boot layer. */
 	readonly focus: string | null
@@ -51,13 +49,12 @@ const createProgram = () =>
 		.option("--theme [id]")
 		.option("--tone [mode]")
 		.option("--width [N]")
-		.option("--sort [mode]")
 		.option("--serve")
 		.option("--port [N]")
 		.option("--config-path")
 		.option("--sidebar [mode]")
 		.option("--no-update-check")
-		.option("--no-mdx")
+		.option("--ext [list]")
 		.option("--focus [mode]")
 		.option("--show [list]")
 		.option("--root [dir]")
@@ -69,19 +66,20 @@ const VALUE_FLAGS: ReadonlySet<string> = new Set([
 	"--theme",
 	"--tone",
 	"--width",
-	"--sort",
 	"--port",
 	"--sidebar",
 	"--focus",
 	"--show",
 	"--root",
+	"--ext",
 ])
 
+const REMOVED_VALUE_FLAGS: ReadonlySet<string> = new Set(["--sort"])
+
 const BOOLEAN_FLAGS: ReadonlySet<string> = new Set([
 	"--serve",
 	"--config-path",
 	"--no-update-check",
-	"--no-mdx",
 	"--help",
 	"-h",
 	"--version",
@@ -91,7 +89,7 @@ const BOOLEAN_FLAGS: ReadonlySet<string> = new Set([
 const findPathArg = (argv: readonly string[]): string | null => {
 	for (let i = 0; i < argv.length; i++) {
 		const arg = argv[i]!
-		if (VALUE_FLAGS.has(arg)) {
+		if (VALUE_FLAGS.has(arg) || REMOVED_VALUE_FLAGS.has(arg)) {
 			const next = argv[i + 1]
 			if (next !== undefined && !next.startsWith("-")) i++
 			continue
@@ -123,7 +121,6 @@ export const parseArgv = (argv: readonly string[]): ParsedArgs => {
 		theme: stringOrNull(opts["theme"]),
 		tone: stringOrNull(opts["tone"]),
 		width: stringOrNull(opts["width"]),
-		sort: stringOrNull(opts["sort"]),
 		serve: opts["serve"] === true,
 		port: stringOrNull(opts["port"]),
 		help: opts["help"] === true,
@@ -131,7 +128,7 @@ export const parseArgv = (argv: readonly string[]): ParsedArgs => {
 		configPath: opts["configPath"] === true,
 		sidebar: stringOrNull(opts["sidebar"]),
 		noUpdateCheck: opts["noUpdateCheck"] === true,
-		noMdx: opts["mdx"] === false,
+		extensions: stringOrNull(opts["ext"]),
 		show: stringOrNull(opts["show"]),
 		focus: stringOrNull(opts["focus"]),
 	}
@@ -152,7 +149,6 @@ options:
   --show <list>  reveal normally-skipped entries; comma-separated subset of:
                    hidden, gitignored. Use --show "" to clear.
   --root <dir>   discovery root to walk (overrides defaultRoot config/env)
-  --sort <mode>  sidebar order: dirs-first (default) or files-first
   --sidebar <m>  initial sidebar visibility: auto (default), on, or off
   --focus <m>    startup focus: sidebar, reader, or filter (default: filter)
   --serve        serve the positional path as HTML in the browser (skips TUI)
@@ -161,7 +157,7 @@ options:
   -v, --version  print version and exit
   --config-path  print path to the config file and exit
   --no-update-check  suppress the "newer version available" check (also via NO_UPDATE_NOTIFIER=1)
-  --no-mdx       exclude .mdx files from discovery (default: included)
+	--ext <list>   include extra file extensions (comma-separated)
 
 examples:
   house README.md
@@ -170,6 +166,6 @@ examples:
 
 configuration:
   file: $XDG_CONFIG_HOME/house/config.toml  (default ~/.config/house/config.toml)
-  keys: theme, tone, mdx, show, focus, defaultRoot
-  env:  HOUSE_THEME, HOUSE_TONE, HOUSE_MDX, HOUSE_SHOW, HOUSE_FOCUS, HOUSE_DEFAULT_ROOT
+	  keys: theme, tone, extensions, show, focus, defaultRoot
+	  env:  HOUSE_THEME, HOUSE_TONE, HOUSE_EXTENSIONS, HOUSE_SHOW, HOUSE_FOCUS, HOUSE_DEFAULT_ROOT
   precedence (high → low): flags → env → file → defaults`

package/src/config/load.ts

@@ -19,7 +19,7 @@ import { themeDefinitions } from "../theme/registry.ts"
 export interface HouseConfig {
 	readonly theme: string
 	readonly tone: "dark" | "light"
-	readonly mdx: boolean
+	readonly extensions: readonly string[]
 	/** Default discovery-root strategy when no explicit `--root` flag is passed. */
 	readonly defaultRoot: "cwd" | "git"
 	/** Categories of normally-skipped entries to opt into. See
@@ -34,7 +34,7 @@ export interface HouseConfig {
 export interface CliOverrides {
 	readonly theme: string | null
 	readonly tone: string | null
-	readonly mdx: boolean | null
+	readonly extensions: readonly string[] | null
 	/** When non-null, the parsed `--show` list completely replaces env/file
 	 *  (no per-category merging — sets compose by replacement, like every
 	 *  other CLI override here). `--show ""` sets the empty set. */
@@ -44,7 +44,7 @@ export interface CliOverrides {
 
 const DEFAULT_THEME = "opencode"
 const DEFAULT_TONE: "dark" | "light" = "dark"
-const DEFAULT_MDX = true
+const DEFAULT_EXTENSIONS: readonly string[] = []
 const DEFAULT_ROOT: "cwd" | "git" = "cwd"
 const DEFAULT_SHOW = ""
 const DEFAULT_FOCUS: "sidebar" | "reader" | "filter" = "filter"
@@ -60,7 +60,7 @@ const themeIds = themeDefinitions.map((t) => t.id)
 const KNOWN_FILE_KEYS: ReadonlySet<string> = new Set([
 	"theme",
 	"tone",
-	"mdx",
+	"extensions",
 	"show",
 	"focus",
 	"defaultRoot",
@@ -70,10 +70,8 @@ const schema = Config.all({
 	theme: Config.schema(Schema.Literals(themeIds), "theme"),
 	tone: Config.schema(Schema.Literals(["dark", "light"] as const), "tone"),
 	defaultRoot: Config.schema(Schema.String, "defaultRoot"),
-	// Boolean stored as string literal because providers stringify values
-	// (TOML bools, env vars, CLI flags all flow through as text). Mapped to
-	// a real boolean in `loadConfig` below.
-	mdx: Config.schema(Schema.Literals(["true", "false"] as const), "mdx"),
+	// Comma-separated extension list. Empty string means no extra extensions.
+	extensions: Config.schema(Schema.String, "extensions"),
 	// `show` arrives as a comma-separated string from every provider
 	// (`fileProvider` coerces TOML arrays via `String()`, which produces
 	// `"hidden,gitignored"`). Token-level validation happens in `loadConfig`
@@ -87,7 +85,7 @@ const defaultsProvider = (): ConfigProvider.ConfigProvider =>
 		theme: DEFAULT_THEME,
 		tone: DEFAULT_TONE,
 		defaultRoot: DEFAULT_ROOT,
-		mdx: String(DEFAULT_MDX),
+		extensions: DEFAULT_EXTENSIONS.join(","),
 		show: DEFAULT_SHOW,
 		focus: DEFAULT_FOCUS,
 	})
@@ -205,13 +203,13 @@ const envProvider = (env: Record<string, string | undefined>): ConfigProvider.Co
 	const theme = env["HOUSE_THEME"]
 	const tone = env["HOUSE_TONE"]
 	const defaultRoot = env["HOUSE_DEFAULT_ROOT"]
-	const mdx = env["HOUSE_MDX"]
+	const extensions = env["HOUSE_EXTENSIONS"]
 	const show = env["HOUSE_SHOW"]
 	const focus = env["HOUSE_FOCUS"]
 	if (theme !== undefined) entries.push(["theme", theme])
 	if (tone !== undefined) entries.push(["tone", tone])
 	if (defaultRoot !== undefined) entries.push(["defaultRoot", defaultRoot])
-	if (mdx !== undefined) entries.push(["mdx", mdx])
+	if (extensions !== undefined) entries.push(["extensions", extensions])
 	if (show !== undefined) entries.push(["show", show])
 	if (focus !== undefined) entries.push(["focus", focus])
 	return ConfigProvider.fromUnknown(Object.fromEntries(entries))
@@ -221,7 +219,7 @@ const cliProvider = (overrides: CliOverrides): ConfigProvider.ConfigProvider =>
 	const entries: Array<[string, string]> = []
 	if (overrides.theme !== null) entries.push(["theme", overrides.theme])
 	if (overrides.tone !== null) entries.push(["tone", overrides.tone])
-	if (overrides.mdx !== null) entries.push(["mdx", String(overrides.mdx)])
+	if (overrides.extensions !== null) entries.push(["extensions", overrides.extensions.join(",")])
 	if (overrides.show !== null) entries.push(["show", overrides.show.join(",")])
 	if (overrides.focus !== null) entries.push(["focus", overrides.focus])
 	return ConfigProvider.fromUnknown(Object.fromEntries(entries))
@@ -264,7 +262,7 @@ export const loadConfig = (
 	const cli = options.cli ?? {
 		theme: null,
 		tone: null,
-		mdx: null,
+		extensions: null,
 		show: null,
 		focus: null,
 	}
@@ -300,7 +298,13 @@ export const loadConfig = (
 				theme: raw.theme,
 				tone: raw.tone,
 				defaultRoot,
-				mdx: raw.mdx === "true",
+				extensions:
+					raw.extensions === ""
+						? []
+						: raw.extensions
+								.split(",")
+								.map((s) => s.trim())
+								.filter(Boolean),
 				show: parsed.value,
 				focus: raw.focus,
 			})

package/src/config/save.ts

@@ -0,0 +1,95 @@
+import { dirname } from "node:path"
+import { lstat, mkdir, readFile, realpath, rename, unlink, writeFile } from "node:fs/promises"
+import { defaultConfigPath } from "./load.ts"
+
+export interface ThemePreference {
+	readonly theme: string
+	readonly tone: "dark" | "light"
+}
+
+let saveQueue: Promise<void> = Promise.resolve()
+
+const encodeTomlString = (value: string): string => JSON.stringify(value)
+
+const upsertTopLevelString = (raw: string, key: keyof ThemePreference, value: string): string => {
+	const encoded = encodeTomlString(value)
+	const lines = raw.split("\n")
+	const keyPattern = new RegExp(`^(\\s*)${key}\\s*=.*$`)
+	let inTopLevel = true
+	let insertAt = lines.length
+
+	for (let i = 0; i < lines.length; i++) {
+		const line = lines[i]!
+		if (/^\s*\[[^\]]+\]\s*(?:#.*)?$/.test(line)) {
+			inTopLevel = false
+			insertAt = Math.min(insertAt, i)
+		}
+		if (!inTopLevel) continue
+		const match = keyPattern.exec(line)
+		if (match) {
+			lines[i] = `${match[1]}${key} = ${encoded}`
+			return lines.join("\n")
+		}
+	}
+
+	const insertion = `${key} = ${encoded}`
+	if (insertAt === lines.length) {
+		if (lines.length === 0 || lines[lines.length - 1] !== "") return `${raw}\n${insertion}\n`
+		lines.splice(lines.length - 1, 0, insertion)
+		return lines.join("\n")
+	}
+
+	lines.splice(insertAt, 0, insertion)
+	return lines.join("\n")
+}
+
+const updateThemePreferenceToml = (raw: string, record: ThemePreference): string => {
+	// Validate the existing file before preserving and editing its text. If the
+	// user has malformed TOML, fail loudly rather than replacing it wholesale.
+	Bun.TOML.parse(raw)
+	return upsertTopLevelString(upsertTopLevelString(raw, "theme", record.theme), "tone", record.tone)
+}
+
+const resolveWritableConfigPath = async (path: string): Promise<string> => {
+	try {
+		const stat = await lstat(path)
+		if (stat.isSymbolicLink()) return await realpath(path)
+	} catch (err) {
+		if ((err as NodeJS.ErrnoException).code !== "ENOENT") throw err
+	}
+	return path
+}
+
+const writeThemePreference = async (record: ThemePreference, path: string): Promise<void> => {
+	const targetPath = await resolveWritableConfigPath(path)
+	path = targetPath
+	const tmp = `${path}.${process.pid}.${Date.now()}.tmp`
+	try {
+		await mkdir(dirname(path), { recursive: true })
+		let next = `theme = ${encodeTomlString(record.theme)}\ntone = ${encodeTomlString(record.tone)}\n`
+		try {
+			const raw = await readFile(path, "utf8")
+			next = updateThemePreferenceToml(raw, record)
+		} catch (err) {
+			if ((err as NodeJS.ErrnoException).code !== "ENOENT") throw err
+		}
+		await writeFile(tmp, next, "utf8")
+		await rename(tmp, path)
+	} catch (err) {
+		try {
+			await unlink(tmp)
+		} catch {
+			// best-effort cleanup
+		}
+		throw err
+	}
+}
+
+export const saveThemePreference = async (
+	record: ThemePreference,
+	path = defaultConfigPath(),
+): Promise<void> => {
+	const run = saveQueue.catch(() => {}).then(() => writeThemePreference(record, path))
+	saveQueue = run.catch(() => {})
+	return run
+}

package/src/discovery/filter.ts

@@ -3,12 +3,26 @@
  *
  * Matching stays intentionally small and pure: case-insensitive subsequence on
  * the filename and full relative path. Ranking prefers what users usually mean
- * in a sidebar:
- *   - filename matches above folder-only matches
- *   - files in the current folder above equally good nested matches
- *   - shallower paths above deeper ones as a soft tie-break
+ * in a sidebar (no configuration, no user knobs):
+ *   - filename matches above folder-only matches (zf/fzf-inspired strong bias)
+ *   - shallower / current-folder paths win over deep nested ones
+ *   - incidental matches purely from deep directory names are heavily demoted
+ *     so "nested folders bubbling up" does not happen for typical queries
  *
  * Empty query preserves discovery/tree order.
+ *
+ * The low-level fuzzyScore uses a "best alignment" scan (try every possible
+ * start position for the first query char, complete greedily, take the highest
+ * scoring match). This avoids the "early spurious char traps" a pure left-to-right
+ * greedy can hit on paths (e.g. "src/r.../readme" for query "readme" must prefer
+ * the boundary "r" in the filename, not the "r" in "src"). This draws from fzf's
+ * v1 "find occurrence then look for better" idea and the general principle that
+ * boundary+consecutive bonuses should win when they exist later in the string.
+ * We deliberately do not depend on fuzzysort/fuse/fzf here: the ranking *policy*
+ * (heavy filename bias, exact/stem bonuses, depth soft penalty) is application
+ * specific to "what makes a sidebar nice" and must be owned so end users get the
+ * good experience with zero configuration or thought. See DESIGN.md §7.4 and the
+ * filter tests.
  */
 
 import type { FileEntry } from "./walk.ts"
@@ -17,19 +31,41 @@ export const fuzzyScore = (query: string, target: string): number | null => {
 	if (query.length === 0) return 0
 	const q = query.toLowerCase()
 	const t = target.toLowerCase()
-	let qi = 0
-	let score = 0
-	let lastMatch = -2
-	for (let i = 0; i < t.length && qi < q.length; i++) {
-		if (t[i] !== q[qi]) continue
-		const isWordStart = i === 0 || t[i - 1] === "/"
-		score += isWordStart ? 10 : 1
-		if (lastMatch === i - 1) score += 5
-		lastMatch = i
-		qi++
+	if (q.length > t.length) return null
+
+	let best: number | null = null
+
+	// Best-alignment: try every viable start for q[0], then complete the rest
+	// greedily from there. Take the alignment that accumulates the most bonus
+	// points (word-start after /, consecutives). This is what gives good OOB
+	// results on tree paths without the caller doing extra work.
+	for (let start = 0; start < t.length; start++) {
+		if (t[start] !== q[0]) continue
+
+		let qi = 1
+		let score = 0
+		let lastMatch = start
+
+		// score first char
+		const isWordStart0 = start === 0 || t[start - 1] === "/"
+		score += isWordStart0 ? 10 : 1
+
+		let i = start + 1
+		for (; i < t.length && qi < q.length; i++) {
+			if (t[i] !== q[qi]) continue
+			const isWordStart = i === 0 || t[i - 1] === "/"
+			score += isWordStart ? 10 : 1
+			if (lastMatch === i - 1) score += 5
+			lastMatch = i
+			qi++
+		}
+
+		if (qi === q.length) {
+			if (best === null || score > best) best = score
+		}
 	}
-	if (qi < q.length) return null
-	return score
+
+	return best
 }
 
 const splitPath = (relativePath: string): { fileName: string; depth: number } => {
@@ -55,15 +91,31 @@ const rankFile = (query: string, file: FileEntry): number | null => {
 	const stem = fileStem(fileName).toLowerCase()
 	const nameScore = fuzzyScore(query, fileName) ?? 0
 
-	let score = pathScore * 10
-	score += nameScore * 100
+	let score = pathScore * 4
+	score += nameScore * 150
 
+	// Filename (and stem) priority — the heart of good sidebar UX.
+	// Users almost always mean "the file whose name contains this", not
+	// "some directory component that happens to have these letters".
 	if (name === q || stem === q) score += 5_000
 	else if (name.startsWith(q) || stem.startsWith(q)) score += 2_000
 	else if (name.includes(q)) score += 1_000
 
-	if (depth === 0) score += 300
-	score -= depth * 10
+	// Strong depth bias so less-nested files appear near the top.
+	// We want shallow files to win over deep "nested folders" even when
+	// the deep file has a decent path match (common with short queries or
+	// dir names). The penalty is now large enough to matter vs. the
+	// match bonuses. Root gets a big kick. This is the main lever for
+	// "position in the tree structure" without any user config.
+	if (depth === 0) score += 800
+	score -= depth * 120
+
+	// Extra penalty when the match is weak or absent in the *basename*.
+	// This aggressively demotes results where the hit is only because the
+	// file lives under a matching deep directory ("nested folders bubbling up").
+	if (nameScore == null || nameScore < 8) {
+		score -= depth * 80
+	}
 
 	return score
 }
@@ -73,16 +125,24 @@ const rankFile = (query: string, file: FileEntry): number | null => {
  * unchanged (preserves the discovery sort order). Non-empty query keeps
  * matches only, sorted by score desc; ties fall back to the input order so
  * the discovery sort still leaks through.
+ *
+ * All the "make this feel right for users exploring a tree" logic lives here
+ * (and in rankFile) so callers (Browser) and end users never have to think
+ * about or configure ranking.
  */
 export const filterFiles = (files: readonly FileEntry[], query: string): readonly FileEntry[] => {
 	if (query.length === 0) return files
-	const scored: { file: FileEntry; score: number; index: number }[] = []
+	const scored: { file: FileEntry; score: number; depth: number; index: number }[] = []
 	for (let i = 0; i < files.length; i++) {
 		const file = files[i]!
 		const score = rankFile(query, file)
 		if (score === null) continue
-		scored.push({ file, score, index: i })
+		const depth = (file.relativePath.match(/\//g) || []).length
+		scored.push({ file, score, depth, index: i })
 	}
-	scored.sort((a, b) => b.score - a.score || a.index - b.index)
+	// Primary: match quality (fuzzy + name bonuses - depth penalties already in score)
+	// Secondary: shallower depth wins (less nested near top)
+	// Tertiary: stable original discovery order
+	scored.sort((a, b) => b.score - a.score || a.depth - b.depth || a.index - b.index)
 	return scored.map((s) => s.file)
 }

package/src/discovery/walk.ts

@@ -18,18 +18,15 @@ export interface DiscoveryWarning {
 	readonly cause: unknown
 }
 
-export type SortOrder = "dirs-first" | "files-first"
-
 export interface WalkOptions {
 	/** Categories of normally-skipped entries to opt into. Empty (the
 	 *  default) yields the conservative set: no dotfiles, no gitignored
 	 *  entries. Order is irrelevant — semantics are set membership. Hard
 	 *  skips (`node_modules`, `.git`, `.venv`) always apply. */
 	readonly show?: Iterable<ShowCategory>
-	/** Group order within each directory. Default `dirs-first`. */
-	readonly sort?: SortOrder
-	/** Include `.mdx` files alongside `.md`/`.markdown`. Default `true`. */
-	readonly mdx?: boolean
+	/** Additional file extensions to include alongside `.md` / `.markdown`.
+	 *  Values may include or omit the leading dot. */
+	readonly extensions?: Iterable<string>
 	/** Non-fatal subtree read errors. Root-level failures still error the walk. */
 	readonly onWarning?: ((warning: DiscoveryWarning) => void) | null
 }
@@ -39,10 +36,14 @@ export class DiscoveryError extends Data.TaggedError("DiscoveryError")<{
 	readonly cause: unknown
 }> {}
 
-const MARKDOWN_EXTENSIONS = new Set([".md", ".markdown", ".mdx"])
-const MARKDOWN_EXTENSIONS_NO_MDX = new Set([".md", ".markdown"])
+const BASE_EXTENSIONS = new Set([".md", ".markdown"])
 const HARD_SKIP_DIRS = new Set(["node_modules", ".git", ".venv"])
 
+const normalizeExtension = (ext: string): string => {
+	const trimmed = ext.trim().toLowerCase()
+	return trimmed.startsWith(".") ? trimmed : `.${trimmed}`
+}
+
 interface IgnoreLevel {
 	readonly dir: string
 	readonly ig: Ignore
@@ -73,14 +74,12 @@ const tryLoadGitignore = async (dir: string): Promise<Ignore | null> => {
 
 const sortEntries = <T extends { name: string; isDirectory: () => boolean }>(
 	entries: readonly T[],
-	order: SortOrder,
 ): T[] =>
 	[...entries].sort((a, b) => {
 		const aDir = a.isDirectory()
 		const bDir = b.isDirectory()
 		if (aDir !== bDir) {
-			if (order === "files-first") return aDir ? 1 : -1
-			return aDir ? -1 : 1
+			return aDir ? 1 : -1
 		}
 		return a.name.localeCompare(b.name)
 	})
@@ -88,7 +87,7 @@ const sortEntries = <T extends { name: string; isDirectory: () => boolean }>(
 /**
  * DFS generator. Yields each markdown FileEntry as it is discovered, before
  * descending further. Per-directory sort still happens before yielding so
- * arrival order within a directory matches the configured sort.
+ * arrival order is files-first and alphabetical within each group.
  *
  * Cancellation: `signal.aborted` is checked between syscalls. Node's
  * `readdir` doesn't accept an AbortSignal, so a single in-flight `readdir`
@@ -99,7 +98,7 @@ async function* walkDirGen(
 	dirPath: string,
 	rootPath: string,
 	parentLevels: readonly IgnoreLevel[],
-	opts: { showHidden: boolean; showGitignored: boolean; sort: SortOrder; mdx: boolean },
+	opts: { showHidden: boolean; showGitignored: boolean; extensions: ReadonlySet<string> },
 	onWarning: ((warning: DiscoveryWarning) => void) | null,
 	signal: AbortSignal,
 ): AsyncGenerator<FileEntry, void, void> {
@@ -123,7 +122,7 @@ async function* walkDirGen(
 	}
 	if (signal.aborted) return
 
-	for (const entry of sortEntries(raw, opts.sort)) {
+	for (const entry of sortEntries(raw)) {
 		if (signal.aborted) return
 
 		// Never follow symlinks — cycle hazard, and a markdown reader doesn't
@@ -142,7 +141,7 @@ async function* walkDirGen(
 
 		if (!entry.isFile()) continue
 		if (!opts.showHidden && entry.name.startsWith(".")) continue
-		const allowed = opts.mdx ? MARKDOWN_EXTENSIONS : MARKDOWN_EXTENSIONS_NO_MDX
+		const allowed = opts.extensions
 		if (!allowed.has(extname(entry.name).toLowerCase())) continue
 		if (!opts.showGitignored && isIgnored(entryPath, false, levels)) continue
 
@@ -161,13 +160,12 @@ async function* walkDirGen(
  * at its next `signal.aborted` check.
  *
  * Rules (see DESIGN.md §6):
- * - Extensions: `.md`, `.markdown`, and `.mdx` (unless `mdx: false`).
+ * - Extensions: `.md`, `.markdown`, plus configured extras.
  * - Hard skips (always): `node_modules`, `.git`, `.venv`.
  * - Hidden files/dirs (leading `.`) skipped unless `show` contains `"hidden"`.
  * - `.gitignore` honored, including nested `.gitignore` files.
  * - Symlinks not followed.
- * - Sort: alphabetical within each group; directories before files
- *   (`dirs-first`, default) or files before directories (`files-first`).
+ * - Sort: files before directories, alphabetical within each group.
  */
 export const walk = (
 	root: string,
@@ -175,11 +173,12 @@ export const walk = (
 ): Stream.Stream<FileEntry, DiscoveryError> => {
 	const absRoot = resolve(root)
 	const show = new Set<ShowCategory>(options.show ?? [])
+	const extensions = new Set(BASE_EXTENSIONS)
+	for (const ext of options.extensions ?? []) extensions.add(normalizeExtension(ext))
 	const opts = {
 		showHidden: show.has("hidden"),
 		showGitignored: show.has("gitignored"),
-		sort: options.sort ?? ("dirs-first" as SortOrder),
-		mdx: options.mdx ?? true,
+		extensions,
 	}
 	const onWarning = options.onWarning ?? null
 	const controller = new AbortController()

package/src/index.tsx

@@ -13,7 +13,7 @@ import { Browser, type StartupFocus } from "./Browser.tsx"
 import { parseArgv, usage } from "./cli/argv.ts"
 import { defaultConfigPath, formatConfigError, loadConfig } from "./config/load.ts"
 import { parseShowList, SHOW_CATEGORIES, type ShowCategory } from "./discovery/show.ts"
-import { walk, type FileEntry, type SortOrder } from "./discovery/walk.ts"
+import { walk, type FileEntry } from "./discovery/walk.ts"
 import { openInBrowser } from "./serve/openBrowser.ts"
 import { startServer } from "./serve/server.ts"
 import { setActiveTheme } from "./theme/colors.ts"
@@ -106,8 +106,7 @@ interface DiscoverShellProps {
 	 *  and the full vocabulary; the underlying categories remain
 	 *  independent everywhere else. */
 	readonly initialShow: readonly ShowCategory[]
-	readonly sort: SortOrder
-	readonly mdx: boolean
+	readonly extensions: readonly string[]
 	readonly maxWidth: number | null
 	readonly sidebarMode: SidebarMode
 	readonly startupFocus: StartupFocus
@@ -117,8 +116,7 @@ export const DiscoverShell = ({
 	target,
 	initialQuery,
 	initialShow,
-	sort,
-	mdx,
+	extensions,
 	maxWidth,
 	sidebarMode,
 	startupFocus,
@@ -147,8 +145,7 @@ export const DiscoverShell = ({
 		countRef.current = 0
 		const warnedProgram = walk(target, {
 			show,
-			sort,
-			mdx,
+			extensions,
 			onWarning: ({ path }) => {
 				const relativePath = relative(resolve(target), path)
 				setSkippedDirCount((prev) => prev + 1)
@@ -182,7 +179,7 @@ export const DiscoverShell = ({
 		return () => {
 			Effect.runFork(Fiber.interrupt(fiber))
 		}
-	}, [target, show, sort, mdx])
+	}, [target, show, extensions])
 
 	const discoveryStatus =
 		scanError ??
@@ -271,9 +268,13 @@ if (import.meta.main) {
 			cli: {
 				theme: args.theme,
 				tone: args.tone,
-				// --no-mdx is a one-way override: present means "off". When
-				// absent, fall through to env/file/default.
-				mdx: args.noMdx ? false : null,
+				extensions:
+					args.extensions === null
+						? null
+						: args.extensions
+								.split(",")
+								.map((s) => s.trim())
+								.filter(Boolean),
 				// `--show` replaces env/file when present (set semantics —
 				// no per-category merge across sources). `null` falls through.
 				show: cliShow,
@@ -287,7 +288,7 @@ if (import.meta.main) {
 		console.error(`house: ${formatConfigError(err)}`)
 		process.exit(2)
 	})
-	const { theme: themeId, tone, mdx, show, focus: startupFocus, defaultRoot } = config
+	const { theme: themeId, tone, extensions, show, focus: startupFocus, defaultRoot } = config
 	const themeDef = getThemeDefinition(themeId)
 	if (themeDef === undefined) {
 		// Unreachable: Config.schema validated themeId against themeDefinitions.
@@ -348,14 +349,6 @@ if (import.meta.main) {
 		process.on("SIGTERM", shutdown)
 		// Bun.serve keeps the event loop alive until stop().
 	} else {
-		let sort: SortOrder = "dirs-first"
-		if (args.sort !== null) {
-			if (args.sort !== "dirs-first" && args.sort !== "files-first") {
-				console.error(`house: --sort must be "dirs-first" or "files-first", got "${args.sort}"`)
-				process.exit(2)
-			}
-			sort = args.sort
-		}
 		let sidebarMode: SidebarMode = "auto"
 		if (args.sidebar !== null) {
 			if (args.sidebar !== "auto" && args.sidebar !== "on" && args.sidebar !== "off") {
@@ -379,8 +372,7 @@ if (import.meta.main) {
 			tone,
 			maxWidth,
 			show,
-			sort,
-			mdx,
+			extensions,
 			sidebarMode,
 			startupFocus,
 			updateCheck: !args.noUpdateCheck,
@@ -395,8 +387,7 @@ interface TuiBootOptions {
 	readonly tone: "dark" | "light"
 	readonly maxWidth: number | null
 	readonly show: readonly ShowCategory[]
-	readonly sort: SortOrder
-	readonly mdx: boolean
+	readonly extensions: readonly string[]
 	readonly sidebarMode: SidebarMode
 	readonly startupFocus: StartupFocus
 	/** Run the npm-registry probe and surface the "update available" notice.
@@ -411,8 +402,7 @@ async function runTui({
 	tone,
 	maxWidth,
 	show,
-	sort,
-	mdx,
+	extensions,
 	sidebarMode,
 	startupFocus,
 	updateCheck,
@@ -455,8 +445,7 @@ async function runTui({
 				target={discoveryRoot}
 				initialQuery={initialQuery}
 				initialShow={show}
-				sort={sort}
-				mdx={mdx}
+				extensions={extensions}
 				maxWidth={maxWidth}
 				sidebarMode={sidebarMode}
 				startupFocus={startupFocus}

package/src/layout/sidebarRow.ts

@@ -10,20 +10,15 @@
  * 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.
+ * Truncation policy: the basename stays whole when possible; the parent path
+ * middle-truncates into `a/…/z`-style output once it exceeds the remaining
+ * width. This preserves both the start and the end of the path, which is
+ * usually what users need to disambiguate nested docs.
  */
 
-export const SIDEBAR_ROW_SEPARATOR = "  ·  "
-const ELISION_PREFIX = "…/"
+import { middleTruncate } from "../ui/middleTruncate.ts"
+
+export const SIDEBAR_ROW_SEPARATOR = " "
 const MIN_PARENT_BUDGET = 3
 
 export interface SidebarRowParts {
@@ -54,18 +49,7 @@ export const formatSidebarRow = (relativePath: string, totalWidth: number): Side
 		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))
+	return row(basename, middleTruncate(parentFull, remaining))
 }
 
 const row = (basename: string, parent: string): SidebarRowParts => ({

package/src/ui/middleTruncate.ts

@@ -0,0 +1,27 @@
+/**
+ * Middle truncation for technical strings.
+ *
+ * Keeps the start and end of a string visible while compressing the middle
+ * to a single ellipsis glyph (`…`). Use for paths, IDs, branch names, and
+ * other values whose head and tail both matter.
+ */
+
+export interface MiddleTruncateOptions {
+	readonly ellipsis?: string
+}
+
+export const middleTruncate = (
+	value: string,
+	width: number,
+	options: MiddleTruncateOptions = {},
+): string => {
+	const ellipsis = options.ellipsis ?? "…"
+	if (width <= 0) return ""
+	if (value.length <= width) return value
+	if (width <= ellipsis.length) return value.slice(0, width)
+
+	const available = width - ellipsis.length
+	const left = Math.ceil(available / 2)
+	const right = Math.floor(available / 2)
+	return value.slice(0, left) + ellipsis + value.slice(value.length - right)
+}