native macOS codings agent orchestrator
Plan sidebar container refactor
Refs #249
+508
1 changed file
doc-onevcat
+508
doc-onevcat/plans/2026-05-03-sidebar-container-refactor-plan.md
+508
doc-onevcat/plans/2026-05-03-sidebar-container-refactor-plan.md
···
1
1
+
# Sidebar Container Refactor Plan
2
2
+
3
3
+
Status: planning
4
4
+
Issue: [#249](https://github.com/onevcat/Prowl/issues/249)
5
5
+
Related: [#222](https://github.com/onevcat/Prowl/issues/222)
6
6
+
7
7
+
## Goal
8
8
+
9
9
+
Refactor the repository sidebar so each repository behaves as one stable visual and drag unit, while worktrees remain selectable, reorderable, and efficient to update.
10
10
+
11
11
+
This should fix the structural mismatch where the app treats repositories as reorderable units but SwiftUI `List` sees repository headers and worktree rows as separate rows. That mismatch shows up as:
12
12
+
13
13
+
- incorrect repository drag insertion indicators when dragging downward across expanded repositories
14
14
+
- unstable bulk expand/collapse animations
15
15
+
- potential sidebar flicker during drag when live terminal / notification / ordering updates arrive
16
16
+
17
17
+
## Current Findings
18
18
+
19
19
+
### 1. Repository sections are not actual list rows
20
20
+
21
21
+
`SidebarListView` renders repositories through an outer `ForEach(...).onMove`.
22
22
+
23
23
+
`RepositorySectionView` then returns:
24
24
+
25
25
+
```swift
26
26
+
Group {
27
27
+
header
28
28
+
.tag(SidebarSelection.repository(repository.id))
29
29
+
if isExpanded {
30
30
+
WorktreeRowsView(...)
31
31
+
}
32
32
+
}
33
33
+
```
34
34
+
35
35
+
In practice, the outer data model says "repository row", but `List` receives separate rows:
36
36
+
37
37
+
```text
38
38
+
Repository A header
39
39
+
Repository A worktree
40
40
+
Repository A worktree
41
41
+
Repository B header
42
42
+
Repository B worktree
43
43
+
```
44
44
+
45
45
+
This explains the observed downward-drag indicator bug:
46
46
+
47
47
+
```text
48
48
+
Target Repo header
49
49
+
o-----------
50
50
+
Target Repo worktree
51
51
+
```
52
52
+
53
53
+
SwiftUI is placing the indicator between list rows. It does not know that the target repository header and its worktree rows should be treated as one repository-level drop zone.
54
54
+
55
55
+
### 2. `List(selection:)` is doing too much
56
56
+
57
57
+
The current `List` carries several behaviors at once:
58
58
+
59
59
+
- special rows: Canvas, Shelf, archived worktrees, repository list header
60
60
+
- repository row selection for plain folders
61
61
+
- worktree multi-selection
62
62
+
- repository expand/collapse
63
63
+
- native repository reorder
64
64
+
- native worktree reorder for pinned and unpinned groups
65
65
+
- reveal-in-sidebar via `ScrollViewReader.scrollTo`
66
66
+
- native sidebar styling and accessibility
67
67
+
68
68
+
This makes local fixes brittle because changing row structure affects selection, drag, animation, and scroll identity at the same time.
69
69
+
70
70
+
### 3. Live state still reaches rows during drag
71
71
+
72
72
+
Some expensive state reads have already been isolated, such as moving repository tab-count reads into `RepoHeaderTabCountBadge`.
73
73
+
74
74
+
Remaining drag-time churn sources include:
75
75
+
76
76
+
- `WorktreeRowsView` animates changes to `rowIDs`
77
77
+
- each worktree row reads terminal notification/task/run-script state
78
78
+
- notification-driven reorder can call `withAnimation(.snappy)` and mutate `worktreeOrderByRepository`
79
79
+
- row hover/action UI changes while a drag session is active
80
80
+
81
81
+
These are not necessarily the root cause of the drop-indicator bug, but they are credible contributors to #222-style flicker.
82
82
+
83
83
+
## Recommended Direction
84
84
+
85
85
+
Use a custom sidebar scroll container rather than trying to keep the current flat `List` structure.
86
86
+
87
87
+
Recommended shape:
88
88
+
89
89
+
```text
90
90
+
ScrollViewReader
91
91
+
└── ScrollView
92
92
+
└── LazyVStack or VStack
93
93
+
├── Special rows
94
94
+
├── RepositoryContainerRow
95
95
+
│ ├── RepositoryHeaderRow
96
96
+
│ └── WorktreeRows
97
97
+
└── FailedRepositoryRow
98
98
+
```
99
99
+
100
100
+
Key property: repository containers are the only repository-level siblings in the outer stack. Expanded worktrees are children inside the container, not siblings beside it.
101
101
+
102
102
+
This aligns UI boundaries with model boundaries:
103
103
+
104
104
+
- repository reorder indicators target repository containers
105
105
+
- expand/collapse animates inside a container
106
106
+
- worktree reorder indicators target worktree rows inside one container
107
107
+
- live worktree updates do not change the outer repository list shape
108
108
+
109
109
+
## Options Considered
110
110
+
111
111
+
### Option A: Keep `List`, wrap worktrees inside one repository row
112
112
+
113
113
+
Pros:
114
114
+
115
115
+
- preserves some native sidebar styling
116
116
+
- repository-level `onMove` might remain mostly native
117
117
+
118
118
+
Cons:
119
119
+
120
120
+
- nested selectable worktree rows inside a single `List` row no longer participate naturally in `List(selection:)`
121
121
+
- worktree-level `onMove` becomes awkward inside a row
122
122
+
- native selection and keyboard behavior still need replacement
123
123
+
- likely keeps a hard-to-debug mix of native and custom drag logic
124
124
+
125
125
+
This option reduces the indicator bug but does not cleanly solve the broader sidebar design.
126
126
+
127
127
+
### Option B: Move fully to `ScrollView` + explicit rows
128
128
+
129
129
+
Pros:
130
130
+
131
131
+
- model and visual structure match
132
132
+
- repo and worktree drag/drop can be made explicit and testable
133
133
+
- selection, focus, and reveal behavior are owned by our code instead of `List` side effects
134
134
+
- easier to freeze drag-time updates intentionally
135
135
+
- eliminates `List` cell reuse as a class of expand/collapse animation bugs
136
136
+
137
137
+
Cons:
138
138
+
139
139
+
- must replace native `List(selection:)`
140
140
+
- must rebuild keyboard navigation, multi-selection, reorder, and accessibility affordances
141
141
+
- more implementation work
142
142
+
143
143
+
This is the recommended route for #249 if the goal is "fix the sidebar design once" rather than patch one symptom.
144
144
+
145
145
+
### Option C: Short-term drag-time freeze only
146
146
+
147
147
+
Pros:
148
148
+
149
149
+
- small
150
150
+
- may help #222 flicker
151
151
+
152
152
+
Cons:
153
153
+
154
154
+
- does not fix repository insertion indicator because row boundaries remain wrong
155
155
+
- leaves the main structural mismatch in place
156
156
+
157
157
+
This can be kept as a subset of Option B, but it is not enough alone.
158
158
+
159
159
+
## Proposed Architecture
160
160
+
161
161
+
### SidebarPresentationModel
162
162
+
163
163
+
Introduce a pure presentation model that flattens current repository state into explicit sidebar units.
164
164
+
165
165
+
Suggested model:
166
166
+
167
167
+
```swift
168
168
+
struct SidebarPresentation: Equatable {
169
169
+
var items: [SidebarItem]
170
170
+
}
171
171
+
172
172
+
enum SidebarItem: Equatable, Identifiable {
173
173
+
case listHeader(SidebarListHeaderModel)
174
174
+
case special(SidebarSpecialRowModel)
175
175
+
case repository(SidebarRepositoryContainerModel)
176
176
+
case failedRepository(FailedRepositoryModel)
177
177
+
}
178
178
+
179
179
+
struct SidebarRepositoryContainerModel: Equatable, Identifiable {
180
180
+
var repositoryID: Repository.ID
181
181
+
var title: String
182
182
+
var rootURL: URL
183
183
+
var kind: Repository.Kind
184
184
+
var isExpanded: Bool
185
185
+
var isRemoving: Bool
186
186
+
var worktreeSections: WorktreeRowSections
187
187
+
}
188
188
+
```
189
189
+
190
190
+
Rules:
191
191
+
192
192
+
- outer `items` contains one item per repository, not one item per row
193
193
+
- worktree sections remain inside the repository container
194
194
+
- presentation construction should be pure and unit-tested
195
195
+
- live terminal state should not be part of the broad presentation model unless required for layout identity
196
196
+
197
197
+
### Selection
198
198
+
199
199
+
Replace `List(selection:)` with explicit selection handling.
200
200
+
201
201
+
Keep `RepositoriesFeature.State.selection` and `sidebarSelectedWorktreeIDs` as the source of truth, but route clicks through helper functions:
202
202
+
203
203
+
- repository header click:
204
204
+
- plain folder: select repository
205
205
+
- git repository: toggle expand by default, or select repository if a future repository-detail mode needs it
206
206
+
- worktree row click:
207
207
+
- normal click: select worktree and focus terminal
208
208
+
- Cmd-click: toggle multi-selection
209
209
+
- Shift-click: optional follow-up, only if current behavior supports it through `List`
210
210
+
- Canvas / Shelf / Archived rows: dispatch existing actions
211
211
+
212
212
+
Selection visuals should be explicit in `RepositoryHeaderRow` and `WorktreeRow`, not inherited from `List`.
213
213
+
214
214
+
### Keyboard Navigation
215
215
+
216
216
+
Preserve the existing command actions first:
217
217
+
218
218
+
- `selectNextWorktree`
219
219
+
- `selectPreviousWorktree`
220
220
+
- `revealSelectedWorktreeInSidebar`
221
221
+
- numbered hotkeys
222
222
+
223
223
+
Do not try to rebuild full Finder-like keyboard navigation in the first pass unless it is currently user-visible and relied upon.
224
224
+
225
225
+
Required V1 behavior:
226
226
+
227
227
+
- command shortcuts still select worktrees
228
228
+
- selected row is scrolled into view on reveal
229
229
+
- focus returns to terminal after single worktree selection
230
230
+
- sidebar focus does not accidentally forward text while Canvas / Shelf rules say it should not
231
231
+
232
232
+
### Repository Reorder
233
233
+
234
234
+
Replace `ForEach(...).onMove` with explicit repository drag/drop.
235
235
+
236
236
+
Suggested approach:
237
237
+
238
238
+
- make `RepositoryContainerRow` draggable with repository ID payload
239
239
+
- render a custom repository insertion indicator between repository containers
240
240
+
- compute drop destination as a repository index
241
241
+
- dispatch existing `.worktreeOrdering(.repositoriesMoved(offsets, destination))` or a new clearer action such as `.repositoriesReordered([Repository.ID])`
242
242
+
243
243
+
The custom indicator should always render at repository container boundaries:
244
244
+
245
245
+
```text
246
246
+
Target Repo header
247
247
+
Target Repo worktree
248
248
+
o-----------
249
249
+
```
250
250
+
251
251
+
This directly fixes the current downward-drag indicator bug.
252
252
+
253
253
+
### Worktree Reorder
254
254
+
255
255
+
Keep worktree reorder scoped inside one repository container.
256
256
+
257
257
+
Suggested approach:
258
258
+
259
259
+
- worktree rows are draggable with worktree ID payload
260
260
+
- pinned and unpinned sections keep separate drop zones
261
261
+
- main and pending rows remain non-movable
262
262
+
- drop destination maps to existing reducer actions:
263
263
+
- `.pinnedWorktreesMoved(repositoryID, offsets, destination)`
264
264
+
- `.unpinnedWorktreesMoved(repositoryID, offsets, destination)`
265
265
+
266
266
+
Cross-repository worktree drag can stay out of scope. The current model does not appear to support moving worktrees between repositories.
267
267
+
268
268
+
### Drag-Time Freeze
269
269
+
270
270
+
Add a small sidebar drag state to suppress non-essential row churn.
271
271
+
272
272
+
During any sidebar drag:
273
273
+
274
274
+
- freeze hover-only row actions
275
275
+
- hide pull request / notification popover affordances that resize rows
276
276
+
- suppress row-ID animations caused by notification-driven reorder
277
277
+
- defer "move notified worktree to top" until drag ends, or apply it without animation after drop
278
278
+
279
279
+
This addresses #222 without requiring every live data read to stop.
280
280
+
281
281
+
### Expand / Collapse
282
282
+
283
283
+
Move expand/collapse animation into `RepositoryContainerRow`.
284
284
+
285
285
+
Rules:
286
286
+
287
287
+
- outer repository container identity must not change when worktrees appear/disappear
288
288
+
- single repo expand/collapse animates child rows inside the container
289
289
+
- bulk expand/collapse updates many containers, but the outer stack still has stable repository items
290
290
+
- avoid animating row identity and live status changes in the same transaction
291
291
+
292
292
+
### Reveal In Sidebar
293
293
+
294
294
+
`ScrollViewReader.scrollTo` can still work, but scroll IDs must be explicit:
295
295
+
296
296
+
- repository container: `SidebarScrollID.repository(repositoryID)`
297
297
+
- worktree row: `SidebarScrollID.worktree(worktreeID)`
298
298
+
- special rows: `SidebarScrollID.canvas`, etc.
299
299
+
300
300
+
When revealing a collapsed worktree:
301
301
+
302
302
+
1. expand its repository
303
303
+
2. yield for layout materialization
304
304
+
3. scroll to `SidebarScrollID.worktree(worktreeID)`
305
305
+
4. consume pending reveal
306
306
+
307
307
+
This matches the current two-yield approach but removes dependency on `List` row materialization.
308
308
+
309
309
+
### Accessibility
310
310
+
311
311
+
Minimum accessibility requirements:
312
312
+
313
313
+
- repository headers expose button/row labels and expanded state
314
314
+
- worktree rows expose selection state
315
315
+
- drag handles or rows expose reorder affordance where AppKit/SwiftUI can support it
316
316
+
- Canvas / Shelf / Archived rows keep meaningful labels
317
317
+
318
318
+
If full native `List` accessibility cannot be matched in V1, document the gap and keep keyboard command coverage strong.
319
319
+
320
320
+
## Implementation Plan
321
321
+
322
322
+
### Phase 0: Baseline and Guardrails
323
323
+
324
324
+
- Add a short manual repro checklist for:
325
325
+
- repository drag up/down over expanded target
326
326
+
- bulk expand/collapse with many repositories
327
327
+
- worktree reorder in pinned/unpinned groups
328
328
+
- sidebar multi-selection
329
329
+
- reveal-in-sidebar
330
330
+
- Add signposts around sidebar presentation build and drag state transitions if trace work is needed.
331
331
+
- Keep current `List` code untouched until presentation tests exist.
332
332
+
333
333
+
### Phase 1: Pure Presentation and Reorder Mapping
334
334
+
335
335
+
Files likely involved:
336
336
+
337
337
+
- `supacode/Features/Repositories/Models/SidebarPresentation.swift` (new)
338
338
+
- `supacodeTests/SidebarPresentationTests.swift` (new)
339
339
+
- existing reducer ordering tests
340
340
+
341
341
+
Deliver:
342
342
+
343
343
+
- pure sidebar presentation builder
344
344
+
- stable scroll IDs
345
345
+
- pure drop-destination mapping for repository and worktree reorder
346
346
+
- tests for:
347
347
+
- expanded repository keeps one outer item with child rows
348
348
+
- failed repositories preserve order
349
349
+
- plain folders produce repository containers with no worktree children
350
350
+
- pinned/main/pending/unpinned sections are preserved
351
351
+
- repository drop destinations map to expected order
352
352
+
- worktree drop destinations map within pinned/unpinned sections
353
353
+
354
354
+
### Phase 2: New Container Views Behind a Switch
355
355
+
356
356
+
Files likely involved:
357
357
+
358
358
+
- `SidebarListView.swift`
359
359
+
- `RepositorySectionView.swift`
360
360
+
- `WorktreeRowsView.swift`
361
361
+
- new `SidebarContainerListView.swift`
362
362
+
- new `RepositoryContainerRow.swift`
363
363
+
364
364
+
Deliver:
365
365
+
366
366
+
- render the new container sidebar behind a local compile-time or private runtime switch
367
367
+
- no reducer changes except new presentation helpers if needed
368
368
+
- preserve row styling visually before enabling custom drag/drop
369
369
+
370
370
+
This phase should be screenshot/manual verified before deleting the old `List` path.
371
371
+
372
372
+
### Phase 3: Explicit Selection and Reveal
373
373
+
374
374
+
Deliver:
375
375
+
376
376
+
- click handling for repository and worktree rows
377
377
+
- explicit selection visuals
378
378
+
- multi-selection behavior matching current sidebar expectations
379
379
+
- reveal-in-sidebar via new scroll IDs
380
380
+
- focused terminal handoff after single worktree selection
381
381
+
382
382
+
Tests:
383
383
+
384
384
+
- pure selection helper tests if logic is factored out
385
385
+
- existing reducer selection tests should keep passing
386
386
+
387
387
+
### Phase 4: Custom Repository Reorder
388
388
+
389
389
+
Deliver:
390
390
+
391
391
+
- repository drag payload
392
392
+
- custom repo-level insertion indicator
393
393
+
- drop handling that dispatches repository reorder
394
394
+
- drag-time UI freeze for non-essential row affordances
395
395
+
396
396
+
Manual verification:
397
397
+
398
398
+
- dragging a repository upward shows indicator below the target repository container when appropriate
399
399
+
- dragging a repository downward never shows the indicator between target header and target worktree rows
400
400
+
- failed repository rows either reorder correctly or are explicitly non-reorderable
401
401
+
402
402
+
### Phase 5: Custom Worktree Reorder
403
403
+
404
404
+
Deliver:
405
405
+
406
406
+
- pinned/unpinned scoped worktree drop zones
407
407
+
- custom worktree insertion indicator
408
408
+
- main/pending rows stay non-movable
409
409
+
- existing persistence paths remain unchanged
410
410
+
411
411
+
Manual verification:
412
412
+
413
413
+
- pinned worktree reorder persists
414
414
+
- unpinned worktree reorder persists
415
415
+
- dragging over main/pending rows does not create invalid moves
416
416
+
417
417
+
### Phase 6: Remove Old `List` Path and Polish
418
418
+
419
419
+
Deliver:
420
420
+
421
421
+
- delete old `List(selection:)` implementation
422
422
+
- remove obsolete `RepositorySectionView` / `WorktreeRowsView` pieces or fold them into new components
423
423
+
- final accessibility pass
424
424
+
- final animation pass for bulk expand/collapse
425
425
+
- update issue #249 with final implementation notes
426
426
+
427
427
+
## Verification Matrix
428
428
+
429
429
+
Automated:
430
430
+
431
431
+
- `SidebarPresentationTests`
432
432
+
- existing `RepositoriesFeatureTests` ordering tests
433
433
+
- existing `RepositorySectionViewTests` migrated or renamed
434
434
+
- `make check`
435
435
+
- `make build-app`
436
436
+
437
437
+
Manual:
438
438
+
439
439
+
1. Select a plain folder repository row.
440
440
+
2. Select a git repository worktree row and confirm terminal focus.
441
441
+
3. Cmd-click multiple worktree rows and confirm bulk archive/delete commands still target selected rows.
442
442
+
4. Expand/collapse one repository.
443
443
+
5. Bulk expand/collapse at least 10 repositories.
444
444
+
6. Drag repository upward and downward across expanded repositories.
445
445
+
7. Drag pinned worktrees within a repository.
446
446
+
8. Drag unpinned worktrees within a repository.
447
447
+
9. Trigger reveal-in-sidebar from Canvas or command.
448
448
+
10. Verify Canvas / Shelf / Archived rows remain selectable.
449
449
+
11. Verify notification/task/run-script indicators update without moving rows during a drag.
450
450
+
451
451
+
## Risks
452
452
+
453
453
+
### Native `List` behavior loss
454
454
+
455
455
+
Risk: custom scroll rows may lose some free AppKit sidebar behavior.
456
456
+
457
457
+
Mitigation:
458
458
+
459
459
+
- preserve command-based navigation first
460
460
+
- add explicit accessibility labels/traits
461
461
+
- keep manual keyboard/accessibility checklist
462
462
+
463
463
+
### Reorder implementation complexity
464
464
+
465
465
+
Risk: custom drag/drop can become more complex than native `.onMove`.
466
466
+
467
467
+
Mitigation:
468
468
+
469
469
+
- keep pure drop-index mapping tested
470
470
+
- keep repository reorder and worktree reorder separate
471
471
+
- defer cross-repository worktree moves
472
472
+
473
473
+
### UI regressions from broad rewrite
474
474
+
475
475
+
Risk: replacing the sidebar in one PR touches selection, animation, and drag.
476
476
+
477
477
+
Mitigation:
478
478
+
479
479
+
- stage behind a private switch until visual behavior is verified
480
480
+
- land presentation model tests first
481
481
+
- keep reducer actions and persistence shape stable
482
482
+
483
483
+
### Performance regressions
484
484
+
485
485
+
Risk: replacing lazy `List` with `VStack` could render too much.
486
486
+
487
487
+
Mitigation:
488
488
+
489
489
+
- start with `LazyVStack`
490
490
+
- switch only repository containers to non-lazy child stacks if expand/collapse animation needs it
491
491
+
- measure with the existing signpost / Instruments workflow if the sidebar feels worse
492
492
+
493
493
+
## Recommendation
494
494
+
495
495
+
Proceed with Option B as the #249 plan: a custom `ScrollView` sidebar with repository containers as outer items.
496
496
+
497
497
+
Do not attempt to fix the repository insertion indicator through reducer index changes. The indicator is a symptom of the current `List` row structure, not the persisted ordering logic.
498
498
+
499
499
+
The safest execution path is:
500
500
+
501
501
+
1. pure presentation model and tests
502
502
+
2. render-only new sidebar path
503
503
+
3. explicit selection/reveal
504
504
+
4. custom repository reorder
505
505
+
5. custom worktree reorder
506
506
+
6. remove old `List` path
507
507
+
508
508
+
This is larger than a tactical #222 fix, but it addresses the underlying sidebar design mismatch and gives future sidebar features a cleaner foundation.