@carlesandres/house 0.4.7 → 0.4.9

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (31) hide show
  1. package/CHANGELOG.md +43 -4
  2. package/README.md +64 -53
  3. package/package.json +2 -1
  4. package/src/Browser.tsx +235 -160
  5. package/src/CommandPalette.tsx +78 -14
  6. package/src/Footer.tsx +44 -37
  7. package/src/Header.tsx +4 -1
  8. package/src/StatusPopover.tsx +189 -0
  9. package/src/cli/argv.ts +15 -12
  10. package/src/commands/buildCommands.ts +22 -33
  11. package/src/commands/score.ts +1 -1
  12. package/src/discovery/filter.ts +83 -23
  13. package/src/discovery/walk.ts +24 -15
  14. package/src/index.tsx +120 -170
  15. package/src/keymap/browser.ts +14 -20
  16. package/src/keymap/keymap.ts +4 -4
  17. package/src/layout/sidebarEmptyState.ts +7 -0
  18. package/src/layout/sidebarRow.ts +1 -1
  19. package/src/markdown/frontmatter.ts +62 -0
  20. package/src/theme/resolve.ts +1 -1
  21. package/src/theme/themes/aura.json +1 -1
  22. package/src/theme/themes/carbonfox.json +1 -1
  23. package/src/theme/themes/lucent-orng.json +4 -4
  24. package/src/theme/themes/nightowl.json +2 -2
  25. package/src/theme/themes/orng.json +2 -2
  26. package/src/theme/themes/solarized.json +6 -2
  27. package/src/theme/themes/vesper.json +2 -2
  28. package/src/tips.ts +0 -5
  29. package/src/update/check.ts +1 -1
  30. package/src/update/runtime.ts +1 -1
  31. package/src/HelpOverlay.tsx +0 -148
package/CHANGELOG.md CHANGED
@@ -6,6 +6,43 @@ The publish workflow (`.github/workflows/publish.yml`) runs on the `release: pub
6
6
 
7
7
  ## [Unreleased]
8
8
 
9
+ ## [0.4.9] — 2026-06-09
10
+
11
+ ### Fixed
12
+
13
+ - Sidebar rows now keep a tighter single-space filename/path gap, and footer hint width calculation better handles wide glyphs.
14
+
15
+ ### Changed
16
+
17
+ - Removed the experimental `--sort` option. The sidebar now consistently lists files before directories, so current-directory files appear before nested subtrees in the base list. This makes less-nested files naturally rank higher even without a search term. When a filter query is active the existing `filterFiles` / `rankFile` scoring (filename bias + strengthened depth penalties) still applies on top.
18
+
19
+ ### Docs
20
+
21
+ - Demo recording now lives in `recordings/record-demo.sh`, with docs and recorded assets updated to match the new capture flow.
22
+
23
+ ## [0.4.8] — 2026-06-02
24
+
25
+ ### Fixed
26
+
27
+ - Discovery scan failures now render short, user-facing footer status instead of raw Effect diagnostics.
28
+ - Partial discovery warnings now show a compact footer trigger that opens root-relative skipped-directory details.
29
+ - Sidebar empty states now distinguish empty roots from zero-match filters with specific copy.
30
+ - Pane frames stay neutral while selected sidebar rows remain highlighted even when the sidebar is inactive.
31
+
32
+ ### Docs
33
+
34
+ - Corrected usage docs and `--help` text: directory browsing is controlled by `--root` / `defaultRoot`; the positional path now seeds the initial browser filter query.
35
+ - Refreshed unified-browser docs, pruned shipped roadmap items, and updated demo tapes after the single Browser model landed.
36
+ - Added ADR 0001 documenting the decision to keep the current `marked`-based browser preview instead of adopting Streamdown for now.
37
+
38
+ ### Changed
39
+
40
+ - 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.
41
+
42
+ ### Tests
43
+
44
+ - Added reusable status popover coverage for parent-owned panels, long-line wrapping, and small-viewport clipping.
45
+
9
46
  ## [0.4.7] — 2026-05-27
10
47
 
11
48
  ### Added
@@ -128,7 +165,7 @@ The publish workflow (`.github/workflows/publish.yml`) runs on the `release: pub
128
165
 
