M1.8: command palette, global keymap, UI commands
- Engine: ui.registerCommands (validated, replaces the previous set),
UI commands in listCommands with ui: true and labelKey, running one
through the engine emits uiCommand {id, params}.
- Frontend: ui/src/commands/ (keymap by key code, fuzzy ranking, Pinia
commands store with handlers, recents and error toasts), the command
palette (Mod+Shift+P), UI commands palette.open, settings.open (Mod+,,
disabled until M1.9b) and view.toggleProjectTree (Mod+1). The editor's
shortcuts.ts moved into the global keymap.
- Tests: engine and control-channel tests for registration and
uiCommand, Vitest for keymap, ranking, store, palette and App wiring.
- Docs: architecture, ui-parity, target-app-parity, gaps, roadmap,
ROADMAP, README.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
parent
2f8fef876b
commit
184b8a3468
33 changed files with 2282 additions and 233 deletions
|
|
@ -1,6 +1,6 @@
|
|||
# Architecture
|
||||
|
||||
> **Status:** M0 decisions recorded, M1 workspace, desktop bridge, tabs and editor, message catalog, engine construction, settings, themes, the recovery journal and notifications documented · **Last updated:** 2026-10-16
|
||||
> **Status:** M0 decisions recorded, M1 workspace, desktop bridge, tabs and editor, message catalog, engine construction, settings, themes, the recovery journal, notifications, UI commands and the palette documented · **Last updated:** 2026-10-16
|
||||
|
||||
## Overview
|
||||
|
||||
|
|
@ -47,6 +47,7 @@ As built in M0:
|
|||
- Effects are requests the engine cannot fulfil below L6 (`Effect::Quit` so far). The host (desktop, tests) applies them after the command returns. Commands never call into Tauri.
|
||||
- `EngineError` has a stable string `code()` used by the control channel and the frontend: `unknown_command`, `disabled` (e.g. a file command without a project), `invalid_params`, `stale_version` (a `buffer.edit` based on an old version), `unsaved_changes` (closing a dirty buffer or project without `force`), `failed`, `internal`.
|
||||
- Shortcut notation: `Mod` is Ctrl on Windows and Linux and Cmd on macOS (`Mod+Q`). Default shortcuts are Lutra's own.
|
||||
- UI commands (M1.8) are the frontend's own commands, listed next to the engine's; see UI commands, palette and keymap below.
|
||||
|
||||
## Guard
|
||||
|
||||
|
|
@ -78,7 +79,7 @@ Theme tokens are defined in Rust (`lutra_engine::theme`) and rendered as CSS cus
|
|||
|
||||
### Events
|
||||
|
||||
`lutra_engine::Event`, serialised as `{"kind": "<camelCase>", ...}`: `projectOpened {root, name}`, `projectClosed`, `treeChanged {dir}`, `bufferOpened {id, path}`, `bufferFocused {id}` (M1.13), `bufferChanged {id, version}`, `dirtyChanged {id, dirty}`, `bufferClosed {id}`, `fileChangedOnDisk {path, id, removed}`, `watchFailed {message}`, `recoveryAvailable {entries}` (M1.7, see Recovery journal). Events say what changed; clients fetch data with `project.children` and `buffer.get`. `file.open` on a file whose buffer is already open returns that buffer and emits `bufferFocused {id}` instead of `bufferOpened` (M1.13): a separate event, so that `bufferOpened` keeps meaning "a new buffer exists" (the host's `engine_ready` replay and other clients rely on that) while every client, including the editor, still learns that the user asked to see that buffer and activates its tab.
|
||||
`lutra_engine::Event`, serialised as `{"kind": "<camelCase>", ...}`: `projectOpened {root, name}`, `projectClosed`, `treeChanged {dir}`, `bufferOpened {id, path}`, `bufferFocused {id}` (M1.13), `bufferChanged {id, version}`, `dirtyChanged {id, dirty}`, `bufferClosed {id}`, `fileChangedOnDisk {path, id, removed}`, `watchFailed {message}`, `recoveryAvailable {entries}` (M1.7, see Recovery journal), `uiCommand {id, params}` (M1.8, see UI commands). Events say what changed; clients fetch data with `project.children` and `buffer.get`. `file.open` on a file whose buffer is already open returns that buffer and emits `bufferFocused {id}` instead of `bufferOpened` (M1.13): a separate event, so that `bufferOpened` keeps meaning "a new buffer exists" (the host's `engine_ready` replay and other clients rely on that) while every client, including the editor, still learns that the user asked to see that buffer and activates its tab.
|
||||
|
||||
Changes on disk reach the engine through `Engine::pump_vfs()`, which hosts call regularly (the desktop's pump thread every 100 ms; tests call it directly). It maps VFS events to `treeChanged` for the parent directories, reloads a clean buffer whose file changed (unless the file already matches, as after our own save) with `bufferChanged`, and reports `fileChangedOnDisk` for a dirty buffer, which keeps its text, or for a removed file. At most 10,000 VFS events are handled per pump.
|
||||
|
||||
|
|
@ -97,7 +98,7 @@ Watched directories: the VFS watcher is non-recursive, so `project.children` wat
|
|||
- `ui/src/stores/editor.ts` holds the tabs (buffer id, path, dirty, notice), the active tab and the close question. It adds a tab from the `file.open` result (opened from the tree) or, for a `bufferOpened` event it did not cause (control channel, replay after a reload), from `buffer.get`. `bufferClosed`, `dirtyChanged`, `fileChangedOnDisk` and project open/close update it; `bufferFocused` activates the tab and outranks adoptions still fetching, so the most recent open wins. The project tree ends a directory the engine listed only partly (`truncated`) with a note row (`project.tree.truncated`). `ui/src/components/editor/engineEvents.ts` checks event fields before the store sees them.
|
||||
- One `BufferSync` per tab (`ui/src/components/editor/bufferSync.ts`) owns the tab's CodeMirror `EditorState`; one `EditorView` shows the active tab's state, so undo history and selection survive tab switches. Every transaction goes through the sync. Local changes are sent with `buffer.edit` against the confirmed version, one call in flight, later keystrokes composed into the next call. On `stale_version`, or a `bufferChanged` with a newer version than ours, the sync fetches `buffer.get`, diffs it against the confirmed text, rebases unsent local changes over that diff (CodeMirror change-set mapping) and applies the remote part to the editor without adding it to undo history. A refused edit (other than stale) is reported and the editor returns to the engine text.
|
||||
- Line breaks: the engine keeps text as on disk and counts `\r\n` as two UTF-16 units; CodeMirror counts every break as one position. `EngineText` remembers which breaks are `\r\n` and converts positions when building edits; inserted breaks are sent with the buffer's line ending, so a CRLF file stays CRLF in memory. Text without `\r\n` (the common case) needs no table.
|
||||
- Save, save all and close run from the engine's default shortcuts (`file.save` `Mod+S`, `file.saveAll` `Mod+Alt+S`, `buffer.close` `Mod+W`), loaded with `listCommands` and matched by key code, with the active buffer as context. Saving and closing wait until the sync has no pending edits.
|
||||
- Save, save all and close run from the engine's default shortcuts (`file.save` `Mod+S`, `file.saveAll` `Mod+Alt+S`, `buffer.close` `Mod+W`), loaded with `listCommands` and matched by key code, with the active buffer as context; since M1.8 through the global keymap (see UI commands, palette and keymap). Saving and closing wait until the sync has no pending edits.
|
||||
- Closing a dirty tab asks Save / Don't Save / Cancel; `buffer.close` without `force` failing with `unsaved_changes` also leads to the question. Lutra saves only on request for now (no autosave).
|
||||
- Theme: the editor reads colours only from `--lt-*` tokens, including the editor tokens from M1.10 (selection, active line, cursor, gutter, match, editor font size); no fallbacks remain.
|
||||
|
||||
|
|
@ -151,6 +152,36 @@ Watched directories: the VFS watcher is non-recursive, so `project.children` wat
|
|||
- **UI:** `ui/src/components/recovery/` (store `recovery.ts`, `RecoveryDialog.vue`, mounted in `App.vue`). The list comes from `recoveryAvailable` and, because that event is not replayed after a page reload, from `recovery.list` on `projectOpened`. Restore all, Restore selected (the rest stay listed) and Discard always pass explicit paths; Escape closes and keeps the journal for the next open.
|
||||
- **Limits:** two Lutra instances on the same project share one journal directory; `diskChanged` misses a disk change that happened before the last journal write.
|
||||
|
||||
### UI commands, palette and keymap (M1.8)
|
||||
|
||||
- **Registration:** the frontend calls `ui.registerCommands {commands: [{id, labelKey, menuPath?, defaultShortcut?}]}` when it starts (`ui/src/commands/store.ts`). A registration replaces the previous one, so a page reload registers again. The engine keeps them in `State::ui_commands` (`crates/engine/src/cmd/ui.rs`). It checks every entry and changes nothing on a bad one (`invalid_params`):
|
||||
- ids have the `area.action` shape (ASCII alphanumeric parts), at most 128 bytes;
|
||||
- an id may not be an engine command or listed twice;
|
||||
- `labelKey` is not empty;
|
||||
- texts are at most 256 bytes; at most 1,000 commands.
|
||||
- **Listing:** `listCommands` returns one list in id order: engine commands and UI commands. `CommandInfo` has `ui: bool`; UI commands also carry `labelKey`, use it as `label` (the engine has no English for them) and are always `enabled` as far as the engine knows.
|
||||
- **Running from outside:** `Engine::execute` on a UI command id queues `uiCommand {id, params}` and returns `null` (params are passed on unchanged). The desktop publishes the event to the window and to control subscribers like any other. The frontend runs the command, so `engine.execute palette.open` over the control channel opens the palette. A `uiCommand` the frontend cannot run (no handler, or disabled) becomes a warning toast.
|
||||
- **Frontend:** `ui/src/commands/`:
|
||||
- `uiCommands.ts` lists the UI commands: `palette.open` `Mod+Shift+P`, `settings.open` `Mod+,`, `view.toggleProjectTree` `Mod+1`.
|
||||
- `keymap.ts` parses Lutra notation and matches by key code (letters, digits and US punctuation by `code`, so Alt and Shift layout effects don't matter). It also formats shortcuts for display with catalog modifier names.
|
||||
- `rank.ts` ranks for the palette.
|
||||
- `store.ts` (Pinia `commands`) holds the merged list, the keymap, the handlers and the recent commands.
|
||||
- **Handlers:** components supply behaviour with `provide(id, {run, enabled?})`:
|
||||
- the palette provides `palette.open`;
|
||||
- the main layout provides `view.toggleProjectTree`;
|
||||
- the editor area provides `file.save`, `file.saveAll` and `buffer.close` with the active buffer as context (they replace the editor-only keymap of M1.6).
|
||||
- A UI command without a handler is disabled. `settings.open` stays disabled until the settings dialog (M1.9b) provides it.
|
||||
- An engine command without a handler runs through `run(id, {})`.
|
||||
- **Enabled state:** a handler's `enabled` decides, else the engine's. The list is refreshed on `projectOpened`/`projectClosed` and whenever the palette opens.
|
||||
- **Keyboard:** one window `keydown` listener in the capture phase (works while CodeMirror or an input has focus). A matching shortcut is always swallowed; a disabled command does nothing. A failure raises `notification.command.failed`.
|
||||
- **Palette** (`ui/src/components/palette/CommandPalette.vue`, mounted in `App.vue`):
|
||||
- **Contents:** it offers UI commands and engine commands that have a menu path or a default shortcut. Protocol commands such as `buffer.edit` are left out.
|
||||
- **Ranking:** labels are catalog text for UI commands and the engine's label otherwise. Tiers: prefix, word prefix, query spread over consecutive word starts, substring, in-order characters; the label or the id may match. Within a tier recent commands come first (in memory, 20, not `palette.open` itself), then shorter texts, then the label.
|
||||
- **Keys:** arrow keys wrap, Enter runs an enabled row, Escape or a click outside closes.
|
||||
- **Running:** the command runs after the palette closed and returned the focus.
|
||||
- **Rows:** disabled rows are dimmed with `aria-disabled`.
|
||||
- **Accessibility:** combobox with listbox and `aria-activedescendant`.
|
||||
|
||||
## Decisions (M0)
|
||||
|
||||
| Question | Decision | Why |
|
||||
|
|
@ -168,6 +199,7 @@ Watched directories: the VFS watcher is non-recursive, so `project.children` wat
|
|||
|
||||
| Date | Change | Summary |
|
||||
|---|---|---|
|
||||
| 2026-10-16 | minor | M1.8: UI commands (`ui.registerCommands`, `uiCommand`, `ui` in listCommands), global keymap, command palette |
|
||||
| 2026-10-16 | minor | M1.12: notifications (host emission, early-event replay, toast store and stack, deferred engine_ready) |
|
||||
| 2026-10-16 | minor | M1.13: open buffers pin their parent directory in the watcher, `bufferFocused`, truncated listing row |
|
||||
| 2026-10-16 | minor | M1.7: recovery journal (storage, debounce, removal, commands, recoveryAvailable, restore dialog) |
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue