@carlesandres/house 0.4.5 → 0.4.7

package/src/Footer.tsx

@@ -21,7 +21,10 @@
  * require a real cell-width counter (e.g. East Asian Width).
  */
 
+import type React from "react"
 import type { KeyBinding } from "./keymap/keymap.ts"
+import { displayKey } from "./keymap/displayKey.ts"
+import { Spinner } from "./Spinner.tsx"
 import { colors } from "./theme/colors.ts"
 
 /** Rows the Footer occupies. Importers use it for layout math so a future
@@ -42,35 +45,16 @@ export interface FooterProps<C> {
 	 *  while the filter input is open (the sidebar already shows the query) or
 	 *  when no filter is applied. */
 	readonly filterQuery?: string | null
+	/** Test seam: override spinner tick speed so tests don't sleep on the full
+	 *  production interval. Ignored when discoveryStatus is null. */
+	readonly discoverySpinnerIntervalMs?: number
+	readonly discoverySpinnerInitialFrameIndex?: number
+	/** Test seam: deterministic footer spinner driver. */
+	readonly discoverySpinnerRegisterTick?: ((tick: () => void) => void) | null
 }
 
 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 {
@@ -116,6 +100,9 @@ export const Footer = <C,>({
 	notice,
 	discoveryStatus,
 	filterQuery,
+	discoverySpinnerIntervalMs,
+	discoverySpinnerInitialFrameIndex,
+	discoverySpinnerRegisterTick,
 }: FooterProps<C>) => {
 	const usableWidth = Math.max(0, width - 2) // 1-cell horizontal padding each side
 
@@ -126,7 +113,7 @@ export const Footer = <C,>({
 		flexDirection: "row",
 		paddingLeft: 1,
 		paddingRight: 1,
-		backgroundColor: colors.surface,
+		backgroundColor: colors.backgroundPanel,
 	} as const
 
 	const hints: Hint[] = []
@@ -183,7 +170,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,20 +185,35 @@ 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>
 		)
 	}
 
 	if (status !== null) {
+		const spinnerProps = {
+			fg: colors.secondary,
+			...(discoverySpinnerIntervalMs === undefined
+				? {}
+				: { intervalMs: discoverySpinnerIntervalMs }),
+			...(discoverySpinnerInitialFrameIndex === undefined
+				? {}
+				: { initialFrameIndex: discoverySpinnerInitialFrameIndex }),
+			...(discoverySpinnerRegisterTick === undefined
+				? {}
+				: { registerTick: discoverySpinnerRegisterTick }),
+		} satisfies React.ComponentProps<typeof Spinner>
+
 		return (
 			<box style={rowStyle}>
-				<text content={statusContent} wrapMode="none" style={{ fg: colors.textMuted }} />
+				<Spinner {...spinnerProps} />
+				<text content=" " 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) => {

package/src/PromptRow.tsx

@@ -3,9 +3,9 @@
  * 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
+ * The `> ` prefix renders in `primary` or `secondary` so it
  * reads as chrome, not placeholder text — only the body span shifts color
- * (textStrong while editing, text when applied, textMuted as placeholder).
+ * (primary 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
@@ -16,7 +16,7 @@ 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. */
+	/** True while the input is focused — shows a cursor and uses primary fg. */
 	readonly editing: boolean
 	/** Body fallback when !editing && query === "". Pass without the `> ` prefix. */
 	readonly placeholder?: string
@@ -31,7 +31,7 @@ export const PromptRow = ({ query, editing, placeholder = "", width }: PromptRow
 	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 bodyFg = editing ? colors.primary : query.length > 0 ? colors.text : colors.textMuted
 
 	const body =
 		rawBody.length <= bodyBudget
@@ -40,9 +40,11 @@ export const PromptRow = ({ query, editing, placeholder = "", width }: PromptRow
 				? "…" + rawBody.slice(rawBody.length - bodyBudget + 1)
 				: rawBody.slice(0, bodyBudget - 1) + "…"
 
+	const prefixFg = editing ? colors.secondary : colors.primary
+
 	return (
 		<text wrapMode="none">
-			<span style={{ fg: colors.textStrong }}>{PREFIX}</span>
+			<span style={{ fg: prefixFg }}>{PREFIX}</span>
 			<span style={{ fg: bodyFg }}>{body}</span>
 		</text>
 	)

package/src/Spinner.tsx

@@ -0,0 +1,39 @@
+import { useEffect, useRef, useState } from "react"
+import { colors } from "./theme/colors.ts"
+
+const FRAMES = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"] as const
+const FRAME_COUNT = FRAMES.length
+const normalizeFrameIndex = (index: number) => ((index % FRAME_COUNT) + FRAME_COUNT) % FRAME_COUNT
+
+export interface SpinnerProps {
+	readonly fg?: string
+	readonly intervalMs?: number
+	readonly initialFrameIndex?: number
+	/** Test seam: deterministic driver for frame advancement. When present,
+	 *  Spinner registers its tick callback here instead of starting an interval. */
+	readonly registerTick?: ((tick: () => void) => void) | null
+}
+
+export const Spinner = ({
+	fg = colors.textMuted,
+	intervalMs = 100,
+	initialFrameIndex = 0,
+	registerTick = null,
+}: SpinnerProps) => {
+	const [index, setIndex] = useState(() => normalizeFrameIndex(initialFrameIndex))
+	const tickRef = useRef<() => void>(() => undefined)
+	tickRef.current = () => setIndex((prev) => (prev + 1) % FRAME_COUNT)
+
+	useEffect(() => {
+		if (registerTick) {
+			registerTick(() => tickRef.current())
+			return
+		}
+		const id = setInterval(() => {
+			tickRef.current()
+		}, intervalMs)
+		return () => clearInterval(id)
+	}, [intervalMs, registerTick])
+
+	return <text content={FRAMES[index] ?? FRAMES[0]} wrapMode="none" style={{ fg }} />
+}

package/src/cli/argv.ts

@@ -1,8 +1,11 @@
+import { Command } from "commander"
 import { themeDefinitions } from "../theme/registry.ts"
 
 export interface ParsedArgs {
 	/** First positional argument, or null if none was given. */
 	readonly path: string | null
+	/** Value of `--root <dir>`, or null. */
+	readonly root: string | null
 	/** Value of `--theme <id>`, or null. Validated by the boot layer against the registry. */
 	readonly theme: string | null
 	/** Value of `--tone dark|light`, or null. Validated by the boot layer. */
@@ -29,9 +32,9 @@ export interface ParsedArgs {
 	readonly noUpdateCheck: boolean
 	/** True when `--no-mdx` was passed: exclude `.mdx` files from discovery. */
 	readonly noMdx: boolean
-	/** True when `--start-in-filter` was passed: open the sidebar filter
-	 *  prompt on launch (one-way override; default is off). */
-	readonly startInFilter: boolean
+	/** Value of `--focus <mode>` (`sidebar`, `reader`, `filter`), or null.
+	 *  Validated by the boot layer. */
+	readonly focus: string | null
 	/** Raw value of `--show <list>`, or null if the flag wasn't passed.
 	 *  Comma-separated list of category names; the boot layer validates
 	 *  tokens against the known vocabulary (see `discovery/show.ts`).
@@ -39,6 +42,67 @@ export interface ParsedArgs {
 	readonly show: string | null
 }
 
+const createProgram = () =>
+	new Command()
+		.allowUnknownOption(true)
+		.allowExcessArguments(true)
+		.exitOverride()
+		.helpOption(false)
+		.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("--focus [mode]")
+		.option("--show [list]")
+		.option("--root [dir]")
+		.option("-h, --help")
+		.option("-v, --version")
+		.argument("[path]")
+
+const VALUE_FLAGS: ReadonlySet<string> = new Set([
+	"--theme",
+	"--tone",
+	"--width",
+	"--sort",
+	"--port",
+	"--sidebar",
+	"--focus",
+	"--show",
+	"--root",
+])
+
+const BOOLEAN_FLAGS: ReadonlySet<string> = new Set([
+	"--serve",
+	"--config-path",
+	"--no-update-check",
+	"--no-mdx",
+	"--help",
+	"-h",
+	"--version",
+	"-v",
+])
+
+const findPathArg = (argv: readonly string[]): string | null => {
+	for (let i = 0; i < argv.length; i++) {
+		const arg = argv[i]!
+		if (VALUE_FLAGS.has(arg)) {
+			const next = argv[i + 1]
+			if (next !== undefined && !next.startsWith("-")) i++
+			continue
+		}
+		if (BOOLEAN_FLAGS.has(arg)) continue
+		if (arg.startsWith("-")) continue
+		return arg
+	}
+	return null
+}
+
 /**
  * Minimal argv parser.
  *
@@ -47,110 +111,29 @@ export interface ParsedArgs {
  * without coupling the parser to it.
  */
 export const parseArgv = (argv: readonly string[]): ParsedArgs => {
-	let path: string | null = null
-	let theme: string | null = null
-	let tone: string | null = null
-	let width: string | null = null
-	let sort: string | null = null
-	let serve = false
-	let port: string | null = null
-	let help = false
-	let version = false
-	let configPath = false
-	let sidebar: string | null = null
-	let noUpdateCheck = false
-	let noMdx = false
-	let show: string | null = null
-	let startInFilter = false
-
-	for (let i = 0; i < argv.length; i++) {
-		const arg = argv[i]!
-		switch (arg) {
-			case "--theme":
-				theme = argv[i + 1] ?? null
-				i++
-				continue
-			case "--tone":
-				tone = argv[i + 1] ?? null
-				i++
-				continue
-			case "--width":
-				width = argv[i + 1] ?? null
-				i++
-				continue
-			case "--sort":
-				sort = argv[i + 1] ?? null
-				i++
-				continue
-			case "--serve":
-				serve = true
-				continue
-			case "--port":
-				port = argv[i + 1] ?? null
-				i++
-				continue
-			case "--help":
-			case "-h":
-				help = true
-				continue
-			case "--version":
-			case "-v":
-				version = true
-				continue
-			case "--config-path":
-				configPath = true
-				continue
-			case "--sidebar": {
-				// Don't swallow the following flag as the sidebar value.
-				// `--sidebar --width 80` should leave sidebar=null (the boot
-				// layer reports a missing value) without losing --width.
-				const next = argv[i + 1]
-				if (next !== undefined && !next.startsWith("-")) {
-					sidebar = next
-					i++
-				}
-				continue
-			}
-			case "--no-update-check":
-				noUpdateCheck = true
-				continue
-			case "--no-mdx":
-				noMdx = true
-				continue
-			case "--start-in-filter":
-				startInFilter = true
-				continue
-			case "--show":
-				// Always consume the following arg, even when it looks like
-				// a flag — `--show ""` is meaningful (explicit empty set),
-				// and the empty-string regression matters more than the
-				// near-miss case of someone forgetting the value. Boot
-				// validates tokens.
-				show = argv[i + 1] ?? null
-				i++
-				continue
-		}
-		if (path === null && !arg.startsWith("-")) {
-			path = arg
-		}
-	}
+	const program = createProgram()
+	program.parse([...argv], { from: "user" })
+	const opts = program.opts<Record<string, unknown>>()
+	const pathArg = findPathArg(argv)
+	const stringOrNull = (value: unknown): string | null => (typeof value === "string" ? value : null)
 
 	return {
-		path,
-		theme,
-		tone,
-		width,
-		sort,
-		serve,
-		port,
-		help,
-		version,
-		configPath,
-		sidebar,
-		noUpdateCheck,
-		noMdx,
-		show,
-		startInFilter,
+		path: typeof pathArg === "string" ? pathArg : null,
+		root: stringOrNull(opts["root"]),
+		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,
+		version: opts["version"] === true,
+		configPath: opts["configPath"] === true,
+		sidebar: stringOrNull(opts["sidebar"]),
+		noUpdateCheck: opts["noUpdateCheck"] === true,
+		noMdx: opts["mdx"] === false,
+		show: stringOrNull(opts["show"]),
+		focus: stringOrNull(opts["focus"]),
 	}
 }
 
@@ -166,8 +149,10 @@ options:
   --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>   discovery root to walk (overrides defaultRoot config)
   --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 given file as HTML in the browser (skips TUI)
   --port <N>     port for --serve (default: OS-assigned)
   -h, --help     show this help and exit
@@ -175,10 +160,9 @@ options:
   --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)
-  --start-in-filter  open the sidebar filter prompt on launch
 
 configuration:
   file: $XDG_CONFIG_HOME/house/config.toml  (default ~/.config/house/config.toml)
-  keys: theme, tone, mdx, show, start_in_filter
-  env:  HOUSE_THEME, HOUSE_TONE, HOUSE_MDX, HOUSE_SHOW, HOUSE_START_IN_FILTER
+  keys: theme, tone, mdx, show, focus, defaultRoot
+  env:  HOUSE_THEME, HOUSE_TONE, HOUSE_MDX, HOUSE_SHOW, HOUSE_FOCUS, HOUSE_DEFAULT_ROOT
   precedence (high → low): flags → env → file → defaults`

package/src/config/load.ts

@@ -20,14 +20,15 @@ export interface HouseConfig {
 	readonly theme: string
 	readonly tone: "dark" | "light"
 	readonly mdx: boolean
+	/** Default discovery-root strategy when no explicit `--root` flag is passed. */
+	readonly defaultRoot: "cwd" | "git"
 	/** Categories of normally-skipped entries to opt into. See
 	 *  `src/discovery/show.ts` for the vocabulary. Empty array (the
 	 *  default) yields the conservative discovery set. */
 	readonly show: readonly ShowCategory[]
-	/** Open the sidebar filter prompt on launch so the user can type
-	 *  immediately. Esc returns to normal focus (no special behavior).
-	 *  Default false. */
-	readonly startInFilter: boolean
+	/** Startup pane/input target. `filter` opens the sidebar filter prompt and
+	 *  focuses it immediately. */
+	readonly focus: "sidebar" | "reader" | "filter"
 }
 
 export interface CliOverrides {
@@ -38,14 +39,15 @@ export interface CliOverrides {
 	 *  (no per-category merging — sets compose by replacement, like every
 	 *  other CLI override here). `--show ""` sets the empty set. */
 	readonly show: readonly ShowCategory[] | null
-	readonly startInFilter: boolean | null
+	readonly focus: "sidebar" | "reader" | "filter" | null
 }
 
 const DEFAULT_THEME = "opencode"
 const DEFAULT_TONE: "dark" | "light" = "dark"
 const DEFAULT_MDX = true
+const DEFAULT_ROOT: "cwd" | "git" = "cwd"
 const DEFAULT_SHOW = ""
-const DEFAULT_START_IN_FILTER = false
+const DEFAULT_FOCUS: "sidebar" | "reader" | "filter" = "filter"
 
 const themeIds = themeDefinitions.map((t) => t.id)
 
@@ -60,12 +62,14 @@ const KNOWN_FILE_KEYS: ReadonlySet<string> = new Set([
 	"tone",
 	"mdx",
 	"show",
-	"start_in_filter",
+	"focus",
+	"defaultRoot",
 ])
 
 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.
@@ -75,16 +79,17 @@ const schema = Config.all({
 	// `"hidden,gitignored"`). Token-level validation happens in `loadConfig`
 	// so the error message can list valid categories at the field's path.
 	show: Config.schema(Schema.String, "show"),
-	start_in_filter: Config.schema(Schema.Literals(["true", "false"] as const), "start_in_filter"),
+	focus: Config.schema(Schema.Literals(["sidebar", "reader", "filter"] as const), "focus"),
 })
 
 const defaultsProvider = (): ConfigProvider.ConfigProvider =>
 	ConfigProvider.fromUnknown({
 		theme: DEFAULT_THEME,
 		tone: DEFAULT_TONE,
+		defaultRoot: DEFAULT_ROOT,
 		mdx: String(DEFAULT_MDX),
 		show: DEFAULT_SHOW,
-		start_in_filter: String(DEFAULT_START_IN_FILTER),
+		focus: DEFAULT_FOCUS,
 	})
 
 /**
@@ -199,14 +204,16 @@ const envProvider = (env: Record<string, string | undefined>): ConfigProvider.Co
 	const entries: Array<[string, string]> = []
 	const theme = env["HOUSE_THEME"]
 	const tone = env["HOUSE_TONE"]
+	const defaultRoot = env["HOUSE_DEFAULT_ROOT"]
 	const mdx = env["HOUSE_MDX"]
 	const show = env["HOUSE_SHOW"]
-	const startInFilter = env["HOUSE_START_IN_FILTER"]
+	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 (show !== undefined) entries.push(["show", show])
-	if (startInFilter !== undefined) entries.push(["start_in_filter", startInFilter])
+	if (focus !== undefined) entries.push(["focus", focus])
 	return ConfigProvider.fromUnknown(Object.fromEntries(entries))
 }
 
@@ -216,8 +223,7 @@ const cliProvider = (overrides: CliOverrides): ConfigProvider.ConfigProvider =>
 	if (overrides.tone !== null) entries.push(["tone", overrides.tone])
 	if (overrides.mdx !== null) entries.push(["mdx", String(overrides.mdx)])
 	if (overrides.show !== null) entries.push(["show", overrides.show.join(",")])
-	if (overrides.startInFilter !== null)
-		entries.push(["start_in_filter", String(overrides.startInFilter)])
+	if (overrides.focus !== null) entries.push(["focus", overrides.focus])
 	return ConfigProvider.fromUnknown(Object.fromEntries(entries))
 }
 
@@ -260,7 +266,7 @@ export const loadConfig = (
 		tone: null,
 		mdx: null,
 		show: null,
-		startInFilter: null,
+		focus: null,
 	}
 	const onWarning = options.onWarning ?? ((msg) => process.stderr.write(`${msg}\n`))
 	const provider = cliProvider(cli).pipe(
@@ -270,6 +276,13 @@ export const loadConfig = (
 	)
 	return schema.parse(provider).pipe(
 		Effect.flatMap((raw) => {
+			const defaultRoot =
+				raw.defaultRoot === "cwd" || raw.defaultRoot === "git" ? raw.defaultRoot : DEFAULT_ROOT
+			if (raw.defaultRoot !== defaultRoot) {
+				onWarning(
+					`house: ignoring invalid value ${JSON.stringify(raw.defaultRoot)} for defaultRoot in config/env; using "${DEFAULT_ROOT}"`,
+				)
+			}
 			const parsed = parseShowList(raw.show)
 			if (!parsed.ok) {
 				// Effect's `Config.ConfigError` requires a `SchemaError` or
@@ -286,9 +299,10 @@ export const loadConfig = (
 			return Effect.succeed({
 				theme: raw.theme,
 				tone: raw.tone,
+				defaultRoot,
 				mdx: raw.mdx === "true",
 				show: parsed.value,
-				startInFilter: raw.start_in_filter === "true",
+				focus: raw.focus,
 			})
 		}),
 	)

package/src/discovery/filter.ts

@@ -1,18 +1,14 @@
 /**
  * Fuzzy filter for the sidebar.
  *
- * Matching: case-insensitive subsequence on `relativePath`. A query "drm"
- * matches "docs/readme.md". Scoring (higher is better):
- *   - +10 for a match at the start of the string or right after `/`
- *     (word boundary — what the user typed lines up with a path segment)
- *   - +5 when the current match is adjacent to the previous one
- *     (consecutive runs read as "drm" matching the literal substring)
- *   - +1 otherwise
+ * 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
  *
- * The scorer is intentionally tiny — the only goal is to surface the
- * "obvious" match for short queries against a few hundred paths. A full
- * fzf-style scorer (with bonuses for camelCase, separators, etc.) is
- * deferred until the simple version proves insufficient.
+ * Empty query preserves discovery/tree order.
  */
 
 import type { FileEntry } from "./walk.ts"
@@ -36,6 +32,42 @@ export const fuzzyScore = (query: string, target: string): number | null => {
 	return score
 }
 
+const splitPath = (relativePath: string): { fileName: string; depth: number } => {
+	const slash = relativePath.lastIndexOf("/")
+	return {
+		fileName: slash >= 0 ? relativePath.slice(slash + 1) : relativePath,
+		depth: slash >= 0 ? relativePath.split("/").length - 1 : 0,
+	}
+}
+
+const fileStem = (fileName: string): string => {
+	const dot = fileName.lastIndexOf(".")
+	return dot > 0 ? fileName.slice(0, dot) : fileName
+}
+
+const rankFile = (query: string, file: FileEntry): number | null => {
+	const pathScore = fuzzyScore(query, file.relativePath)
+	if (pathScore === null) return null
+
+	const { fileName, depth } = splitPath(file.relativePath)
+	const q = query.toLowerCase()
+	const name = fileName.toLowerCase()
+	const stem = fileStem(fileName).toLowerCase()
+	const nameScore = fuzzyScore(query, fileName) ?? 0
+
+	let score = pathScore * 10
+	score += nameScore * 100
+
+	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
+
+	return score
+}
+
 /**
  * Filter and re-rank a file list by a query. Empty query returns the input
  * unchanged (preserves the discovery sort order). Non-empty query keeps
@@ -47,7 +79,7 @@ export const filterFiles = (files: readonly FileEntry[], query: string): readonl
 	const scored: { file: FileEntry; score: number; index: number }[] = []
 	for (let i = 0; i < files.length; i++) {
 		const file = files[i]!
-		const score = fuzzyScore(query, file.relativePath)
+		const score = rankFile(query, file)
 		if (score === null) continue
 		scored.push({ file, score, index: i })
 	}