129
166
  ### Added
130
167
 
131
- - 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.
168
+ - 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.
132
169
 
133
170
  ## [0.4.0] — 2026-05-21
134
171
 
@@ -161,7 +198,7 @@ Beta release gates (DESIGN §10.2) closed.
161
198
 
162
199
  ### Docs
163
200
 
164
- - README embeds a VHS-generated demo gif; `tape/` holds the source scripts.
201
+ - README embeds the recorded demo asset; `recordings/` holds the capture workflow.
165
202
  - `CONTRIBUTING.md` documents the `captureSpans()` / `MockTreeSitterClient` / `TestRecorder` testing patterns and the "before blaming `<markdown>`" stale-watcher debugging checklist.
166
203
 
167
204
  ## [0.3.0] — 2026-05-16
@@ -202,7 +239,7 @@ Beta release gates (DESIGN §10.2) closed.
202
239
  - **`--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.
203
240
  - **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.
204
241
  - **`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.
205
- - **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.
242
+ - **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.
206
243
 
207
244
  ### Changed
208
245
 
@@ -257,7 +294,9 @@ The v1 MVP, published as `@carlesandres/openmdr` on npm.
257
294
 
258
295
  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.
259
296
 
260
- [Unreleased]: https://github.com/carlesandres/house/compare/v0.4.7...HEAD
297
+ [Unreleased]: https://github.com/carlesandres/house/compare/v0.4.9...HEAD
298
+ [0.4.9]: https://github.com/carlesandres/house/compare/v0.4.8...v0.4.9
299
+ [0.4.8]: https://github.com/carlesandres/house/compare/v0.4.7...v0.4.8
261
300
  [0.4.7]: https://github.com/carlesandres/house/compare/v0.4.6...v0.4.7
262
301
  [0.4.6]: https://github.com/carlesandres/house/compare/v0.4.5...v0.4.6
263
302
  [0.4.5]: https://github.com/carlesandres/house/compare/v0.4.4...v0.4.5
package/README.md CHANGED
@@ -1,8 +1,8 @@
1
1
  # ⌂ house
2
2
 
3
- 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.
3
+ 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.
4
4
 
5
- ![house demo](tape/house.gif)
5
+ <video src="recordings/house-demo.mp4" controls muted loop playsinline></video>
6
6
 
7
7
  ## Features
8
8
 
@@ -42,29 +42,40 @@ bun add -g @carlesandres/house
42
42
  ## Usage
43
43
 
44
44
  ```
45
- house [options] <path>
45
+ house [query] [options]
46
46
  ```
47
47
 
