@carlesandres/house 0.3.1 → 0.4.1

package/CHANGELOG.md

@@ -1,94 +1,75 @@
 # Changelog
 
-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.
+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.
 
-The publish workflow (`.github/workflows/publish.yml`) runs on the
-`release: published` event, runs `npm publish` via Trusted Publisher,
-and lets GitHub auto-generate release notes from commit subjects; this
-file is the curated, narrative version.
+The publish workflow (`.github/workflows/publish.yml`) runs on the `release: published` event, runs `npm publish` via Trusted Publisher, and lets GitHub auto-generate release notes from commit subjects; this file is the curated, narrative version.
 
 ## [Unreleased]
 
+## [0.4.1] — 2026-05-22
+
+### Added
+
+- Header chrome: borderless one-row identity strip above the panes carries the ⌂ brand mark and running version. Renders in both directory mode (Browser) and single-file mode (App). Hidden on terminals shorter than 20 rows so tight panes keep the reader breathable.
+
+## [0.4.0] — 2026-05-21
+
+### Added
+
+- Command palette v1: `ctrl+p` opens a modal palette with visible browser commands derived from the keymap, including quit, sidebar toggle, help, filter, open-in-browser, and theme controls.
+- Palette search uses a small tiered scorer so empty queries stay in keymap order while typed queries rank stronger title and word-boundary matches.
+
+### Fixed
+
+- Reader scroll focus is suspended while overlays are open, preventing palette arrow navigation from scrolling the markdown pane behind the modal.
+
+### Tests
+
+- Added command-palette interaction coverage plus scroll regression checks.
+
 ## [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.
+- 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.
+- 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.
+- 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
 
-- **Project renamed from `openmdr` to `house`.** The npm package is now
-  `@carlesandres/house`; `@carlesandres/openmdr` is deprecated and will
-  not receive further releases. The CLI binary is now `house` (was
-  `openmdr`). The GitHub repository moved to
-  `https://github.com/carlesandres/house`; GitHub auto-redirects old
-  URLs and issue/PR numbers are preserved. The theme schema file moved
-  to `schema/house-theme.schema.json` and its `$id` is now a GitHub URL
-  on the new repo.
-- `/` is no longer reserved (DESIGN.md §7.3) — it now drives the filter
-  input.
+- **Project renamed from `openmdr` to `house`.** The npm package is now `@carlesandres/house`; `@carlesandres/openmdr` is deprecated and will not receive further releases. The CLI binary is now `house` (was `openmdr`). The GitHub repository moved to `https://github.com/carlesandres/house`; GitHub auto-redirects old URLs and issue/PR numbers are preserved. The theme schema file moved to `schema/house-theme.schema.json` and its `$id` is now a GitHub URL on the new repo.
+- `/` is no longer reserved (DESIGN.md §7.3) — it now drives the filter input.
 
 ### Added
 
-- `--sort <mode>` flag selecting the per-directory group order in the
-  sidebar. `dirs-first` (the existing default) keeps directories above
-  files; `files-first` flips it, surfacing top-level files like
-  `README.md` before nested subtrees.
-- `/` opens a filter input at the bottom of the sidebar. Typed
-  characters narrow the list with a fuzzy subsequence match on the
-  file's relative path; matches are re-ranked by score (word-boundary
-  and consecutive-character bonuses). Esc clears the query and closes
-  the filter; Return closes it and focuses the reader on the highlighted
-  match.
+- `--sort <mode>` flag selecting the per-directory group order in the sidebar. `dirs-first` (the existing default) keeps directories above files; `files-first` flips it, surfacing top-level files like `README.md` before nested subtrees.
+- `/` opens a filter input at the bottom of the sidebar. Typed characters narrow the list with a fuzzy subsequence match on the file's relative path; matches are re-ranked by score (word-boundary and consecutive-character bonuses). Esc clears the query and closes the filter; Return closes it and focuses the reader on the highlighted match.
 
 ## [0.2.1] — 2026-05-13
 
 ### Added
 
