@carlesandres/house 0.4.6 → 0.4.8

package/CHANGELOG.md

@@ -6,6 +6,56 @@ The publish workflow (`.github/workflows/publish.yml`) runs on the `release: pub
 
 ## [Unreleased]
 
+## [0.4.8] — 2026-06-02
+
+### Fixed
+
+- Discovery scan failures now render short, user-facing footer status instead of raw Effect diagnostics.
+- Partial discovery warnings now show a compact footer trigger that opens root-relative skipped-directory details.
+- Sidebar empty states now distinguish empty roots from zero-match filters with specific copy.
+- Pane frames stay neutral while selected sidebar rows remain highlighted even when the sidebar is inactive.
+
+### Docs
+
+- Corrected usage docs and `--help` text: directory browsing is controlled by `--root` / `defaultRoot`; the positional path now seeds the initial browser filter query.
+- Refreshed unified-browser docs, roadmap state, and demo tapes after the single Browser model landed.
+- Added ADR 0001 documenting the decision to keep the current `marked`-based browser preview instead of adopting Streamdown for now.
+
+### Changed
+
+- Removed the separate file-target launch path: non-serve launches always open the browser over the discovery root, with any positional path applied as the initial sidebar filter.
+
+### Tests
+
+- Added reusable status popover coverage for parent-owned panels, long-line wrapping, and small-viewport clipping.
+
+## [0.4.7] — 2026-05-27
+
+### Added
+
+- `--root <path>` and TOML `defaultRoot` let launches default to a configured browsing root while preserving explicit path arguments.
+- Discovery/indexing status now shows a spinner in the chrome instead of only static text.
+
+### Changed
+
+- File actions now use uppercase `E` / `O` instead of lowercase `e` / `o`, adding a small amount of friction to edit and open-in-browser actions.
+- Sidebar filtering now applies after a short debounce to reduce churn while typing.
+- Filtered browsing now keeps the first match sticky/selected as results update.
+
+### Fixed
+
+- PTY typing coverage and footer hint tests now match the shifted file-action bindings.
+- CI typechecking now satisfies exact optional prop typing in the release branch.
+
+### Docs
+
+- Removed the obsolete `CONTEXT.md` glossary and inlined the beta-term explanation into `DESIGN.md` with cleaned-up cross-references.
+- ROADMAP shipped items were pruned after the covered work landed.
+
+### Tests
+
+- Browser test noise from React act warnings was reduced around the new filter behavior coverage.
+
 ## [0.4.6] — 2026-05-25
 
 ### Added
@@ -73,7 +123,7 @@ The publish workflow (`.github/workflows/publish.yml`) runs on the `release: pub
 
 ### Added
 
-- Editor hand-off: press `e` to open the selected file in `$EDITOR`/`$VISUAL` (`#19`).
+- Editor hand-off: press `E` to open the selected file in `$EDITOR`/`$VISUAL` (`#19`).
 - Sidebar rows now render basename-first with segment-aware parent-path elision, improving scanability in deep trees.
 - `ctrl+\\` clears an active sidebar filter query without leaving filter mode.
 
@@ -101,7 +151,7 @@ The publish workflow (`.github/workflows/publish.yml`) runs on the `release: pub
 
 ### 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.
+- Header chrome: borderless one-row identity strip above the panes carries the ⌂ brand mark and running version. Renders in the Browser UI for both directory and named-file launches. Hidden on terminals shorter than 20 rows so tight panes keep the reader breathable.
 
 ## [0.4.0] — 2026-05-21
 
@@ -175,7 +225,7 @@ Beta release gates (DESIGN §10.2) closed.
 - **`--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.
+- **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 the Browser UI for both directory and named-file launches. Theme changes take effect immediately; syntax highlighting rebuilds with the new palette.
 
 ### Changed
 
@@ -207,7 +257,7 @@ 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`.
+- Bindings: `j`/`k` + arrows, shift-jump, page/half-page, `g`/`G`, `return`/`l`/`→`, `escape`/`h`/`←`, `[`/`]`, `tab`, `\`, `?`, `q`/`ctrl+c`. Reserved (not bound): `/`, `r`.
 
 ### Added — release infra
 
@@ -230,7 +280,9 @@ 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.6...HEAD
+[Unreleased]: https://github.com/carlesandres/house/compare/v0.4.8...HEAD
+[0.4.8]: https://github.com/carlesandres/house/compare/v0.4.7...v0.4.8
+[0.4.7]: https://github.com/carlesandres/house/compare/v0.4.6...v0.4.7
 [0.4.6]: https://github.com/carlesandres/house/compare/v0.4.5...v0.4.6
 [0.4.5]: https://github.com/carlesandres/house/compare/v0.4.4...v0.4.5
 [0.4.4]: https://github.com/carlesandres/house/compare/v0.4.3...v0.4.4

package/README.md

@@ -1,6 +1,6 @@
 # ⌂ house
 
-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.
+A terminal markdown reader and navigator — themable and configurable, with a keyboard-driven modern UI. Browse a directory of `.md` files without leaving the terminal.
 
 ![house demo](tape/house.gif)
 
@@ -42,10 +42,21 @@ bun add -g @carlesandres/house
 ## Usage
 
 ```
