Lutra/docs/ui-parity.md
danny d097558ba5 M4.10: remotes: fetch, pull, push, clone and manage remotes
Owner decision D23: Lutra runs fetch, pull (merge or rebase per the new
git.pull.mode setting), push (upstream set on the first push) and clone
through the user's git. Any HTTPS or SSH server works; sign-in stays with
git's credential helper (its own window is allowed for network calls only)
and the ssh agent. Terminal prompts stay off, ext:: is refused, and URL
userinfo is redacted in every message, progress line and remote listing.

- vcs: Call::network with a 30 min timeout, a stderr progress sink and a
  Cancel flag that kills git's process group; remote.rs with clone_repo,
  fetch, pull, push (--porcelain rejections), remotes and add/set-url/
  remove; explained refusals (rejected push, sign-in, host key, not found,
  unreachable, no upstream, local changes, conflicts).
- engine: git.fetch/pull/push/clone/cancel/remotes/remoteAdd/remoteSetUrl/
  remoteRemove, one network call at a time, gitProgress events,
  gitChanged after changes.
- ui: status-bar progress with Cancel and ahead/behind, vcs.fetch/pull/
  push/clone/manageRemotes (Git menu, no default shortcuts), Clone
  Repository and Manage Remotes dialogs; desktop pick_dir IPC.
- Tests against local bare repositories only (vcs 8, engine 3, Vitest 11)
  plus unit and property tests; docs updated.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-29 17:50:26 +01:00

23 KiB
Raw Blame History

UI parity checklist

