@carlesandres/house 0.3.0

package/src/io/readFile.ts

@@ -0,0 +1,14 @@
+import { readFile } from "node:fs/promises"
+import { Data, Effect } from "effect"
+
+export class FileReadError extends Data.TaggedError("FileReadError")<{
+	readonly path: string
+	readonly cause: unknown
+}> {}
+
+/** Read a UTF-8 text file. Errors as `FileReadError`. */
+export const readFileText = (path: string): Effect.Effect<string, FileReadError> =>
+	Effect.tryPromise({
+		try: () => readFile(path, "utf8"),
+		catch: (cause) => new FileReadError({ path, cause }),
+	})

package/src/keymap/browser.ts

@@ -0,0 +1,229 @@
+/**
+ * Browser keymap — the data backing `Browser.tsx`'s `useKeyboard` handler
+ * and (next iteration) the `?` help overlay.
+ */
+
+import type { FileEntry } from "../discovery/walk.ts"
+import type { KeyBinding } from "./keymap.ts"
+
+export type BrowserFocus = "sidebar" | "reader"
+
+export interface BrowserCtx {
+	readonly files: readonly FileEntry[]
+	readonly focus: BrowserFocus
+	readonly sidebarVisible: boolean
+	readonly helpVisible: boolean
+	readonly filterOpen: boolean
+	readonly setFocus: (next: BrowserFocus | ((prev: BrowserFocus) => BrowserFocus)) => void
+	readonly setSelectedIndex: (updater: (prev: number) => number) => void
+	readonly setSidebarVisible: (updater: (prev: boolean) => boolean) => void
+	readonly setHelpVisible: (updater: (prev: boolean) => boolean) => void
+	readonly openFilter: () => void
+	readonly cycleTheme: (delta: 1 | -1) => void
+	readonly toggleTone: () => void
+	readonly quit: () => void
+	/** Start (or retarget) the HTML preview server on the focused file. */
+	readonly serveCurrent: () => void
+}
+
+/** Step size for shift+j/k and the space/b/page keys. Constant for v1; could
+ *  later be derived from the visible window height. */
+const JUMP = 8
+
+const clamp = (n: number, min: number, max: number) => Math.max(min, Math.min(max, n))
+const lastIndex = (c: BrowserCtx) => Math.max(0, c.files.length - 1)
+const haveFiles = (c: BrowserCtx) => c.files.length > 0
+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 inReader = (c: BrowserCtx) => c.focus === "reader"
+const inSidebarWithFiles = (c: BrowserCtx) => inSidebar(c) && haveFiles(c)
+const inReaderWithFiles = (c: BrowserCtx) => inReader(c) && haveFiles(c)
+
+export const browserBindings: readonly KeyBinding<BrowserCtx>[] = [
+	// Global
+	{
+		id: "quit",
+		group: "Global",
+		description: "Quit",
+		hint: "quit",
+		keys: ["q", "ctrl+c"],
+		run: (c) => c.quit(),
+	},
+	{
+		id: "focus.toggle",
+		group: "Global",
+		description: "Toggle focus (sidebar ↔ reader)",
+		hint: "focus",
+		keys: ["tab"],
+		run: (c) => c.setFocus((f) => (f === "sidebar" ? "reader" : "sidebar")),
+	},
+	{
+		id: "sidebar.toggle",
+		group: "Global",
+		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")
+		},
+	},
+	{
+		id: "help.toggle",
+		group: "Global",
+		description: "Show / dismiss help",
+		hint: "help",
+		keys: ["?"],
+		run: (c) => c.setHelpVisible((v) => !v),
+	},
+	{
+		id: "filter.open",
+		group: "Sidebar",
+		description: "Filter files (fuzzy match on path)",
+		hint: "filter",
+		keys: ["/"],
+		when: inSidebarFilterClosed,
+		run: (c) => c.openFilter(),
+	},
+	{
+		id: "serve.current",
+		group: "Global",
+		description: "Open current file in browser as HTML",
+		hint: "html",
+		keys: ["o"],
+		when: haveFiles,
+		run: (c) => c.serveCurrent(),
+	},
+	{
+		id: "theme.next",
+		group: "Global",
+		description: "Next theme",
+		hint: "theme",
+		keys: ["t"],
+		run: (c) => c.cycleTheme(1),
+	},
+	{
+		id: "theme.prev",
+		group: "Global",
+		description: "Previous theme",
+		keys: ["shift+t"],
+		run: (c) => c.cycleTheme(-1),
+	},
+	{
+		id: "theme.toneToggle",
+		group: "Global",
+		description: "Toggle dark / light tone",
+		keys: ["shift+l"],
+		run: (c) => c.toggleTone(),
+	},
+
+	// Sidebar
+	{
+		id: "sidebar.down",
+		group: "Sidebar",
+		description: "Move selection down",
+		keys: ["j", "down"],
+		when: inSidebarWithFiles,
+		run: (c) => stepBy(c, 1),
+	},
+	{
+		id: "sidebar.up",
+		group: "Sidebar",
+		description: "Move selection up",
+		keys: ["k", "up"],
+		when: inSidebarWithFiles,
+		run: (c) => stepBy(c, -1),
+	},
+	{
+		id: "sidebar.jumpDown",
+		group: "Sidebar",
+		description: `Jump down ${JUMP}`,
+		keys: ["shift+j"],
+		when: inSidebarWithFiles,
+		run: (c) => stepBy(c, JUMP),
+	},
+	{
+		id: "sidebar.jumpUp",
+		group: "Sidebar",
+		description: `Jump up ${JUMP}`,
+		keys: ["shift+k"],
+		when: inSidebarWithFiles,
+		run: (c) => stepBy(c, -JUMP),
+	},
+	{
+		id: "sidebar.pageDown",
+		group: "Sidebar",
+		description: "Page down",
+		keys: ["space", "pagedown", "ctrl+d"],
+		when: inSidebarWithFiles,
+		run: (c) => stepBy(c, JUMP),
+	},
+	{
+		id: "sidebar.pageUp",
+		group: "Sidebar",
+		description: "Page up",
+		keys: ["b", "pageup", "ctrl+u"],
+		when: inSidebarWithFiles,
+		run: (c) => stepBy(c, -JUMP),
+	},
+	{
+		id: "sidebar.top",
+		group: "Sidebar",
+		description: "Jump to first file",
+		keys: ["g"],
+		when: inSidebarWithFiles,
+		run: (c) => c.setSelectedIndex(() => 0),
+	},
+	{
+		id: "sidebar.bottom",
+		group: "Sidebar",
+		description: "Jump to last file",
+		keys: ["shift+g"],
+		when: inSidebarWithFiles,
+		run: (c) => c.setSelectedIndex(() => lastIndex(c)),
+	},
+	{
+		id: "sidebar.open",
+		group: "Sidebar",
+		description: "Open file (focus reader)",
+		hint: "open",
+		keys: ["return", "right", "l"],
+		when: inSidebar,
+		run: (c) => c.setFocus("reader"),
+	},
+
+	// Reader
+	{
+		id: "reader.back",
+		group: "Reader",
+		description: "Back to sidebar",
+		hint: "back",
+		keys: ["escape", "left", "h"],
+		when: inReader,
+		run: (c) => c.setFocus("sidebar"),
+	},
+	{
+		id: "reader.prevFile",
+		group: "Reader",
+		description: "Prev file",
+		hint: "prev",
+		keys: ["["],
+		when: inReaderWithFiles,
+		run: (c) => stepBy(c, -1),
+	},
+	{
+		id: "reader.nextFile",
+		group: "Reader",
+		description: "Next file",
+		hint: "next",
+		keys: ["]"],
+		when: inReaderWithFiles,
+		run: (c) => stepBy(c, 1),
+	},
+]