-- Footer hint row in the browser pane, generated from the keymap so the
-  visible hints stay in sync with the bindings.
-- `ROADMAP.md` as the single index of planned work; footer/header chrome
-  issues registered there.
+- Footer hint row in the browser pane, generated from the keymap so the visible hints stay in sync with the bindings.
+- `ROADMAP.md` as the single index of planned work; footer/header chrome issues registered there.
 
 ### Changed
 
 - Sidebar toggle rebound from `\` to `s`.
-- Help overlay: theme keys (`t` / `T` / `L`) now cycle while the overlay
-  is open; the help hint label switches to `close` while the overlay is
-  showing.
-- `DESIGN.md` §5.3 expanded with competitive-review gaps; keys reserved
-  for history and bookmarks.
+- Help overlay: theme keys (`t` / `T` / `L`) now cycle while the overlay is open; the help hint label switches to `close` while the overlay is showing.
+- `DESIGN.md` §5.3 expanded with competitive-review gaps; keys reserved for history and bookmarks.
 
 ### Fixed
 
@@ -99,42 +80,17 @@ Beta release gates (DESIGN §10.2) closed.
 
 ### Added — themes
 
-- **33 bundled JSON themes** selectable via `--theme <id>`: `aura`, `ayu`,
-  `carbonfox`, `catppuccin`, `catppuccin-frappe`, `catppuccin-macchiato`,
-  `cobalt2`, `cursor`, `dracula`, `everforest`, `flexoki`, `github`,
-  `gruvbox`, `kanagawa`, `lucent-orng`, `material`, `matrix`, `mercury`,
-  `monokai`, `nightowl`, `nord`, `one-dark`, `opencode`, `orng`,
-  `osaka-jade`, `palenight`, `rosepine`, `solarized`, `synthwave84`,
-  `tokyonight`, `vercel`, `vesper`, `zenburn`. Token values sourced
-  directly from each upstream's canonical palette via
-  `dev/build-themes.ts`.
-- **`--tone dark|light`** flag to select the variant of a theme. Defaults
-  to `dark`. Not all themes have a well-tuned light variant; quality is
-  best-effort for those.
-- **JSON theme format**: each theme is a `{defs, theme: {dark, light}}`
-  file validated against `schema/openmdr-theme.schema.json`. The format
-  mirrors opencode's TUI theme shape; `defs` supports variable
-  substitution.
-- **`dev/build-themes.ts`**: fetches themes from the opencode GitHub API,
-  strips diff tokens, resolves variables, and regenerates `src/theme/loader.ts`.
-  Supports `GITHUB_TOKEN` and `--dry-run`. Not shipped in the npm package.
-- **Runtime theme cycling**: press `t` / `T` to step forward / backward
-  through all themes without restarting. Press `L` (shift+l) to toggle
-  between dark and light tone. Works in both browser mode and single-file
-  mode. Theme changes take effect immediately; syntax highlighting
-  rebuilds with the new palette.
+- **33 bundled JSON themes** selectable via `--theme <id>`: `aura`, `ayu`, `carbonfox`, `catppuccin`, `catppuccin-frappe`, `catppuccin-macchiato`, `cobalt2`, `cursor`, `dracula`, `everforest`, `flexoki`, `github`, `gruvbox`, `kanagawa`, `lucent-orng`, `material`, `matrix`, `mercury`, `monokai`, `nightowl`, `nord`, `one-dark`, `opencode`, `orng`, `osaka-jade`, `palenight`, `rosepine`, `solarized`, `synthwave84`, `tokyonight`, `vercel`, `vesper`, `zenburn`. Token values sourced directly from each upstream's canonical palette via `dev/build-themes.ts`.
+- **`--tone dark|light`** flag to select the variant of a theme. Defaults to `dark`. Not all themes have a well-tuned light variant; quality is best-effort for those.
+- **JSON theme format**: each theme is a `{defs, theme: {dark, light}}` file validated against `schema/openmdr-theme.schema.json`. The format mirrors opencode's TUI theme shape; `defs` supports variable substitution.
+- **`dev/build-themes.ts`**: fetches themes from the opencode GitHub API, strips diff tokens, resolves variables, and regenerates `src/theme/loader.ts`. Supports `GITHUB_TOKEN` and `--dry-run`. Not shipped in the npm package.
+- **Runtime theme cycling**: press `t` / `T` to step forward / backward through all themes without restarting. Press `L` (shift+l) to toggle between dark and light tone. Works in both browser mode and single-file mode. Theme changes take effect immediately; syntax highlighting rebuilds with the new palette.
 
 ### Changed
 
-- Theme system replaced: derivation engine (`derive.ts`) and the 12
-  TS-value themes removed in favour of the JSON format above. The
-  `ColorPalette` interface is unchanged; existing consumers (`Browser`,
-  `App`, `HelpOverlay`) required no changes beyond the re-render wiring.
-- `--theme` default changed from `dark` to `opencode` (the opencode
-  project's own palette).
-- Effect Atoms (`@effect/atom-react`) wired for re-render signalling:
-  `themeAtom` holds `{ id, tone }`; `RegistryProvider` wraps both render
-  paths in `index.tsx`.
+- Theme system replaced: derivation engine (`derive.ts`) and the 12 TS-value themes removed in favour of the JSON format above. The `ColorPalette` interface is unchanged; existing consumers (`Browser`, `App`, `HelpOverlay`) required no changes beyond the re-render wiring.
+- `--theme` default changed from `dark` to `opencode` (the opencode project's own palette).
+- Effect Atoms (`@effect/atom-react`) wired for re-render signalling: `themeAtom` holds `{ id, tone }`; `RegistryProvider` wraps both render paths in `index.tsx`.
 
 ## [0.1.0] — 2026-05-10
 
@@ -142,17 +98,13 @@ The v1 MVP, published as `@carlesandres/openmdr` on npm.
 
 ### Added — TUI
 
-- Two-pane browser: sidebar + reader, with a focus model, sidebar
-  visibility toggle (`\`), and a `?` help overlay generated from the
-  bindings array.
+- Two-pane browser: sidebar + reader, with a focus model, sidebar visibility toggle (`\`), and a `?` help overlay generated from the bindings array.
 - Single-file mode when invoked on a file path.
-- Themes: dark + light as typed `ColorPalette` values, mutable singleton
-  consumer, selected via `--theme`.
+- Themes: dark + light as typed `ColorPalette` values, mutable singleton consumer, selected via `--theme`.
 
 ### Added — discovery
 
-- Recursive walk from the path argument (or cwd), `.md` / `.markdown` /
-  `.mdx` only.
+- Recursive walk from the path argument (or cwd), `.md` / `.markdown` / `.mdx` only.
 - Honors `.gitignore` (root + nested).
 - Hard-skips `node_modules`, `.git`, `.venv` (always, even with `--all`).
 - Does not follow symlinks.
@@ -163,49 +115,28 @@ The v1 MVP, published as `@carlesandres/openmdr` on npm.
 
 ### Added — keymap
 
-- `KeyBinding[]` with `id` / `description` / `keys` / `group` / optional
-  `when` / `run`. Single source for both `useKeyboard` dispatch and the
-  help overlay.
-- Bindings: `j`/`k` + arrows, shift-jump, page/half-page, `g`/`G`,
-  `return`/`l`/`→`, `escape`/`h`/`←`, `[`/`]`, `tab`, `\`, `?`,
-  `q`/`ctrl+c`. Reserved (not bound): `/`, `e`, `o`, `r`.
+- `KeyBinding[]` with `id` / `description` / `keys` / `group` / optional `when` / `run`. Single source for both `useKeyboard` dispatch and the help overlay.
+- Bindings: `j`/`k` + arrows, shift-jump, page/half-page, `g`/`G`, `return`/`l`/`→`, `escape`/`h`/`←`, `[`/`]`, `tab`, `\`, `?`, `q`/`ctrl+c`. Reserved (not bound): `/`, `e`, `o`, `r`.
 
 ### Added — release infra
 
-- Distribution as `@carlesandres/openmdr` on npm (Bun runtime required
-  on user's `PATH`, no compiled binary). Modeled on ghui.
-- `.github/workflows/ci.yml`: typecheck, lint, format:check, test,
-  and `npm pack --dry-run` on every push and PR.
-- `.github/workflows/publish.yml`: `release: published` triggers
-  `npm publish` via Trusted Publisher (OIDC, no token), with a
-  tag-vs-`package.json`-version assertion before publish.
+- Distribution as `@carlesandres/openmdr` on npm (Bun runtime required on user's `PATH`, no compiled binary). Modeled on ghui.
+- `.github/workflows/ci.yml`: typecheck, lint, format:check, test, and `npm pack --dry-run` on every push and PR.
+- `.github/workflows/publish.yml`: `release: published` triggers `npm publish` via Trusted Publisher (OIDC, no token), with a tag-vs-`package.json`-version assertion before publish.
 - `.oxfmtrc.json`: pinned formatting so `format:check` is meaningful.
 
 ### Added — docs
 
-- `DESIGN.md`: foundational design doc (13 sections; §3 non-goals,
-  §5.3 deferred, §7.3 reserved keys, §10 v2 gates, §12 deferred
-  patterns with triggers).
-- `README.md`, `CONTRIBUTING.md`, `AGENTS.md` (cookbook for AI
-  assistants), `LICENSE` (MIT).
-- Issue templates (bug + feature + blank), PR template. All
-  communication routes through GitHub issues.
+- `DESIGN.md`: foundational design doc (13 sections; §3 non-goals, §5.3 deferred, §7.3 reserved keys, §10 v2 gates, §12 deferred patterns with triggers).
+- `README.md`, `CONTRIBUTING.md`, `AGENTS.md` (cookbook for AI assistants), `LICENSE` (MIT).
+- Issue templates (bug + feature + blank), PR template. All communication routes through GitHub issues.
 
 ### Added — tests
 
-- 75 headless tests via `testRender` + `captureCharFrame` +
-  `mockInput`.
+- 75 headless tests via `testRender` + `captureCharFrame` + `mockInput`.
 
 ### Out of scope (deliberate, see DESIGN.md §3 / §5.3)
 
-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.3.0...HEAD
-[0.3.0]: https://github.com/carlesandres/house/compare/v0.2.1...v0.3.0
-[0.2.1]: https://github.com/carlesandres/house/compare/v0.2.0...v0.2.1
-[0.2.0]: https://github.com/carlesandres/house/compare/v0.1.0...v0.2.0
-[0.1.0]: https://github.com/carlesandres/house/releases/tag/v0.1.0
+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.1...HEAD [0.4.1]: https://github.com/carlesandres/house/compare/v0.4.0...v0.4.1 [0.4.0]: https://github.com/carlesandres/house/compare/v0.3.1...v0.4.0 [0.3.1]: https://github.com/carlesandres/house/compare/v0.3.0...v0.3.1 [0.3.0]: https://github.com/carlesandres/house/compare/v0.2.1...v0.3.0 [0.2.1]: https://github.com/carlesandres/house/compare/v0.2.0...v0.2.1 [0.2.0]: https://github.com/carlesandres/house/compare/v0.1.0...v0.2.0 [0.1.0]: https://github.com/carlesandres/house/releases/tag/v0.1.0

package/README.md

@@ -1,10 +1,18 @@
-# house
+# ⌂ house
 
-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.
+A terminal markdown reader and navigator — themable and configurable, with a keyboard-driven modern UI. Point it at a directory and browse its `.md` files without leaving the terminal.
 
 ![house demo](tape/house.gif)
 
+## Features
+
+- **30+ themes** with dark and light tones
+- **Responsive layout**
+- **Fuzzy search** across nested folders (`.gitignore`-aware)
+- **Command palette**
+- **Keyboard-driven**
+- **Open in browser**
+
 Requires [Bun](https://bun.sh) on `PATH`.
 
 ## Install
@@ -18,7 +26,7 @@ bun add -g @carlesandres/house
 ## Upgrade
 
 ```bash