Status: main window layout (M1.5), project tree running against the engine (M1.4), editor tabs with a CodeMirror editor (M1.6), light and dark themes (M1.10), restore dialog for unsaved changes (M1.7), notification toasts (M1.12), command palette and global keymap (M1.8), settings dialog with search (M1.9b), syntax highlighting and editor.reveal (M2.2), Find tool window in the bottom panel (M2.4), go-to popup (M2.6), left stripe and Structure tool window (M2.7), app menu (M3.9), Terminal tool window and bottom panel tabs (M3.6), Problems tool window and editor diagnostics (M3.3), completion, quick documentation and parameter info (M3.4), string and path settings with completion and tooltip settings (H4), banner-aligned themes with diagnostic and VCS colours (H5), Changes tool window (M4.2), Git change markers and status colours (M4.4), diff viewer and the project tree's context menu (M4.3), branch widget and popup (M4.5), fetch/pull/push progress, the clone and remotes dialogs (M4.10) · Last updated: 2026-10-28

  • Main window: tool window stripes, editor area, status bar, navigation bar
    • M2.7 (2026-10-17): a left stripe with one tab per left tool window (Project, Structure); the shown one is marked, clicking it again hides the window. Still missing: right docking, several bottom tool windows, drag to rearrange, navigation bar, layout persistence.
    • M1.5 (2026-10-14): left tool window with header, hide button, collapsed stripe with a show button, resizable by pointer and keyboard; editor area placeholder; status bar. Missing: stripes with several tool windows, bottom/right docking, navigation bar, layout persistence. Not checked in the running app yet (needs M1.4).
  • Main menu
    • M3.9 (2026-10-19): a slim header bar with a menu button (Lucide menu) top left; its dropdown lists every command with a menuPath (engine and UI), grouped File, Edit, View, Go, Help in Lutra's own order, with shortcuts; disabled entries dimmed and not runnable. Keyboard: Alt+M (menu.open, also over uiCommand), arrows, Home/End, Enter/Space, Escape/Tab, type-ahead. An exclusive modal and launcher (one-modal rule). Vitest; live check on Windows 11 (port 7939). Missing: a display-mode option (always visible menu bar), native macOS menu bar, submenus and separators, an Edit group (no edit commands yet), an About window. Behaviour notes: plan/phpstorm/14-main-menu.md.
  • Project tool window (tree, scroll from source, file operations)
    • M1.5 (2026-10-14): tree of the open folder with lazy project.children listings, folders and PHP files with Lucide icons, ignored/excluded entries dimmed, keyboard navigation (WAI-ARIA tree: arrows, Home/End, Enter), double-click opens, refresh on TreeChanged, listing errors shown in the tree, empty state with Open Folder…. Vitest only, against a mocked engine.
    • M1.4 (2026-10-15): runs against the real engine in the app: projects open from the folder picker or the command line, the tree updates live when files change on disk; checked with ui.screenshot on Windows 11. M1.13 (2026-10-16): a partly listed folder ends with a "Listing truncated" note; opening a file that is already open (tree, control channel) switches to its tab (Vitest; live check pending (gaming mode)). Missing: scroll from source (Select Opened File), expand/collapse all, views list, sort options, speed search, file colours, file operations. Behaviour notes: plan/phpstorm/02-project-view.md.
  • Editor tabs (pin, split, reorder, close others)
    • M1.6 (2026-10-15): tab bar above a CodeMirror 6 editor; files open from the project tree (Enter, double click) next to the active tab, or from engine events (control channel, page reload); click and Left/Right activate, the close button, a middle click and Mod+W close; a dot marks unsaved changes; closing a dirty tab asks Save / Don't Save / Cancel; Mod+S saves, Mod+Alt+S saves all (shortcuts read from the engine's command specs); a non-blocking notice when a dirty file changes or disappears on disk. Checked with ui.screenshot on Windows 11 and Vitest. Missing: preview tab, pin, split, reorder by drag, close others/all, reopen closed tab, tab limit, tab context menu, recent-files switcher, duplicate-name disambiguation. Behaviour notes: plan/phpstorm/03-editor-tabs.md.
  • Editor syntax highlighting (Lutra's own colours, no copied scheme)
    • M2.2 (2026-10-16): the language is picked from the file extension when a tab opens: PHP (with the HTML, CSS and JavaScript around <?php blocks), HTML, CSS, JS/TS, JSON, YAML, Markdown; other files stay plain. Eleven syntax tokens (--lt-syntax-keyword/string/number/comment/variable/function/type/constant/tag/attribute/operator) in both themes, each ≥ 4.5:1 on the editor background and the active line. editor.reveal {path, line, column} (UI command, palette, control channel) opens the file, activates the tab, places the cursor and centres it. Checked in the app on Windows 11 (bundled UI, control channel): PHP with embedded HTML in dark and light, editor.reveal into a closed CRLF file (last line, then line 302 centred). Vitest; keystroke to highlight on a 1 MB PHP file 3.0–11.4 ms median (jsdom, JavaScript work only, measured, not yet in the WebView). Missing: semantic highlighting (from the language server), a colour scheme editor, more languages (XML, SQL, Twig, Blade, .env), font styles (bold/italic) per token.
  • Restore dialog for unsaved changes after a crash
    • M1.7 (2026-10-16): modal dialog after a project opens when the recovery journal holds unsaved texts: files with the time they were journaled and a hint when the file changed on disk since; Restore All, Restore Selected (the others stay listed), Discard; Escape keeps the journal for the next open; restore failures listed. Catalog strings, --lt-* tokens, Vitest (10 tests). Live check pending (gaming mode). Missing: a diff against the disk version, local history. M1.15: a restore or discard from elsewhere (control channel) removes the settled files and closes the dialog when none are left; the dialog waits behind the palette and the settings dialog. Behaviour notes: plan/phpstorm/04-recovery.md.
  • Command palette / search everywhere
    • M1.8 (2026-10-16): command palette (Mod+Shift+P) over every user-facing command, engine and UI (commands with a menu path or default shortcut, plus UI commands): fuzzy ranking on the label and the id (prefix, word prefix, word starts, substring, in-order characters), recently run commands first, shortcuts shown, disabled commands dimmed and not runnable, arrow keys, Enter, Escape, focus returned on close; a failing command raises an error toast. One global keymap (ui/src/commands/) matches every command's default shortcut by key code; UI commands palette.open, settings.open (Mod+,, opens the settings dialog since M1.9b) and view.toggleProjectTree (Mod+1). Vitest (keymap, ranking, store, palette, App); live check pending (gaming mode). Missing: files, classes, symbols and text tabs (search everywhere), settings in the results, synonyms and abbreviations, inline toggles, assigning a shortcut from the palette, recent commands across restarts. M1.15: one modal at a time; running any command (also as a uiCommand) closes the palette, opening the palette closes the settings dialog and the close question. Behaviour notes: plan/phpstorm/05-palette.md.
  • Settings dialog with search
    • M1.9b (2026-10-16): dialog (Mod+,, palette, control channel) built from settings.list: sections on the left, controls by type (select, number with min/max, switch), labels and descriptions from the catalog, search over label, description, key and section with matches grouped by section, Reset to default per setting, changes applied at once with inline errors, live updates on settingsChanged, theme picker (appearance.theme, switches at once), editor font size applied to the editor; Escape closes, focus trapped, every control reachable by Tab. Vitest (14 tests); live check pending (gaming mode). Missing: a tree of nested categories, project-level settings and their marker, modified markers, highlighting matches, export/import, more settings (keymap, code style, inspections). Behaviour notes: plan/phpstorm/06-settings.md.
    • H4 (2026-10-24): every string setting gets a text field (applied on Enter or leaving it; refused in place with a catalog hint for quotes or spaces around a path, control characters, more than 4,096 bytes); a path setting (key ending in path/executable: php.executable, phpactor.path, and M4.1's git.executable without UI changes) also gets "Browse…" with the native file picker and "Detected automatically" while empty; string rows stack the field under the text at full width. New Editor settings: completion auto popup, completion popup delay, documentation tooltip delay, read live by the editor. settings.open {section?, query?} for agents. Vitest (12 control tests, 6 live-wiring tests). Checked in the app (bundled UI, control port 7954): PHP section with both path fields, a value set over the control channel shown at once (plus the toolchain's PHP toast), the new Editor settings changed live, an out-of-range hover delay refused by the engine, search "delay"; screenshots read; the user's settings restored afterwards. "Browse…" was not clicked in the app (no synthetic input); Vitest covers it with a mocked picker.
  • Keymap editor (Lutra's own default keymap; no copied keymaps)
    • M1.8 (2026-10-16): the global keymap built from the default shortcuts of engine and UI commands; no user keymap and no editor yet.
  • Light and dark themes from theme tokens
    • M1.10 (2026-10-16): Lutra Dark and Lutra Light from Rust tokens, switched live through appearance.theme (no reload), system follows the OS preference, the first frame uses the stored theme; the editor (selection, active line, cursor, gutter, matches), tabs and notices have their own tokens; WCAG AA contrast checked by Vitest for every text pair in both themes. Covered by Vitest DOM and control-channel tests; live check pending (gaming mode). M1.9b: theme picker in the settings dialog, editor font size from editor.fontSize. Missing: a theme command in the palette, the native title bar following the theme, colour scheme editor, high-contrast theme.
    • H5 (2026-10-25): both themes follow the README banner, approved by the owner from before/after screenshots (tree, PHP editor, Problems, terminal, palette, settings; Windows 11, bundled UI, control port 7955): cream-tinted light theme, faintly plum-tinted dark theme, raspberry only as the accent, retuned syntax colours, the terminal on the editor surface. Diagnostics get their own colours (--lt-diag-*: error, amber warning, blue info, muted hint) in the underline, gutter dot, tooltip stripe and Problems icon; --lt-vcs-* status colours for M4.4; completion kind icons coloured by kind. Every text colour ≥ 4.5:1 and icon colour ≥ 3:1 in both themes (Vitest contrast test).
  • Notifications and background task indicator
    • M1.12 (2026-10-16): toasts at the bottom right for engine and host notifications (corrupt settings and journal entries at startup, folder that cannot be opened, unsaved_changes when switching projects, file watching stopped, failed commands without their own UI): info dismissed after 5 s, warnings and errors stay until closed, close button and Escape, at most 5 visible with "+n more", role="status"/role="alert"; startup notifications are replayed when the page starts listening. Vitest (19 store and component tests); live check pending (gaming mode). Missing: a notification log / Notifications tool window, actions inside a toast, balloon grouping, "don't show again", background task indicator with progress.
  • Structure tool window
    • M2.7 (2026-10-17): in the left tool window, chosen from the new stripe (Project | Structure); the active tab's declarations (namespaces, class-likes, functions, methods, properties, constants, enum cases) as a WAI-ARIA tree with Lucide kind icons in syntax colours and the short signature; follows the active tab and edits; click or Enter jumps to the name (editor.reveal), arrows walk and fold, collapsed nodes kept per file; empty states for no file, no declarations, still reading, too large. view.toggleStructure Mod+2. Checked in the app on Windows 11 over the control channel (tree, jump to a method, tree updated after an edit; no clicks, the control channel cannot send input). Missing: speed search, sorting and filters, visibility markers, inherited members, autoscroll from the caret, the File Structure popup, VCS colours, running tests from an entry.
  • Problems tool window
    • M3.3 (2026-10-21): a Problems tab in the bottom panel (next to Find and Terminal): the language server's diagnostics of every reported file, grouped by file (name, directory, count), errors first, then by position; each row with a Lucide severity icon in a token colour (error --lt-error, warning --lt-accent, info and hint --lt-fg-muted), the message, source and code, and the 1-based position; a status line with totals or the server state (starting, restarting, failed, not running). Click or Enter reveals the position (editor.reveal), arrows / Page / Home / End move. problems.open Mod+Alt+P (Lutra's own), menu View/Problems. In the editor: wavy underlines per severity, a gutter dot and the message with source and code on hover (CodeMirror lint, tokens only), mapped through edits until the next publication. Diagnostics come from Phpactor, not from Lutra's own inspections. Vitest; live check with the real Phpactor on Windows 11. Missing: a current-file tab or filter, severity filters, sort and group options, quick-fixes (code actions), the editor's problem counter, scrollbar marks, next/previous problem. Behaviour notes: plan/phpstorm/11-problems.md.
  • Code completion popup, quick documentation, parameter info
    • M3.4 (2026-10-22): CodeMirror's completion list with Lutra's triggers, a Lucide icon per kind (with the kind's catalog name as tooltip), the matched characters in --lt-accent, detail on the right, documentation beside the list; quick documentation as a tooltip on hover (350 ms) and on editor.quickDocumentation Mod+I; parameter info above the cursor with the active parameter bold in --lt-accent, a counter for overloads and the parameter's documentation; editor.complete and editor.parameterInfo in the palette and the Edit menu. Markdown rendered without HTML, tokens only. Checked in the app with the real Phpactor (screenshots). Missing: the documentation popup's toolbar and links, a documentation tool window, type info, completion settings beyond auto popup and delays (case sensitivity, sorting). H4: auto popup on/off, popup delay and hover delay from Settings › Editor, applied live to open editors. Behaviour notes: plan/phpstorm/12-completion.md.
  • Go to file / class / symbol popup
    • M2.6 (2026-10-17): one popup with Files / Classes / Symbols tabs (Tab / Shift+Tab or a click; the text stays), opened by goto.fileOpen Mod+P, goto.classOpen Mod+Alt+C, goto.symbolOpen Mod+T (Lutra's own keys) or by an agent with {query}; live fuzzy results (60 ms debounce, stale answers dropped) with matched characters marked, a Lucide icon per kind, the directory, namespace or container beside the name, library (vendor) rows dimmed with a label; an indexing hint with progress, re-queried on indexReady; arrows / Page keys move, Enter or a click opens through editor.reveal, Escape or a click outside closes; an exclusive modal. Checked in the running app. Missing: recent files on an empty query, a non-project toggle, file-type filter, :line suffixes, preview, more tabs (actions, text), sending results to Find.
  • Find tool window
    • M2.4 (2026-10-17): docked in the new bottom panel (resizable by pointer and keyboard, collapses to its header, closes; results kept while closed). Query field with case / whole word / regex toggles (aria-pressed), include and exclude globs, status line with counts and time, cancel, truncated hint, refused query as an alert; results grouped by file with the match highlighted, a listbox with keyboard navigation; Enter or click reveals the match. find.open Mod+Alt+F. Missing: tabs per search, grouping options, a preview pane, expand/collapse per file, rerun and next/previous occurrence buttons, context menu, export, history.
  • Terminal tool window
    • M3.6 (2026-10-18): a Terminal tab in the bottom panel (the panel shows Find and Terminal as tabs while both are open; Left/Right switch); xterm.js with the fit addon follows the panel size; several terminals as sub-tabs (Local, Local (2)…) with a close button each and a new-terminal button, Left/Right/Home/End/Delete on a sub-tab, an ended shell dims its tab and prints its exit code; output survives collapsing the panel; copy with Mod+Shift+C or Ctrl+C on a selection, paste with Mod+Shift+V or Ctrl+V; while a terminal has the focus plain Ctrl keys go to the shell and only Mod+Shift / Mod+Alt shortcuts reach Lutra; Lutra's own ANSI palette in both themes (text colours ≥ 4.5:1). terminal.open Mod+Shift+T. Missing: renaming and splitting tabs, a context menu, search, clickable links and paths, drag and drop, a key back to the editor, a confirmation before killing a running process, terminal settings.
  • Git tool window
    • M4.2 (2026-10-25): a Changes tab in the bottom panel (vcs.openChanges Mod+Alt+Shift+G, menu Git › Changes): Staged, Changes and Untracked groups with counts, file names coloured by status (--lt-vcs-*, deleted struck through, a staged rename shows its old path), a checkbox per file and per group to stage or unstage, Up/Down/Page/Home/End and Space in the list, double-click or Enter opens the diff (M4.3) or the file; a commit message box with Amend and Commit (Mod+Enter; vcs.commit Mod+Alt+Shift+M focuses it), saving open files first; a refresh button (vcs.refresh); hints when git is missing or the folder is not a repository. Vitest (19 tests). Missing: a tree view and grouping by directory or module, changelists, chunk staging, a context menu (rollback, delete, add to .gitignore), recent commit messages, commit options (sign-off, author, skip hooks), commit and push, a commit preview of the diff. Behaviour notes: plan/phpstorm/16-vcs-basics.md.
    • M4.4 (2026-10-25): the editor gutter shows a bar beside lines added or changed since the staged version and a notch where lines were deleted (tooltips from the catalog), updated 150 ms after typing and whenever Git changes; file names in the project tree and the tabs take the Git status colour (added, modified, deleted, untracked, conflicted; ignored entries inside a repository). Vitest. Missing: clicking a marker to see the old text, revert or stage the chunk, next/previous change, markers against HEAD, coloured directories.
    • M4.3 (2026-10-26): "Diff: " tabs in the editor area after the file tabs (vcs.showDiff Mod+Alt+Shift+D, menu Git › Show Diff; double-click or Enter in Changes; right click or Shift+F10 on a file in the project tree → Show Diff): the staged version or the last commit on the left, read-only, and the working copy on the right, editable like its own tab; a caption says what is compared; changed lines and words tinted with the VCS tokens, a change bar in each gutter, unchanged stretches collapsed to a clickable row; next/previous change Alt+Shift+] / Alt+Shift+[ (wrapping); notices for binary, too large and deleted files and for git's errors. The project tree got its first context menu (Open, Show Diff; WAI-ARIA menu, keyboard). Vitest. Missing: unified view, revert/stage arrows between the sides, synchronised horizontal scrolling, whitespace and highlighting options, comparing with any revision, a diff window of its own, more tree context menu items.
    • M4.5 (2026-10-26): the status bar shows the current branch (Lucide git-branch), or the short hash when detached, hidden outside a repository. A click or vcs.branches (menu Git › Branches…) opens a popup above it: a filter field, "New branch…", Local (current one checked, upstream beside it) and Remote headings; Up/Down/Page keys, Enter or a click checks out, Escape or a click outside closes and returns the focus. "New branch…" switches to a name field with a "Check out" checkbox; git's refusal shows under the field. An exclusive modal. Vitest (16 tests). Missing: merge, rebase, rename, delete, compare with current, favourites, recent branches first, incoming/outgoing markers, a submenu per branch.
    • M4.10 (2026-10-28): Git › Fetch / Pull / Push (vcs.fetch, vcs.pull, vcs.push, no default shortcuts) with a status-bar item left of the branch: "Fetching: Receiving objects 45%" and a Cancel button while one runs, otherwise ↑ahead ↓behind against the upstream (hidden when in step); toasts for done, cancelled and git's explained refusal. Git › Clone Repository… (vcs.clone, also without a project): URL and folder fields, Browse… (native folder picker; the folder follows the repository name in the URL), git's refusal in the dialog, then the cloned project opens. Git › Manage Remotes… (vcs.manageRemotes): remotes with redacted URLs and push URLs, Edit URL, Remove (asked in the row), an add form. Both dialogs are exclusive modals. Vitest (11 tests). Missing: push dialog with the commits to push and a target branch, force push, tags, pull options per call, a clone dialog listing the user's repositories on a hosting service.

Revision history

Date Change Summary
2026-10-28 minor Fetch/pull/push with progress, clone and remotes dialogs (M4.10)
2026-10-26 minor Branch widget and popup (M4.5)
2026-10-26 minor Diff viewer and the project tree's context menu (M4.3)
2026-10-25 minor Git change markers in the gutter, status colours in the tree and tabs (M4.4)
2026-10-25 minor Changes tool window (M4.2)
2026-10-25 minor Themes: banner-aligned palettes, diagnostic and VCS colours, completion icon colours (H5)
2026-10-24 minor Settings dialog: string and path controls, completion and tooltip settings (H4)
2026-10-22 minor Completion popup, quick documentation and parameter info partial (M3.4)
2026-10-21 minor Problems tool window partial, editor diagnostics (M3.3)
2026-10-19 minor Main menu partial (M3.9)
2026-10-18 minor Terminal tool window partial, bottom panel tabs (M3.6)
2026-10-17 minor Go-to popup partial (M2.6)
2026-10-17 minor Structure tool window partial, left stripe (M2.7)
2026-10-17 minor Find tool window partial, bottom panel (M2.4)
2026-10-16 minor Editor syntax highlighting partial; editor.reveal (M2.2)
2026-10-16 patch Palette and restore dialog: modal rule, restore dialog follows outside restores (M1.15)
2026-10-16 minor Settings dialog partial; theme picker and editor font size (M1.9b)
2026-10-16 minor Command palette and global keymap partial (M1.8)
2026-10-16 minor Notifications partial (M1.12)
2026-10-16 minor Truncated listing note, re-open switches tab (M1.13)
2026-10-16 minor Restore dialog (M1.7)
2026-10-16 minor Themes partial (M1.10)
2026-10-15 minor Editor tabs partial (M1.6)
2026-10-15 minor Project tool window runs against the engine (M1.4)
2026-10-14 minor Notes on main window and project tool window (M1.5)
2026-10-13 major Baseline