docs(systemviews): map CRUD parity plan
- commit
- 8c27e698c90535e77bb0c52deb784dcc8fed8863
- author
- brice · · 2026-04-24 01:48 UTC
- parent
- d84415e
- signature
- GPG Verified
CD88F9E564E0102646FB6077A1A07C7C7C3E349D· arch-gpg Verified for the committer email
1 file · +105 -0
A docs/systemviews-wasm-crud-plan.md +105 -0
| @@ -0,0 +1,105 @@ | |||
| 1 | + | # Systemviews WASM CRUD and Architecture Plan | |
| 2 | + | ||
| 3 | + | This note captures the parity target for the `feat/systemviews-wasm` branch after merging `main`. | |
| 4 | + | ||
| 5 | + | ## Current branch baseline | |
| 6 | + | ||
| 7 | + | - Worktree: `.worktrees/feat/systemviews-wasm` | |
| 8 | + | - Branch: `feat/systemviews-wasm` | |
| 9 | + | - Merge baseline: `d84415e5` (`Merge branch 'main' into feat/systemviews-wasm`) | |
| 10 | + | - Vendor baseline: `go mod vendor` has been run in the worktree and `go list -mod=vendor ./...` succeeds there. | |
| 11 | + | - Root-checkout diagnostics may still report vendoring issues because the editor diagnostics point at `/home/brice/dev/projects/dumber`, not this branch worktree. | |
| 12 | + | ||
| 13 | + | ## Clean architecture contract | |
| 14 | + | ||
| 15 | + | Keep the dependency direction explicit: | |
| 16 | + | ||
| 17 | + | | Layer | Role for systemviews | Must not do | | |
| 18 | + | | --- | --- | --- | | |
| 19 | + | | `internal/domain` | Pure entities/value objects and pure helpers such as history range parsing. | Import ports, usecases, adapters, GTK/CEF/WebKit, or config packages. | | |
| 20 | + | | `internal/application/usecase` | Own favorites/history/config/keybinding behavior and validation. | Import infrastructure adapters or UI packages. | | |
| 21 | + | | `internal/application/port` | Define the systemview-facing contracts and DTOs. | Depend on CEF/WebKit/SQLite/config concrete types. | | |
| 22 | + | | `internal/infrastructure/*` | Implement handlers, scheme serving, bridge transports, persistence, config payload readers. | Put UI workflow or business rules here. | | |
| 23 | + | | `internal/ui/systemviews` | Render and orchestrate WASM UI through ports. | Call repositories, config package, CEF/WebKit, or SQLite directly. | | |
| 24 | + | | `internal/ui/dispatcher` / coordinators | Convert native actions into pane/tab/navigation orchestration. | Bypass usecases for domain state changes. | | |
| 25 | + | ||
| 26 | + | Preferred direction for new work: | |
| 27 | + | ||
| 28 | + | 1. Add behavior to existing usecases first when it is business logic. | |
| 29 | + | 2. Expose it through application ports. | |
| 30 | + | 3. Implement WebUI/systemview handlers in `internal/infrastructure/handlers`. | |
| 31 | + | 4. Consume those handlers from `internal/infrastructure/systemviewsbridge`. | |
| 32 | + | 5. Render and bind user interactions in `internal/ui/systemviews`. | |
| 33 | + | ||
| 34 | + | ## Old Svelte UI CRUD matrix | |
| 35 | + | ||
| 36 | + | ### History (`webui/src/pages/homepage/*`) | |
| 37 | + | ||
| 38 | + | | Operation | Old Svelte surface | Backend message/API | Current WASM status | Gap | | |
| 39 | + | | --- | --- | --- | --- | --- | | |
| 40 | + | | Read timeline | `HistoryPanel.svelte`, `HistoryTimeline.svelte`, `HistoryItem.svelte` | `history_timeline` | Present, but bare list only (`internal/ui/systemviews/history_view.go`). | Add pagination, loading/error/empty states, row metadata, favicons, visit counts. | | |
| 41 | + | | Read/search | `HistorySearch.svelte`, `keyboard.ts` local fuzzy + FTS | `history_search_fts` | Bridge client supports it. | Add search UI, debounce/local filtering, FTS fallback, visible result count. | | |
| 42 | + | | Read filters/stats | `HistoryFilters.svelte`, `AnalyticsPanel.svelte` | `history_domain_stats`, `history_analytics` | Bridge client supports both; config route renders keybinding/config summaries only. | Add domain chips, stats summary, analytics cards/charts or text equivalent. | | |
| 43 | + | | Create | Browser navigation writes history outside the systemview UI. | Existing history repository/usecases. | Not a user-facing CRUD action. | No manual create needed. | | |
| 44 | + | | Update | Not supported in old UI. | None. | None. | Keep out of scope unless a future title-edit requirement appears. | | |
| 45 | + | | Delete one | `HistoryItem.svelte`, `keyboard.ts` | `history_delete_entry` | Bridge client supports it; UI not interactive. | Add row delete action with confirmation and refresh. | | |
| 46 | + | | Delete range/all | `HistoryCleanup.svelte`, `keyboard.ts` | `history_delete_range`, `history_clear_all` | Bridge client supports range; route UI not interactive. | Add cleanup modal/actions for hour/day/week/month/all. | | |
| 47 | + | | Delete domain | `keyboard.ts`, `HistoryFilters.svelte` | `history_delete_domain` | Bridge client supports it. | Add domain-action UI and confirmation. | | |
| 48 | + | | Open row | `navigateTo(entry.url)` | Browser navigation | Static links exist. | Add keyboard open and active-row focus management. | | |
| 49 | + | ||
| 50 | + | ### Favorites, folders, tags (`webui/src/pages/homepage/favorites/*`) | |
| 51 | + | ||
| 52 | + | | Operation | Old Svelte surface | Backend message/API | Current WASM status | Gap | | |
| 53 | + | | --- | --- | --- | --- | --- | | |
| 54 | + | | Read favorites | `FavoritesPanel.svelte`, `FavoriteGrid.svelte`, `FavoriteCard.svelte` | `favorite_list` | Present, but bare link list (`favorites_view.go`). | Add rich rows/cards, favicons, shortcut badges, folder/tag metadata. | | |
| 55 | + | | Create favorite | Old homepage hints imply adding/pinning from history; native omnibox toggle exists outside this page. | `ManageFavoritesUseCase.Add` exists, but no homepage/systemview message. | Missing from `port.HomepageFavorites`/`SystemviewFavoritesService` and handlers. | Add `favorite_create` handler/bridge and UI. | | |
| 56 | + | | Update favorite | `FavoriteEditor.svelte` locally updates title and uses folder/shortcut/tag handlers. | `favorite_set_shortcut`, `favorite_set_folder`, `tag_assign`, `tag_remove`; no title update handler. | Partial bridge support. | Add `favorite_update` for title/favicon/url policy; keep folder/shortcut/tag specialized calls or fold into update after design. | | |
| 57 | + | | Delete favorite | `FavoriteEditor.svelte` local-only delete placeholder. | `ManageFavoritesUseCase.Remove` exists, but no homepage/systemview message. | Missing. | Add `favorite_delete` handler/bridge/UI. | | |
| 58 | + | | Read folders | `FolderList.svelte` | `folder_list` | Present as static list. | Add counts, selected filter, empty state. | | |
| 59 | + | | Create folder | `FolderList.svelte` inline create | `folder_create` | Bridge and handler exist. | Add interactive UI. | | |
| 60 | + | | Update folder | Handler exists (`folder_update`). | `folder_update` | Bridge exists. | Add rename/icon UI. | | |
| 61 | + | | Delete folder | Handler exists (`folder_delete`). | `folder_delete` | Bridge exists. | Add UI, confirm, refresh favorite folder state. | | |
| 62 | + | | Read tags | `TagCloud.svelte` | `tag_list` | Present as static list. | Add color chips and selection. | | |
| 63 | + | | Create tag | `TagCloud.svelte` inline create | `tag_create` | Bridge and handler exist. | Add UI with color picker/palette. | | |
| 64 | + | | Update tag | Handler exists (`tag_update`). | `tag_update` | Bridge exists. | Add rename/color edit UI. | | |
| 65 | + | | Delete tag | Handler exists (`tag_delete`). | `tag_delete` | Bridge exists. | Add confirm UI and refresh assignments. | | |
| 66 | + | | Assign/remove tag | `FavoriteEditor.svelte` | `tag_assign`, `tag_remove` | Bridge exists. | Add editor UI. | | |
| 67 | + | ||
| 68 | + | ### Config and keybindings (`webui/src/pages/ConfigPage.svelte`, `webui/src/pages/config/*`) | |
| 69 | + | ||
| 70 | + | | Operation | Old Svelte surface | Backend message/API | Current WASM status | Gap | | |
| 71 | + | | --- | --- | --- | --- | --- | | |
| 72 | + | | Read config | `ConfigPage.svelte` | `/api/config` | Bridge supports direct API and route renders flattened values. | Replace flattened read-only view with grouped editable forms. | | |
| 73 | + | | Read defaults | Reset dialog in `ConfigPage.svelte` | `/api/config/default` | Bridge supports direct API. | Add reset-to-default flow. | | |
| 74 | + | | Save config | `save_config` via native bridge | `save_config` | Bridge supports it. Existing app config watcher hot-reloads appearance/keybindings/engine settings. | Add form save flow, validation, success/error UI, refresh after save. | | |
| 75 | + | | Appearance update | Fonts, UI scale, color scheme, palettes | `save_config` | Payload shape exists in `SystemviewConfigPayload`. | Add form controls and palette validation. | | |
| 76 | + | | Search shortcuts CRUD | `ShortcutsTable.svelte` | Saved inside config payload | Missing interactive UI. | Add table/list editing and `%s`/`{query}` validation. | | |
| 77 | + | | Performance update | Performance tab | `save_config` | Payload shape exists; CEF gating needed. | Add profile/custom fields and restart warning. | | |
| 78 | + | | Keybindings read | `KeybindingsTab.svelte` | `get_keybindings` | Route renders read-only keybinding groups. | Add editable keybinding UI. | | |
| 79 | + | | Keybindings update | `KeyCaptureModal.svelte` | `set_keybinding`, `reset_keybinding`, `reset_all_keybindings` | Bridge supports message types. | Add capture/reset UI and conflict display. | | |
| 80 | + | ||
| 81 | + | ## Native shortcut and split-pane target | |
| 82 | + | ||
| 83 | + | Add first-class global actions: | |
| 84 | + | ||
| 85 | + | | Action | Default key | Target behavior | | |
| 86 | + | | --- | --- | --- | | |
| 87 | + | | `open_history_systemview` | `ctrl+h` | Split active pane to the right with `dumb://history`, or focus an existing history systemview pane if the chosen behavior is focus-first. | | |
| 88 | + | | `open_favorites_systemview` | Proposed: unset by default or `ctrl+shift+h` only if accepted. | Split/focus `dumb://favorites`. | | |
| 89 | + | | `open_config_systemview` | Proposed: unset by default to avoid conflicts; user can bind in config. | Split/focus `dumb://config`. | | |
| 90 | + | ||
| 91 | + | Implementation path: | |
| 92 | + | ||
| 93 | + | 1. Add input actions in `internal/ui/input/shortcuts.go` and config defaults/schema in `internal/infrastructure/config`. | |
| 94 | + | 2. Map the actions in global shortcuts and keybinding DTOs. | |
| 95 | + | 3. Add a coordinator method such as `WorkspaceCoordinator.SplitURL(ctx, SplitRight, "dumb://history")` so dispatcher does not manipulate pane internals. | |
| 96 | + | 4. Use existing `ManagePanesUseCase.Split` with `SplitPaneInput.InitialURL` to keep domain/usecase clean. | |
| 97 | + | 5. Add tests in input, dispatcher, config defaults/schema, and workspace coordinator. | |
| 98 | + | ||
| 99 | + | ## Implementation notes | |
| 100 | + | ||
| 101 | + | - Do not resurrect `webui/`; the branch intentionally removed Svelte assets. | |
| 102 | + | - Keep WASM UI code small and stateful. Avoid pushing business rules into HTML string helpers. | |
| 103 | + | - Prefer explicit bridge request methods over ad-hoc message strings in UI code. | |
| 104 | + | - Every destructive action needs confirmation and a visible refresh/error path. | |
| 105 | + | - Every feature should remain usable by keyboard because these pages are browser management surfaces, not marketing pages. | |
| @@ -0,0 +1,105 @@ | |||||
| 1 | + | # Systemviews WASM CRUD and Architecture Plan | |||
| 2 | + | ||||
| 3 | + | This note captures the parity target for the `feat/systemviews-wasm` branch after merging `main`. | |||
| 4 | + | ||||
| 5 | + | ## Current branch baseline | |||
| 6 | + | ||||
| 7 | + | - Worktree: `.worktrees/feat/systemviews-wasm` | |||
| 8 | + | - Branch: `feat/systemviews-wasm` | |||
| 9 | + | - Merge baseline: `d84415e5` (`Merge branch 'main' into feat/systemviews-wasm`) | |||
| 10 | + | - Vendor baseline: `go mod vendor` has been run in the worktree and `go list -mod=vendor ./...` succeeds there. | |||
| 11 | + | - Root-checkout diagnostics may still report vendoring issues because the editor diagnostics point at `/home/brice/dev/projects/dumber`, not this branch worktree. | |||
| 12 | + | ||||
| 13 | + | ## Clean architecture contract | |||
| 14 | + | ||||
| 15 | + | Keep the dependency direction explicit: | |||
| 16 | + | ||||
| 17 | + | | Layer | Role for systemviews | Must not do | | |||
| 18 | + | | --- | --- | --- | | |||
| 19 | + | | `internal/domain` | Pure entities/value objects and pure helpers such as history range parsing. | Import ports, usecases, adapters, GTK/CEF/WebKit, or config packages. | | |||
| 20 | + | | `internal/application/usecase` | Own favorites/history/config/keybinding behavior and validation. | Import infrastructure adapters or UI packages. | | |||
| 21 | + | | `internal/application/port` | Define the systemview-facing contracts and DTOs. | Depend on CEF/WebKit/SQLite/config concrete types. | | |||
| 22 | + | | `internal/infrastructure/*` | Implement handlers, scheme serving, bridge transports, persistence, config payload readers. | Put UI workflow or business rules here. | | |||
| 23 | + | | `internal/ui/systemviews` | Render and orchestrate WASM UI through ports. | Call repositories, config package, CEF/WebKit, or SQLite directly. | | |||
| 24 | + | | `internal/ui/dispatcher` / coordinators | Convert native actions into pane/tab/navigation orchestration. | Bypass usecases for domain state changes. | | |||
| 25 | + | ||||
| 26 | + | Preferred direction for new work: | |||
| 27 | + | ||||
| 28 | + | 1. Add behavior to existing usecases first when it is business logic. | |||
| 29 | + | 2. Expose it through application ports. | |||
| 30 | + | 3. Implement WebUI/systemview handlers in `internal/infrastructure/handlers`. | |||
| 31 | + | 4. Consume those handlers from `internal/infrastructure/systemviewsbridge`. | |||
| 32 | + | 5. Render and bind user interactions in `internal/ui/systemviews`. | |||
| 33 | + | ||||
| 34 | + | ## Old Svelte UI CRUD matrix | |||
| 35 | + | ||||
| 36 | + | ### History (`webui/src/pages/homepage/*`) | |||
| 37 | + | ||||
| 38 | + | | Operation | Old Svelte surface | Backend message/API | Current WASM status | Gap | | |||
| 39 | + | | --- | --- | --- | --- | --- | | |||
| 40 | + | | Read timeline | `HistoryPanel.svelte`, `HistoryTimeline.svelte`, `HistoryItem.svelte` | `history_timeline` | Present, but bare list only (`internal/ui/systemviews/history_view.go`). | Add pagination, loading/error/empty states, row metadata, favicons, visit counts. | | |||
| 41 | + | | Read/search | `HistorySearch.svelte`, `keyboard.ts` local fuzzy + FTS | `history_search_fts` | Bridge client supports it. | Add search UI, debounce/local filtering, FTS fallback, visible result count. | | |||
| 42 | + | | Read filters/stats | `HistoryFilters.svelte`, `AnalyticsPanel.svelte` | `history_domain_stats`, `history_analytics` | Bridge client supports both; config route renders keybinding/config summaries only. | Add domain chips, stats summary, analytics cards/charts or text equivalent. | | |||
| 43 | + | | Create | Browser navigation writes history outside the systemview UI. | Existing history repository/usecases. | Not a user-facing CRUD action. | No manual create needed. | | |||
| 44 | + | | Update | Not supported in old UI. | None. | None. | Keep out of scope unless a future title-edit requirement appears. | | |||
| 45 | + | | Delete one | `HistoryItem.svelte`, `keyboard.ts` | `history_delete_entry` | Bridge client supports it; UI not interactive. | Add row delete action with confirmation and refresh. | | |||
| 46 | + | | Delete range/all | `HistoryCleanup.svelte`, `keyboard.ts` | `history_delete_range`, `history_clear_all` | Bridge client supports range; route UI not interactive. | Add cleanup modal/actions for hour/day/week/month/all. | | |||
| 47 | + | | Delete domain | `keyboard.ts`, `HistoryFilters.svelte` | `history_delete_domain` | Bridge client supports it. | Add domain-action UI and confirmation. | | |||
| 48 | + | | Open row | `navigateTo(entry.url)` | Browser navigation | Static links exist. | Add keyboard open and active-row focus management. | | |||
| 49 | + | ||||
| 50 | + | ### Favorites, folders, tags (`webui/src/pages/homepage/favorites/*`) | |||
| 51 | + | ||||
| 52 | + | | Operation | Old Svelte surface | Backend message/API | Current WASM status | Gap | | |||
| 53 | + | | --- | --- | --- | --- | --- | | |||
| 54 | + | | Read favorites | `FavoritesPanel.svelte`, `FavoriteGrid.svelte`, `FavoriteCard.svelte` | `favorite_list` | Present, but bare link list (`favorites_view.go`). | Add rich rows/cards, favicons, shortcut badges, folder/tag metadata. | | |||
| 55 | + | | Create favorite | Old homepage hints imply adding/pinning from history; native omnibox toggle exists outside this page. | `ManageFavoritesUseCase.Add` exists, but no homepage/systemview message. | Missing from `port.HomepageFavorites`/`SystemviewFavoritesService` and handlers. | Add `favorite_create` handler/bridge and UI. | | |||
| 56 | + | | Update favorite | `FavoriteEditor.svelte` locally updates title and uses folder/shortcut/tag handlers. | `favorite_set_shortcut`, `favorite_set_folder`, `tag_assign`, `tag_remove`; no title update handler. | Partial bridge support. | Add `favorite_update` for title/favicon/url policy; keep folder/shortcut/tag specialized calls or fold into update after design. | | |||
| 57 | + | | Delete favorite | `FavoriteEditor.svelte` local-only delete placeholder. | `ManageFavoritesUseCase.Remove` exists, but no homepage/systemview message. | Missing. | Add `favorite_delete` handler/bridge/UI. | | |||
| 58 | + | | Read folders | `FolderList.svelte` | `folder_list` | Present as static list. | Add counts, selected filter, empty state. | | |||
| 59 | + | | Create folder | `FolderList.svelte` inline create | `folder_create` | Bridge and handler exist. | Add interactive UI. | | |||
| 60 | + | | Update folder | Handler exists (`folder_update`). | `folder_update` | Bridge exists. | Add rename/icon UI. | | |||
| 61 | + | | Delete folder | Handler exists (`folder_delete`). | `folder_delete` | Bridge exists. | Add UI, confirm, refresh favorite folder state. | | |||
| 62 | + | | Read tags | `TagCloud.svelte` | `tag_list` | Present as static list. | Add color chips and selection. | | |||
| 63 | + | | Create tag | `TagCloud.svelte` inline create | `tag_create` | Bridge and handler exist. | Add UI with color picker/palette. | | |||
| 64 | + | | Update tag | Handler exists (`tag_update`). | `tag_update` | Bridge exists. | Add rename/color edit UI. | | |||
| 65 | + | | Delete tag | Handler exists (`tag_delete`). | `tag_delete` | Bridge exists. | Add confirm UI and refresh assignments. | | |||
| 66 | + | | Assign/remove tag | `FavoriteEditor.svelte` | `tag_assign`, `tag_remove` | Bridge exists. | Add editor UI. | | |||
| 67 | + | ||||
| 68 | + | ### Config and keybindings (`webui/src/pages/ConfigPage.svelte`, `webui/src/pages/config/*`) | |||
| 69 | + | ||||
| 70 | + | | Operation | Old Svelte surface | Backend message/API | Current WASM status | Gap | | |||
| 71 | + | | --- | --- | --- | --- | --- | | |||
| 72 | + | | Read config | `ConfigPage.svelte` | `/api/config` | Bridge supports direct API and route renders flattened values. | Replace flattened read-only view with grouped editable forms. | | |||
| 73 | + | | Read defaults | Reset dialog in `ConfigPage.svelte` | `/api/config/default` | Bridge supports direct API. | Add reset-to-default flow. | | |||
| 74 | + | | Save config | `save_config` via native bridge | `save_config` | Bridge supports it. Existing app config watcher hot-reloads appearance/keybindings/engine settings. | Add form save flow, validation, success/error UI, refresh after save. | | |||
| 75 | + | | Appearance update | Fonts, UI scale, color scheme, palettes | `save_config` | Payload shape exists in `SystemviewConfigPayload`. | Add form controls and palette validation. | | |||
| 76 | + | | Search shortcuts CRUD | `ShortcutsTable.svelte` | Saved inside config payload | Missing interactive UI. | Add table/list editing and `%s`/`{query}` validation. | | |||
| 77 | + | | Performance update | Performance tab | `save_config` | Payload shape exists; CEF gating needed. | Add profile/custom fields and restart warning. | | |||
| 78 | + | | Keybindings read | `KeybindingsTab.svelte` | `get_keybindings` | Route renders read-only keybinding groups. | Add editable keybinding UI. | | |||
| 79 | + | | Keybindings update | `KeyCaptureModal.svelte` | `set_keybinding`, `reset_keybinding`, `reset_all_keybindings` | Bridge supports message types. | Add capture/reset UI and conflict display. | | |||
| 80 | + | ||||
| 81 | + | ## Native shortcut and split-pane target | |||
| 82 | + | ||||
| 83 | + | Add first-class global actions: | |||
| 84 | + | ||||
| 85 | + | | Action | Default key | Target behavior | | |||
| 86 | + | | --- | --- | --- | | |||
| 87 | + | | `open_history_systemview` | `ctrl+h` | Split active pane to the right with `dumb://history`, or focus an existing history systemview pane if the chosen behavior is focus-first. | | |||
| 88 | + | | `open_favorites_systemview` | Proposed: unset by default or `ctrl+shift+h` only if accepted. | Split/focus `dumb://favorites`. | | |||
| 89 | + | | `open_config_systemview` | Proposed: unset by default to avoid conflicts; user can bind in config. | Split/focus `dumb://config`. | | |||
| 90 | + | ||||
| 91 | + | Implementation path: | |||
| 92 | + | ||||
| 93 | + | 1. Add input actions in `internal/ui/input/shortcuts.go` and config defaults/schema in `internal/infrastructure/config`. | |||
| 94 | + | 2. Map the actions in global shortcuts and keybinding DTOs. | |||
| 95 | + | 3. Add a coordinator method such as `WorkspaceCoordinator.SplitURL(ctx, SplitRight, "dumb://history")` so dispatcher does not manipulate pane internals. | |||
| 96 | + | 4. Use existing `ManagePanesUseCase.Split` with `SplitPaneInput.InitialURL` to keep domain/usecase clean. | |||
| 97 | + | 5. Add tests in input, dispatcher, config defaults/schema, and workspace coordinator. | |||
| 98 | + | ||||
| 99 | + | ## Implementation notes | |||
| 100 | + | ||||
| 101 | + | - Do not resurrect `webui/`; the branch intentionally removed Svelte assets. | |||
| 102 | + | - Keep WASM UI code small and stateful. Avoid pushing business rules into HTML string helpers. | |||
| 103 | + | - Prefer explicit bridge request methods over ad-hoc message strings in UI code. | |||
| 104 | + | - Every destructive action needs confirmation and a visible refresh/error path. | |||
| 105 | + | - Every feature should remain usable by keyboard because these pages are browser management surfaces, not marketing pages. | |||