@carlesandres/house 0.4.5 → 0.4.7

package/CHANGELOG.md

@@ -6,6 +6,61 @@ The publish workflow (`.github/workflows/publish.yml`) runs on the `release: pub
 
 ## [Unreleased]
 
+## [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
+
+- Reader empty states now show one tip at a time and rotate through a relevance-ordered set of workflow hints.
+
+### Changed
+
+- Startup behavior now uses `--focus <sidebar|reader|filter>`, `HOUSE_FOCUS`, and TOML `focus = "..."`; the built-in startup default is now `filter`.
+- Active filter/status metadata now uses the secondary theme token, matching opencode's use of `secondary` for active contextual metadata.
+- UI theme consumers now use the opencode-aligned `primary` token directly for strong emphasis and selected foreground.
+- UI chrome no longer uses house-only aliases (`surface`, `selectedBg`, `selectedBgInactive`), and background/backgroundPanel are no longer reordered by luminance.
+- Sidebar filtering now ranks basename matches above folder-only matches and softly prefers current-folder files over deeper nested paths, while keeping empty-query tree order unchanged.
+
+### Fixed
+
+- Tabbing away from the sidebar filter now lands on the reader without dropping filter mode, and the next `Tab` restores focus to the filter input instead of the sidebar list.
+- Batched key input no longer clears active filter focus unexpectedly during tab cycling.
+
+### Docs
+
+- Added semantic token usage guidance for supported theme tokens.
+- DESIGN now documents the sidebar filter's basename-first, pure-function ranking model.
+
+### Tests
+
+- Added headless and PTY regression coverage for filter tab-cycle focus restoration.
+
 ## [0.4.5] — 2026-05-24
 
 ### Changed
@@ -26,7 +81,6 @@ The publish workflow (`.github/workflows/publish.yml`) runs on the `release: pub
 
 - Discovery visibility controls: new `--show <list>` CLI flag, `HOUSE_SHOW` env var, and TOML `show = ["..."]` config, replacing boolean discovery toggles with explicit categories (`hidden`, `gitignored`).
 - Session visibility toggle: `shift+a` flips discovery between the configured visibility set and showing all categories, preserving selection across the re-walk.
-- Launch-in-filter option: `--start-in-filter` CLI flag, `HOUSE_START_IN_FILTER` env var, and TOML `start_in_filter = true` open the sidebar filter prompt focused at startup.
 
 ### Changed
 
@@ -46,7 +100,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.
 
@@ -180,7 +234,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
 
@@ -203,7 +257,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.5...HEAD
+[Unreleased]: https://github.com/carlesandres/house/compare/v0.4.7...HEAD
+[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
 [0.4.3]: https://github.com/carlesandres/house/compare/v0.4.2...v0.4.3

package/README.md

@@ -57,10 +57,10 @@ house [options] <path>
 | `--show <list>` | `""` | Reveal normally-skipped entries; comma-separated subset of `hidden`, `gitignored`. Use `--show ""` to clear. |
 | `--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) |
 | `--port <N>` | OS-assigned | Port for `--serve` |
 | `--no-mdx` | off | Exclude `.mdx` files from discovery |
-| `--start-in-filter` | off | Open the sidebar filter prompt on launch so you can type a query immediately. Press Esc to dismiss. |
 | `--no-update-check` | off | Suppress the "newer version available" check (also via `NO_UPDATE_NOTIFIER=1`) |
 | `--config-path` | — | Print the resolved config-file path and exit |
 | `-h`, `--help` | — | Show help and exit |
@@ -82,19 +82,19 @@ theme = "tokyonight"
 tone  = "dark"
 mdx   = true
 show  = ["hidden", "gitignored"]
-start_in_filter = false
+focus = "filter"
 ```
 
-Supported keys: `theme`, `tone`, `mdx`, `show`, `start_in_filter`.
+Supported keys: `theme`, `tone`, `mdx`, `show`, `focus`.
 
 `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`, `--start-in-filter`)
-2. Env vars (`HOUSE_THEME`, `HOUSE_TONE`, `HOUSE_MDX`, `HOUSE_SHOW`, `HOUSE_START_IN_FILTER`)
+1. CLI flags (`--theme`, `--tone`, `--no-mdx`, `--show`, `--focus`)
+2. Env vars (`HOUSE_THEME`, `HOUSE_TONE`, `HOUSE_MDX`, `HOUSE_SHOW`, `HOUSE_FOCUS`)
 3. Config file
-4. Built-in defaults (`opencode` / `dark` / `mdx = true` / `show = []` / `start_in_filter = false`)
+4. Built-in defaults (`opencode` / `dark` / `mdx = true` / `show = []` / `focus = "filter"`)
 
 `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.
 
@@ -111,8 +111,8 @@ The file is optional — a missing file is fine. Invalid keys, unknown themes, o
 | `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 |
@@ -149,6 +149,9 @@ The file is optional — a missing file is fine. Invalid keys, unknown themes, o
 
 Each theme supports dark and light tones. Cycle with `t` / `T`; toggle tone with `L`.
 
+For the supported semantic theme tokens and their intended usage, see
+[DESIGN.md §7.5](https://github.com/carlesandres/house/blob/main/DESIGN.md#75-theming).
+
 ## Inspiration
 
 - [glow](https://github.com/charmbracelet/glow) — render markdown on the CLI, with pizzazz

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@carlesandres/house",
-	"version": "0.4.5",
+	"version": "0.4.7",
 	"description": "TUI-first markdown reader on opentui",
 	"type": "module",
 	"license": "MIT",
@@ -56,6 +56,7 @@
 		"@effect/atom-react": "4.0.0-beta.70",
 		"@opentui/core": "0.2.15",
 		"@opentui/react": "0.2.15",
+		"commander": "^14.0.3",
 		"effect": "4.0.0-beta.70",
 		"ignore": "^7.0.5",
 		"marked": "^18.0.4",