package/src/keymap/keymap.ts

@@ -0,0 +1,86 @@
+/**
+ * Tiny declarative keymap.
+ *
+ * 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.
+ *
+ * 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
+ * trigger that would warrant adopting that machinery.
+ */
+
+/** The shape of a parsed key event we care about. `KeyEvent` from opentui satisfies this. */
+export interface KeyMatch {
+	readonly name: string
+	readonly shift?: boolean
+	readonly ctrl?: boolean
+	readonly meta?: boolean
+}
+
+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. */
+	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. */
+	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
+	 *  array drives overflow priority (later bindings get truncated first). */
+	readonly hint?: string
+	/** If present, the binding only fires when this returns true. */
+	readonly when?: (ctx: C) => boolean
+	readonly run: (ctx: C) => void
+}
+
+interface ParsedChord {
+	readonly key: string
+	readonly shift: boolean
+	readonly ctrl: boolean
+	readonly meta: boolean
+}
+
+const parseChord = (raw: string): ParsedChord => {
+	const parts = raw.toLowerCase().split("+")
+	const key = parts.at(-1) ?? ""
+	return {
+		key,
+		shift: parts.includes("shift"),
+		ctrl: parts.includes("ctrl"),
+		meta: parts.includes("meta"),
+	}
+}
+
+const chordMatches = (chord: ParsedChord, key: KeyMatch): boolean => {
+	if (chord.key !== key.name) return false
+	if (chord.shift !== Boolean(key.shift)) return false
+	if (chord.ctrl !== Boolean(key.ctrl)) return false
+	if (chord.meta !== Boolean(key.meta)) return false
+	return true
+}
+
+/**
+ * Return the first binding that (a) is enabled for `ctx` and (b) has a key
+ * that matches `key`. Runs the binding's action and returns it. Returns null
+ * if nothing matched.
+ */
+export const dispatch = <C>(
+	bindings: readonly KeyBinding<C>[],
+	ctx: C,
+	key: KeyMatch,
+): KeyBinding<C> | null => {
+	for (const binding of bindings) {
+		if (binding.when && !binding.when(ctx)) continue
+		for (const raw of binding.keys) {
+			if (chordMatches(parseChord(raw), key)) {
+				binding.run(ctx)
+				return binding
+			}
+		}
+	}
+	return null
+}

