pi-vim-tree 0.1.1 → 0.1.2

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.
package/CHANGELOG.md CHANGED
@@ -1,5 +1,14 @@
1
1
  # Changelog
2
2
 
3
+ ## [0.1.2] - 2026-11-20
4
+
5
+ - **The scroll keys moved.** `ctrl+f` / `ctrl+b` / `ctrl+u` / `ctrl+d` now scroll the side preview and nothing else; list paging is `f` / `b` (whole page) and `u` / `d` (half page). The four control keys belong to the preview the way they belong to the help window in Vim or `less`: when the preview is closed, too narrow to render, or its body fits on one screen, they do nothing. They never fall back to the list, and they never reach Pi's native keys underneath.
6
+ - The tree can be closed with the key that opened it. In the tree, `app.session.tree` closes it - whatever `keybindings.json` binds that action to. The key is read through Pi's `KeybindingsManager`, not hardcoded, so `/reload` and a changed binding are picked up. It is unbound by default, so nothing happens until you bind it; on terminals where `ctrl+i` and Tab are the same byte, binding it to `ctrl+i` makes Tab close the tree too.
7
+ - The filter mode (`gt` / `gl` / `gu` / `ga` / `gd`) is remembered. Pi only passes `treeFilterMode` in when the tree opens and never writes back a mode picked inside the tree, so the extension records it: in memory for the session, and in `vim-tree.json` in the agent directory across launches. Changing `treeFilterMode` in `/settings` takes precedence and resyncs the memory, so the setting never gets shadowed.
8
+ - The mouse wheel scrolls what is under it: over the preview panel it scrolls the preview by whole lines, over Pi's tree panel it moves the list cursor (row by row, like `j` / `k`). Over the preview panel it falls back to the tree when the preview cannot scroll. Only `wheel` is taken over - clicks and drags still go to Pi, and the label editor keeps every event while it is open.
9
+ - Two loaded copies of the extension no longer fight over the patch: the copy that loaded last owns it, and `/vim-tree off` on a stale copy only disables that copy instead of restoring native methods under the active one. This is the `/vim-tree:1` / `/vim-tree:2` case - Pi appends `:1` / `:2` when the same command name is registered twice. `/vim-tree` now warns when it detects another loaded copy, and the test suite loads two copies on purpose to check it.
10
+ - The README explains the two ways to load the extension while working - `pi -e` for a single run, or the auto-discovered extensions directory (or an `extensions` entry in settings) for `/reload` - and what the `[u]` / `[p]` / `[t]` scope tags next to extension commands mean. It also opens with one table of the everyday keys - Pi's tree panel and the preview panel side by side - and documents the remembered filter mode, the wheel, and that a stray `npm install` replaces the links `test/setup.sh` creates.
11
+
3
12
  ## [0.1.1] - 2026-11-16
4
13
 
5
14
  - The preview pane now renders the selected entry with Pi's own `Markdown` component and `getMarkdownTheme()`, so headings, lists, quotes and fenced code blocks look like they do in the conversation, including syntax highlighting. It follows the active theme, custom themes included, and adds no new dependency: the renderer and highlight.js come from Pi itself.
package/README.md CHANGED
@@ -1,99 +1,67 @@
1
- > Pi can create extensions. Ask it to build one for your use case.
2
-
3
1
  # pi-vim-tree
4
2
 