48
- `<path>` can be a directory (walks for `.md`, `.markdown`, and `.mdx` files) or a single markdown file. Defaults to the current directory if omitted.
48
+ 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.
49
+
50
+ `[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.
51
+
52
+ Examples:
53
+
54
+ ```bash
55
+ house # browse the configured discovery root
56
+ house README.md # browse with README.md preloaded as the sidebar filter
57
+ house --root docs # browse docs/ as the discovery root
58
+ house --serve README.md
59
+ ```
49
60
 
50
61
  ### Options
51
62
 
52
- | Flag | Default | Description |
53
- |------|---------|-------------|
54
- | `--theme <name>` | `opencode` | Starting theme (see list below) |
55
- | `--tone dark\|light` | `dark` | Starting tone |
56
- | `--width <N>` | — | Cap rendered markdown width at N columns |
57
- | `--show <list>` | `""` | Reveal normally-skipped entries; comma-separated subset of `hidden`, `gitignored`. Use `--show ""` to clear. |
58
- | `--sort <mode>` | `dirs-first` | Sidebar order: `dirs-first` or `files-first` |
59
- | `--sidebar <mode>` | `auto` | Initial sidebar visibility: `auto`, `on`, or `off` |
60
- | `--focus <mode>` | `filter` | Startup focus: `sidebar`, `reader`, or `filter`. `filter` opens the sidebar filter prompt immediately. |
61
- | `--serve` | off | Serve the given file as HTML in the browser (skips TUI) |
62
- | `--port <N>` | OS-assigned | Port for `--serve` |
63
- | `--no-mdx` | off | Exclude `.mdx` files from discovery |
64
- | `--no-update-check` | off | Suppress the "newer version available" check (also via `NO_UPDATE_NOTIFIER=1`) |
65
- | `--config-path` | — | Print the resolved config-file path and exit |
66
- | `-h`, `--help` | — | Show help and exit |
67
- | `-v`, `--version` | — | Print version and exit |
63
+ | Flag | Default | Description |
64
+ | -------------------- | ----------------- | ------------------------------------------------------------------------------------------------------------ |
65
+ | `--theme <name>` | `opencode` | Starting theme (see list below) |
66
+ | `--tone dark\|light` | `dark` | Starting tone |
67
+ | `--width <N>` | — | Cap rendered markdown width at N columns |
68
+ | `--show <list>` | `""` | Reveal normally-skipped entries; comma-separated subset of `hidden`, `gitignored`. Use `--show ""` to clear. |
69
+ | `--root <dir>` | current directory | Discovery root to walk; overrides `defaultRoot` config/env |
70
+ | `--sidebar <mode>` | `auto` | Initial sidebar visibility: `auto`, `on`, or `off` |
71
+ | `--focus <mode>` | `filter` | Startup focus: `sidebar`, `reader`, or `filter`. `filter` opens the sidebar filter prompt immediately. |
72
+ | `--serve` | off | Serve the positional path as HTML in the browser (skips TUI) |
73
+ | `--port <N>` | OS-assigned | Port for `--serve` |
74
+ | `--no-mdx` | off | Exclude `.mdx` files from discovery |
75
+ | `--no-update-check` | off | Suppress the "newer version available" check (also via `NO_UPDATE_NOTIFIER=1`) |
76
+ | `--config-path` | — | Print the resolved config-file path and exit |
77
+ | `-h`, `--help` | — | Show help and exit |
78
+ | `-v`, `--version` | — | Print version and exit |
68
79
 
69
80
  ## Configuration
70
81
 
@@ -83,18 +94,19 @@ tone = "dark"
83
94
  mdx = true
84
95
  show = ["hidden", "gitignored"]
85
96
  focus = "filter"
97
+ defaultRoot = "cwd" # or "git"
86
98
  ```
87
99
 
88
- Supported keys: `theme`, `tone`, `mdx`, `show`, `focus`.
100
+ Supported keys: `theme`, `tone`, `mdx`, `show`, `focus`, `defaultRoot`.
89
101
 
90
102
  `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.
91
103
 
92
104
  Precedence, highest to lowest:
93
105
 
94
- 1. CLI flags (`--theme`, `--tone`, `--no-mdx`, `--show`, `--focus`)
95
- 2. Env vars (`HOUSE_THEME`, `HOUSE_TONE`, `HOUSE_MDX`, `HOUSE_SHOW`, `HOUSE_FOCUS`)
106
+ 1. CLI flags (`--theme`, `--tone`, `--no-mdx`, `--show`, `--focus`, `--root`)
107
+ 2. Env vars (`HOUSE_THEME`, `HOUSE_TONE`, `HOUSE_MDX`, `HOUSE_SHOW`, `HOUSE_FOCUS`, `HOUSE_DEFAULT_ROOT`)
96
108
  3. Config file
97
- 4. Built-in defaults (`opencode` / `dark` / `mdx = true` / `show = []` / `focus = "filter"`)
109
+ 4. Built-in defaults (`opencode` / `dark` / `mdx = true` / `show = []` / `focus = "filter"` / `defaultRoot = "cwd"`)
98
110
 
99
111
  `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.
100
112
 