package/src/serve/css.ts

@@ -0,0 +1,120 @@
+/**
+ * Neutral GitHub-ish CSS for the serve action.
+ *
+ * Embedded inline by render.ts so each served page is self-contained — no
+ * second request, "Save Page As" gives a working file, future --export
+ * reuses the same renderer.
+ */
+export const css = `
+:root {
+	color-scheme: light dark;
+	--bg: #ffffff;
+	--fg: #1f2328;
+	--muted: #59636e;
+	--border: #d1d9e0;
+	--code-bg: #f6f8fa;
+	--accent: #0969da;
+	--blockquote: #59636e;
+	--blockquote-border: #d1d9e0;
+}
+@media (prefers-color-scheme: dark) {
+	:root {
+		--bg: #0d1117;
+		--fg: #e6edf3;
+		--muted: #9198a1;
+		--border: #30363d;
+		--code-bg: #151b23;
+		--accent: #4493f8;
+		--blockquote: #9198a1;
+		--blockquote-border: #30363d;
+	}
+}
+* { box-sizing: border-box; }
+html, body {
+	margin: 0;
+	padding: 0;
+	background: var(--bg);
+	color: var(--fg);
+}
+body {
+	font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", "Noto Sans",
+		Helvetica, Arial, sans-serif, "Apple Color Emoji", "Segoe UI Emoji";
+	font-size: 16px;
+	line-height: 1.6;
+}
+main {
+	max-width: 860px;
+	margin: 0 auto;
+	padding: 2.5rem 1.5rem 6rem;
+}
+h1, h2, h3, h4, h5, h6 {
+	margin-top: 1.75em;
+	margin-bottom: 0.6em;
+	font-weight: 600;
+	line-height: 1.25;
+}
+h1 { font-size: 2em; padding-bottom: .3em; border-bottom: 1px solid var(--border); }
+h2 { font-size: 1.5em; padding-bottom: .3em; border-bottom: 1px solid var(--border); }
+h3 { font-size: 1.25em; }
+h4 { font-size: 1em; }
+h5 { font-size: .9em; }
+h6 { font-size: .85em; color: var(--muted); }
+p, ul, ol, blockquote, pre, table { margin: 0 0 1em; }
+a { color: var(--accent); text-decoration: none; }
+a:hover { text-decoration: underline; }
+ul, ol { padding-left: 2em; }
+li + li { margin-top: .25em; }
+blockquote {
+	margin: 0 0 1em;
+	padding: 0 1em;
+	color: var(--blockquote);
+	border-left: .25em solid var(--blockquote-border);
+}
+code {
+	font-family: ui-monospace, SFMono-Regular, "SF Mono", Menlo, Consolas,
+		"Liberation Mono", monospace;
+	font-size: 85%;
+	padding: .2em .4em;
+	background: var(--code-bg);
+	border-radius: 6px;
+}
+pre {
+	background: var(--code-bg);
+	border: 1px solid var(--border);
+	padding: 1em;
+	border-radius: 6px;
+	overflow: auto;
+	font-size: 85%;
+	line-height: 1.45;
+}
+pre code {
+	padding: 0;
+	background: transparent;
+	border-radius: 0;
+	font-size: 100%;
+}
+table {
+	border-collapse: collapse;
+	display: block;
+	overflow: auto;
+	width: max-content;
+	max-width: 100%;
+}
+th, td { padding: .4em .8em; border: 1px solid var(--border); }
+th { background: var(--code-bg); font-weight: 600; }
+hr { height: 1px; border: 0; background: var(--border); margin: 1.5em 0; }
+img { max-width: 100%; }
+kbd {
+	display: inline-block;
+	padding: 3px 5px;
+	font-family: ui-monospace, SFMono-Regular, "SF Mono", Menlo, Consolas, monospace;
+	font-size: 11px;
+	line-height: 10px;
+	color: var(--fg);
+	vertical-align: middle;
+	background: var(--code-bg);
+	border: 1px solid var(--border);
+	border-radius: 6px;
+	box-shadow: inset 0 -1px 0 var(--border);
+}
+`.trim()

