PM: merge M1.12 notifications
Some checks are pending
ci / ci (macos-15) (push) Waiting to run
ci / ci (ubuntu-24.04) (push) Waiting to run
ci / ci (windows-2025) (push) Waiting to run

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

# Conflicts:
#	docs/architecture.md
#	docs/gaps.md
#	docs/roadmap.md
#	docs/target-app-parity.md
#	docs/ui-parity.md
This commit is contained in:
danny 2026-10-16 16:22:14 +02:00
commit 2f8fef876b
21 changed files with 1178 additions and 94 deletions

View file

@ -1,6 +1,6 @@
# Architecture
> **Status:** M0 decisions recorded, M1 workspace, desktop bridge, tabs and editor, message catalog, engine construction, settings, themes and the recovery journal 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 and notifications documented · **Last updated:** 2026-10-16
## Overview
@ -87,8 +87,8 @@ Watched directories: the VFS watcher is non-recursive, so `project.children` wat
### Desktop bridge (M1.4)
- The desktop host publishes every event, from commands and from its pump thread, to control channel subscribers and to the window as the Tauri event `engine://event` with the engine `Event` as payload. Events are published while the engine lock is held, so their order is the engine's order.
- `ui/src/ipc.ts` exposes `onEngineEvent(handler) => unsubscribe` with the typed union `EngineEventPayload`. The first successful subscription calls the IPC command `engine_ready`; the host then replays `projectOpened` and `bufferOpened` for the current state to the window only. A project opened from the command line (`lutra-desktop --control 7979 PATH`) or before a page reload therefore still reaches the UI.
- `project.openDialog` returns `Effect::PickFolder`; the host shows the native folder picker (`tauri-plugin-dialog`, from Rust, non-blocking) and runs `project.open` with the choice. At most one picker is open; cancelling does nothing. A folder that cannot be opened (for example `unsaved_changes`) is only logged to stderr until the UI can show notifications.
- `ui/src/ipc.ts` exposes `onEngineEvent(handler) => unsubscribe` with the typed union `EngineEventPayload`. Once the subscriptions started together (all of them while the page mounts) are registered, `ipc.ts` calls the IPC command `engine_ready` once; the host then replays `projectOpened` and `bufferOpened` for the current state, followed by the notifications and `watchFailed` events published before (M1.12), to the window only. A project opened from the command line (`lutra-desktop --control 7979 PATH`) or before a page reload therefore still reaches the UI.
- `project.openDialog` returns `Effect::PickFolder`; the host shows the native folder picker (`tauri-plugin-dialog`, from Rust, non-blocking) and runs `project.open` with the choice. At most one picker is open; cancelling does nothing. A folder that cannot be opened becomes a `notification` (M1.12): `unsaved_changes` a warning, anything else an error.
- Capabilities: the main window may only listen to and unlisten from events (`core:event:allow-listen`, `core:event:allow-unlisten`). Engine commands are app commands and need no permission; the dialog plugin is used from Rust only, so the frontend gets no dialog permission.
- Contract fix: the project UI from M1.5 was written against assumed shapes. `ui/src/components/project/engineEvents.ts` is now the adapter between the engine contract and the UI types: `toProjectEvent` translates `{kind: "projectOpened", root, name}` and friends into the store's events, and `toTreeEntries` translates `project.children`'s `{dir, entries: [{name, path, kind: file|directory|other, ignored, role}], truncated}` into tree entries (`kind: dir|file`, `role`, `excluded`, `special` for `other`) plus `truncated`. Malformed entries are skipped; a result without `entries` becomes an `ipc` error on the directory.
@ -111,7 +111,7 @@ Watched directories: the VFS watcher is non-recursive, so `project.children` wat
### Engine construction (M1.9a)
- `EngineConfig { config_dir, data_dir }` and `Engine::with_config(config) -> Result<Engine, EngineError>`. The desktop builds the Tauri app first, takes `app_config_dir()` and `app_data_dir()` from its path resolver, creates the engine, the host and the control channel, and creates the window in the setup hook. `Engine::new()` has no persistence (settings in memory only) and serves tests and the control test backend; `lutra_testkit::engine_config(root)` gives temp dirs for tests.
- Construction never fails because of the settings file. Problems are queued as a warning `notification` event; the desktop takes the startup events and logs them to stderr (the UI does not see startup notifications yet, M1.12).
- Construction never fails because of the settings file. Problems are queued as a warning `notification` event; the desktop takes the startup events and publishes them, and the window receives them on `engine_ready` (M1.12).
### Settings (M1.9a)
@ -121,6 +121,15 @@ Watched directories: the VFS watcher is non-recursive, so `project.children` wat
- Commands: `settings.list` → `[{key, type: enum|int, default, enumValues?, min?, max?, labelKey, descriptionKey, section}]` (catalog keys `settings.<key>.label` / `.description`; `section` is an id shown with `settings.section.<id>`), `settings.get {keys?}` → `{values}`, `settings.set {key, value}` → `{value}`, `settings.reset {key}` → `{value}`. Unknown keys and bad values fail with `invalid_params`; a write failure fails with `failed` and changes nothing.
- Events: `settingsChanged {keys}` when an effective value changes; `notification {id, level: info|warning|error, messageKey?, message?, params?}` (ids `n1`, `n2`…).
### Notifications (M1.12)
- **Event:** `notification {id, level: info|warning|error, messageKey?, message?, params?}`; ids `n1`, `n2`… from one sequence per engine. `messageKey` is a catalog key, `message` the English fallback. The engine emits them for settings (M1.9a) and journal (M1.7) problems; the host asks the engine for one with `Engine::notify` (same id sequence) for errors that have no caller to return to:
- folder picker and command-line path: `notification.project.unsavedChanges {path, what}` (warning) for `unsaved_changes`, `notification.project.openFailed {path, reason}` (error) otherwise, `notification.project.notLocal {reason}` (error) for a picked folder that is not a local path;
- pump: `notification.vfs.pumpFailed {reason}` (warning), once until a pump succeeds again.
- **Replay:** the host keeps notifications and `watchFailed` published before the window called `engine_ready` (at most 50) and sends them after the state replay; afterwards nothing is kept. The store ignores an id it already shows, so a second replay does not duplicate.
- **`watchFailed`** stays an engine event (control channel clients use it); the frontend maps it to a warning toast `notification.watch.failed {reason}`. `workspace.rs` is unchanged.
- **UI:** `ui/src/stores/notifications.ts` (Pinia) turns events into toasts (catalog text with params if the key exists, else `message`, else the key; untrusted fields checked, unknown levels count as errors) and offers `notify` / `notifyError(command, error)` to frontend code. Failed commands that have no UI of their own raise an error toast `notification.command.failed {command, message}` (today `theme.systemPreference` and loading the editor keymap); errors shown in place (tree listings, editor and project errors, the restore dialog) stay in place. `ui/src/components/notifications/NotificationStack.vue`, mounted in `App.vue`, stacks the toasts at the bottom right, newest at the bottom: info as `role="status"`, dismissed after 5 s; warnings and errors as `role="alert"`, until closed. Each toast has a close button and closes with Escape while focused; at most 5 show, older ones collapse into a "+n more" button that expands the stack; at most 100 are kept. Colours are the editor notices' (`--lt-notice-bg`, error tint), with a level stripe (muted, accent, error).
### Themes (M1.10)
- `lutra_engine::theme` defines `DARK` (`lutra-dark`) and `LIGHT` (`lutra-light`) with the same token names, plus shared font tokens. Besides the base colours (`bg`, `editor-bg`, `fg`, `fg-muted`, `border`, `accent`, `error`, `statusbar-*`) both define `editor-selection-bg`, `editor-active-line-bg`, `editor-cursor`, `editor-gutter-bg`, `editor-gutter-fg`, `editor-match-bg`, `tab-active-bg`, `tab-modified`, `notice-bg`; `font-size-editor` is shared (14px). Values are opaque `#rrggbb` derived from the palette (selection, match and notice are the accent mixed into the background); the designer may change values, never names.
@ -159,6 +168,7 @@ Watched directories: the VFS watcher is non-recursive, so `project.children` wat
| Date | Change | Summary |
|---|---|---|
| 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) |
| 2026-10-16 | minor | M1.10: themes (light theme, editor tokens, theme.list, theme.systemPreference, themeChanged, init script from the setting, live switch, contrast test) |