@carlesandres/house 0.3.0 → 0.3.1

package/CHANGELOG.md

@@ -1,6 +1,6 @@
 # Changelog
 
-All notable changes to house (renamed from `openmdr` in 0.3.0) land here. Format follows
+All notable changes to house land here. Format follows
 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and the project
 follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html) from
 v0.1.0 onward.
@@ -12,6 +12,38 @@ file is the curated, narrative version.
 
 ## [Unreleased]
 
+## [0.3.1] — 2026-05-17
+
+Beta release gates (DESIGN §10.2) closed.
+
+### Fixed
+
+- Language-tagged fenced code blocks no longer disappear while markdown
+  highlighting settles. `house` now uses opentui `0.2.12`, which includes
+  markdown/code-block rendering fixes, and the browser pane no longer
+  remounts markdown for one file while still holding another file's loaded
+  content.
+- Strikethrough text (`~~strike~~`) now renders distinctly (dim + muted
+  foreground) instead of as plain body text. opentui's syntax-style API
+  has no true strikethrough attribute; this is the closest visual we can
+  produce, documented in DESIGN §5.1.
+
+### Changed
+
+- Reduced re-renders and allocations in `Browser` / `Footer` hot paths.
+- DESIGN §10.2 test gate rephrased to target the integration surface
+  house owns (the tree-sitter scope map) rather than re-testing opentui's
+  renderer; `test/theme-syntax-map.test.ts` enforces scope coverage for
+  every node type §5.1.3 promises.
+
+### Docs
+
+- README embeds a VHS-generated demo gif; `tape/` holds the source
+  scripts.
+- `CONTRIBUTING.md` documents the `captureSpans()` / `MockTreeSitterClient`
+  / `TestRecorder` testing patterns and the "before blaming `<markdown>`"
+  stale-watcher debugging checklist.
+
 ## [0.3.0] — 2026-05-16
 
 ### Changed

package/README.md

@@ -1,15 +1,9 @@
 # house
 