@@ -104,42 +116,41 @@ The file is optional — a missing file is fine. Invalid keys, unknown themes, o
104
116
 
105
117
  ### Global
106
118
 
107
- | Key | Action |
108
- |-----|--------|
109
- | `q` / `ctrl+c` | Quit |
110
- | `tab` | Toggle focus (sidebar ↔ reader) |
111
- | `s` | Toggle sidebar visibility |
112
- | `?` | Show / dismiss help overlay |
113
- | `ctrl+p` | Command palette |
114
- | `O` | Open current file in browser as HTML |
115
- | `E` | Open current file in `$EDITOR` (`$VISUAL` takes precedence) |
116
- | `t` | Next theme |
117
- | `T` | Previous theme |
118
- | `L` | Toggle dark / light tone |
119
+ | Key | Action |
120
+ | -------------- | ----------------------------------------------------------- |
121
+ | `q` / `ctrl+c` | Quit |
122
+ | `tab` | Toggle focus (sidebar ↔ reader) |
123
+ | `s` | Toggle sidebar visibility |
124
+ | `ctrl+p` | Command palette |
125
+ | `O` | Open current file in browser as HTML |
126
+ | `E` | Open current file in `$EDITOR` (`$VISUAL` takes precedence) |
127
+ | `t` | Next theme |
128
+ | `T` | Previous theme |
129
+ | `L` | Toggle dark / light tone |
119
130
 
120
131
  ### Sidebar
121
132
 
122
- | Key | Action |
123
- |-----|--------|
124
- | `j` / `↓` | Move selection down |
125
- | `k` / `↑` | Move selection up |
126
- | `J` | Jump down 8 |
127
- | `K` | Jump up 8 |
128
- | `space` / `pagedown` / `ctrl+d` | Page down |
129
- | `b` / `pageup` / `ctrl+u` | Page up |
130
- | `g` | First file |
131
- | `G` | Last file |
132
- | `/` | Filter files (fuzzy match on path) |
133
- | `A` | Toggle hidden + gitignored entries (session-only; round-trips with the configured `show`) |
134
- | `↵` / `→` / `l` | Open file (focus reader) |
133
+ | Key | Action |
134
+ | ------------------------------- | ----------------------------------------------------------------------------------------- |
135
+ | `j` / `↓` | Move selection down |
136
+ | `k` / `↑` | Move selection up |
137
+ | `J` | Jump down 8 |
138
+ | `K` | Jump up 8 |
139
+ | `space` / `pagedown` / `ctrl+d` | Page down |
140
+ | `b` / `pageup` / `ctrl+u` | Page up |
141
+ | `g` | First file |
142
+ | `G` | Last file |
143
+ | `/` | Filter files (fuzzy match on path) |
144
+ | `A` | Toggle hidden + gitignored entries (session-only; round-trips with the configured `show`) |
145
+ | `↵` / `→` / `l` | Open file (focus reader) |
135
146
 
136
147
  ### Reader
137
148
 
138
- | Key | Action |
139
- |-----|--------|
149
+ | Key | Action |
150
+ | ----------------- | --------------- |
140
151
  | `esc` / `←` / `h` | Back to sidebar |
141
- | `[` | Previous file |
142
- | `]` | Next file |
152
+ | `[` | Previous file |
153
+ | `]` | Next file |
143
154
 
144
155
  ## Themes
145
156
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@carlesandres/house",
3
- "version": "0.4.7",
3
+ "version": "0.4.9",
4
4
  "description": "TUI-first markdown reader on opentui",
5
5
  "type": "module",
6
6
  "license": "MIT",
@@ -42,6 +42,7 @@
42
42
  "scripts": {
43
43
  "dev": "bun --watch src/index.tsx",
44
44
  "start": "bun run src/index.tsx",
45
+ "record-demo": "bash recordings/record-demo.sh",
45
46
  "typecheck": "tsc --noEmit",
46
47
  "lint": "oxlint --tsconfig tsconfig.json src/",
47
48
  "format": "oxfmt src/",