package/src/serve/openBrowser.ts

@@ -0,0 +1,19 @@
+/**
+ * Best-effort "open URL in default browser". Fire and forget — failures are
+ * silent because the URL has already been printed; user can click it.
+ */
+
+import { spawn } from "node:child_process"
+
+export const openInBrowser = (url: string): void => {
+	const cmd =
+		process.platform === "darwin" ? "open" : process.platform === "win32" ? "cmd" : "xdg-open"
+	const args = process.platform === "win32" ? ["/c", "start", "", url] : [url]
+	try {
+		const child = spawn(cmd, args, { stdio: "ignore", detached: true })
+		child.on("error", () => {})
+		child.unref()
+	} catch {
+		// platform without a launcher; URL was printed already.
+	}
+}

package/src/serve/render.ts

@@ -0,0 +1,56 @@
+/**
+ * renderHtml — wraps marked-rendered markdown in a self-contained HTML page.
+ *
+ * Embeds the CSS and a tiny SSE reload script so each response is one round
+ * trip. The reload script reconnects on drop; the server's `/__reload`
+ * endpoint pushes a `reload` event whenever the served file changes.
+ */
+
+import { marked } from "marked"
+import { css } from "./css.ts"
+
+const escapeHtml = (s: string): string =>
+	s.replace(/[&<>"']/g, (c) => {
+		switch (c) {
+			case "&":
+				return "&amp;"
+			case "<":
+				return "&lt;"
+			case ">":
+				return "&gt;"
+			case '"':
+				return "&quot;"
+			default:
+				return "&#39;"
+		}
+	})
+
+const reloadScript = `
+<script>
+(function () {
+	function connect() {
+		var es = new EventSource("/__reload");
+		es.addEventListener("reload", function () { location.reload(); });
+		es.onerror = function () { es.close(); setTimeout(connect, 500); };
+	}
+	connect();
+})();
+</script>
+`.trim()
+
+export const renderHtml = (markdown: string, title: string): string => {
+	const body = marked.parse(markdown, { async: false }) as string
+	return `<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>${escapeHtml(title)}</title>
+<style>${css}</style>
+</head>
+<body>
+<main>${body}</main>
+${reloadScript}
+</body>
+</html>`
+}

package/src/serve/server.ts

