@carlesandres/house 0.4.7 → 0.4.8

package/src/discovery/walk.ts

@@ -13,6 +13,11 @@ export interface FileEntry {
 	readonly name: string
 }
 
+export interface DiscoveryWarning {
+	readonly path: string
+	readonly cause: unknown
+}
+
 export type SortOrder = "dirs-first" | "files-first"
 
 export interface WalkOptions {
@@ -25,6 +30,8 @@ export interface WalkOptions {
 	readonly sort?: SortOrder
 	/** Include `.mdx` files alongside `.md`/`.markdown`. Default `true`. */
 	readonly mdx?: boolean
+	/** Non-fatal subtree read errors. Root-level failures still error the walk. */
+	readonly onWarning?: ((warning: DiscoveryWarning) => void) | null
 }
 
 export class DiscoveryError extends Data.TaggedError("DiscoveryError")<{
@@ -93,9 +100,11 @@ async function* walkDirGen(
 	rootPath: string,
 	parentLevels: readonly IgnoreLevel[],
 	opts: { showHidden: boolean; showGitignored: boolean; sort: SortOrder; mdx: boolean },
+	onWarning: ((warning: DiscoveryWarning) => void) | null,
 	signal: AbortSignal,
 ): AsyncGenerator<FileEntry, void, void> {
 	if (signal.aborted) return
+	const isRoot = dirPath === rootPath
 
 	let levels = parentLevels
 	if (!opts.showGitignored) {
@@ -104,7 +113,14 @@ async function* walkDirGen(
 		if (ig) levels = [...parentLevels, { dir: dirPath, ig }]
 	}
 
-	const raw = await readdir(dirPath, { withFileTypes: true })
+	let raw
+	try {
+		raw = await readdir(dirPath, { withFileTypes: true })
+	} catch (error) {
+		if (isRoot) throw error
+		onWarning?.({ path: dirPath, cause: error })
+		return
+	}
 	if (signal.aborted) return
 
 	for (const entry of sortEntries(raw, opts.sort)) {
@@ -120,7 +136,7 @@ async function* walkDirGen(
 			if (HARD_SKIP_DIRS.has(entry.name)) continue
 			if (!opts.showHidden && entry.name.startsWith(".")) continue
 			if (!opts.showGitignored && isIgnored(entryPath, true, levels)) continue
-			yield* walkDirGen(entryPath, rootPath, levels, opts, signal)
+			yield* walkDirGen(entryPath, rootPath, levels, opts, onWarning, signal)
 			continue
 		}
 
@@ -165,10 +181,11 @@ export const walk = (
 		sort: options.sort ?? ("dirs-first" as SortOrder),
 		mdx: options.mdx ?? true,
 	}
+	const onWarning = options.onWarning ?? null
 	const controller = new AbortController()
 	const iterable: AsyncIterable<FileEntry> = {
 		[Symbol.asyncIterator]() {
-			const gen = walkDirGen(absRoot, absRoot, [], opts, controller.signal)
+			const gen = walkDirGen(absRoot, absRoot, [], opts, onWarning, controller.signal)
 			return {
 				next: () => gen.next(),
 				return: async (value?: void) => {

package/src/index.tsx

@@ -1,51 +1,30 @@
 #!/usr/bin/env bun
-/**
- * house — entry point.
- *
- * Reads a markdown file path from argv and renders it via opentui's built-in
- * <markdown> component inside a scrollbox. q / ctrl+c to quit.
- *
- * Discovery, sidebar, theming, and richer Effect wiring all land after this.
- */
+/** house — entry point. Boots the browser TUI or `--serve` preview. */
 
 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"
-import { RegistryProvider, useAtomSet, useAtomValue } from "@effect/atom-react"
+import { dirname, isAbsolute, relative, resolve } from "node:path"
+import { createCliRenderer } from "@opentui/core"
+import { createRoot } from "@opentui/react"
+import { RegistryProvider } from "@effect/atom-react"
 import { Cause, Duration, Effect, Fiber, Stream } from "effect"
-import { useEffect, useMemo, useRef, useState } from "react"
+import { useEffect, useRef, useState } from "react"
 import pkg from "../package.json" with { type: "json" }
 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 { Header } from "./Header.tsx"
-import { readFileText } from "./io/readFile.ts"
 import { openInBrowser } from "./serve/openBrowser.ts"
 import { startServer } from "./serve/server.ts"
-import { colors, setActiveTheme } from "./theme/colors.ts"
+import { setActiveTheme } from "./theme/colors.ts"
 import { themeAtom, type ThemeState } from "./theme/atom.ts"
-import { getThemeDefinition, themeDefinitions } from "./theme/registry.ts"
+import { getThemeDefinition } from "./theme/registry.ts"
 import { formatQuitNotice } from "./update/notice.ts"
 import { currentUpdateInfo, startUpdateProbe } from "./update/runtime.ts"
 import { useUpdateNotice } from "./update/useUpdateNotice.ts"
 
-export interface AppProps {
-	/** Markdown source to render. */
-	readonly content: string
-	/** Optional title shown in the header's current-file slot. Defaults to a generic label. */
-	readonly title?: string
-	/** Cap the rendered markdown's width at N columns (left-aligned). Null = fill the pane. */
-	readonly maxWidth?: number | null
-	/** Override quit behavior. Tests pass a spy; the binary uses the default. */
-	readonly onQuit?: () => void
-}
-
 /**
- * DiscoverShell — owns the streaming walk for directory mode. Mounts Browser
+ * DiscoverShell — owns the streaming walk for the Browser. Mounts Browser
  * immediately with `files=[]` and pushes entries as the stream emits.
  *
  * Batching: `Stream.groupedWithin(64, 60ms)` coalesces bursts so we don't
@@ -92,8 +71,36 @@ export const resolveDiscoveryRoot = async ({
 	return cwd
 }
 
+export const validateDiscoveryRoot = async (root: string): Promise<void> => {
+	let stats: Awaited<ReturnType<typeof stat>>
+	try {
+		stats = await stat(root)
+	} catch (err) {
+		throw new Error(`cannot access discovery root ${root}: ${String(err)}`)
+	}
+	if (!stats.isDirectory()) {
+		throw new Error(`discovery root must be a directory, got file ${root}`)
+	}
+}
+
+export const formatPartialDiscoveryStatus = ({
+	skippedCount,
+	lastSkippedPath,
+}: {
+	readonly skippedCount: number
+	readonly lastSkippedPath: string | null
+}): string | null => {
+	if (skippedCount <= 0) return null
+	const noun = skippedCount === 1 ? "directory" : "directories"
+	const suffix = lastSkippedPath && skippedCount === 1 ? `: ${lastSkippedPath}` : ""
+	return `scan incomplete: skipped ${skippedCount} ${noun}${suffix}`
+}
+
+export const formatFatalDiscoveryStatus = (): string => "scan failed: unable to read discovery root"
+
 interface DiscoverShellProps {
 	readonly target: string
+	readonly initialQuery: string
 	/** Resolved discovery vocabulary from the config layer. The shift+a
 	 *  toggle (#145) is session-only sugar that flips between this set
 	 *  and the full vocabulary; the underlying categories remain
@@ -106,8 +113,9 @@ interface DiscoverShellProps {
 	readonly startupFocus: StartupFocus
 }
 
-const DiscoverShell = ({
+export const DiscoverShell = ({
 	target,
+	initialQuery,
 	initialShow,
 	sort,
 	mdx,
@@ -120,6 +128,8 @@ const DiscoverShell = ({
 	const [files, setFiles] = useState<readonly FileEntry[]>([])
 	const [scanning, setScanning] = useState<boolean>(true)
 	const [scanError, setScanError] = useState<string | null>(null)
+	const [skippedDirCount, setSkippedDirCount] = useState<number>(0)
+	const [lastSkippedDir, setLastSkippedDir] = useState<string | null>(null)
 	// Files arrive in a ref-tracked count so the status string can show
 	// "indexing… N" even when React hasn't yet flushed the latest setFiles.
 	const countRef = useRef(0)
@@ -132,8 +142,23 @@ const DiscoverShell = ({
 		setFiles([])
 		setScanning(true)
 		setScanError(null)
+		setSkippedDirCount(0)
+		setLastSkippedDir(null)
 		countRef.current = 0
-		const program = walk(target, { show, sort, mdx }).pipe(
+		const warnedProgram = walk(target, {
+			show,
+			sort,
+			mdx,
+			onWarning: ({ path }) => {
+				const relativePath = relative(resolve(target), path)
+				setSkippedDirCount((prev) => prev + 1)
+				setLastSkippedDir(
+					relativePath.length > 0 && !relativePath.startsWith("..") && !isAbsolute(relativePath)
+						? relativePath
+						: path,
+				)
+			},
+		}).pipe(
 			Stream.groupedWithin(64, Duration.millis(60)),
 			Stream.runForEach((chunk) =>
 				Effect.sync(() => {
@@ -147,25 +172,33 @@ const DiscoverShell = ({
 				onSuccess: () => Effect.sync(() => setScanning(false)),
 				onFailure: (cause) =>
 					Effect.sync(() => {
-						// Interruption is the normal teardown path — don't surface it.
 						if (Cause.hasInterrupts(cause)) return
-						setScanError(`scan failed: ${Cause.pretty(cause)}`)
+						setScanError(formatFatalDiscoveryStatus())
 						setScanning(false)
 					}),
 			}),
 		)
-		const fiber = Effect.runFork(program)
+		const fiber = Effect.runFork(warnedProgram)
 		return () => {
 			Effect.runFork(Fiber.interrupt(fiber))
 		}
 	}, [target, show, sort, mdx])
 
-	const discoveryStatus = scanError ?? (scanning ? `indexing… ${countRef.current}` : null)
+	const discoveryStatus =
+		scanError ??
+		(scanning
+			? `indexing… ${countRef.current}`
+			: formatPartialDiscoveryStatus({
+					skippedCount: skippedDirCount,
+					lastSkippedPath: lastSkippedDir,
+				}))
 
 	return (
 		<Browser
 			files={files}
+			initialQuery={initialQuery}
 			maxWidth={maxWidth}
+			emptyRootLabel={target}
 			discoveryStatus={discoveryStatus}
 			sidebarMode={sidebarMode}
 			startupFocus={startupFocus}
@@ -183,79 +216,22 @@ const DiscoverShell = ({
 	)
 }
 
-export const App = ({ content, title = "house", maxWidth = null, onQuit }: AppProps) => {
-	const renderer = useRenderer()
-	const { width, height } = useTerminalDimensions()
-	const theme = useAtomValue(themeAtom)
-	const setTheme = useAtomSet(themeAtom)
-	const syntaxStyle = useMemo(() => SyntaxStyle.fromStyles(colors.syntax), [theme])
-
-	const cycleTheme = (delta: 1 | -1) => {
-		const idx = themeDefinitions.findIndex((d) => d.id === theme.id)
-		const next = themeDefinitions[(idx + delta + themeDefinitions.length) % themeDefinitions.length]
-		if (!next) return
-		setActiveTheme(next, theme.tone)
-		setTheme({ id: next.id, tone: theme.tone })
-	}
-
-	const toggleTone = () => {
-		const nextTone = theme.tone === "dark" ? "light" : "dark"
-		const def = getThemeDefinition(theme.id)
-		if (def) setActiveTheme(def, nextTone)
-		setTheme({ id: theme.id, tone: nextTone })
-	}
-
-	useKeyboard((key) => {
-		if (key.name === "q" || (key.ctrl && key.name === "c")) {
-			if (onQuit) {
-				onQuit()
-				return
-			}
-			renderer?.destroy()
-			process.exit(0)
-		}
-		if (key.name === "t" && !key.shift) cycleTheme(1)
-		if (key.name === "t" && key.shift) cycleTheme(-1)
-		if (key.name === "l" && key.shift) toggleTone()
-	})
-
-	const paneBorderSides: BorderSides[] = ["top", "bottom"]
-
-	return (
-		<box style={{ width, height, flexDirection: "column", backgroundColor: colors.background }}>
-			<Header width={width} currentFile={title} />
-			<box
-				style={{
-					border: paneBorderSides,
-					borderColor: colors.border,
-					padding: 1,
-					flexGrow: 1,
-					flexShrink: 1,
-					backgroundColor: colors.background,
-				}}
-			>
-				<scrollbox
-					style={{
-						scrollY: true,
-						scrollX: false,
-						flexGrow: 1,
-						flexShrink: 1,
-						backgroundColor: colors.background,
-					}}
-					focused
-				>
-					<markdown
-						content={content}
-						syntaxStyle={syntaxStyle}
-						fg={colors.text}
-						bg={colors.background}
-						conceal
-						style={{ width: maxWidth ?? "100%" }}
-					/>
-				</scrollbox>
-			</box>
-		</box>
-	)
+export const resolveInitialQuery = ({
+	pathArg,
+	discoveryRoot,
+	cwd,
+}: {
+	readonly pathArg: string | null
+	readonly discoveryRoot: string
+	readonly cwd: string
+}): string => {
+	if (pathArg === null) return ""
+	const resolvedPath = resolve(cwd, pathArg)
+	const rel = relative(discoveryRoot, resolvedPath)
+	if (rel.length === 0) return ""
+	if (!rel.startsWith("..") && !isAbsolute(rel)) return rel
+	if (pathArg.startsWith("./")) return pathArg.slice(2)
+	return pathArg
 }
 
 let updateExitHookRegistered = false
@@ -331,10 +307,15 @@ if (import.meta.main) {
 	}
 
 	const cwd = process.cwd()
-	const target = args.path ?? "."
 	const discoveryRoot = await resolveDiscoveryRoot({ cliRoot: args.root, defaultRoot, cwd })
+	const initialQuery = resolveInitialQuery({ pathArg: args.path, discoveryRoot, cwd })
 
 	if (args.serve) {
+		const target = args.path
+		if (target === null) {
+			console.error("house: --serve requires a file path")
+			process.exit(2)
+		}
 		let stats: Awaited<ReturnType<typeof stat>>
 		try {
 			stats = await stat(target)
@@ -392,8 +373,8 @@ if (import.meta.main) {
 			}
 		}
 		await runTui({
-			target,
 			discoveryRoot,
+			initialQuery,
 			themeId,
 			tone,
 			maxWidth,
@@ -408,8 +389,8 @@ if (import.meta.main) {
 }
 
 interface TuiBootOptions {
-	readonly target: string
 	readonly discoveryRoot: string
+	readonly initialQuery: string
 	readonly themeId: string
 	readonly tone: "dark" | "light"
 	readonly maxWidth: number | null
@@ -424,8 +405,8 @@ interface TuiBootOptions {
 }
 
 async function runTui({
-	target,
 	discoveryRoot,
+	initialQuery,
 	themeId,
 	tone,
 	maxWidth,
@@ -436,14 +417,6 @@ async function runTui({
 	startupFocus,
 	updateCheck,
 }: TuiBootOptions): Promise<void> {
-	let stats: Awaited<ReturnType<typeof stat>>
-	try {
-		stats = await stat(target)
-	} catch (err) {
-		console.error(`house: cannot access ${target}: ${String(err)}`)
-		process.exit(1)
-	}
-
 	if (updateCheck) {
 		// Fire the npm-registry probe in the background. Result lands in a
 		// module singleton; the React tree picks it up via `useUpdateNotice`
@@ -462,40 +435,32 @@ async function runTui({
 		}
 	}
 
-	const renderer = await createCliRenderer({ exitOnCtrlC: false })
+	const renderer = await createCliRenderer({
+		exitOnCtrlC: false,
+		useMouse: true,
+		enableMouseMovement: true,
+		screenMode: "alternate-screen",
+	})
+	renderer.useMouse = true
 	const initialTheme: ThemeState = { id: themeId, tone }
-
-	if (stats.isDirectory()) {
-		createRoot(renderer).render(
-			<RegistryProvider initialValues={[[themeAtom, initialTheme]]}>
-				<DiscoverShell
-					target={discoveryRoot}
-					initialShow={show}
-					sort={sort}
-					mdx={mdx}
-					maxWidth={maxWidth}
-					sidebarMode={sidebarMode}
-					startupFocus={startupFocus}
-				/>
-			</RegistryProvider>,
-		)
-	} else {
-		const content = await Effect.runPromise(
-			readFileText(target).pipe(
-				Effect.tapError((err) =>
-					Effect.sync(() => {
-						console.error(`house: cannot read ${err.path}: ${String(err.cause)}`)
-					}),
-				),
-			),
-		).catch(() => {
-			process.exit(1)
-		})
-		if (typeof content !== "string") process.exit(1)
-		createRoot(renderer).render(
-			<RegistryProvider initialValues={[[themeAtom, initialTheme]]}>
-				<App content={content} title={target} maxWidth={maxWidth} />
-			</RegistryProvider>,
-		)
+	try {
+		await validateDiscoveryRoot(discoveryRoot)
+	} catch (err) {
+		console.error(`house: ${err instanceof Error ? err.message : String(err)}`)
+		process.exit(1)
 	}
+	createRoot(renderer).render(
+		<RegistryProvider initialValues={[[themeAtom, initialTheme]]}>
+			<DiscoverShell
+				target={discoveryRoot}
+				initialQuery={initialQuery}
+				initialShow={show}
+				sort={sort}
+				mdx={mdx}
+				maxWidth={maxWidth}
+				sidebarMode={sidebarMode}
+				startupFocus={startupFocus}
+			/>
+		</RegistryProvider>,
+	)
 }

package/src/keymap/browser.ts

@@ -1,6 +1,5 @@
 /**
- * Browser keymap — the data backing `Browser.tsx`'s `useKeyboard` handler
- * and (next iteration) the `?` help overlay.
+ * Browser keymap — the data backing `Browser.tsx`'s `useKeyboard` handler.
  */
 
 import type { FileEntry } from "../discovery/walk.ts"
@@ -18,7 +17,6 @@ export interface BrowserCtx {
 	readonly focus: BrowserFocus
 	/** User's sticky sidebar preference. Visibility is `shown || focus==="sidebar"`. */
 	readonly sidebarShown: boolean
-	readonly helpVisible: boolean
 	readonly filterOpen: boolean
 	readonly restoreFilterOnSidebarFocus: boolean
 	/** Current applied/edited filter query. Used by `filter.clearOrOpen`'s
@@ -29,7 +27,6 @@ export interface BrowserCtx {
 	readonly setSelectedIndex: (updater: (prev: number) => number) => void
 	/** Toggle `shown` and adjust focus per DESIGN.md §7.1 (see s-behavior table). */
 	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
@@ -65,6 +62,7 @@ const stepBy = (c: BrowserCtx, delta: number) =>
 const inSidebar = (c: BrowserCtx) => c.focus === "sidebar"
 const filterClosed = (c: BrowserCtx) => !c.filterOpen
 const paletteClosed = (c: BrowserCtx) => !c.paletteOpen
+const inputClosed = (c: BrowserCtx) => filterClosed(c) && paletteClosed(c)
 const inReader = (c: BrowserCtx) => c.focus === "reader"
 const inSidebarWithFiles = (c: BrowserCtx) => inSidebar(c) && haveFiles(c)
 /** Reader-only sibling-step gate: needs a current selection plus a sibling
@@ -80,6 +78,7 @@ export const browserBindings: readonly KeyBinding<BrowserCtx>[] = [
 		description: "Quit",
 		hint: "quit",
 		keys: ["q", "ctrl+c"],
+		hintWhen: inputClosed,
 		run: (c) => c.quit(),
 	},
 	{
@@ -102,16 +101,9 @@ export const browserBindings: readonly KeyBinding<BrowserCtx>[] = [
 		description: "Toggle sidebar visibility",
 		hint: "sidebar",
 		keys: ["s"],
+		hintWhen: inputClosed,
 		run: (c) => c.toggleShown(),
 	},
-	{
-		id: "help.toggle",
-		group: "Global",
-		description: "Show / dismiss help",
-		hint: "help",
-		keys: ["?"],
-		run: (c) => c.setHelpVisible((v) => !v),
-	},
 	{
 		id: "filter.open",
 		group: "Sidebar",
@@ -133,17 +125,16 @@ export const browserBindings: readonly KeyBinding<BrowserCtx>[] = [
 		// 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
+		// clear input, keep modal open. Palette 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
+		// behavior; the `hintWhen` gate keeps the footer hint 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,
+		hintWhen: (c) => filterClosed(c) && !c.paletteOpen && c.filterQuery.length > 0,
 		run: (c) => c.clearAndOpenFilter(),
 	},
 	{
@@ -152,10 +143,9 @@ export const browserBindings: readonly KeyBinding<BrowserCtx>[] = [
 		description: "Command palette",
 		hint: "palette",
 		keys: ["ctrl+p"],
-		// Filter swallows ctrl+p as a typed character in its own branch, so this
-		// `when` only matters when the palette is already open (which it
-		// shouldn't re-open). #70 Q2 — fires from everywhere except the filter,
-		// closes help on its way in (handled in Browser.tsx).
+		// The filter modal handles this chord directly so the palette can open
+		// while filter input owns the rest of the keyboard. This gate keeps the
+		// normal dispatcher from reopening an already-open palette.
 		when: paletteClosed,
 		run: (c) => c.openPalette(),
 	},
@@ -178,6 +168,7 @@ export const browserBindings: readonly KeyBinding<BrowserCtx>[] = [
 		description: "Next theme",
 		hint: "theme",
 		keys: ["t"],
+		hintWhen: inputClosed,
 		run: (c) => c.cycleTheme(1),
 	},
 	{
@@ -267,6 +258,7 @@ export const browserBindings: readonly KeyBinding<BrowserCtx>[] = [
 		hint: "open",
 		keys: ["return", "right", "l"],
 		when: inSidebar,
+		hintWhen: (c) => inSidebar(c) && hasSelected(c),
 		run: (c) => c.setFocus("reader"),
 	},
 
@@ -280,6 +272,7 @@ export const browserBindings: readonly KeyBinding<BrowserCtx>[] = [
 		hint: "html",
 		keys: ["shift+o"],
 		when: hasSelected,
+		hintWhen: (c) => inputClosed(c) && hasSelected(c),
 		run: (c) => c.serveCurrent(),
 	},
 	{
@@ -289,6 +282,7 @@ export const browserBindings: readonly KeyBinding<BrowserCtx>[] = [
 		hint: "edit",
 		keys: ["shift+e"],
 		when: hasSelected,
+		hintWhen: (c) => inputClosed(c) && hasSelected(c),
 		run: (c) => c.editCurrent(),
 	},
 	{

package/src/keymap/keymap.ts

@@ -3,8 +3,8 @@
  *
  * Bindings are values: `{ id, description, keys, when?, run }`. A pure
  * `dispatch` looks up the first matching, enabled binding for a key event
- * and runs it. The same array drives the help overlay, so there is one
- * source of truth.
+ * and runs it. The same array also drives footer hints and command-palette
+ * derivation, so there is one source of truth.
  *
  * Deliberately *not* a port of ghui's `@ghui/keymap`: no chord sequences,
  * no count prefixes, no scope contramaps. See DESIGN.md §12 for the full
@@ -22,11 +22,11 @@ export interface KeyMatch {
 export interface KeyBinding<C> {
 	/** Stable id; used for tests and (later) command-palette routing. */
 	readonly id: string
-	/** Human-readable summary, shown in the help overlay. */
+	/** Human-readable summary used by docs and palette command titles. */
 	readonly description: string
 	/** Key chords that trigger this binding, e.g. ["j", "down"], ["shift+k"], ["ctrl+c"]. */
 	readonly keys: readonly string[]
-	/** Optional grouping label for the help overlay. Bindings without a group are excluded from help. */
+	/** Optional grouping label for derived UI/documentation surfaces. */
 	readonly group?: string
 	/** Optional compact label for the footer hint row, e.g. "help" for `?:help`.
 	 *  Bindings without a hint are excluded from the footer. Order in the bindings

package/src/layout/sidebarEmptyState.ts

@@ -0,0 +1,7 @@
+const HEAD_ELISION_PREFIX = "…"
+
+export const fitSidebarEmptyValue = (value: string, width: number): string => {
+	if (value.length <= width) return value
+	if (width <= 1) return value.slice(value.length - 1)
+	return HEAD_ELISION_PREFIX + value.slice(value.length - width + 1)
+}

package/src/markdown/frontmatter.ts

@@ -0,0 +1,62 @@
+export interface FrontmatterField {
+	readonly key: string
+	readonly value: string
+}
+
+export interface FrontmatterRenderModel {
+	readonly body: string
+	readonly fields: readonly FrontmatterField[]
+}
+
+const FRONTMATTER_OPEN = "---"
+const FRONTMATTER_CLOSE = "---"
+
+const normalizeValue = (raw: string): string => {
+	const value = raw.trim()
+	if (
+		(value.startsWith('"') && value.endsWith('"')) ||
+		(value.startsWith("'") && value.endsWith("'"))
+	) {
+		return value.slice(1, -1)
+	}
+	return value
+}
+
+const formatKey = (key: string): string => key.replace(/[-_]+/g, " ")
+
+const toDisplayField = (key: string, value: string): FrontmatterField => ({
+	key: formatKey(key),
+	value: normalizeValue(value),
+})
+
+export const parseFrontmatter = (content: string): FrontmatterRenderModel => {
+	if (
+		!content.startsWith(`${FRONTMATTER_OPEN}\n`) &&
+		!content.startsWith(`${FRONTMATTER_OPEN}\r\n`)
+	) {
+		return { body: content, fields: [] }
+	}
+
+	const lines = content.split(/\r?\n/)
+	if (lines[0] !== FRONTMATTER_OPEN) return { body: content, fields: [] }
+
+	const closeIndex = lines.indexOf(FRONTMATTER_CLOSE, 1)
+	if (closeIndex <= 0) return { body: content, fields: [] }
+
+	const fields: FrontmatterField[] = []
+	for (const line of lines.slice(1, closeIndex)) {
+		if (line.trim().length === 0) continue
+		const colon = line.indexOf(":")
+		if (colon <= 0) return { body: content, fields: [] }
+		const key = line.slice(0, colon).trim()
+		const value = line.slice(colon + 1)
+		if (key.length === 0) return { body: content, fields: [] }
+		fields.push(toDisplayField(key, value))
+	}
+
+	const body = lines
+		.slice(closeIndex + 1)
+		.join("\n")
+		.replace(/^\n+/, "")
+	return { body, fields }
+}