@carlesandres/house 0.3.1 → 0.4.0

package/src/config/load.ts

@@ -0,0 +1,166 @@
+/**
+ * Layered configuration loader.
+ *
+ * Precedence (high to low): CLI args → env vars → user TOML file → built-in defaults.
+ * Each source is wrapped as a `ConfigProvider` and composed via `orElse`,
+ * which falls through per-key when the upstream source returns `undefined`.
+ *
+ * The schema (`Config.schema` + `Schema.Literals`) validates `theme` against
+ * the registered theme ids and `tone` against `"dark" | "light"`. Validation
+ * failures and TOML parse errors both surface as `ConfigError` from `loadConfig`.
+ */
+
+import { homedir } from "node:os"
+import { join } from "node:path"
+import { Config, ConfigProvider, Effect, Schema } from "effect"
+import { themeDefinitions } from "../theme/registry.ts"
+
+export interface HouseConfig {
+	readonly theme: string
+	readonly tone: "dark" | "light"
+}
+
+export interface CliOverrides {
+	readonly theme: string | null
+	readonly tone: string | null
+}
+
+const DEFAULT_THEME = "opencode"
+const DEFAULT_TONE: "dark" | "light" = "dark"
+
+const themeIds = themeDefinitions.map((t) => t.id)
+
+/**
+ * Top-level keys the config file is allowed to set. Kept in sync by hand
+ * with `schema` below — when adding a key, add it both places.
+ * Used by `fileProvider` to reject typo'd keys (e.g. `them = "..."`) loudly
+ * rather than silently falling back to defaults.
+ */
+const KNOWN_FILE_KEYS: ReadonlySet<string> = new Set(["theme", "tone"])
+
+const schema = Config.all({
+	theme: Config.schema(Schema.Literals(themeIds), "theme"),
+	tone: Config.schema(Schema.Literals(["dark", "light"] as const), "tone"),
+})
+
+const defaultsProvider = (): ConfigProvider.ConfigProvider =>
+	ConfigProvider.fromUnknown({ theme: DEFAULT_THEME, tone: DEFAULT_TONE })
+
+/**
+ * Reads a TOML file at `path`. Missing file → `undefined` for every key
+ * (per-key fallthrough). Malformed TOML → `SourceError` (hard fail upstream).
+ */
+const fileProvider = (path: string): ConfigProvider.ConfigProvider => {
+	let cache: { data: Record<string, unknown> | null } | null = null
+	const load = Effect.gen(function* () {
+		if (cache !== null) return cache.data
+		const file = Bun.file(path)
+		const exists = yield* Effect.promise(() => file.exists())
+		if (!exists) {
+			cache = { data: null }
+			return null
+		}
+		const text = yield* Effect.promise(() => file.text())
+		const parsed = yield* Effect.try({
+			try: () => Bun.TOML.parse(text) as Record<string, unknown>,
+			catch: (cause) =>
+				new ConfigProvider.SourceError({
+					message: `invalid TOML in ${path}: ${cause instanceof Error ? cause.message : String(cause)}`,
+					cause,
+				}),
+		})
+		const unknown = Object.keys(parsed).filter((k) => !KNOWN_FILE_KEYS.has(k))
+		if (unknown.length > 0) {
+			const known = [...KNOWN_FILE_KEYS].join(", ")
+			return yield* Effect.fail(
+				new ConfigProvider.SourceError({
+					message: `unknown key${unknown.length > 1 ? "s" : ""} in ${path}: ${unknown.map((k) => `"${k}"`).join(", ")} (known: ${known})`,
+				}),
+			)
+		}
+		cache = { data: parsed }
+		return parsed
+	})
+	return ConfigProvider.make((path) =>
+		Effect.gen(function* () {
+			const data = yield* load
+			if (data === null) return undefined
+			if (path.length === 0) {
+				return ConfigProvider.makeRecord(new Set(Object.keys(data)))
+			}
+			const head = path[0]
+			if (typeof head !== "string") return undefined
+			const value = data[head]
+			if (value === undefined) return undefined
+			if (typeof value === "string") return ConfigProvider.makeValue(value)
+			// Numbers/booleans coerced to their string form so Schema.Literals matches.
+			return ConfigProvider.makeValue(String(value))
+		}),
+	)
+}
+
+/**
+ * Reads `HOUSE_THEME` / `HOUSE_TONE` directly into a `fromUnknown` provider.
+ *
+ * We don't use `fromEnv().pipe(nested("HOUSE"), constantCase)` here because
+ * `ConfigProvider.orElse` composes providers via `.get(path)` (raw store
+ * access), which bypasses `mapInput`/`prefix`. That means an env provider
+ * built with `nested` + `constantCase` silently returns `undefined` once it
+ * sits behind an `orElse`. Reading env vars eagerly sidesteps the issue.
+ */
+const envProvider = (env: Record<string, string | undefined>): ConfigProvider.ConfigProvider => {
+	const entries: Array<[string, string]> = []
+	const theme = env["HOUSE_THEME"]
+	const tone = env["HOUSE_TONE"]
+	if (theme !== undefined) entries.push(["theme", theme])
+	if (tone !== undefined) entries.push(["tone", tone])
+	return ConfigProvider.fromUnknown(Object.fromEntries(entries))
+}
+
+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])
+	return ConfigProvider.fromUnknown(Object.fromEntries(entries))
+}
+
+export interface LoadOptions {
+	readonly cli?: CliOverrides
+	/** Override the TOML path (tests). Defaults to `$XDG_CONFIG_HOME/house/config.toml`. */
+	readonly filePath?: string
+	/** Override env (tests). Defaults to `process.env`. */
+	readonly env?: Record<string, string>
+}
+
+export const defaultConfigPath = (): string =>
+	join(process.env["XDG_CONFIG_HOME"] ?? join(homedir(), ".config"), "house", "config.toml")
+
+/**
+ * Renders a `ConfigError` (or any error) as a short single-line message
+ * suitable for `console.error("house: " + ...)`. Strips Effect's
+ * `ConfigError(SchemaError(...))` wrapping when present.
+ */
+export const formatConfigError = (err: unknown): string => {
+	if (err instanceof Config.ConfigError) {
+		const cause = err.cause
+		const raw = "message" in cause ? cause.message : String(cause)
+		return raw
+			.replace(/\s+at \[[^\]]+\]\s*$/, "")
+			.replace(/\s+/g, " ")
+			.trim()
+	}
+	if (err instanceof Error) return err.message
+	return String(err)
+}
+
+export const loadConfig = (
+	options: LoadOptions = {},
+): Effect.Effect<HouseConfig, Config.ConfigError> => {
+	const cli = options.cli ?? { theme: null, tone: null }
+	const provider = cliProvider(cli).pipe(
+		ConfigProvider.orElse(envProvider(options.env ?? process.env)),
+		ConfigProvider.orElse(fileProvider(options.filePath ?? defaultConfigPath())),
+		ConfigProvider.orElse(defaultsProvider()),
+	)
+	return schema.parse(provider)
+}