-npm update -g @carlesandres/house
+npm i -g @carlesandres/house
 # or
 bun add -g @carlesandres/house
 ```
@@ -37,6 +45,32 @@ house [options] <path>
 |------|---------|-------------|
 | `--theme <name>` | `opencode` | Starting theme (see list below) |
 | `--tone dark\|light` | `dark` | Starting tone |
+| `--config-path` | — | Print the resolved config-file path and exit |
+
+## Configuration
+
+house reads optional defaults from a TOML file:
+
+```
+$XDG_CONFIG_HOME/house/config.toml   (defaults to ~/.config/house/config.toml)
+```
+
+Run `house --config-path` to print the exact location.
+
+```toml
+# ~/.config/house/config.toml
+theme = "tokyonight"
+tone  = "dark"
+```
+
+Precedence, highest to lowest:
+
+1. CLI flags (`--theme`, `--tone`)
+2. Env vars (`HOUSE_THEME`, `HOUSE_TONE`)
+3. Config file
+4. Built-in defaults (`opencode` / `dark`)
+
+The file is optional — a missing file is fine. Invalid keys, unknown themes, or malformed TOML fail loudly with a one-line error. Per-project config (`.house/config.toml`) and additional keys are deferred.
 
 ## Keys
 
@@ -78,15 +112,9 @@ house [options] <path>
 
 ## Themes
 
-33 built-in themes, all sourced from the
-[opencode](https://github.com/anomalyco/opencode) TUI palette:
+33 built-in themes, all sourced from the [opencode](https://github.com/anomalyco/opencode) TUI palette:
 
-`aura` · `ayu` · `carbonfox` · `catppuccin` · `catppuccin-frappe` ·
-`catppuccin-macchiato` · `cobalt2` · `cursor` · `dracula` · `everforest` ·
-`flexoki` · `github` · `gruvbox` · `kanagawa` · `lucent-orng` · `material` ·
-`matrix` · `mercury` · `monokai` · `nightowl` · `nord` · `one-dark` ·
-`opencode` · `orng` · `osaka-jade` · `palenight` · `rosepine` · `solarized` ·
-`synthwave84` · `tokyonight` · `vercel` · `vesper` · `zenburn`
+`aura` · `ayu` · `carbonfox` · `catppuccin` · `catppuccin-frappe` · `catppuccin-macchiato` · `cobalt2` · `cursor` · `dracula` · `everforest` · `flexoki` · `github` · `gruvbox` · `kanagawa` · `lucent-orng` · `material` · `matrix` · `mercury` · `monokai` · `nightowl` · `nord` · `one-dark` · `opencode` · `orng` · `osaka-jade` · `palenight` · `rosepine` · `solarized` · `synthwave84` · `tokyonight` · `vercel` · `vesper` · `zenburn`
 
 Each theme supports dark and light tones. Cycle with `t` / `T`; toggle tone with `L`.
 

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@carlesandres/house",
-	"version": "0.3.1",
+	"version": "0.4.1",
 	"description": "TUI-first markdown reader on opentui",
 	"type": "module",
 	"license": "MIT",
@@ -45,7 +45,8 @@
 		"format:check": "oxfmt --check src/",
 		"test": "bun test",
 		"build:themes": "bun run dev/build-themes.ts",
-		"repro:pty-codeblocks": "bun run dev/repro-pty-codeblocks.ts"
+		"repro:pty-codeblocks": "bun run dev/repro-pty-codeblocks.ts",
+		"prepare": "git config core.hooksPath .githooks 2>/dev/null || true"
 	},
 	"dependencies": {
 		"@effect/atom-react": "4.0.0-beta.59",