@carlesandres/house 0.4.5 → 0.4.7

package/src/index.tsx

@@ -9,6 +9,7 @@
  */
 
 import { stat } from "node:fs/promises"
+import { dirname, resolve } from "node:path"
 import { createCliRenderer, SyntaxStyle } from "@opentui/core"
 import type { BorderSides } from "@opentui/core"
 import { createRoot, useKeyboard, useRenderer, useTerminalDimensions } from "@opentui/react"
@@ -16,7 +17,7 @@ import { RegistryProvider, useAtomSet, useAtomValue } from "@effect/atom-react"
 import { Cause, Duration, Effect, Fiber, Stream } from "effect"
 import { useEffect, useMemo, useRef, useState } from "react"
 import pkg from "../package.json" with { type: "json" }
-import { Browser } from "./Browser.tsx"
+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"
@@ -58,6 +59,39 @@ export interface AppProps {
  */
 export type SidebarMode = "auto" | "on" | "off"
 
+const pathIsDirectory = async (path: string): Promise<boolean> => {
+	try {
+		return (await stat(path)).isDirectory()
+	} catch {
+		return false
+	}
+}
+
+const findGitRoot = async (cwd: string): Promise<string> => {
+	const start = resolve(cwd)
+	let current = start
+	for (;;) {
+		if (await pathIsDirectory(resolve(current, ".git"))) return current
+		const parent = dirname(current)
+		if (parent === current) return start
+		current = parent
+	}
+}
+
+export const resolveDiscoveryRoot = async ({
+	cliRoot,
+	defaultRoot,
+	cwd,
+}: {
+	readonly cliRoot: string | null
+	readonly defaultRoot: "cwd" | "git"
+	readonly cwd: string
+}): Promise<string> => {
+	if (cliRoot !== null) return cliRoot
+	if (defaultRoot === "git") return findGitRoot(cwd)
+	return cwd
+}
+
 interface DiscoverShellProps {
 	readonly target: string
 	/** Resolved discovery vocabulary from the config layer. The shift+a
@@ -69,7 +103,7 @@ interface DiscoverShellProps {
 	readonly mdx: boolean
 	readonly maxWidth: number | null
 	readonly sidebarMode: SidebarMode
-	readonly startInFilter: boolean
+	readonly startupFocus: StartupFocus
 }
 
 const DiscoverShell = ({
@@ -79,7 +113,7 @@ const DiscoverShell = ({
 	mdx,
 	maxWidth,
 	sidebarMode,
-	startInFilter,
+	startupFocus,
 }: DiscoverShellProps) => {
 	const updateNotice = useUpdateNotice()
 	const [show, setShow] = useState<readonly ShowCategory[]>(initialShow)
@@ -134,7 +168,7 @@ const DiscoverShell = ({
 			maxWidth={maxWidth}
 			discoveryStatus={discoveryStatus}
 			sidebarMode={sidebarMode}
-			startInFilter={startInFilter}
+			startupFocus={startupFocus}
 			updateNotice={updateNotice}
 			onToggleAll={() => {
 				// shift+a is the only place the categories are treated as a
@@ -267,15 +301,17 @@ if (import.meta.main) {
 				// `--show` replaces env/file when present (set semantics —
 				// no per-category merge across sources). `null` falls through.
 				show: cliShow,
-				// One-way override: present means "on". Absent → env/file/default.
-				startInFilter: args.startInFilter ? true : null,
+				focus:
+					args.focus === "sidebar" || args.focus === "reader" || args.focus === "filter"
+						? args.focus
+						: null,
 			},
 		}),
 	).catch((err: unknown) => {
 		console.error(`house: ${formatConfigError(err)}`)
 		process.exit(2)
 	})
-	const { theme: themeId, tone, mdx, show, startInFilter } = config
+	const { theme: themeId, tone, mdx, show, focus: startupFocus, defaultRoot } = config
 	const themeDef = getThemeDefinition(themeId)
 	if (themeDef === undefined) {
 		// Unreachable: Config.schema validated themeId against themeDefinitions.
@@ -294,7 +330,9 @@ if (import.meta.main) {
 		maxWidth = n
 	}
 
+	const cwd = process.cwd()
 	const target = args.path ?? "."
+	const discoveryRoot = await resolveDiscoveryRoot({ cliRoot: args.root, defaultRoot, cwd })
 
 	if (args.serve) {
 		let stats: Awaited<ReturnType<typeof stat>>
@@ -345,8 +383,17 @@ if (import.meta.main) {
 			}
 			sidebarMode = args.sidebar
 		}
+		if (args.focus !== null) {
+			if (args.focus !== "sidebar" && args.focus !== "reader" && args.focus !== "filter") {
+				console.error(
+					`house: --focus must be "sidebar", "reader", or "filter", got "${args.focus}"`,
+				)
+				process.exit(2)
+			}
+		}
 		await runTui({
 			target,
+			discoveryRoot,
 			themeId,
 			tone,
 			maxWidth,
@@ -354,7 +401,7 @@ if (import.meta.main) {
 			sort,
 			mdx,
 			sidebarMode,
-			startInFilter,
+			startupFocus,
 			updateCheck: !args.noUpdateCheck,
 		})
 	}
@@ -362,6 +409,7 @@ if (import.meta.main) {
 
 interface TuiBootOptions {
 	readonly target: string
+	readonly discoveryRoot: string
 	readonly themeId: string
 	readonly tone: "dark" | "light"
 	readonly maxWidth: number | null
@@ -369,7 +417,7 @@ interface TuiBootOptions {
 	readonly sort: SortOrder
 	readonly mdx: boolean
 	readonly sidebarMode: SidebarMode
-	readonly startInFilter: boolean
+	readonly startupFocus: StartupFocus
 	/** Run the npm-registry probe and surface the "update available" notice.
 	 *  False suppresses both the toast and the quit-time print. */
 	readonly updateCheck: boolean
@@ -377,6 +425,7 @@ interface TuiBootOptions {
 
 async function runTui({
 	target,
+	discoveryRoot,
 	themeId,
 	tone,
 	maxWidth,
@@ -384,7 +433,7 @@ async function runTui({
 	sort,
 	mdx,
 	sidebarMode,
-	startInFilter,
+	startupFocus,
 	updateCheck,
 }: TuiBootOptions): Promise<void> {
 	let stats: Awaited<ReturnType<typeof stat>>
@@ -420,13 +469,13 @@ async function runTui({
 		createRoot(renderer).render(
 			<RegistryProvider initialValues={[[themeAtom, initialTheme]]}>
 				<DiscoverShell
-					target={target}
+					target={discoveryRoot}
 					initialShow={show}
 					sort={sort}
 					mdx={mdx}
 					maxWidth={maxWidth}
 					sidebarMode={sidebarMode}
-					startInFilter={startInFilter}
+					startupFocus={startupFocus}
 				/>
 			</RegistryProvider>,
 		)

package/src/keymap/browser.ts

@@ -11,7 +11,7 @@ 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
+	 *  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
@@ -20,6 +20,7 @@ export interface BrowserCtx {
 	readonly sidebarShown: boolean
 	readonly helpVisible: boolean
 	readonly filterOpen: boolean
+	readonly restoreFilterOnSidebarFocus: 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
@@ -87,7 +88,13 @@ export const browserBindings: readonly KeyBinding<BrowserCtx>[] = [
 		description: "Toggle focus (sidebar ↔ reader)",
 		hint: "focus",
 		keys: ["tab"],
-		run: (c) => c.setFocus((f) => (f === "sidebar" ? "reader" : "sidebar")),
+		run: (c) => {
+			if (c.focus === "reader" && c.restoreFilterOnSidebarFocus) {
+				c.openFilter()
+			} else {
+				c.setFocus((f) => (f === "sidebar" ? "reader" : "sidebar"))
+			}
+		},
 	},
 	{
 		id: "sidebar.toggle",
@@ -271,7 +278,7 @@ export const browserBindings: readonly KeyBinding<BrowserCtx>[] = [
 		group: "File",
 		description: "Open current file in browser as HTML",
 		hint: "html",
-		keys: ["o"],
+		keys: ["shift+o"],
 		when: hasSelected,
 		run: (c) => c.serveCurrent(),
 	},
@@ -280,7 +287,7 @@ export const browserBindings: readonly KeyBinding<BrowserCtx>[] = [
 		group: "File",
 		description: "Open current file in $EDITOR",
 		hint: "edit",
-		keys: ["e"],
+		keys: ["shift+e"],
 		when: hasSelected,
 		run: (c) => c.editCurrent(),
 	},

package/src/keymap/displayKey.ts

@@ -0,0 +1,17 @@
+/** Terminal-friendly display form for a binding's first key chord. */
+export 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
+	}
+}

package/src/keymap/keymap.ts

@@ -62,6 +62,9 @@ const parseChord = (raw: string): ParsedChord => {
 }
 
 const chordMatches = (chord: ParsedChord, key: KeyMatch): boolean => {
+	if (chord.key === "tab" && key.name === "i" && key.ctrl && !key.shift && !key.meta) {
+		return true
+	}
 	if (chord.key !== key.name) return false
 	if (chord.shift !== Boolean(key.shift)) return false
 	if (chord.ctrl !== Boolean(key.ctrl)) return false

package/src/serve/server.ts

@@ -2,7 +2,7 @@
  * Local HTML preview server for a single markdown file.
  *
  * One long-lived `Bun.serve` instance. The served file path is swappable
- * via `setTarget(path)` — used by the TUI's `o` binding so pressing it on a
+ * via `setTarget(path)` — used by the TUI's `O` binding so pressing it on a
  * new file retargets the existing server (live-reload fires) instead of
  * spawning a second one.
  *

package/src/theme/colors.ts

@@ -6,52 +6,20 @@ import type { ColorPalette, ResolvedTheme, ThemeDefinition, Tone } from "./types
  * Adapt a resolved theme (opencode-shaped flat tokens) to the
  * {@link ColorPalette} shape consumed by Browser / HelpOverlay / index.
  *
- * - UI tokens map name-for-name where they overlap.
- * - `surface` ← `backgroundPanel`, `selectedBg` ← `backgroundElement`,
- *   `selectedBgInactive` ← `borderSubtle`.
- * - `textStrong` ← `primary` (opencode's convention for emphasized brand
- *   text in UI chrome). Markdown rendering still reads `markdownStrong`
- *   directly via the syntax map.
+ * - UI tokens map name-for-name with OpenCode's TUI theme semantics.
  * - `syntax` is a fully populated opentui tree-sitter scope map built from
  *   `markdown*` and `syntax*` tokens.
  */
-/** Relative luminance of a `#rrggbb` color (0..1). Sufficient for ordering
- *  two near-neutral chrome colors — not a full WCAG contrast calculation.
- *  Non-hex inputs fall back to 0.5 so the caller's ordering is a no-op. */
-const luminance = (hex: string): number => {
-	const m = /^#([0-9a-fA-F]{6})$/.exec(hex)
-	if (!m) return 0.5
-	const h = m[1]!
-	const r = parseInt(h.slice(0, 2), 16)
-	const g = parseInt(h.slice(2, 4), 16)
-	const b = parseInt(h.slice(4, 6), 16)
-	// Rec. 601 weighting — perceptual ordering, not the linearized WCAG variant.
-	return (0.299 * r + 0.587 * g + 0.114 * b) / 255
-}
-
-/** Pane chrome assumes the active/raised pane sits on the darker of the two
- *  background tokens and the dim chrome on the lighter one. Most themes
- *  define `background` darker than `backgroundPanel` and this is a no-op;
- *  some (e.g. cursor) flip the polarity, in which case we swap so the
- *  active-pane convention stays consistent across themes. */
-const orientChrome = (r: ResolvedTheme): { raised: string; dim: string } => {
-	const bg = r.background
-	const panel = r.backgroundPanel
-	return luminance(bg) <= luminance(panel) ? { raised: bg, dim: panel } : { raised: panel, dim: bg }
-}
-
 const buildPalette = (r: ResolvedTheme): ColorPalette => {
-	const { raised, dim } = orientChrome(r)
 	return {
-		background: raised,
-		surface: dim,
+		background: r.background,
+		backgroundPanel: r.backgroundPanel,
+		backgroundElement: r.backgroundElement,
 		text: r.text,
-		textStrong: r.primary,
 		textMuted: r.textMuted,
 		border: r.border,
 		borderActive: r.borderActive,
-		selectedBg: r.backgroundElement,
-		selectedBgInactive: r.borderSubtle,
+		borderSubtle: r.borderSubtle,
 		selectedListItemText: r.selectedListItemText,
 		primary: r.primary,
 		secondary: r.secondary,

package/src/theme/types.ts

@@ -82,21 +82,20 @@ export type TokenName = keyof ThemeTokens
 export type ResolvedTheme = Readonly<Record<TokenName, HexColor>>
 
 /**
- * The flat color object consumed by Browser/HelpOverlay/index. Keeps the
- * existing names (`background`, `surface`, `text`, `syntax`, …) so the
- * UI files don't all have to change. Values come from
- * `colors.ts`'s adapter, which maps `ResolvedTheme` → this shape.
+ * The flat color object consumed by Browser/HelpOverlay/index. Uses the
+ * OpenCode-aligned UI token names directly (`background`, `backgroundPanel`,
+ * `backgroundElement`, `borderSubtle`, `primary`, `secondary`, …). Values
+ * come from `colors.ts`'s adapter, which maps `ResolvedTheme` → this shape.
  */
 export interface ColorPalette {
 	readonly background: string
-	readonly surface: string
+	readonly backgroundPanel: string
+	readonly backgroundElement: string
 	readonly text: string
-	readonly textStrong: string
 	readonly textMuted: string
 	readonly border: string
 	readonly borderActive: string
-	readonly selectedBg: string
-	readonly selectedBgInactive: string
+	readonly borderSubtle: string
 	readonly selectedListItemText: string
 	readonly primary: string
 	readonly secondary: string

package/src/tips.ts

@@ -0,0 +1,93 @@
+import type { BrowserCtx } from "./keymap/browser.ts"
+import type { KeyBinding } from "./keymap/keymap.ts"
+import { displayKey } from "./keymap/displayKey.ts"
+
+export interface TipLine {
+	readonly id: string
+	readonly text: string
+}
+
+interface TipDefinition {
+	readonly id: string
+	readonly bindingId?: string
+	readonly render: (parts: { readonly key: string | null }) => string
+	readonly when?: (ctx: BrowserCtx) => boolean
+}
+
+const tipDefinitions: readonly TipDefinition[] = [
+	{
+		id: "filter.start",
+		bindingId: "filter.open",
+		render: ({ key }) => `Press ${key ?? "/"} to start filtering files by path.`,
+		when: (ctx) => ctx.filterQuery.length === 0 && !ctx.filterOpen,
+	},
+	{
+		id: "filter.resume",
+		bindingId: "filter.open",
+		render: ({ key }) => `Press ${key ?? "/"} to reopen the current filter and keep refining it.`,
+		when: (ctx) => ctx.filterQuery.length > 0 && !ctx.filterOpen,
+	},
+	{
+		id: "filter.commit",
+		bindingId: "filter.open",
+		render: () => "Press Enter in the filter to open the selected match in the reader.",
+		when: (ctx) => ctx.filterQuery.length === 0,
+	},
+	{
+		id: "filter.clear",
+		bindingId: "filter.clearOrOpen",
+		render: ({ key }) => `Press ${key ?? "ctrl+\\"} to clear the current filter and start over.`,
+		when: (ctx) => ctx.filterQuery.length > 0,
+	},
+	{
+		id: "filtered-navigation",
+		render: () => "Use [ and ] to move through files while the current filter stays applied.",
+		when: (ctx) => ctx.filterQuery.length > 0,
+	},
+	{
+		id: "focus.toggle",
+		bindingId: "focus.toggle",
+		render: ({ key }) => `Press ${key ?? "tab"} to switch between the sidebar and reader.`,
+	},
+	{
+		id: "sidebar.toggle",
+		bindingId: "sidebar.toggle",
+		render: ({ key }) =>
+			`Press ${key ?? "s"} to hide or show the sidebar without losing your place.`,
+	},
+	{
+		id: "help.open",
+		bindingId: "help.toggle",
+		render: ({ key }) => `Press ${key ?? "?"} to open the full keyboard help at any time.`,
+	},
+]
+
+const firstKeyByBindingId = <C>(bindings: readonly KeyBinding<C>[]): ReadonlyMap<string, string> =>
+	new Map(
+		bindings.flatMap((binding) => {
+			const firstKey = binding.keys[0]
+			return firstKey ? [[binding.id, displayKey(firstKey)] as const] : []
+		}),
+	)
+
+export const buildReaderEmptyStateTips = (
+	bindings: readonly KeyBinding<BrowserCtx>[],
+	ctx: BrowserCtx,
+): readonly TipLine[] => {
+	const keyByBindingId = firstKeyByBindingId(bindings)
+
+	return tipDefinitions
+		.filter((tip) => !tip.when || tip.when(ctx))
+		.map((tip) => ({
+			id: tip.id,
+			text: `Tip: ${tip.render({ key: tip.bindingId ? (keyByBindingId.get(tip.bindingId) ?? null) : null })}`,
+		}))
+}
+
+export const pickTipByRotation = (
+	tips: readonly TipLine[],
+	rotationIndex: number,
+): TipLine | null => {
+	if (tips.length === 0) return null
+	return tips[((rotationIndex % tips.length) + tips.length) % tips.length] ?? null
+}