-> **Renamed from `openmdr`.** The old npm package `@carlesandres/openmdr`
-> is deprecated; install `@carlesandres/house` instead. The CLI binary is
-> now `house` (was `openmdr`).
-
-A terminal markdown reader built on [opentui](https://github.com/nicholasgasior/opentui).
+A terminal markdown reader built on [opentui](https://github.com/anomalyco/opentui).
 Point it at a directory and navigate its `.md` files without leaving the terminal.
 
-```
-npx @carlesandres/house docs/
-```
+![house demo](tape/house.gif)
 
 Requires [Bun](https://bun.sh) on `PATH`.
 
@@ -52,8 +46,9 @@ house [options] <path>
 |-----|--------|
 | `q` / `ctrl+c` | Quit |
 | `tab` | Toggle focus (sidebar ↔ reader) |
-| `\` | Toggle sidebar visibility |
+| `s` | Toggle sidebar visibility |
 | `?` | Show / dismiss help overlay |
+| `o` | Open current file in browser as HTML |
 | `t` | Next theme |
 | `T` | Previous theme |
 | `L` | Toggle dark / light tone |
@@ -64,12 +59,13 @@ house [options] <path>
 |-----|--------|
 | `j` / `↓` | Move selection down |
 | `k` / `↑` | Move selection up |
-| `J` | Jump down 10 |
-| `K` | Jump up 10 |
-| `space` / `ctrl+d` | Page down |
-| `b` / `ctrl+u` | Page up |
+| `J` | Jump down 8 |
+| `K` | Jump up 8 |
+| `space` / `pagedown` / `ctrl+d` | Page down |
+| `b` / `pageup` / `ctrl+u` | Page up |
 | `g` | First file |
 | `G` | Last file |
+| `/` | Filter files (fuzzy match on path) |
 | `↵` / `→` / `l` | Open file (focus reader) |
 
 ### Reader
@@ -94,6 +90,12 @@ house [options] <path>
 
 Each theme supports dark and light tones. Cycle with `t` / `T`; toggle tone with `L`.
 
+## Inspiration
+
+- [glow](https://github.com/charmbracelet/glow) — render markdown on the CLI, with pizzazz
+- [ghui](https://github.com/kitlangton/ghui) — keyboard-driven terminal UI for GitHub pull requests
+- [hunk](https://github.com/modem-dev/hunk) — review-first terminal diff viewer for agent-authored changesets
+
 ## License
 
 MIT

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@carlesandres/house",
-	"version": "0.3.0",
+	"version": "0.3.1",
 	"description": "TUI-first markdown reader on opentui",
 	"type": "module",
 	"license": "MIT",
@@ -44,12 +44,13 @@
 		"format": "oxfmt src/",
 		"format:check": "oxfmt --check src/",
 		"test": "bun test",
-		"build:themes": "bun run dev/build-themes.ts"
+		"build:themes": "bun run dev/build-themes.ts",
+		"repro:pty-codeblocks": "bun run dev/repro-pty-codeblocks.ts"
 	},
 	"dependencies": {
 		"@effect/atom-react": "4.0.0-beta.59",
-		"@opentui/core": "0.2.1",
-		"@opentui/react": "0.2.1",
+		"@opentui/core": "0.2.12",
+		"@opentui/react": "0.2.12",
 		"effect": "4.0.0-beta.59",
 		"ignore": "^7.0.5",
 		"marked": "^18.0.3",

package/src/Browser.tsx

@@ -14,7 +14,7 @@ import { SyntaxStyle } from "@opentui/core"
 import { useKeyboard, useRenderer, useTerminalDimensions } from "@opentui/react"
 import { useAtomValue, useAtomSet } from "@effect/atom-react"
 import { Effect } from "effect"
-import { useEffect, useMemo, useRef, useState } from "react"
+import { useCallback, useEffect, useMemo, useRef, useState } from "react"
 import { filterFiles } from "./discovery/filter.ts"
 import { type FileEntry } from "./discovery/walk.ts"
 import { Footer, FOOTER_HEIGHT } from "./Footer.tsx"
@@ -69,7 +69,7 @@ export const Browser = ({
 	const [selectedIndex, setSelectedIndex] = useState(() =>
 		clamp(initialIndex, 0, Math.max(0, files.length - 1)),
 	)
-	const [content, setContent] = useState<string>("")
+	const [loaded, setLoaded] = useState<{ path: string; content: string } | null>(null)
 	const [error, setError] = useState<string | null>(null)
 	const [focus, setFocus] = useState<"sidebar" | "reader">("sidebar")
 	const [sidebarVisible, setSidebarVisible] = useState<boolean>(true)
@@ -121,7 +121,6 @@ export const Browser = ({
 	}
 
 	const displayedFiles = useMemo(() => filterFiles(files, filterQuery), [files, filterQuery])
-
 	// When the filtered list shrinks, keep selectedIndex valid. The reset to 0
 	// on every query change happens in the keystroke handler, not here, so a
 	// no-op rerender doesn't snap the cursor back to the top.
@@ -145,24 +144,24 @@ export const Browser = ({
 		if (target === renderedPath) return
 		const timer = setTimeout(() => setRenderedPath(target), 80)
 		return () => clearTimeout(timer)
-	}, [selected, renderedPath])
+	}, [selected?.path, renderedPath])
 
 	useEffect(() => {
 		if (!renderedPath) {
-			setContent("")
+			setLoaded(null)
 			return
 		}
 		let cancelled = false
 		readFile(renderedPath).then(
 			(text) => {
 				if (!cancelled) {
-					setContent(text)
+					setLoaded({ path: renderedPath, content: text })
 					setError(null)
 				}
 			},
 			(err: unknown) => {
 				if (!cancelled) {
-					setContent("")
+					setLoaded(null)
 					setError(`Cannot read ${renderedPath}: ${String(err)}`)
 				}
 			},
@@ -330,6 +329,7 @@ export const Browser = ({
 	const sidebarTitle = sidebarActive ? " ▸ files " : "   files "
 	const readerLabel = selected?.relativePath ?? title
 	const readerTitle = readerActive ? ` ▸ ${readerLabel} ` : `   ${readerLabel} `
+	const content = loaded?.path === renderedPath ? loaded.content : ""
 
 	// Sidebar virtualization: render only the visible window. Without this,
 	// every keystroke re-renders all N file rows even though only the bg of
@@ -352,16 +352,25 @@ export const Browser = ({
 	const sidebarTextWidth = Math.max(4, sidebarWidth - 2)
 	// Right-anchored truncation: keep the filename visible, lose the prefix
 	// with a leading ellipsis when the path is too long.
-	const truncatePath = (s: string): string =>
-		s.length <= sidebarTextWidth ? s : "…" + s.slice(s.length - sidebarTextWidth + 1)
+	const truncatePath = useCallback(
+		(s: string): string =>
+			s.length <= sidebarTextWidth ? s : "…" + s.slice(s.length - sidebarTextWidth + 1),
+		[sidebarTextWidth],
+	)
 
 	// While help is open, the `?` key closes the overlay — relabel its hint
 	// so the footer accurately describes what pressing the key will do.
-	const footerBindings = helpVisible
-		? browserBindings
-				.filter((b) => HELP_ALLOWED_IDS.has(b.id))
-				.map((b) => (b.id === "help.toggle" ? { ...b, hint: "close" } : b))
-		: browserBindings
+	// Memoized: `helpVisible` changes rarely; `browserBindings` and
+	// `HELP_ALLOWED_IDS` are module-level constants.
+	const footerBindings = useMemo(
+		() =>
+			helpVisible
+				? browserBindings
+						.filter((b) => HELP_ALLOWED_IDS.has(b.id))
+						.map((b) => (b.id === "help.toggle" ? { ...b, hint: "close" } : b))
+				: browserBindings,
+		[helpVisible],
+	)
 
 	return (
 		<box style={{ width, height, flexDirection: "column", backgroundColor: colors.background }}>

package/src/Footer.tsx

@@ -126,13 +126,13 @@ export const Footer = <C,>({ bindings, ctx, width, notice, filter }: FooterProps
 		)
 	}
 
-	const hintContent = fitHints(
-		bindings
-			.filter((b) => (b.when ? b.when(ctx) : true))
-			.map(formatHint)
-			.filter((s): s is string => s !== null),
-		usableWidth,
-	)
+	const hints: string[] = []
+	for (const b of bindings) {
+		if (b.when && !b.when(ctx)) continue
+		const h = formatHint(b)
+		if (h !== null) hints.push(h)
+	}
+	const hintContent = fitHints(hints, usableWidth)
 	const noticeContent = notice
 		? notice.length > usableWidth
 			? notice.slice(0, usableWidth)

package/src/theme/colors.ts

@@ -50,6 +50,9 @@ const buildSyntaxMap = (r: ResolvedTheme): Record<string, StyleDefinitionInput>
 		"markup.bold": { fg: r.markdownStrong, bold: true },
 		"markup.strong": { fg: r.markdownStrong, bold: true },
 		"markup.italic": { fg: r.markdownEmph, italic: true },
+		// opentui's SyntaxStyle has no strikethrough attribute — best-effort:
+		// dim + muted color so `~~strike~~` is at least visually distinguishable.
+		"markup.strikethrough": { fg: r.textMuted, dim: true },
 		"markup.list": { fg: r.markdownListItem },
 		"markup.quote": { fg: r.markdownBlockQuote, italic: true },
 		"markup.raw": { fg: r.markdownCode, bg: codeBg },