5
- A Vim-flavoured patch for Pi's built-in `/tree` view. It adds Vim-style folding, motion, and status feedback on top of the native tree, and hands everything else back to Pi unchanged.
6
-
7
- The extension patches the native tree in place. It never replaces `/tree`, never changes what the tree contains, and can be turned off at runtime to restore the original behaviour exactly.
8
-
9
- **Key capabilities:**
10
- - **Vim folding** - `zc`/`zo`/`za`/`zC`/`zO`/`zA`/`zm`/`zr`/`zM`/`zR`/`zj`/`zk`/`zv` with Vim's semantics
11
- - **Stable line numbers** - folding never renumbers rows, so `G`, `{n}G`, `gg`, and `%` always mean the same row
12
- - **Logical cursor row** - folding hides the row under the cursor but keeps its place, and restores it when the fold opens again
13
- - **Jump list** - `ctrl+o` and `ctrl+i` walk backwards and forwards through your jumps, the way Vim's jump list does
14
- - **Marks** - `m` plus a letter or digit sets a mark, backtick plus the same name jumps back to it
15
- - **Showcmd status bar** - pending prefixes and executed commands echo the way Vim's `showcmd` does
16
- - **Fixed-height layout** - the list never resizes, so filtering or folding never makes the panel jump
17
- - **Side preview** - the selected message body is shown next to the tree, rendered as Markdown with syntax highlighting, fzf `--preview-window` style
18
-
19
- **Example use cases:**
20
- - Navigating long sessions without losing your place
21
- - Collapsing noisy branches while keeping jump targets stable
22
- - Reaching a collapsed branch with a single keystroke (`zA`, `zv`)
23
- - Working with the tree in a fixed-size panel inside larger terminal layouts
24
-
25
- ## Table of Contents
26
-
27
- - [Installation](#installation)
28
- - [Requirements](#requirements)
29
- - [Commands](#commands)
30
- - [Key Bindings](#key-bindings)
31
- - [Folding](#folding)
32
- - [Motion](#motion)
33
- - [Search](#search)
34
- - [Preview](#preview)
35
- - [Folding Model](#folding-model)
36
- - [Line Numbers and Jumps](#line-numbers-and-jumps)
37
- - [Logical Cursor Row](#logical-cursor-row)
38
- - [Marks](#marks)
39
- - [Jump List](#jump-list)
40
- - [Status Bar](#status-bar)
41
- - [Layout](#layout)
42
- - [Compatibility](#compatibility)
43
- - [Troubleshooting](#troubleshooting)
44
- - [Differences from Vim](#differences-from-vim)
45
- - [Development](#development)
46
-
47
- ## Installation
48
-
49
- Install it as a Pi package:
3
+ Vim folding, motion, jump list, marks and a Markdown preview for Pi's built-in `/tree`.
50
4
 
51
- ```bash
52
- pi install npm:pi-vim-tree
53
- ```
5
+ It patches the native tree in place - same rows, same search, same actions - and puts Vim keys on top. Nothing is replaced, and `/vim-tree off` restores native behaviour exactly.
6
+
7
+ **Two panels: Pi's default tree list, and a preview of the selected message.**
8
+
9
+ ## Everyday Keys
10
+
11
+ The list panel is Pi's own `/tree` - every kind of entry appears there: user message, reply, tool call. The preview panel is added by this extension and shows the full content of the row under the cursor, rendered as Markdown.
12
+
13
+ | I want to | Tree panel (left) - Pi's `/tree` list | Preview panel (right) - the selected message |
14
+ | --- | --- | --- |
15
+ | Move | `j` / `k` - or the wheel | `ctrl+e` / `ctrl+y` line · `ctrl+u` / `ctrl+d` half page · `ctrl+f` / `ctrl+b` page - or the wheel |
16
+ | Switch branch | **`h` / `l`** (previous / next branch head, wraps) · also `ctrl+j` / `ctrl+k`, `shift+up` / `shift+down` | - |
17
+ | Jump by number | `{n}G` row `n` · `G` last · `gg` first · `%` matching branch · `g0` my branch | - |
18
+ | Come back | `ctrl+o` / `ctrl+i` - the jump list, Vim's | - |
19
+ | Park a spot | `m` + a letter, back with `` ` `` + the same letter | - |
20
+ | Label a row | `L` edit its label · `T` show / hide label timestamps | - |
21
+ | Wipe bookkeeping | `J` clears the jump list · `M` clears all marks | - |
22
+ | Fold noise away | `za` toggle · `zc` / `zo` close / open · `zM` / `zR` all · `zv` reveal the cursor row | - |
23
+ | Thin the tree out | `gt` / `gl` / `gu` / `ga` / `gd` filters (remembered) | - |
24
+ | Find something | `/` then `n` / `N` (or `p`) | - |
25
+ | Leave | `q`, or your `app.session.tree` key | - |
54
26
 
55
- Or try it for a single run without adding it to your settings:
27
+ Learn `h` / `l` first: branch heads are the only structure a tree has, so hopping them does what `w` / `b` does in text - and every hop lands in the jump list, so `ctrl+o` walks you back through the branches you visited.
28
+
29
+ ## Contents
30
+
31
+ [Install](#install) · [Requirements](#requirements) · [Commands](#commands) · [Keys](#keys) · [Behaviour](#behaviour) · [Compatibility](#compatibility) · [Troubleshooting](#troubleshooting) · [Differences from Vim](#differences-from-vim) · [Releasing](#releasing) · [Development](#development)
32
+
33
+ ## Install
56
34
 
57
35
  ```bash
58
- pi -e npm:pi-vim-tree
36
+ pi install npm:pi-vim-tree
59
37
  ```
60
38
 
61
- Without npm, copy `extensions/vim-tree.ts` into Pi's global extension directory:
39
+ One-off run, or without npm at all:
62
40
 
63
41
  ```bash
64
- mkdir -p ~/.pi/agent/extensions
65
- cp extensions/vim-tree.ts ~/.pi/agent/extensions/vim-tree.ts
42
+ pi -e npm:pi-vim-tree
43
+ mkdir -p ~/.pi/agent/extensions && cp extensions/vim-tree.ts ~/.pi/agent/extensions/
66
44
  ```
67
45
 
68
- Restart Pi, or hot-reload the extension with `/reload`. Extensions in `~/.pi/agent/extensions/` are auto-discovered and can be reloaded without restarting the session.
69
-
70
- To disable the patch at startup, set `PI_VIM_TREE=0` in the environment. Pi then loads the extension but applies nothing.
46
+ `/reload` hot-reloads; files in `~/.pi/agent/extensions/` are auto-discovered. `PI_VIM_TREE=0` loads the extension but applies nothing.
71
47
 
72
48
  ## Requirements
73
49
 
74
- Pi 1.5.1 or newer. The extension works by patching Pi's internal tree component, so it needs access to those internals - it locates them by content rather than by file name, because the bundle's chunk names change with every release.
75
-
76
- When Pi changes the internals in a way the extension does not recognise, it stays silent and leaves the native tree alone. `/vim-tree` then reports why.
77
-
78
- Node.js 22.19 or newer, same as Pi itself. The extension adds no runtime dependencies.
50
+ Pi 1.5.1+, Node 22.19+. The patch targets Pi's internal tree classes inside the compiled bundle. Chunk names change every release (`chunk-44DLKSKE.js` in 1.5.0, `chunk-ZKNSXGL5.js` in 1.5.1), so the chunk is found by content, not by file name. If the internals change shape, nothing is patched, the native tree keeps working, and `/vim-tree` reports why. No runtime dependencies.
79
51
 
80
52
  ## Commands
81
53
 
82
- | Command | Description |
54
+ | Command | Effect |
83
55
  | --- | --- |
84
- | `/vim-tree` | Report the current state (on/off, build id, and the reason if the patch could not be applied) |
85
- | `/vim-tree on` | Apply the patch to `/tree` |
86
- | `/vim-tree off` | Remove every patch and restore native behaviour |
56
+ | `/vim-tree` | State, build id, and the reason if the patch could not be applied |
57
+ | `/vim-tree on` | Apply the patch |
58
+ | `/vim-tree off` | Undo every patch |
87
59
 
88
- `off` is a full undo: each patched method is registered in an undo registry and reverted in reverse order, including the tree instance's filter handling and the search state.
60
+ `off` is a full undo: patched methods are reverted in reverse order, and the tree instance gets its original height, filter mode, fold state and label-timestamp flag back. While the label editor is open the extension steps aside and hands every key to Pi.
89
61
 
90
- The tree *instance* is restored as well. While it is active the extension changes the list height, the filter mode, the fold state and the label-timestamp flag - all of them native fields - so `off` puts the original values back, clears the search box and resets the mode. Without that the native tree would come back with the wrong number of rows, a filter still applied, or folds left over.
62
+ ## Keys
91
63
 
92
- While the label editor is open, the extension steps aside completely and hands every key to Pi, so labels are typed exactly the way Pi types them.
93
-
94
- ## Key Bindings
95
-
96
- Native tree keys (`j`/`k`, `enter`, `L` label, `T` label time, `/` search) keep working. Label and label time are on the uppercase keys only - lowercase `l` is branch motion now, and lowercase `t` is unbound. The extension adds:
64
+ Native keys (`j` / `k`, `enter`, `/`, `L`, `T`) keep working. Lowercase `l` is branch motion and `t` is unbound, which is why label and label time live on the uppercase keys.
97
65
 
98
66
  ### Folding
99
67
 
@@ -124,17 +92,27 @@ Native tree keys (`j`/`k`, `enter`, `L` label, `T` label time, `/` search) keep
124
92
  | `G` / `{n}G` | Jump to the last row / to row `{n}` |
125
93
  | `%` | Jump to the matching branch |
126
94
  | `gt` / `gl` / `gu` / `ga` / `gd` | Filter: no tools / labelled only / user only / all / default |
127
- | `ctrl+f` / `ctrl+b` | Page down / up |
95
+ | `f` / `b` | Page down / up |
128
96
  | `u` / `d` | Half page up / down |
129
- | `ctrl+u` / `ctrl+d` | Half page up / down (same as `u` / `d`) |
130
97
 
131
- ### Leaving
98
+ List paging is the lowercase `f` / `b` / `u` / `d` group; `ctrl+f` / `ctrl+b` / `ctrl+u` / `ctrl+d` belong to the preview.
99
+
100
+ ### Preview
132
101
 
133
102
  | Key | Action |
134
103
  | --- | --- |
135
- | `q` | Close the tree (like `q` in a Vim help/preview window, or in `less` / `fzf`) |
104
+ | `ctrl+h` (or `F4`) | Toggle the side preview |
105
+ | `ctrl+e` / `ctrl+y` | Scroll the preview by one line |
106
+ | `ctrl+u` / `ctrl+d` | Scroll the preview by half a page |
107
+ | `ctrl+f` / `ctrl+b` | Scroll the preview by a whole page |
108
+
109
+ The body is rendered with Pi's own `Markdown` component and `getMarkdownTheme()`, so headings, lists, quotes and code blocks look like the conversation, syntax highlighting included. It borrows the active theme; without one it falls back to plain wrapped text.
110
+
111
+ Those four control keys belong to the preview and nothing else. Closed, too narrow, or a body that fits on one screen - they do nothing: no fallback to the list, no leak to Pi's native keys.
136
112
 
137
- `esc` keeps its native meaning (cancel the search box, otherwise leave the tree) - nothing is layered on top of it. Clearing a pending command or the search highlight is `ctrl+l`'s job, matching the `ctrl+l` mapping people already have in Vim.
113
+ ### Mouse
114
+
115
+ Only the wheel is taken over: over the preview panel it scrolls the preview by lines, over the tree panel it moves the cursor row by row (like repeated `j` / `k`, never a screen jump). Over the preview panel it falls back to the tree when the preview cannot scroll. Clicks and drags are Pi's; the label editor keeps every event.
138
116
 
139
117
  ### Search
140
118
 
@@ -145,184 +123,186 @@ Native tree keys (`j`/`k`, `enter`, `L` label, `T` label time, `/` search) keep
145
123
  | `p` | Previous match |
146
124
  | `ctrl+l` | Clear the search term and the highlight |
147
125
 
148
- ### Preview
126
+ ### Leaving
149
127
 
150
128
  | Key | Action |
151
129
  | --- | --- |
152
- | `ctrl+h` (or `F4`) | Toggle the side preview |
153
- | `ctrl+e` / `ctrl+y` | Scroll the preview by one line |
130
+ | `q` | Close the tree (like `q` in a Vim help window, or in `less` / `fzf`) |
131
+ | your `app.session.tree` key | Close the tree - the key that opened it closes it, so the binding toggles |
154
132
 
155
- The body is rendered with Pi's own `Markdown` component and `getMarkdownTheme()`, so headings, lists, quotes and fenced code blocks look exactly like they do in the conversation - including syntax highlighting (same theme tokens, same highlight.js grammars, custom themes included). It scrolls as a one-line window over the rendered lines: `ctrl+e` / `ctrl+y`. `ctrl+d` / `ctrl+u` (and `d` / `u`) move the list cursor by half a page instead.
133
+ The toggle key is whatever `keybindings.json` binds `app.session.tree` to, read through Pi's `KeybindingsManager` - not hardcoded. It is unbound by default, so nothing happens until you bind it:
156
134
 
157
- The preview needs no theme of its own: it borrows the active one. If the theme is unavailable, it falls back to plain wrapped text; search-term highlighting is only applied in that fallback, because recolouring Markdown lines would corrupt their ANSI styling. The tree rows still mark the matches either way.
135
+ ```json
136
+ { "app.session.tree": ["ctrl+shift+t"] }
137
+ ```
158
138
 
159
- ## Folding Model
139
+ On terminals where `ctrl+i` and Tab are the same byte, binding it to `ctrl+i` makes Tab close the tree too. `esc` keeps its native meaning (cancel the search box, otherwise leave the tree).
160
140
 
161
- Pi's native tree marks the rows that can be folded with `⊟`, and shows `⊞` once a fold is closed. pi-vim-tree folds exactly those rows, and nothing else:
141
+ ### Filters
162
142
 
163
- - Only branch points fold. Leaf rows and the root row have no fold marker, so they never fold.
164
- - A fold closes the whole subtree below the row.
165
- - `zm` and `zr` work on *levels*, not on individual rows. Levels are numbered consecutively (like Vim's `foldlevel`) because Pi's own indent only increments at branch points, which would otherwise produce a `1 -> 3 -> 5` sequence.
143
+ The mode you pick with `gt` / `gl` / `gu` / `ga` / `gd` is remembered: in memory for the session, and in `vim-tree.json` in the agent directory (`~/.pi/agent/vim-tree.json` unless `PI_CODING_AGENT_DIR` says otherwise) across launches. Pi passes `treeFilterMode` in when the tree opens and never writes back a mode picked inside, so the extension records it.
166
144
 
167
- The current level and the total number of levels are shown in the title bar:
145
+ Changing `treeFilterMode` in `/settings` wins - that value becomes the new baseline and the memory is resynced to it, so the setting is never shadowed. Deleting `vim-tree.json` resets the memory to the setting.
168
146
 
169
- ```
170
- Session Tree Fold 2/5 · Match 1/3
171
- ```
147
+ ## Behaviour
172
148
 
173
- ## Line Numbers and Jumps
149
+ ### Folds
174
150
 
175
- Line numbers are computed against the **unfolded** list, the way Vim counts buffer lines. Folding a branch hides the rows inside it and leaves their numbers blank; it never renumbers the rows below.
151
+ Pi marks foldable rows with `⊟`, `⊞` once closed. pi-vim-tree folds exactly those rows and nothing else.
176
152
 
177
- Because of that, every jump command resolves against the same fixed list:
153
+ - Only branch points fold - leaf rows and the root have no marker.
154
+ - A fold closes the whole subtree below it.
155
+ - `zm` / `zr` step *levels*, numbered consecutively like Vim's `foldlevel` (Pi's indent only increments at branch points, which would give `1 -> 3 -> 5`). The current level and the total live in the title bar: `Session Tree Fold 2/5`.
178
156
 
179
- - `G` and `{n}G` jump to an absolute row number
180
- - `gg` jumps to the first row
181
- - `%` jumps to the matching branch
157
+ ### Line Numbers
182
158
 
183
- If the target row is hidden inside a fold, the fold is opened first and the jump lands on the row itself. `g0` follows the same rule.
159
+ Numbers are computed against the **unfolded** list, the way Vim counts buffer lines. Folding hides rows and leaves their numbers blank; nothing below is renumbered.
184
160
 
185
- ## Logical Cursor Row
161
+ So every jump resolves against one fixed list: `G`, `{n}G`, `gg`, `%`, `g0`. If the target sits inside a fold, the fold opens first and the jump lands on the row itself.
186
162
 
187
- Pi-vim-tree keeps a single *logical cursor row* - the row the cursor really belongs to, even when it is hidden.
163
+ ### Cursor Row
188
164
 
189
- - Folding does not change it.
190
- - While it is hidden, the cursor is displayed on its nearest visible ancestor (the fold row).
191
- - When the fold opens again and the row becomes visible, the cursor returns to it.
192
- - Only moving the cursor replaces it.
165
+ One *logical cursor row* is kept - the row the cursor really belongs to, even while hidden.
193
166
 
194
- The number of folds covering that row is derived from the parent chain, so folds in unrelated branches are never counted.
167
+ - Folding does not move it; while hidden, the cursor is drawn on its nearest visible ancestor.
168
+ - Opening the fold puts the cursor back on it. Only moving the cursor replaces it.
169
+ - The number of folds covering it comes from the parent chain, so folds in unrelated branches are never counted.
195
170
 
196
- `zv` remembers the row that a fold hid. Moving the cursor afterwards does not throw that memory away, so `zv` still brings you back to it - unlike the logical cursor row, which follows the cursor by Vim's rules.
171
+ `zv` separately remembers the row a fold hid, and moving the cursor does not clear that memory - unlike the logical cursor row, which follows the cursor by Vim's rules.
197
172
 
198
- ## Marks
173
+ ### Marks
199
174
 
200
- Marks work like in Vim. `m` followed by a letter or a digit stores the current row under that name; backtick followed by the same name jumps back to it. If the marked row is hidden inside a fold, the fold is opened first.
175
+ `m` plus a name stores the current row; backtick plus the same name jumps back, opening folds if needed.
201
176
 
202
177
  | Key | Action |
203
178
  | --- | --- |
204
179
  | `m` + letter or digit | Set a mark on the current row |
205
180
  | `` ` `` + letter or digit | Jump to that mark |
206
- | `` ` `` + `` ` `` | Jump back to the position before the last jump - press it again to come back, and again to go back |
181
+ | `` ` `` + `` ` `` | Jump to the position before the last jump - press again to come back, and again to go back |
207
182
  | `M` | Delete all marks (Vim's `:delmarks!`) |
208
183
 
209
- There are 62 mark names: `a` to `z`, `A` to `Z` and `0` to `9`.
210
-
211
- There is no single-mark delete key: `d` is half-page scroll now, so a mark goes away by clearing them all with `M` or by overwriting it. Setting a mark again under the same name simply replaces the old position.
184
+ 62 names: `a`-`z`, `A`-`Z`, `0`-`9`. No single-mark delete - `d` is half-page scroll, so a mark is cleared with `M` or overwritten.
212
185
 
213
- Marks live in the extension rather than in the tree view, so they survive closing and reopening `/tree`. They are cleared when the session changes, because the row ids they point at belong to the old session.
186
+ Marks live in the extension, so they survive closing and reopening `/tree`, and are cleared when the session changes - the row ids belong to the old session.
214
187
 
215
- Backtick backtick jumps to the position you were at before the last jump - Vim's "previous context" mark. It toggles: the next press brings you forward again, and the next one takes you back, so you can move between the two positions without re-typing the key. A fresh jump resets it to "back".
216
-
217
- ## Jump List
218
-
219
- `ctrl+o` and `ctrl+i` move through the jump list, exactly like Vim in normal mode: `ctrl+o` goes to the previous jump, `ctrl+i` goes to the next one.
188
+ ### Jump List
220
189
 
221
190
  | Key | Action |
222
191
  | --- | --- |
223
192
  | `ctrl+o` / `ctrl+i` | Older / newer position in the jump list |
224
193
  | `J` | Clear the jump list (Vim's `:clearjumps`) |
225
194
 
226
- Only *jumps* are recorded - `gg`, `G`, `{n}G`, `%`, `g0`, a branch-head jump (`h` / `l`, `ctrl+j` / `ctrl+k`, `shift+down` / `shift+up`), a mark jump, a committed search, and `n` / `N` / `p`. Branch-head jumps are structural jumps, the same class as Vim's `{` / `}`, so scanning branches with `h`/`l` and then pressing `ctrl+o` walks back through them one branch at a time. Line movement (`j` / `k`), scrolling (`u` / `d`, `ctrl+f/b`, `ctrl+u/d`) and fold jumps (`zj` / `zk`) do not enter the list, same as in Vim.
227
-
228
- The list behaves like browser history: jumping somewhere new truncates the entries ahead of the current position, so `ctrl+i` no longer walks into a branch you have left. A count works too - `{n}` followed by `ctrl+o` jumps back several entries at once.
229
-
230
- Entries are deduplicated by row, so a round of `l`/`h` branch scanning never piles up the same branch twice.
231
-
232
- Two limits match Vim:
195
+ Only *jumps* are recorded: `gg`, `G`, `{n}G`, `%`, `g0`, branch-head jumps (`h` / `l`, `ctrl+j` / `ctrl+k`, `shift+down` / `shift+up`), mark jumps, a committed search, `n` / `N` / `p`. Movement (`j` / `k`), list paging (`u` / `d`, `f` / `b`), fold jumps (`zj` / `zk`) and preview scrolling do not enter the list.
233
196
 
234
- - **At most 100 entries.** The oldest entries are dropped first.
235
- - **No duplicates.** Jumping to a row you visited before removes the older copy, so `ctrl+o` returns to that position once, not twice.
197
+ Like browser history, a new jump truncates what was ahead. A count works: `{n}` then `ctrl+o`. Entries are deduplicated by row, so scanning `l` / `h` never piles up the same branch twice. Vim's limits apply: at most 100 entries, no duplicates.
236
198
 
237
- ## Status Bar
199
+ ### Status Bar
238
200
 
239
- The status bar follows Vim's `showcmd` behaviour in three tiers:
201
+ `showcmd` in three tiers:
240
202
 
241
203
  | State | Behaviour |
242
204
  | --- | --- |
243
205
  | Waiting for a second key (`11`, `g`, `z`) | The prefix stays on screen |
244
- | Command finished (`j`, `11G`) | The command flashes briefly and is then cleared |
206
+ | Command finished (`j`, `11G`) | The command flashes briefly, then clears |
245
207
  | Unmatched key | Nothing is shown |
246
208
 
247
- The mode badge (`NORMAL` / `SEARCH`) is followed by the pending input in the default foreground colour.
248
-
249
- The counters next to the `Session Tree` title follow the same rule as the fold counter - they appear only when there is something to report, and disappear when it is gone:
209
+ The mode badge (`NORMAL` / `SEARCH`) is followed by the pending input. Counters appear only when there is something to report:
250
210
 
251
211
  ```
252
212
  Session Tree Fold 2/5 · Match 1/3 · Jump 4/9 · Mark a,b
253
213
  ```
254
214
 
255
- `Jump x/y` is your position in the jump list and how long the list is. `Mark a,b` lists the marks you have set. Clear the jump list with `J` and the marks with `M`, and both counters vanish again.
256
-
257
- ## Layout
215
+ `Jump x/y` is your position in the jump list and its length; `Mark a,b` lists the marks you set. `J` and `M` clear them, and the counters go with them.
258
216
 
259
- The list keeps a fixed height - 60% of the available space, capped at 30 rows - so folding, filtering, or a shorter session never resizes the panel and never makes surrounding UI shift.
217
+ ### Layout
260
218
 
261
- The preview occupies the right 55% of the width, fzf `--preview-window right:55%` style. Because the list height is fixed and the preview only takes horizontal space, toggling the preview causes no reflow at all. The body itself is rendered as Markdown, like the conversation - see [Preview](#preview).
219
+ The list keeps a fixed height - 60% of the available space, capped at 30 rows - so folding, filtering or a shorter session never resizes the panel. The preview panel takes the right 55% of the width, fzf `--preview-window right:55%` style, so toggling it causes no reflow at all.
262
220
 
263
221
  ## Compatibility
264
222
 
265
- The patch works on Pi's internal tree classes, which live in the compiled bundle. Chunk file names change between releases (`chunk-44DLKSKE.js` in 1.5.0, `chunk-ZKNSXGL5.js` in 1.5.1), so the extension locates the chunk by its content, imports it dynamically, and patches the prototype.
266
-
267
- Because it relies on private fields, it self-checks on startup. If Pi's internals change shape, the extension stays silent and falls back to native behaviour, and `/vim-tree` reports the reason.
223
+ The patch rides on private tree classes in Pi's compiled bundle, so it self-checks on startup. When the internals change shape it stays silent, leaves the native tree alone, and `/vim-tree` says why. Chunks are located by content, so renamed files (`chunk-44DLKSKE.js` -> `chunk-ZKNSXGL5.js`) are fine.
268
224
 
269
225
  ## Troubleshooting
270
226
 
271
- **`/vim-tree` says "not applied".** Pi's internals changed in a way the extension does not recognise. Update Pi and reload; if it still fails, the reason is printed by `/vim-tree`.
227
+ **`/vim-tree` says "not applied".** The internals changed in a way the extension does not recognise. Update Pi and reload; the reason is printed either way.
272
228
 
273
- **The keys do nothing.** The extension is off (`/vim-tree on`), or the tree does not have keyboard focus. Native tree keys keep working in both cases.
229
+ **The keys do nothing.** The extension is off (`/vim-tree on`), or the tree does not have focus. Native keys work in both cases.
274
230
 
275
- **The tree looks shorter than before.** The list height is fixed at 60% of the terminal (30 rows max) so that folding and filtering never make the panel jump. Resize the terminal to get more rows.
231
+ **The tree looks shorter than before.** Fixed height - 60% of the terminal, 30 rows max. Resize the terminal.
276
232
 
277
- **The tree shows a lot of `remote-pi` rows.** Those are custom messages the remote-pi package appends to the session history, one per rename. Pi's tree filter has no way to hide custom messages.
233
+ **`ctrl+f` does nothing.** The preview is closed, too narrow, or its body fits on one screen - those four keys only scroll the preview. Page the list with `f` / `b` or `u` / `d`.
278
234
 
279
- **The preview shows raw Markdown** (`#` headings, `**asterisks**`, no colours). The preview fell back to plain text because Pi's theme was not available at render time. Restarting Pi re-initialises the theme; if it still happens, `/vim-tree` and the Pi log will show why.
235
+ **The tree opens with a filter I did not pick.** That is the remembered mode. Change `treeFilterMode` in `/settings` (it wins and resyncs), or delete `vim-tree.json` from the agent directory.
280
236
 
281
- ## Releasing
237
+ **The tree shows a lot of `remote-pi` rows.** Those are custom messages the remote-pi package appends on every rename. Pi's filter has no way to hide custom messages.
238
+
239
+ **The slash command shows up as `/vim-tree:1` and `/vim-tree:2`.** Two copies are loaded - Pi appends `:1` / `:2` when a command name is registered twice, and the `[u]` / `[p]` / `[t]` tag tells you the scope. The copy that loaded last owns the patch, so `/vim-tree off` on the other one only disables itself. Keep one source: `pi list`, `pi remove <source>`, `~/.pi/agent/extensions/`, the `extensions` key in settings. `/vim-tree` warns when it detects another copy.
240
+
241
+ **The preview shows raw Markdown.** The theme was unavailable at render time, so it fell back to plain text. Restarting Pi re-initialises the theme; if it still happens, `/vim-tree` and the Pi log say why.
242
+
243
+ ## Differences from Vim
244
+
245
+ Deliberate:
246
+
247
+ | Behaviour | Vim | pi-vim-tree |
248
+ | --- | --- | --- |
249
+ | `g0` | Go to column 0 | Jumps to the session's active branch - a tree has no columns |
250
+ | `zm` / `zr` | Reset manually closed folds | Manual folds survive |
251
+ | `zm` | Decrements a counter, so closing several levels takes several presses | Steps one level immediately |
252
+ | Folding the root | Not possible | Falls back to folding the root when a chain has no branch point |
253
+ | Search scope | Whole buffer, including hidden lines | Visible rows only |
254
+ | `zX` / `zE` | Operate on manually closed folds | Not implemented - the tree has a single kind of fold |
255
+ | Mark names | `a`-`z`, `A`-`Z` (digits are numbered buffers) | The same 62 names, and `m0`-`m9` set marks too |
256
+ | `ctrl+f` / `ctrl+b` | Scroll the buffer a page | Scroll the side preview; the list pages with `f` / `b` |
257
+ | `ctrl+u` / `ctrl+d` | Scroll the buffer half a page | Scroll the side preview; the list pages with `u` / `d` |
258
+ | Filter mode | N/A | Remembered across sessions in `vim-tree.json` |
282
259
 
283
- The package is published from this directory:
260
+ ## Releasing
284
261
 
285
262
  ```bash
286
263
  npm publish --access public
287
264
  ```
288
265
 
289
- Publishing needs a second factor. Use the code from your authenticator app, or the browser confirmation flow - do **not** use a recovery code: npm treats that as a security-sensitive action and can suspend the account.
266
+ Bump `version` in `package.json` and add a matching `## [x.y.z]` heading to `CHANGELOG.md` first - Pi shows those entries to users after an update.
290
267
 
291
- For unattended releases, configure **trusted publishing** (OpenID Connect) on the npm package and point it at a GitHub Actions workflow. That removes the need for tokens entirely.
268
+ Publishing needs a second factor: use the authenticator app or the browser confirmation, **not** a recovery code (npm treats that as security-sensitive and can suspend the account). For unattended releases, configure trusted publishing (OIDC) on the package and point it at a GitHub Actions workflow.
292
269
 
293
- Publishing from a directory without a git repository is fine - npm does not require one. There is then no `gitHead` in the metadata, no provenance attestation, and no repository link on the npm page, and every release is a manual `npm login` plus 2FA. The TypeScript source ships in the tarball, so users can still read exactly what runs.
270
+ Publishing from a directory without a git repository is fine: no `gitHead`, no provenance, no repository link on the npm page, and every release is a manual `npm login` plus 2FA. The TypeScript source ships in the tarball, so users can read exactly what runs.
294
271
 
295
- Verify the published artifact without installing it:
272
+ Verify the artifact without installing it:
296
273
 
297
274
  ```bash
298
275
  pi -e npm:pi-vim-tree
299
276
  ```
300
277
 
301
- ## Differences from Vim
278
+ ## Development
302
279
 
303
- These are deliberate:
280
+ The extension is a single file with no build step; `npm` is only needed to publish.
304
281
 
305
- | Behaviour | Vim | pi-vim-tree |
282
+ Pick **one** source to load it. Loading the same extension twice is what produces `/vim-tree:1` / `:2`, and the copies then fight over the patch.
283
+
284
+ | Goal | Command | Scope tag |
306
285
  | --- | --- | --- |
307
- | `g0` | Go to column 0 | Jumps to the session's active branch - a tree has no columns, so Vim's `g0` has nothing to do here |
308
- | `zm` / `zr` | Reset manually closed folds | Manual folds survive |
309
- | `zm` | Decrements a counter, so closing several levels takes several presses | Steps one level immediately |
310
- | Folding the root | Not possible | Falls back to folding the root when a chain has no branch point |
311
- | Search scope | Searches the whole buffer, including hidden lines | Searches the visible rows only |
312
- | `zX` / `zE` | Operate on manually closed folds | Not implemented - the tree has a single kind of fold |
313
- | Mark names | `a`-`z`, `A`-`Z` (digits are numbered-buffer marks) | The same 62 names, and `m0`-`m9` set marks too |
286
+ | One-off run | `pi -e ./extensions/vim-tree.ts` | `[t]` |
287
+ | Hot reload with `/reload` | link or copy into `~/.pi/agent/extensions/` | `[u]` |
288
+ | Keep the file where it is | add the path to `extensions` in `~/.pi/agent/settings.json` | `[u]` |
289
+ | As a package | `pi install ./this-dir` | `[u]` |
314
290
 
315
- ## Development
291
+ The tag is what Pi prints in autocomplete: `u` = user, `p` = project, `t` = temporary. A symlink keeps one copy of the file while `/reload` still sees edits:
316
292
 
317
- The extension is a single file with no build step. `npm` is only needed to publish it as a package.
293
+ ```bash
294
+ ln -sfn "$PWD/extensions/vim-tree.ts" ~/.pi/agent/extensions/vim-tree.ts
295
+ ```
296
+
297
+ ### `npm install` is never needed
318
298
 
319
- The test suite drives the **real** Pi `TreeSelectorComponent`, loaded from the installed bundle, and feeds it real key bytes:
299
+ Everything the extension imports comes from Pi; `npm install` has nothing to install and replaces the links `test/setup.sh` creates (re-run it afterwards). The links are per package inside a real `node_modules/@earendil-works` directory on purpose: an earlier version linked the whole scope at Pi's own `node_modules`, and a stray `npm install` then resolved the peers through that link and pruned Pi's packages as "extraneous", leaving Pi unable to start.
300
+
301
+ ### Tests
320
302
 
321
303
  ```bash
322
- ./test/setup.sh # 把已安装的 pi 里的 node_modules 链过来(裸 node 需要能 import pi-tui)
304
+ ./test/setup.sh # link Pi's node_modules so bare node can import pi-tui
323
305
  npm test
324
306
  ```
325
307
 
326
- It asserts on the visible rows, the selected row, the counters in the title bar, the fold markers, the jump list and the marks. A failing assertion prints the actual and expected values, and the exit code is non-zero.
327
-
328
- The suite also covers the `/vim-tree off` path: after turning the extension off, the tree must render byte for byte like a tree that was never patched.
308
+ The suite drives the **real** `TreeSelectorComponent` from the installed bundle with real key bytes, and asserts on visible rows, the selected row, the title-bar counters, fold markers, the jump list and the marks. It covers `/vim-tree off` (the tree must render byte for byte like one never patched) and loads two copies on purpose to check that a stale copy's `off` cannot tear down the active patch. Re-run `setup.sh` after upgrading Pi.
@@ -7,11 +7,21 @@
7
7
  * - `ctrl+o` / `ctrl+i`(=Tab):跳转栈后退 / 前进(vim 的 jump list)
8
8
  * - `ctrl+h`(或 f4) :开关右栏预览
9
9
  * - `ctrl+e` / `ctrl+y` :预览内容上下翻一行
10
- * - `ctrl+f` / `ctrl+b` :列表翻整页
11
- * - `u` / `d`(以及 `ctrl+u` / `ctrl+d`):列表翻半页(上 / 下)
10
+ * - `ctrl+u` / `ctrl+d` :预览内容上下翻半页
11
+ * - `ctrl+f` / `ctrl+b` :预览内容上下翻整页
12
+ * (预览这六个键只动右栏;预览关着 / 内容不足一屏就吞掉,不动列表、不落回原生)
13
+ * - `u` / `d` :列表翻半页(上 / 下)
14
+ * - `f` / `b` :列表翻整页(less 手感)
12
15
  * - `ctrl+l` :清掉搜索词和命中高亮
13
16
  * - `L` / `T` :标签编辑 / 标签时间戳(只认大写,小写让给动作键)
14
17
  * - `q` :关掉树(原生只有 esc 能关;vim 的 help/preview 窗口也是 q)
18
+ * - 过滤模式(gt/gl/gu/ga/gd)会被记住:退出 /tree 再进、甚至下次启动都还是上次那个模式
19
+ * (存 agent 目录的 vim-tree.json;`/settings` 里改 `treeFilterMode` 时以设置项为准)
20
+ * - 鼠标滚轮 :左栏滚列表(按行移光标)、右栏滚预览(按行滑窗);
21
+ * 事件被吞掉,不会漏给下层的 chat 正文。只接管滚轮,点击 / 拖拽原样还给原生。
22
+ * - 进树的那个键 :在树里**再按一次**就关(开 / 关同一个键)。
23
+ * 键位不写死 —— 读 pi 的 `app.session.tree`(keybindings.json 里配什么就是什么),
24
+ * 没配就永远不命中。注意:老终端里 ctrl+i 与 Tab 同字节,配成 ctrl+i 时 Tab 也会关树。
15
25
  * - `z` 家族按 vim 折叠语义走:`zc/zo/za` 收/展/切换,`zO/zC` 整棵子树收/展,
16
26
  * `zm/zr` 收/放一层,`zM/zR` 全收/全展,`zj/zk` 跳到下一个/上一个折痕,
17
27
  * `zA` 递归切换(折着就整棵展开,展开就整棵收起),
@@ -76,8 +86,8 @@
76
86
  * (类原型上的 handleInput/render、树实例上的 applyFilter、搜索状态),不留残留。
77
87
  */
78
88
 
79
- import { Container, Input, Markdown, decodeKittyPrintable, matchesKey, truncateToWidth, visibleWidth, wrapTextWithAnsi } from "@earendil-works/pi-tui";
80
- import { existsSync, readdirSync, readFileSync } from "node:fs";
89
+ import { Container, Input, Markdown, decodeKittyPrintable, getKeybindings, matchesKey, truncateToWidth, visibleWidth, wrapTextWithAnsi } from "@earendil-works/pi-tui";
90
+ import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
81
91
  import { homedir } from "node:os";
82
92
  import { dirname, join } from "node:path";
83
93
  import { pathToFileURL } from "node:url";
@@ -112,7 +122,7 @@ const MODE_SEARCH = "\x1b[48;5;84m\x1b[38;5;235m";
112
122
  const MODE_END = "\x1b[0m";
113
123
 
114
124
  /** 构建标记:/vim-tree 会把它显示出来,用来确认 /reload 之后跑的是不是新代码 */
115
- const BUILD = "2026-11-13 keys: h/l branch, u/d half page, q quit, L/T uppercase only";
125
+ const BUILD = "2026-11-18 keys: f/b list page, ctrl+f/b/u/d preview scroll, app.session.tree toggles the tree, wheel scrolls";
116
126
 
117
127
  const STATE = {
118
128
  enabled: process.env.PI_VIM_TREE !== "0",
@@ -121,9 +131,12 @@ const STATE = {
121
131
  patched: false,
122
132
  notice: "",
123
133
  warned: false,
134
+ tookOver: false, // 打补丁时发现已经有人占了:说明同一份扩展被加载了两遍
124
135
  treeList: undefined as any,
125
136
  tui: undefined as any,
126
137
  marks: new Map<string, string>(), // vim 的标记:名字 → 行 id(跨 /tree 开关都留着)
138
+ // 记住的过滤模式:{ mode: 用户上一次选的, initial: 那一轮 pi settings 里的值 }
139
+ filter: undefined as { mode?: string; initial?: string } | undefined,
127
140
  };
128
141
 
129
142
  // ---------------------------------------------------------------- 补丁登记
@@ -659,9 +672,83 @@ function setFilter(treeList: any, mode: string): void {
659
672
  treeList.applyFilter();
660
673
  treeList.__vtCount = 0;
661
674
  treeList.__vtPendingG = 0;
675
+ rememberFilter(mode);
662
676
  }
663
677
 
664
- /** 翻屏:factor=1 整页、0.5 半页;vim 的 ctrl+f/b、ctrl+u/d */
678
+ /**
679
+ * 过滤模式的记忆(gt/gl/gu/ga/gd 选的那个)。
680
+ * pi 自己只在打开树的时候把 settings 里的 `treeFilterMode` 传进来,树里改了不会回写;
681
+ * 所以由扩展记:同一次运行内存里记,跨会话落在 agent 目录的 `vim-tree.json`。
682
+ * `/settings` 里改过 `treeFilterMode`(打开树时传进来的初始值变了)→ 以设置项为准,并把记忆同步过去,
683
+ * 不然记忆会永远盖住设置面板。
684
+ */
685
+ function filterStateFile(): string {
686
+ return join(process.env.PI_CODING_AGENT_DIR ?? join(homedir(), ".pi", "agent"), "vim-tree.json");
687
+ }
688
+
689
+ function filterMemory(): { mode?: string; initial?: string } {
690
+ if (!STATE.filter) {
691
+ try {
692
+ const raw = JSON.parse(readFileSync(filterStateFile(), "utf8")) as any;
693
+ STATE.filter = {
694
+ mode: typeof raw?.treeFilterMode === "string" ? raw.treeFilterMode : undefined,
695
+ initial: typeof raw?.treeFilterInitial === "string" ? raw.treeFilterInitial : undefined,
696
+ };
697
+ } catch {
698
+ STATE.filter = {};
699
+ }
700
+ }
701
+ return STATE.filter;
702
+ }
703
+
704
+ function saveFilterMemory(): void {
705
+ const memory = filterMemory();
706
+ try {
707
+ mkdirSync(dirname(filterStateFile()), { recursive: true });
708
+ writeFileSync(
709
+ filterStateFile(),
710
+ `${JSON.stringify({ treeFilterMode: memory.mode, treeFilterInitial: memory.initial }, null, 2)}\n`,
711
+ );
712
+ } catch (error) {
713
+ warnOnce(`could not save filter preference: ${(error as Error)?.message ?? String(error)}`);
714
+ }
715
+ }
716
+
717
+ /** 用户在树里选了新模式 → 记下来(值没变就不写盘) */
718
+ function rememberFilter(mode: string): void {
719
+ const memory = filterMemory();
720
+ if (memory.mode === mode) return;
721
+ memory.mode = mode;
722
+ saveFilterMemory();
723
+ }
724
+
725
+ /** 新树第一次露面:把记住的模式套上去(每棵树只做一次) */
726
+ function syncRememberedFilter(treeList: any): void {
727
+ if (treeList.__vtFilterSync) return;
728
+ treeList.__vtFilterSync = true;
729
+ const memory = filterMemory();
730
+ const initial = String(treeList.filterMode ?? "default");
731
+ if (!memory.initial) {
732
+ // 第一次运行:拿 pi 传进来的(settings 的 treeFilterMode)当基准
733
+ memory.mode = memory.mode ?? initial;
734
+ memory.initial = initial;
735
+ saveFilterMemory();
736
+ return;
737
+ }
738
+ if (initial !== memory.initial) {
739
+ // /settings 里改过 → 设置项优先,记忆跟着同步
740
+ memory.initial = initial;
741
+ memory.mode = initial;
742
+ saveFilterMemory();
743
+ return;
744
+ }
745
+ if (memory.mode && memory.mode !== initial) {
746
+ treeList.filterMode = memory.mode;
747
+ treeList.applyFilter();
748
+ }
749
+ }
750
+
751
+ /** 翻屏:factor=1 整页、0.5 半页;列表的 f/b、u/d */
665
752
  function scrollLines(treeList: any, factor: number): boolean {
666
753
  const total = treeList.filteredNodes?.length ?? 0;
667
754
  if (total === 0) return false;
@@ -682,6 +769,19 @@ function clearSearchResults(treeList: any): void {
682
769
  treeList.applyFilter();
683
770
  }
684
771
 
772
+ /**
773
+ * 进树的那个键(keybindings.json 里的 `app.session.tree`):树里再按一次就退出(开 / 关同一个键)。
774
+ * 不写死键位,直接问 pi 装进 pi-tui 的那个 KeybindingsManager;**没配就永远不命中**。
775
+ * 注意:老终端里 ctrl+i 和 Tab 是同一个字节,所以真把 app.session.tree 配成 ctrl+i 时,Tab 也会关树。
776
+ */
777
+ function matchesTreeKey(data: string): boolean {
778
+ try {
779
+ return getKeybindings().matches(data, "app.session.tree");
780
+ } catch {
781
+ return false; // 拿不到键位管理器(非交互场景 / 版本不合)就当没配
782
+ }
783
+ }
784
+
685
785
  /** ctrl+l:打开标签编辑(等价于原生 app.tree.editLabel) */
686
786
  function openLabelEditor(treeList: any): boolean {
687
787
  const flat = treeList.filteredNodes?.[treeList.selectedIndex];
@@ -1027,6 +1127,29 @@ function previewState(treeList: any, entryId: string | undefined): { id: string
1027
1127
  return state;
1028
1128
  }
1029
1129
 
1130
+ /**
1131
+ * 预览当前能不能滚:预览开着、且内容超出一屏。
1132
+ * page/total 是上一次渲染留下的(列表高度固定,所以这就是真实页大小)。
1133
+ */
1134
+ function previewScrollMeta(treeList: any): { page: number; total: number } | undefined {
1135
+ const info: { page: number; total: number } | undefined = treeList.__vtPreviewInfo;
1136
+ if (!STATE.preview || !info || info.page <= 0 || info.total <= info.page) return undefined;
1137
+ return info;
1138
+ }
1139
+
1140
+ /**
1141
+ * 滚预览 N 行(正数往下):一行是 ctrl+e/y,半页/整页由调用方按 previewScrollMeta().page 换算。
1142
+ * 返回 false = 预览不可滚(关着 / 内容不足一屏),调用方自己决定落回哪里。
1143
+ */
1144
+ function scrollPreview(treeList: any, lines: number): boolean {
1145
+ const info = previewScrollMeta(treeList);
1146
+ if (!info) return false;
1147
+ const state = previewState(treeList, selectedId(treeList));
1148
+ const maxOffset = Math.max(0, info.total - info.page);
1149
+ state.offset = Math.max(0, Math.min(maxOffset, state.offset + lines));
1150
+ return true;
1151
+ }
1152
+
1030
1153
 
1031
1154
  // ---------------------------------------------------------------- 折叠(vim z 家族)
1032
1155
 
@@ -1648,7 +1771,7 @@ function customizeChrome(treeList: any, out: string[], width: number): void {
1648
1771
  const items = [
1649
1772
  "j/k move",
1650
1773
  "u/d half page",
1651
- "ctrl+f/b page",
1774
+ "f/b page",
1652
1775
  "ctrl+l clear search",
1653
1776
  "ctrl+o/i jump back/fwd",
1654
1777
  "zc/zo/za/zO/zC/zA folds",
@@ -1662,7 +1785,7 @@ function customizeChrome(treeList: any, out: string[], width: number): void {
1662
1785
  "h/l branch · g0 current",
1663
1786
  "ctrl+j/k branch",
1664
1787
  "gt/gl/gu/ga/gd filters",
1665
- "ctrl+h ctrl+e/y preview",
1788
+ "ctrl+h preview · ctrl+e/y/u/d/f/b scroll",
1666
1789
  "L label",
1667
1790
  "T label time",
1668
1791
  "/ search",
@@ -2071,6 +2194,8 @@ function layoutScreen(component: any, lines: string[], width: number, hardMax: n
2071
2194
  const leftWidth = Math.max(24, Math.round(width * (1 - PREVIEW_SPLIT)));
2072
2195
  const rightWidth = width - leftWidth - 1;
2073
2196
  const canSplit = previewEnabled && rightWidth >= 12;
2197
+ // 鼠标滚轮按这一列分左右栏(见 vtHandleMouse)
2198
+ treeList.__vtSplitCol = canSplit ? leftWidth : undefined;
2074
2199
 
2075
2200
  let previewLines: string[] = [];
2076
2201
  treeList.__vtPreviewInfo = { page: 0, total: 0 };
@@ -2091,7 +2216,7 @@ function layoutScreen(component: any, lines: string[], width: number, hardMax: n
2091
2216
  .map((line) => (wrapped.plain && previewTokens.length > 0 ? highlightTokens(line, previewTokens, false) : line));
2092
2217
  const label =
2093
2218
  wrapped.total > page
2094
- ? `preview ${state.offset + 1}-${Math.min(wrapped.total, state.offset + page)}/${wrapped.total} ctrl+d/u half · ctrl+e/y line`
2219
+ ? `preview ${state.offset + 1}-${Math.min(wrapped.total, state.offset + page)}/${wrapped.total} ctrl+d/u half · ctrl+f/b page · ctrl+e/y line`
2095
2220
  : "preview (all)";
2096
2221
  previewLines = [`${DIM}${label}${RESET}`, ...visible];
2097
2222
  } else if (previewEnabled) {
@@ -2181,11 +2306,23 @@ function vtHandleInner(component: any, data: string, forward: (data: string) =>
2181
2306
  }
2182
2307
 
2183
2308
  ensureSearch(treeList);
2309
+ syncRememberedFilter(treeList);
2184
2310
 
2185
2311
  if (process.env.PI_VIM_TREE_DEBUG === "2") console.error(`[vim-tree] key ${JSON.stringify(data)}`);
2186
2312
 
2187
2313
  const mode = modeOf(treeList);
2188
2314
 
2315
+ // 进树的那个键(pi 的 `app.session.tree`,keybindings.json 里配什么就是什么):在树里再按一次 = 关树。
2316
+ // 不写死键位:直接问 pi 装进 pi-tui 的那个 KeybindingsManager(用户改键 / `/reload` 都会跟着变);
2317
+ // 没配(默认空列表)就永远不命中。
2318
+ if (mode === "normal" && matchesTreeKey(data)) {
2319
+ treeList.__vtCount = 0;
2320
+ treeList.__vtPendingG = 0;
2321
+ treeList.__vtPendingZ = 0;
2322
+ if (typeof treeList.onCancel === "function") treeList.onCancel();
2323
+ return;
2324
+ }
2325
+
2189
2326
  // ---- 下面这些是指令键,只在 normal 生效;search 模式是纯输入(像 chat 输入框)
2190
2327
  if (mode === "normal") {
2191
2328
  // esc 在 normal 下不拦:原样交给原生(原生 esc = 取消/关树)。
@@ -2210,7 +2347,8 @@ function vtHandleInner(component: any, data: string, forward: (data: string) =>
2210
2347
  return;
2211
2348
  }
2212
2349
 
2213
- // ctrl+f / ctrl+b 翻整页,u / d(以及 ctrl+u / ctrl+d)翻半页(vim 的翻屏)
2350
+ // ctrl+f / ctrl+b 整页、ctrl+u / ctrl+d 半页:**只滚预览**(less / vim 的翻屏手感)。
2351
+ // 预览关着或内容不足一屏就吞掉 —— 不落回列表(列表翻屏是 u/d 和 f/b),也不放进原生过滤器键。
2214
2352
  if (
2215
2353
  matchesKey(data, "ctrl+f") ||
2216
2354
  matchesKey(data, "ctrl+b") ||
@@ -2219,7 +2357,10 @@ function vtHandleInner(component: any, data: string, forward: (data: string) =>
2219
2357
  ) {
2220
2358
  const down = matchesKey(data, "ctrl+f") || matchesKey(data, "ctrl+d");
2221
2359
  const half = matchesKey(data, "ctrl+u") || matchesKey(data, "ctrl+d");
2222
- scrollLines(treeList, (down ? 1 : -1) * (half ? 0.5 : 1));
2360
+ const meta = previewScrollMeta(treeList);
2361
+ if (!meta) return;
2362
+ const step = Math.max(1, Math.round(meta.page * (half ? 0.5 : 1)));
2363
+ scrollPreview(treeList, down ? step : -step);
2223
2364
  return;
2224
2365
  }
2225
2366
 
@@ -2231,17 +2372,7 @@ function vtHandleInner(component: any, data: string, forward: (data: string) =>
2231
2372
 
2232
2373
  // 预览滚动:ctrl+e/y 一行;预览不可滚时吞掉(别掉进原生的过滤器键)
2233
2374
  if (matchesKey(data, "ctrl+e") || matchesKey(data, "ctrl+y")) {
2234
- const info: { page: number; total: number } | undefined = treeList.__vtPreviewInfo;
2235
- const canScroll = STATE.preview && info !== undefined && info.page > 0 && info.total > info.page;
2236
- if (!canScroll) return;
2237
-
2238
- const down = matchesKey(data, "ctrl+e");
2239
- const step = 1;
2240
-
2241
- const selectedId = treeList.filteredNodes?.[treeList.selectedIndex]?.node?.entry?.id;
2242
- const state = previewState(treeList, selectedId);
2243
- state.offset += down ? step : -step;
2244
- if (state.offset < 0) state.offset = 0;
2375
+ if (!scrollPreview(treeList, matchesKey(data, "ctrl+e") ? 1 : -1)) return;
2245
2376
  return;
2246
2377
  }
2247
2378
 
@@ -2474,7 +2605,7 @@ function vtHandleInner(component: any, data: string, forward: (data: string) =>
2474
2605
  return;
2475
2606
  }
2476
2607
 
2477
- // u / d:翻半页(vim 的 ctrl+u / ctrl+d),和 ctrl+u / ctrl+d 是同一个动作
2608
+ // u / d:列表翻半页(vim 的 ctrl+u / ctrl+d 手感,但 ctrl 那组让给预览了)
2478
2609
  if (data === "u" || data === "d") {
2479
2610
  scrollLines(treeList, data === "d" ? 0.5 : -0.5);
2480
2611
  treeList.__vtCount = 0;
@@ -2482,6 +2613,14 @@ function vtHandleInner(component: any, data: string, forward: (data: string) =>
2482
2613
  return;
2483
2614
  }
2484
2615
 
2616
+ // f / b:列表翻整页(less 手感;ctrl+f/b 只滚预览)
2617
+ if (data === "f" || data === "b") {
2618
+ scrollLines(treeList, data === "f" ? 1 : -1);
2619
+ treeList.__vtCount = 0;
2620
+ treeList.__vtPendingG = 0;
2621
+ return;
2622
+ }
2623
+
2485
2624
  // 一页 = 原生 pgup/pgdn
2486
2625
  if (matchesKey(data, "pageDown") || matchesKey(data, "pageUp")) {
2487
2626
  treeList.__vtCount = 0;
@@ -2535,6 +2674,43 @@ function vtHandleInner(component: any, data: string, forward: (data: string) =>
2535
2674
  return;
2536
2675
  }
2537
2676
 
2677
+ /**
2678
+ * 鼠标滚轮:**右栏滚预览、左栏滚列表**(pi 的鼠标事件给的是组件内坐标,按上次 render 的宽度分栏)。
2679
+ * 列表按 wheelDelta 行移动光标(跟 j/k 一样,不整屏跳);预览按行滚并夹在内容范围内。
2680
+ * 其余事件(点击 / 拖拽 / 按下)原样还给原生 —— 只接管滚轮。
2681
+ */
2682
+ function vtHandleMouse(component: any, event: any, forward: (event: any) => unknown): unknown {
2683
+ const treeList = component?.treeList;
2684
+ if (!treeList || event?.type !== "wheel") return forward(event);
2685
+ // 标签编辑框开着时整套交给原生(跟键盘那边一个规矩)
2686
+ if (component.labelInput) return forward(event);
2687
+ const delta = Number(event?.wheelDelta ?? 0);
2688
+ if (!Number.isFinite(delta) || delta === 0) return forward(event);
2689
+
2690
+ const width = Number(treeList.__vtWidth ?? event?.width ?? 0);
2691
+ const previewEnabled = STATE.preview && !component.labelInput;
2692
+ // 分栏线:上次 render 记下的那个列(跟画出来的一致),没有就现算
2693
+ const splitCol = Number(treeList.__vtSplitCol ?? Math.max(24, Math.round(width * (1 - PREVIEW_SPLIT))));
2694
+ const overPreview = previewEnabled && event.x > splitCol && scrollPreview(treeList, delta);
2695
+
2696
+ if (process.env.PI_VIM_TREE_DEBUG === "2") {
2697
+ console.error(
2698
+ `[vim-tree] wheel x=${event.x} y=${event.y} delta=${delta} split=${splitCol} width=${width} → ${overPreview ? "preview" : "list"}`,
2699
+ );
2700
+ }
2701
+
2702
+ if (overPreview) return { handled: true };
2703
+
2704
+ // 左栏(或预览关着 / 太窄没分栏):列表框里按滚轮行数移动光标
2705
+ const total = treeList.filteredNodes?.length ?? 0;
2706
+ if (total === 0) return { handled: true };
2707
+ const step = Math.max(1, Math.abs(delta));
2708
+ const next = (treeList.selectedIndex ?? 0) + (delta < 0 ? -step : step);
2709
+ treeList.selectedIndex = Math.max(0, Math.min(total - 1, next));
2710
+ treeList.__vtLogical = selectedId(treeList);
2711
+ return { handled: true };
2712
+ }
2713
+
2538
2714
  // ---------------------------------------------------------------- 补丁
2539
2715
 
2540
2716
  function patchClass(cls: any): void {
@@ -2548,12 +2724,18 @@ function patchClass(cls: any): void {
2548
2724
  const orig: OrigMethods =
2549
2725
  stored && typeof stored.handleInput === "function" && typeof stored.render === "function"
2550
2726
  ? stored
2551
- : { handleInput: proto.handleInput, render: proto.render };
2727
+ : { handleInput: proto.handleInput, render: proto.render, handleMouse: proto.handleMouse };
2552
2728
  proto.__vtOrig = orig;
2553
2729
  proto.__vtPatched = true;
2730
+ // 同一份扩展被加载两遍时(例如既装到 ~/.pi/agent/extensions/ 又用 `pi -e`),
2731
+ // 两个模块实例各自有一套 STATE,但只共用一个 prototype:后打的把先打的盖掉。
2732
+ // 用 owner 令牌记住“当前是谁在管”,旧的实例就不可能在 off 时把新的补丁拆掉。
2733
+ const owner = {};
2734
+ if (proto.__vtOwner) STATE.tookOver = true;
2735
+ proto.__vtOwner = owner;
2554
2736
 
2555
2737
  proto.handleInput = function handleInput(this: any, data: string): unknown {
2556
- if (!STATE.enabled) return orig.handleInput.call(this, data);
2738
+ if (!STATE.enabled || proto.__vtOwner !== owner) return orig.handleInput.call(this, data);
2557
2739
  // 标签编辑框开着的时候整套交给原生:它才知道怎么把按键喂给 LabelInput,
2558
2740
  // 我们接管了 handleInput 就得把这个分支还回去,否则标签打不进字。
2559
2741
  if (this.labelInput) return orig.handleInput.call(this, data);
@@ -2567,12 +2749,18 @@ function patchClass(cls: any): void {
2567
2749
  };
2568
2750
 
2569
2751
  proto.render = function render(this: any, width: number): string[] {
2570
- if (!STATE.enabled) return orig.render.call(this, width);
2752
+ if (!STATE.enabled || proto.__vtOwner !== owner) return orig.render.call(this, width);
2571
2753
 
2572
2754
  let hardMax = 0;
2573
2755
  try {
2574
2756
  const treeList = this.treeList;
2575
2757
  if (treeList) STATE.treeList = treeList;
2758
+ // 鼠标事件给的是“组件内坐标”,分栏位置得跟这次 render 用同一个宽度算
2759
+ if (treeList) treeList.__vtWidth = width;
2760
+ // 先把“原生过滤模式”记下来(off 时要还回去),再套记忆,顺序不能反
2761
+ if (treeList) ensureSearch(treeList);
2762
+ // 退出再进 = 新的 treeList:把用户上次选的过滤模式套回来
2763
+ if (treeList) syncRememberedFilter(treeList);
2576
2764
  if (treeList && typeof treeList.maxVisibleLines === "number") {
2577
2765
  ensureSearch(treeList);
2578
2766
  // 行号基准(未折叠的行清单):先算好,渲染中就不会改树状态
@@ -2603,10 +2791,30 @@ function patchClass(cls: any): void {
2603
2791
  }
2604
2792
  };
2605
2793
 
2794
+ proto.handleMouse = function handleMouse(this: any, event: any): unknown {
2795
+ if (!STATE.enabled || proto.__vtOwner !== owner) return orig.handleMouse?.call(this, event);
2796
+ STATE.treeList = this.treeList;
2797
+ try {
2798
+ return vtHandleMouse(this, event, (e: any) => orig.handleMouse?.call(this, e));
2799
+ } catch (error) {
2800
+ warnOnce(`mouse error, falling back to native: ${(error as Error)?.message ?? String(error)}`);
2801
+ return orig.handleMouse?.call(this, event);
2802
+ }
2803
+ };
2804
+
2606
2805
  STATE.patched = true;
2607
2806
  onDisable(() => {
2807
+ // 被后来的实例接管了:别去拆别人的补丁(否则两边都不工作)
2808
+ if (proto.__vtOwner !== owner) {
2809
+ STATE.patched = false;
2810
+ return;
2811
+ }
2812
+ proto.__vtOwner = undefined;
2608
2813
  proto.handleInput = orig.handleInput;
2609
2814
  proto.render = orig.render;
2815
+ // 原生没有 handleMouse:直接删掉,别留一个 undefined 占着
2816
+ if (orig.handleMouse) proto.handleMouse = orig.handleMouse;
2817
+ else delete proto.handleMouse;
2610
2818
  proto.__vtPatched = false;
2611
2819
  STATE.patched = false;
2612
2820
  restoreNativeTreeState(STATE.treeList);
@@ -2691,7 +2899,7 @@ export default function vimTreeExtension(pi: ExtensionAPI): void {
2691
2899
  }
2692
2900
 
2693
2901
  ctx.ui.notify(
2694
- `vim-tree: ${STATE.patched && STATE.enabled ? "on" : "off"} · build ${BUILD}${STATE.notice ? `(${STATE.notice})` : ""}`,
2902
+ `vim-tree: ${STATE.patched && STATE.enabled ? "on" : "off"} · build ${BUILD}${STATE.notice ? ` (${STATE.notice})` : ""}${STATE.tookOver ? " · another copy is also loaded (see /vim-tree:1, :2) - keep only one source" : ""}`,
2695
2903
  );
2696
2904
  },
2697
2905
  });
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "pi-vim-tree",
3
- "version": "0.1.1",
3
+ "version": "0.1.2",
4
4
  "description": "Vim-style folding, motion, jump list and marks for Pi's built-in /tree view.",
5
5
  "author": "ooostrich",
6
6
  "type": "module",