package/src/discovery/walk.ts

@@ -1,6 +1,6 @@
 import { readdir, readFile } from "node:fs/promises"
 import { extname, join, relative, resolve } from "node:path"
-import { Data, Effect } from "effect"
+import { Data, Effect, Stream } from "effect"
 import ignore, { type Ignore } from "ignore"
 
 export interface FileEntry {
@@ -71,21 +71,38 @@ const sortEntries = <T extends { name: string; isDirectory: () => boolean }>(
 		return a.name.localeCompare(b.name)
 	})
 
-const walkDir = async (
+/**
+ * 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.
+ *
+ * Cancellation: `signal.aborted` is checked between syscalls. Node's
+ * `readdir` doesn't accept an AbortSignal, so a single in-flight `readdir`
+ * on a slow filesystem still runs to completion before we notice — the
+ * generator only exits at the next checkpoint.
+ */
+async function* walkDirGen(
 	dirPath: string,
 	rootPath: string,
 	parentLevels: readonly IgnoreLevel[],
-	results: FileEntry[],
 	opts: { all: boolean; sort: SortOrder },
-): Promise<void> => {
+	signal: AbortSignal,
+): AsyncGenerator<FileEntry, void, void> {
+	if (signal.aborted) return
+
 	let levels = parentLevels
 	if (!opts.all) {
 		const ig = await tryLoadGitignore(dirPath)
+		if (signal.aborted) return
 		if (ig) levels = [...parentLevels, { dir: dirPath, ig }]
 	}
 
 	const raw = await readdir(dirPath, { withFileTypes: true })
+	if (signal.aborted) return
+
 	for (const entry of sortEntries(raw, opts.sort)) {
+		if (signal.aborted) return
+
 		// Never follow symlinks — cycle hazard, and a markdown reader doesn't
 		// need them. May be relaxed (files only) in a later iteration.
 		if (entry.isSymbolicLink()) continue
@@ -96,7 +113,7 @@ const walkDir = async (
 			if (HARD_SKIP_DIRS.has(entry.name)) continue
 			if (!opts.all && entry.name.startsWith(".")) continue
 			if (!opts.all && isIgnored(entryPath, true, levels)) continue
-			await walkDir(entryPath, rootPath, levels, results, opts)
+			yield* walkDirGen(entryPath, rootPath, levels, opts, signal)
 			continue
 		}
 
@@ -105,16 +122,19 @@ const walkDir = async (
 		if (!MARKDOWN_EXTENSIONS.has(extname(entry.name).toLowerCase())) continue
 		if (!opts.all && isIgnored(entryPath, false, levels)) continue
 
-		results.push({
+		yield {
 			path: entryPath,
 			relativePath: relative(rootPath, entryPath),
 			name: entry.name,
-		})
+		}
 	}
 }
 
 /**
- * Walk a directory tree and return markdown files in a stable order.
+ * Stream markdown files under `root`. Entries arrive in DFS order respecting
+ * the per-directory sort. The stream is interruptible at syscall boundaries:
+ * the consumer's teardown trips an AbortController, and the generator exits
+ * at its next `signal.aborted` check.
  *
  * Rules (see DESIGN.md §6):
  * - Extensions: `.md`, `.markdown`, `.mdx`.
@@ -128,16 +148,35 @@ const walkDir = async (
 export const walk = (
 	root: string,
 	options: WalkOptions = {},
-): Effect.Effect<readonly FileEntry[], DiscoveryError> =>
-	Effect.tryPromise({
-		try: async () => {
-			const absRoot = resolve(root)
-			const results: FileEntry[] = []
-			await walkDir(absRoot, absRoot, [], results, {
-				all: options.all ?? false,
-				sort: options.sort ?? "dirs-first",
-			})
-			return results
+): Stream.Stream<FileEntry, DiscoveryError> => {
+	const absRoot = resolve(root)
+	const opts = {
+		all: options.all ?? false,
+		sort: options.sort ?? ("dirs-first" as SortOrder),
+	}
+	const controller = new AbortController()
+	const iterable: AsyncIterable<FileEntry> = {
+		[Symbol.asyncIterator]() {
+			const gen = walkDirGen(absRoot, absRoot, [], opts, controller.signal)
+			return {
+				next: () => gen.next(),
+				return: async (value?: void) => {
+					controller.abort()
+					return gen.return(value as void)
+				},
+			}
 		},
-		catch: (cause) => new DiscoveryError({ root, cause }),
-	})
+	}
+	return Stream.fromAsyncIterable(iterable, (cause) => new DiscoveryError({ root, cause }))
+}
+
+/**
+ * Test/convenience helper: collect the full walk into an array. Mirrors the
+ * pre-streaming `walk()` signature so call sites that don't need streaming
+ * (notably tests) stay terse.
+ */
+export const walkToArray = (
+	root: string,
+	options: WalkOptions = {},
+): Effect.Effect<readonly FileEntry[], DiscoveryError> =>
+	Stream.runCollect(walk(root, options)).pipe(Effect.map((chunk) => Array.from(chunk)))

package/src/index.tsx

@@ -12,18 +12,19 @@ import { stat } from "node:fs/promises"
 import { createCliRenderer, SyntaxStyle } from "@opentui/core"
 import { createRoot, useKeyboard, useRenderer, useTerminalDimensions } from "@opentui/react"
 import { RegistryProvider, useAtomSet, useAtomValue } from "@effect/atom-react"
-import { Effect } from "effect"
-import { useMemo } from "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 { parseArgv, usage } from "./cli/argv.ts"
-import { walk, type SortOrder } from "./discovery/walk.ts"
+import { defaultConfigPath, formatConfigError, loadConfig } from "./config/load.ts"
+import { walk, type FileEntry, type SortOrder } from "./discovery/walk.ts"
 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 { themeAtom, type ThemeState } from "./theme/atom.ts"
-import { getThemeDefinition, isThemeId, themeDefinitions } from "./theme/registry.ts"
+import { getThemeDefinition, themeDefinitions } from "./theme/registry.ts"
 
 export interface AppProps {
 	/** Markdown source to render. */
@@ -36,6 +37,78 @@ export interface AppProps {
 	readonly onQuit?: () => void
 }
 
+/**
+ * DiscoverShell — owns the streaming walk for directory mode. Mounts Browser
+ * immediately with `files=[]` and pushes entries as the stream emits.
+ *
+ * Batching: `Stream.groupedWithin(64, 60ms)` coalesces bursts so we don't
+ * trigger one React render per file. Tuned by feel — small enough that
+ * results still feel live on tiny trees, large enough to keep render
+ * frequency sane on big ones. Revisit if profiling says otherwise.
+ *
+ * Cancellation: the walk runs on a forked fiber; unmount interrupts it.
+ * `Quit` in Browser tears down the renderer and exits, which propagates
+ * naturally — the cleanup effect still fires before process.exit completes.
+ */
+export type SidebarMode = "auto" | "on" | "off"
+
+interface DiscoverShellProps {
+	readonly target: string
+	readonly all: boolean
+	readonly sort: SortOrder
+	readonly maxWidth: number | null
+	readonly sidebarMode: SidebarMode
+}
+
+const DiscoverShell = ({ target, all, sort, maxWidth, sidebarMode }: DiscoverShellProps) => {
+	const [files, setFiles] = useState<readonly FileEntry[]>([])
+	const [scanning, setScanning] = useState<boolean>(true)
+	const [scanError, setScanError] = 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)
+
+	useEffect(() => {
+		const program = walk(target, { all, sort }).pipe(
+			Stream.groupedWithin(64, Duration.millis(60)),
+			Stream.runForEach((chunk) =>
+				Effect.sync(() => {
+					const arr = Array.from(chunk)
+					if (arr.length === 0) return
+					countRef.current += arr.length
+					setFiles((prev) => [...prev, ...arr])
+				}),
+			),
+			Effect.matchCauseEffect({
+				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)}`)
+						setScanning(false)
+					}),
+			}),
+		)
+		const fiber = Effect.runFork(program)
+		return () => {
+			Effect.runFork(Fiber.interrupt(fiber))
+		}
+	}, [target, all, sort])
+
+	const discoveryStatus = scanError ?? (scanning ? `indexing… ${countRef.current}` : null)
+
+	return (
+		<Browser
+			files={files}
+			title={target}
+			maxWidth={maxWidth}
+			discoveryStatus={discoveryStatus}
+			sidebarMode={sidebarMode}
+		/>
+	)
+}
+
 export const App = ({ content, title = "house", maxWidth = null, onQuit }: AppProps) => {
 	const renderer = useRenderer()
 	const { width, height } = useTerminalDimensions()
@@ -121,20 +194,21 @@ if (import.meta.main) {
 		console.log(pkg.version)
 		process.exit(0)
 	}
-
-	const themeId = args.theme ?? "opencode"
-	if (!isThemeId(themeId)) {
-		const known = themeDefinitions.map((t) => t.id).join(", ")
-		console.error(`house: unknown theme "${themeId}". Known: ${known}`)
-		process.exit(2)
+	if (args.configPath) {
+		console.log(defaultConfigPath())
+		process.exit(0)
 	}
-	const tone = args.tone ?? "dark"
-	if (tone !== "dark" && tone !== "light") {
-		console.error(`house: --tone must be "dark" or "light", got "${tone}"`)
+
+	const config = await Effect.runPromise(
+		loadConfig({ cli: { theme: args.theme, tone: args.tone } }),
+	).catch((err: unknown) => {
+		console.error(`house: ${formatConfigError(err)}`)
 		process.exit(2)
-	}
+	})
+	const { theme: themeId, tone } = config
 	const themeDef = getThemeDefinition(themeId)
 	if (themeDef === undefined) {
+		// Unreachable: Config.schema validated themeId against themeDefinitions.
 		console.error(`house: unknown theme "${themeId}"`)
 		process.exit(2)
 	}
@@ -193,7 +267,15 @@ if (import.meta.main) {
 			}
 			sort = args.sort
 		}
-		await runTui({ target, themeId, tone, maxWidth, all: args.all, sort })
+		let sidebarMode: SidebarMode = "auto"
+		if (args.sidebar !== null) {
+			if (args.sidebar !== "auto" && args.sidebar !== "on" && args.sidebar !== "off") {
+				console.error(`house: --sidebar must be "auto", "on", or "off", got "${args.sidebar}"`)
+				process.exit(2)
+			}
+			sidebarMode = args.sidebar
+		}
+		await runTui({ target, themeId, tone, maxWidth, all: args.all, sort, sidebarMode })
 	}
 }
 
@@ -204,6 +286,7 @@ interface TuiBootOptions {
 	readonly maxWidth: number | null
 	readonly all: boolean
 	readonly sort: SortOrder
+	readonly sidebarMode: SidebarMode
 }
 
 async function runTui({
@@ -213,6 +296,7 @@ async function runTui({
 	maxWidth,
 	all,
 	sort,
+	sidebarMode,
 }: TuiBootOptions): Promise<void> {
 	let stats: Awaited<ReturnType<typeof stat>>
 	try {
@@ -226,21 +310,15 @@ async function runTui({
 	const initialTheme: ThemeState = { id: themeId, tone }
 
 	if (stats.isDirectory()) {
-		const files = await Effect.runPromise(
-			walk(target, { all, sort }).pipe(
-				Effect.tapError((err) =>
-					Effect.sync(() => {
-						console.error(`house: cannot walk ${target}: ${String(err.cause)}`)
-					}),
-				),
-			),
-		).catch(() => {
-			process.exit(1)
-		})
-		if (!Array.isArray(files)) process.exit(1)
 		createRoot(renderer).render(
 			<RegistryProvider initialValues={[[themeAtom, initialTheme]]}>
-				<Browser files={files} title={target} maxWidth={maxWidth} />
+				<DiscoverShell
+					target={target}
+					all={all}
+					sort={sort}
+					maxWidth={maxWidth}
+					sidebarMode={sidebarMode}
+				/>
 			</RegistryProvider>,
 		)
 	} else {

package/src/keymap/browser.ts

@@ -11,14 +11,18 @@ export type BrowserFocus = "sidebar" | "reader"
 export interface BrowserCtx {
 	readonly files: readonly FileEntry[]
 	readonly focus: BrowserFocus
-	readonly sidebarVisible: boolean
+	/** User's sticky sidebar preference. Visibility is `shown || focus==="sidebar"`. */
+	readonly sidebarShown: boolean
 	readonly helpVisible: boolean
 	readonly filterOpen: boolean
+	readonly paletteOpen: boolean
 	readonly setFocus: (next: BrowserFocus | ((prev: BrowserFocus) => BrowserFocus)) => void
 	readonly setSelectedIndex: (updater: (prev: number) => number) => void
-	readonly setSidebarVisible: (updater: (prev: boolean) => boolean) => 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
+	readonly openPalette: () => void
 	readonly cycleTheme: (delta: 1 | -1) => void
 	readonly toggleTone: () => void
 	readonly quit: () => void
@@ -37,7 +41,8 @@ const stepBy = (c: BrowserCtx, delta: number) =>
 	c.setSelectedIndex((i) => clamp(i + delta, 0, lastIndex(c)))
 
 const inSidebar = (c: BrowserCtx) => c.focus === "sidebar"
-const inSidebarFilterClosed = (c: BrowserCtx) => inSidebar(c) && !c.filterOpen
+const filterClosed = (c: BrowserCtx) => !c.filterOpen
+const paletteClosed = (c: BrowserCtx) => !c.paletteOpen
 const inReader = (c: BrowserCtx) => c.focus === "reader"
 const inSidebarWithFiles = (c: BrowserCtx) => inSidebar(c) && haveFiles(c)
 const inReaderWithFiles = (c: BrowserCtx) => inReader(c) && haveFiles(c)
@@ -66,13 +71,7 @@ export const browserBindings: readonly KeyBinding<BrowserCtx>[] = [
 		description: "Toggle sidebar visibility",
 		hint: "sidebar",
 		keys: ["s"],
-		run: (c) => {
-			const willHide = c.sidebarVisible
-			c.setSidebarVisible((v) => !v)
-			// When hiding the sidebar, move focus to the reader so input has a
-			// target. When revealing it, move focus back to the sidebar.
-			c.setFocus(willHide ? "reader" : "sidebar")
-		},
+		run: (c) => c.toggleShown(),
 	},
 	{
 		id: "help.toggle",
@@ -88,9 +87,25 @@ export const browserBindings: readonly KeyBinding<BrowserCtx>[] = [
 		description: "Filter files (fuzzy match on path)",
 		hint: "filter",
 		keys: ["/"],
-		when: inSidebarFilterClosed,
+		// Fires from anywhere except inside an already-open filter. `openFilter`
+		// itself force-opens the sidebar and moves focus there, so the binding
+		// no longer needs to gate on focus or sidebar visibility.
+		when: filterClosed,
 		run: (c) => c.openFilter(),
 	},
+	{
+		id: "palette.open",
+		group: "Global",
+		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).
+		when: paletteClosed,
+		run: (c) => c.openPalette(),
+	},
 	{
 		id: "serve.current",
 		group: "Global",

package/src/layout/resolve.ts

@@ -0,0 +1,60 @@
+/**
+ * Layout primitives for the two-pane shape (sidebar + reader).
+ *
+ * Visibility and width are decoupled (see DESIGN.md §7.1):
+ *   visible = shown || focus === "sidebar"
+ * Width is a pure function of viewport, independent of visibility:
+ *   resolveSidebarWidth(viewport, preferred)
+ *
+ * Both render code and key handlers consume these primitives — there is no
+ * parallel implementation living in JSX.
+ */
+
+/** Minimum useful sidebar width; below this, file rows truncate too aggressively. */
+export const SIDEBAR_MIN_WIDTH = 28
+/** Maximum sidebar width; beyond this, wasted whitespace on wide terminals. */
+export const SIDEBAR_MAX_WIDTH = 60
+/** Reader pane minimum; below this, prose wraps unpleasantly. */
+export const READER_MIN_WIDTH = 40
+/** Column gap painted between the two panes when both are inline. */
+export const DIVIDER_WIDTH = 1
+/** Launch-bucket threshold for `--sidebar=auto`. < this → start hidden. */
+export const TIGHT_VIEWPORT_THRESHOLD = 80
+
+/**
+ * Continuous clamp. `preferred` is the user's desired width (until #13 lands,
+ * derived from viewport). The reader-min ceiling means the sidebar yields
+ * space rather than squeezing the reader below readability.
+ *
+ * Result is not clamped *up* to SIDEBAR_MIN when the viewport itself is too
+ * narrow to hold both panes — the caller decides whether to render at all
+ * (e.g. drawer instead of inline). See `canFitInline`.
+ */
+export const resolveSidebarWidth = (viewport: number, preferred: number): number => {
+	const ceiling = viewport - DIVIDER_WIDTH - READER_MIN_WIDTH
+	const lower = Math.min(SIDEBAR_MIN_WIDTH, Math.max(0, ceiling))
+	const upper = Math.max(lower, ceiling)
+	return Math.max(lower, Math.min(upper, preferred))
+}
+
+/**
+ * Default preferred sidebar width, derived from viewport until persistent
+ * config (#13) provides a user-set value. Matches the previous inline math.
+ */
+export const defaultPreferredWidth = (viewport: number): number =>
+	Math.max(SIDEBAR_MIN_WIDTH, Math.min(SIDEBAR_MAX_WIDTH, Math.floor(viewport * 0.25)))
+
+/**
+ * True when an inline (side-by-side) layout still gives the reader at least
+ * READER_MIN_WIDTH. When false, the caller should render the sidebar as a
+ * drawer instead — see DESIGN.md §7.1 Q2.
+ */
+export const canFitInline = (viewport: number): boolean =>
+	viewport >= SIDEBAR_MIN_WIDTH + DIVIDER_WIDTH + READER_MIN_WIDTH
+
+/**
+ * Launch bucket decision for `--sidebar=auto`. Buckets are consulted once at
+ * launch only; subsequent visibility changes go through `shown` + focus.
+ */
+export const initialShownForAuto = (viewport: number): boolean =>
+	viewport >= TIGHT_VIEWPORT_THRESHOLD