@carlesandres/house 0.4.13 → 0.4.14

package/CHANGELOG.md

@@ -6,6 +6,12 @@ The publish workflow (`.github/workflows/publish.yml`) runs on the `release: pub
 
 ## [Unreleased]
 
+## [0.4.14] — 2026-06-15
+
+### Added
+
+- Browser header now shows the active discovery root, and empty states reuse the same canonical root label for consistent launch context.
+
 ## [0.4.13] — 2026-06-15
 
 ### Added
@@ -333,7 +339,8 @@ 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.13...HEAD
+[Unreleased]: https://github.com/carlesandres/house/compare/v0.4.14...HEAD
+[0.4.14]: https://github.com/carlesandres/house/compare/v0.4.13...v0.4.14
 [0.4.13]: https://github.com/carlesandres/house/compare/v0.4.12...v0.4.13
 [0.4.12]: https://github.com/carlesandres/house/compare/v0.4.11...v0.4.12
 [0.4.11]: https://github.com/carlesandres/house/compare/v0.4.10...v0.4.11

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@carlesandres/house",
-	"version": "0.4.13",
+	"version": "0.4.14",
 	"description": "TUI-first markdown reader on opentui",
 	"type": "module",
 	"license": "MIT",

package/src/Browser.tsx

@@ -55,8 +55,8 @@ export interface BrowserProps {
 	readonly wrapWidth?: number
 	/** Initial reader wrap mode. Runtime toggles are session-only. */
 	readonly initialWrap?: boolean
-	/** Discovery root label used in the post-discovery empty-vault sidebar row. */
-	readonly emptyRootLabel?: string
+	/** Canonical discovery root label used anywhere the UI names the scan scope. */
+	readonly rootLabel?: string
 	/** Persistent footer indicator (e.g. "indexing… 42"). Pass null/undefined
 	 *  when discovery has finished; the indicator clears. */
 	readonly discoveryStatus?: string | null
@@ -187,7 +187,7 @@ export const Browser = ({
 	initialQuery = "",
 	wrapWidth = 80,
 	initialWrap = false,
-	emptyRootLabel = "current root",
+	rootLabel = "current root",
 	discoveryStatus = null,
 	discoverySpinnerIntervalMs,
 	discoverySpinnerInitialFrameIndex,
@@ -990,7 +990,7 @@ export const Browser = ({
 								: "No markdown files in"
 							: "No files match"
 					}
-					value={files.length === 0 ? (discoveryActive ? "…" : emptyRootLabel) : filterApplied}
+					value={files.length === 0 ? (discoveryActive ? "…" : rootLabel) : filterApplied}
 				/>
 			) : (
 				visibleFiles.map((file, idx) => {
@@ -1044,7 +1044,7 @@ export const Browser = ({
 		<box
 			style={{ width, height, flexDirection: "column", backgroundColor: colors.backgroundPanel }}
 		>
-			<Header width={width} currentFile={currentFile} />
+			<Header width={width} currentFile={currentFile} rootLabel={rootLabel} />
 			<box
 				style={{
 					flexDirection: "row",

package/src/Header.tsx

@@ -5,20 +5,113 @@
  * current filename on the left, version on the right. The row is
  * informational, not interactive — see issue #38 for the design discussion.
  *
- * Width degrades gracefully: the version drops first when the row gets
- * tight, then the filename, leaving the brand mark as the irreducible
- * identity element. Always rendered — the row is worth one cell on any
- * viewport so the user never loses the filename indicator (notably, when
- * the sidebar drawer overlays the reader on narrow viewports).
+ * Width degrades gracefully: the discovery root truncates/drops first, then
+ * the wordmark, then the version, then the filename truncates, leaving the
+ * brand mark as the irreducible identity element. Always rendered — the row is
+ * worth one cell on any viewport so the user never loses the filename/root
+ * indicator (notably, when the sidebar drawer overlays the reader on narrow
+ * viewports).
  */
 
 import pkg from "../package.json" with { type: "json" }
 import { BRAND, BRAND_NAME } from "./brand.ts"
 import { colors } from "./theme/colors.ts"
+import { middleTruncate } from "./ui/middleTruncate.ts"
 
 export const HEADER_HEIGHT = 1
 
 const FILE_SEPARATOR = " · "
+const HEADER_HORIZONTAL_PADDING = 2
+const HEADER_GROUP_GAP = 1
+const MIN_TRUNCATED_ROOT_WIDTH = 5
+
+export interface HeaderSegment {
+	readonly id: "brand" | "file" | "root"
+	readonly text: string
+	readonly tone: "brand" | "primary" | "muted"
+}
+
+export interface HeaderLayout {
+	readonly left: readonly HeaderSegment[]
+	readonly right: string | null
+}
+
+export interface HeaderLayoutInput {
+	readonly width: number
+	readonly currentFile?: string | null | undefined
+	readonly rootLabel?: string | null | undefined
+	readonly version: string
+}
+
+export const layoutHeaderSegments = ({
+	width,
+	currentFile,
+	rootLabel,
+	version,
+}: HeaderLayoutInput): HeaderLayout => {
+	const usableWidth = Math.max(0, width - HEADER_HORIZONTAL_PADDING)
+	const file = currentFile && currentFile.length > 0 ? currentFile : null
+	const root = rootLabel && rootLabel.length > 0 ? rootLabel : null
+	const right = `v${version}`
+	const brand: HeaderSegment = { id: "brand", text: `${BRAND} ${BRAND_NAME}`, tone: "brand" }
+	const iconBrand: HeaderSegment = { id: "brand", text: BRAND, tone: "brand" }
+	const fileSegment: HeaderSegment | null =
+		file === null ? null : { id: "file", text: file, tone: "primary" }
+	const rootSegment: HeaderSegment | null =
+		root === null ? null : { id: "root", text: root, tone: "muted" }
+	const segments = [brand, ...(fileSegment === null ? [] : [fileSegment])]
+
+	if (rootSegment !== null && fits([...segments, rootSegment], right, usableWidth)) {
+		return { left: [...segments, rootSegment], right }
+	}
+
+	const rootWidth =
+		rootSegment === null
+			? 0
+			: usableWidth -
+				joinedLength(segments) -
+				FILE_SEPARATOR.length -
+				HEADER_GROUP_GAP -
+				right.length
+	if (root !== null && root.length > rootWidth && rootWidth >= MIN_TRUNCATED_ROOT_WIDTH) {
+		return {
+			left: [...segments, { id: "root", text: middleTruncate(root, rootWidth), tone: "muted" }],
+			right,
+		}
+	}
+
+	if (fits(segments, right, usableWidth)) return { left: segments, right }
+
+	const iconSegments = [iconBrand, ...(fileSegment === null ? [] : [fileSegment])]
+	if (fits(iconSegments, right, usableWidth)) return { left: iconSegments, right }
+	if (fits(iconSegments, null, usableWidth)) return { left: iconSegments, right: null }
+	if (file !== null) {
+		const fileWidth = usableWidth - BRAND.length - FILE_SEPARATOR.length
+		if (fileWidth > 0) {
+			return {
+				left: [iconBrand, { id: "file", text: middleTruncate(file, fileWidth), tone: "primary" }],
+				right: null,
+			}
+		}
+	}
+
+	return { left: [iconBrand], right: null }
+}
+
+const joinedLength = (segments: readonly HeaderSegment[]): number =>
+	segments.reduce(
+		(total, segment, idx) => total + segment.text.length + (idx === 0 ? 0 : FILE_SEPARATOR.length),
+		0,
+	)
+
+const fits = (
+	segments: readonly HeaderSegment[],
+	right: string | null,
+	usableWidth: number,
+): boolean => {
+	const rightWidth = right === null ? 0 : HEADER_GROUP_GAP + right.length
+	return joinedLength(segments) + rightWidth <= usableWidth
+}
 
 export interface HeaderProps {
 	readonly width: number
@@ -26,27 +119,15 @@ export interface HeaderProps {
 	 *  it next to the brand mark — replaces the per-pane border title that
 	 *  used to carry this information. */
 	readonly currentFile?: string | null
+	/** Canonical discovery root / scan-scope label. */
+	readonly rootLabel?: string | null
 	/** Optional override for the version string (testing). Defaults to
 	 *  the running package's version. */
 	readonly version?: string
 }
 
-export const Header = ({ width, currentFile, version = pkg.version }: HeaderProps) => {
-	const brand = `${BRAND} ${BRAND_NAME}`
-	const right = `v${version}`
-	const file = currentFile && currentFile.length > 0 ? currentFile : null
-	const usableWidth = Math.max(0, width - 2) // 1-cell horizontal padding each side
-
-	// Priority: brand > filename > version. Brand is the irreducible identity
-	// anchor. Filename is per-selection useful info — keep it before the
-	// largely-static version string. `1` is the minimum gap between left and
-	// right groups so they never visually collide.
-	const leftWithFile = file !== null ? `${brand}${FILE_SEPARATOR}${file}` : brand
-	const showFileWithVersion = leftWithFile.length + 1 + right.length <= usableWidth
-	const showFileWithoutVersion = leftWithFile.length <= usableWidth
-	const showFile = file !== null && (showFileWithVersion || showFileWithoutVersion)
-	const left = showFile ? leftWithFile : brand
-	const showRight = left.length + 1 + right.length <= usableWidth
+export const Header = ({ width, currentFile, rootLabel, version = pkg.version }: HeaderProps) => {
+	const layout = layoutHeaderSegments({ width, currentFile, rootLabel, version })
 
 	return (
 		<box
@@ -62,10 +143,18 @@ export const Header = ({ width, currentFile, version = pkg.version }: HeaderProp
 			}}
 		>
 			<text wrapMode="none">
-				<span style={{ fg: colors.text }}>{brand}</span>
-				{showFile && <span style={{ fg: colors.textMuted }}>{`${FILE_SEPARATOR}${file}`}</span>}
+				{layout.left.map((segment, idx) => (
+					<span
+						key={`${segment.id}-${idx}`}
+						style={{ fg: segment.tone === "muted" ? colors.textMuted : colors.text }}
+					>
+						{`${idx === 0 ? "" : FILE_SEPARATOR}${segment.text}`}
+					</span>
+				))}
 			</text>
-			{showRight && <text content={right} wrapMode="none" style={{ fg: colors.text }} />}
+			{layout.right !== null && (
+				<text content={layout.right} wrapMode="none" style={{ fg: colors.text }} />
+			)}
 		</box>
 	)
 }

package/src/discovery/rootLabel.ts

@@ -0,0 +1,18 @@
+import { isAbsolute, relative } from "node:path"
+
+export interface DiscoveryRootLabelInput {
+	readonly discoveryRoot: string
+	readonly home: string
+}
+
+export const formatDiscoveryRootLabel = ({
+	discoveryRoot,
+	home,
+}: DiscoveryRootLabelInput): string => {
+	if (discoveryRoot === home) return "~"
+	const homeRelative = relative(home, discoveryRoot)
+	if (homeRelative.length > 0 && !homeRelative.startsWith("..") && !isAbsolute(homeRelative)) {
+		return `~/${homeRelative}`
+	}
+	return discoveryRoot
+}

package/src/index.tsx

@@ -2,6 +2,7 @@
 /** house — entry point. Boots the browser TUI or `--serve` preview. */
 
 import { stat } from "node:fs/promises"
+import { homedir } from "node:os"
 import { dirname, isAbsolute, relative, resolve } from "node:path"
 import { createCliRenderer } from "@opentui/core"
 import { createRoot } from "@opentui/react"
@@ -13,6 +14,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 { formatDiscoveryRootLabel } from "./discovery/rootLabel.ts"
 import { walk, type FileEntry } from "./discovery/walk.ts"
 import { openInBrowser } from "./serve/openBrowser.ts"
 import { startServer } from "./serve/server.ts"
@@ -64,7 +66,7 @@ export const resolveDiscoveryRoot = async ({
 	readonly defaultRoot: "cwd" | "git"
 	readonly cwd: string
 }): Promise<string> => {
-	if (cliRoot !== null) return cliRoot
+	if (cliRoot !== null) return resolve(cwd, cliRoot)
 	if (defaultRoot === "git") return findGitRoot(cwd)
 	return cwd
 }
@@ -104,6 +106,7 @@ interface DiscoverShellProps {
 	 *  and the full vocabulary; the underlying categories remain
 	 *  independent everywhere else. */
 	readonly initialShow: readonly ShowCategory[]
+	readonly rootLabel?: string
 	readonly extensions: readonly string[]
 	readonly wrapWidth: number
 	readonly initialWrap: boolean
@@ -114,6 +117,7 @@ export const DiscoverShell = ({
 	target,
 	initialQuery,
 	initialShow,
+	rootLabel = target,
 	extensions,
 	wrapWidth,
 	initialWrap,
@@ -194,7 +198,7 @@ export const DiscoverShell = ({
 			initialQuery={initialQuery}
 			wrapWidth={wrapWidth}
 			initialWrap={initialWrap}
-			emptyRootLabel={target}
+			rootLabel={rootLabel}
 			discoveryStatus={discoveryStatus}
 			startupFocus={startupFocus}
 			updateNotice={updateNotice}
@@ -454,6 +458,7 @@ async function runTui({
 				target={discoveryRoot}
 				initialQuery={initialQuery}
 				initialShow={show}
+				rootLabel={formatDiscoveryRootLabel({ discoveryRoot, home: homedir() })}
 				extensions={extensions}
 				wrapWidth={wrapWidth}
 				initialWrap={initialWrap}