@@ -0,0 +1,163 @@
+/**
+ * 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
+ * new file retargets the existing server (live-reload fires) instead of
+ * spawning a second one.
+ *
+ * Live reload: an SSE endpoint at `/__reload` holds connections open and
+ * pushes a `reload` event whenever the watched file changes. A new watcher
+ * is created per `setTarget` call; the previous one is closed.
+ */
+
+import { basename } from "node:path"
+import { watch, type FSWatcher } from "node:fs"
+import { readFile } from "node:fs/promises"
+import { renderHtml } from "./render.ts"
+
+export interface ServerHandle {
+	/** Base URL, e.g. http://localhost:51234 */
+	readonly url: string
+	/** Swap which file is served. Pushes a reload to connected clients. */
+	setTarget(path: string): void
+	/** Path currently being served. */
+	currentTarget(): string
+	stop(): Promise<void>
+}
+
+export interface StartOptions {
+	readonly path: string
+	/** 0 = OS-assigned. */
+	readonly port?: number
+}
+
+type ReloadController = ReadableStreamDefaultController<Uint8Array>
+
+const encoder = new TextEncoder()
+const sseEvent = (event: string, data = ""): Uint8Array =>
+	encoder.encode(`event: ${event}\ndata: ${data}\n\n`)
+
+export const startServer = ({ path, port = 0 }: StartOptions): ServerHandle => {
+	let target = path
+	let watcher: FSWatcher | null = null
+	const clients = new Set<ReloadController>()
+
+	const broadcastReload = () => {
+		for (const c of clients) {
+			try {
+				c.enqueue(sseEvent("reload"))
+			} catch {
+				clients.delete(c)
+			}
+		}
+	}
+
+	// `fs.watch` watches an inode, not a path. Editors that save via
+	// write-tmp + rename (vim default, VS Code, JetBrains, …) replace the
+	// inode, after which our watcher fires nothing. So we re-watch on every
+	// event, and debounce because a single save often emits 2–3 events.
+	const startWatching = (p: string) => {
+		watcher?.close()
+		watcher = null
+		let timer: ReturnType<typeof setTimeout> | null = null
+		try {
+			watcher = watch(p, () => {
+				if (timer) clearTimeout(timer)
+				timer = setTimeout(() => {
+					broadcastReload()
+					startWatching(p)
+				}, 30)
+			})
+			watcher.on("error", () => {
+				// Stale handle after rename; the change event already scheduled
+				// a re-watch. Swallow so it doesn't crash the process.
+			})
+		} catch {
+			// Path went away between presses. Server still serves the last
+			// good read; live reload stays off until the path returns.
+		}
+	}
+	startWatching(target)
+
+	const server = Bun.serve({
+		port,
+		// Bind to loopback. Default is 0.0.0.0 (LAN-exposed); we render the
+		// user's local files, so leaking them to the network would be a
+		// surprise. URL strings are localhost-only by construction below.
+		hostname: "127.0.0.1",
+		async fetch(req) {
+			const url = new URL(req.url)
+			if (url.pathname === "/__reload") {
+				// `cancel` receives a reason, not the controller — capture
+				// the controller in `start` so we can remove it from the set
+				// on disconnect. Without this, dead clients accumulate.
+				let ctrl: ReloadController | null = null
+				const stream = new ReadableStream<Uint8Array>({
+					start(controller) {
+						ctrl = controller
+						clients.add(controller)
+						// Initial comment keeps some proxies from buffering.
+						controller.enqueue(encoder.encode(": connected\n\n"))
+					},
+					cancel() {
+						if (ctrl) clients.delete(ctrl)
+					},
+				})
+				return new Response(stream, {
+					headers: {
+						"content-type": "text/event-stream",
+						"cache-control": "no-cache",
+						connection: "keep-alive",
+					},
+				})
+			}
+			if (url.pathname !== "/") {
+				return new Response("not found", { status: 404 })
+			}
+			try {
+				const md = await readFile(target, "utf8")
+				const html = renderHtml(md, basename(target))
+				return new Response(html, {
+					headers: {
+						"content-type": "text/html; charset=utf-8",
+						"cache-control": "no-store",
+					},
+				})
+			} catch (err) {
+				return new Response(`cannot read ${target}: ${String(err)}`, {
+					status: 500,
+					headers: { "content-type": "text/plain; charset=utf-8" },
+				})
+			}
+		},
+	})
+
+	const url = `http://localhost:${server.port}`
+
+	return {
+		url,
+		currentTarget: () => target,
+		setTarget: (next) => {
+			if (next === target) {
+				broadcastReload()
+				return
+			}
+			target = next
+			startWatching(next)
+			broadcastReload()
+		},
+		stop: async () => {
+			watcher?.close()
+			for (const c of clients) {
+				try {
+					c.close()
+				} catch {
+					// already closed
+				}
+			}
+			clients.clear()
+			await server.stop(true)
+		},
+	}
+}