-house [options] <path>
+house [query] [options]
 ```
 
-`<path>` can be a directory (walks for `.md`, `.markdown`, and `.mdx` files) or a single markdown file. Defaults to the current directory if omitted.
+By default, `house` opens the browser over the configured discovery root: the current directory, or the git root when `defaultRoot = "git"` is configured. Use `--root <dir>` to browse a specific directory.
+
+`[query]` seeds the initial sidebar filter query. It can be a filename, a relative path, or any path fragment you want to match. It does **not** set the discovery root; use `--root <dir>` for that.
+
+Examples:
+
+```bash
+house                  # browse the configured discovery root
+house README.md        # browse with README.md preloaded as the sidebar filter
+house --root docs      # browse docs/ as the discovery root
+house --serve README.md
+```
 
 ### Options
 
@@ -55,10 +66,11 @@ house [options] <path>
 | `--tone dark\|light` | `dark` | Starting tone |
 | `--width <N>` | — | Cap rendered markdown width at N columns |
 | `--show <list>` | `""` | Reveal normally-skipped entries; comma-separated subset of `hidden`, `gitignored`. Use `--show ""` to clear. |
+| `--root <dir>` | current directory | Discovery root to walk; overrides `defaultRoot` config/env |
 | `--sort <mode>` | `dirs-first` | Sidebar order: `dirs-first` or `files-first` |
 | `--sidebar <mode>` | `auto` | Initial sidebar visibility: `auto`, `on`, or `off` |
 | `--focus <mode>` | `filter` | Startup focus: `sidebar`, `reader`, or `filter`. `filter` opens the sidebar filter prompt immediately. |
-| `--serve` | off | Serve the given file as HTML in the browser (skips TUI) |
+| `--serve` | off | Serve the positional path as HTML in the browser (skips TUI) |
 | `--port <N>` | OS-assigned | Port for `--serve` |
 | `--no-mdx` | off | Exclude `.mdx` files from discovery |
 | `--no-update-check` | off | Suppress the "newer version available" check (also via `NO_UPDATE_NOTIFIER=1`) |
@@ -83,18 +95,19 @@ tone  = "dark"
 mdx   = true
 show  = ["hidden", "gitignored"]
 focus = "filter"
+defaultRoot = "cwd" # or "git"
 ```
 
-Supported keys: `theme`, `tone`, `mdx`, `show`, `focus`.
+Supported keys: `theme`, `tone`, `mdx`, `show`, `focus`, `defaultRoot`.
 
 `show` is a list of normally-skipped categories to opt into. Known categories: `hidden` (dot-prefixed entries), `gitignored` (entries matched by a `.gitignore`). Default is the empty list. Hard skips (`node_modules`, `.git`, `.venv`) always apply.
 
 Precedence, highest to lowest:
 
-1. CLI flags (`--theme`, `--tone`, `--no-mdx`, `--show`, `--focus`)
-2. Env vars (`HOUSE_THEME`, `HOUSE_TONE`, `HOUSE_MDX`, `HOUSE_SHOW`, `HOUSE_FOCUS`)
+1. CLI flags (`--theme`, `--tone`, `--no-mdx`, `--show`, `--focus`, `--root`)
+2. Env vars (`HOUSE_THEME`, `HOUSE_TONE`, `HOUSE_MDX`, `HOUSE_SHOW`, `HOUSE_FOCUS`, `HOUSE_DEFAULT_ROOT`)
 3. Config file
-4. Built-in defaults (`opencode` / `dark` / `mdx = true` / `show = []` / `focus = "filter"`)
+4. Built-in defaults (`opencode` / `dark` / `mdx = true` / `show = []` / `focus = "filter"` / `defaultRoot = "cwd"`)
 
 `HOUSE_SHOW` takes a comma-separated list (`HOUSE_SHOW=hidden,gitignored`). For `show` specifically, each source completely replaces the next — categories don't merge across layers. Press `shift+a` in the TUI to round-trip between the configured set and the full vocabulary without editing config.
 
@@ -109,10 +122,9 @@ The file is optional — a missing file is fine. Invalid keys, unknown themes, o
 | `q` / `ctrl+c` | Quit |
 | `tab` | Toggle focus (sidebar ↔ reader) |
 | `s` | Toggle sidebar visibility |
-| `?` | Show / dismiss help overlay |
 | `ctrl+p` | Command palette |
-| `o` | Open current file in browser as HTML |
-| `e` | Open current file in `$EDITOR` (`$VISUAL` takes precedence) |
+| `O` | Open current file in browser as HTML |
+| `E` | Open current file in `$EDITOR` (`$VISUAL` takes precedence) |
 | `t` | Next theme |
 | `T` | Previous theme |
 | `L` | Toggle dark / light tone |

package/package.json

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