Document UI UX roadmap audit

docs/UI_UX_AUDIT_2026-06-30.md

@@ -0,0 +1,494 @@
+# Verstak2 UI/UX Audit - 2026-06-30
+
+## Scope
+
+This audit compares current Verstak2 against the old Verstak repository at
+`/home/mirivlad/git/verstak`. The old repository is used only as UI/UX,
+feature, and workflow reference. Code and architecture are not copied.
+
+No previous complete UI/UX comparison report was found in the Verstak2
+repositories. Existing documents cover implementation plans and roadmap items,
+but not an end-to-end scenario audit.
+
+## Environment
+
+- Date: 2026-06-30
+- Verstak2 desktop repo: `/home/mirivlad/git/verstak2/verstak-desktop`
+- Old Verstak repo: `/home/mirivlad/git/verstak`
+- Tooling:
+  - Node.js v24.18.0 installed locally under `/tmp/verstak2-tools`
+  - Playwright Chromium used through local CLI wrapper
+  - Wails CLI v2.12.0 installed locally
+  - Debian 13 WebKitGTK package present as `libwebkit2gtk-4.1-dev`
+- Wails note:
+  - `wails doctor` still reports missing `libwebkit2gtk-4.0-dev`.
+  - Wails v2.12.0 supports WebKitGTK 4.1 with Go build tag `webkit2_41`.
+  - `go test -tags webkit2_41 ./...` passes for current `verstak-desktop`.
+
+## Artifacts
+
+Screenshots are stored in:
+
+`docs/ui-ux-audit-assets/2026-06-30/`
+
+- `v1-start.png`
+- `v1-today.png`
+- `v1-inbox.png`
+- `v1-activity.png`
+- `v2-plugin-manager.png`
+- `v2-workspace-files.png`
+- `v2-command-palette.png`
+- `v2-workspace-activity.png`
+- `v2-workspace-browser-inbox.png`
+
+## Verification Summary
+
+### Repository Update
+
+All Verstak2 subrepositories were updated. `verstak-desktop` initially could
+not fast-forward because of local tracked changes in generated Wails typings
+and `scripts/build.sh`. Those changes were saved in:
+
+`stash@{0}: codex-pre-ui-audit-desktop-update`
+
+After that, `verstak-desktop` fast-forwarded to `origin/main`.
+
+### Automated Checks
+
+Current `verstak-desktop`:
+
+- `go test -tags webkit2_41 ./...`: pass
+- `npm --prefix frontend run build`: pass
+- `frontend npm run test:e2e`: 42 passed, 11 failed
+- `scripts/check.sh` with `GOFLAGS=-tags=webkit2_41`: fails on gofmt only:
+  - `plugins/platform-test/backend/main.go`
+  - `build/bin/plugins/platform-test/backend/main.go`
+
+### E2E Failures Worth Tracking
+
+The failed E2E tests cluster around:
+
+- Plugin Manager navigation selectors expecting `.sidebar .nav-item` while the
+  current sidebar uses different structure/classes.
+- File/workbench editor height regressions:
+  - text editor height was about 266px where test expects over 300px;
+  - markdown preview height was about 217px where test expects over 300px.
+- Platform Test status bar component failure:
+  - `openDiagnostics` component not found in bundle.
+- Sync status bar failure:
+  - `SyncStatusBar` bundle content is empty.
+
+Some selector failures may be stale test assumptions. The editor height and
+status bar errors are visible workflow/UI issues.
+
+### Post-Pull Status - 2026-06-30 Later Sync
+
+After pulling `verstak-desktop` to `46f754c` (`feat: workspace routing,
+GlobalSearch, and shell refinements`), several roadmap items from this audit
+are now implemented and verified.
+
+Current verification:
+
+- `GOFLAGS=-tags=webkit2_41 go test ./...`: pass
+- `npm --prefix frontend run test:e2e`: 71 passed
+- Focused UX coverage now includes:
+  - app starts in the first workspace instead of Plugin Manager;
+  - workspace opens with a shell-level Today tab before plugin tools;
+  - workspace selection and main content stay in sync after Plugin Manager
+    round trips;
+  - workspace tool selection survives Workbench open/back/close flows;
+  - status bar plugin failures do not render large error panels;
+  - Plugin Manager remains reachable from the status/settings menu;
+  - Files uses readable dates and understandable labeled controls;
+  - Vault Selection is localized and has clear primary actions;
+  - global search stays visible after opening tool views;
+  - global search searches workspaces and file contents with RU/EN layout
+    fallback;
+  - plugin settings modal has enough space for complex panels;
+  - Browser Inbox desktop workflow renders an empty capture flow, stored
+    captures, detail metadata, and create/remove actions;
+  - Activity desktop workflow renders an empty event flow, stored events, and
+    worklog suggestions;
+  - Command Palette promotes shell workflow commands before diagnostics and can
+    open Today, Files, Activity, Browser Inbox, Plugin Manager, and start
+    markdown/text file creation;
+  - Command Palette can run Sync Now and open Sync settings.
+
+The historical screenshots in `docs/ui-ux-audit-assets/2026-06-30/` remain
+useful as "before" evidence, but the active roadmap below supersedes the
+original P0 ordering.
+
+## Scenario Findings
+
+### 1. First Meaningful Screen
+
+Old Verstak opens into a working shell:
+
+- left navigation has clear system sections: Today, Inbox, Activity;
+- workspace tree sits in the same navigation context;
+- global search is immediately visible in the header;
+- sync status and settings are discoverable but secondary.
+
+Verstak2 opens into Plugin Manager:
+
+- the first screen is technical/admin-oriented rather than user-task-oriented;
+- plugin cards expose implementation details such as capabilities, roots,
+  permissions, API versions, and contribution counts;
+- status bar plugin errors are visible immediately;
+- workspace entry exists in the sidebar, but it is not the primary landing
+  experience.
+
+Verdict: Verstak2 is feature-visible, but not user-workflow-first.
+
+### 2. Navigation Model
+
+Old Verstak has one coherent navigation model:
+
+- System section for cross-workspace workflows;
+- Workspace section for user cases/spaces;
+- settings and sync anchored at the bottom;
+- current page title and search are consistent.
+
+Verstak2 separates:
+
+- Tools;
+- Workspaces;
+- workspace tabs;
+- Plugin Manager;
+- status bar settings.
+
+This is architecturally accurate for a platform, but it leaks platform concepts
+too strongly into daily use. The user needs "work", "capture", "search",
+"activity", and "settings"; they should not need to reason about plugin
+contributions on the main path.
+
+### 3. Workspace Files
+
+Verstak2 workspace Files is one of the stronger current screens:
+
+- workspace header exists;
+- search slot exists;
+- Files, Activity, Browser Inbox tabs are correctly scoped to workspace;
+- file rows, folder rows, filtering, sorting, and action buttons are present.
+
+Problems:
+
+- Files toolbar buttons render visually as near-identical small squares in the
+  screenshot. Accessibility names exist, but visible affordance is poor.
+- Editor/preview area appears too short in E2E, causing regressions for file
+  opening workflows.
+- Status bar error area consumes a large part of the lower viewport and reduces
+  usable file space.
+
+### 4. Activity
+
+Old Verstak gives Activity a clear system-level place and empty state.
+Today also exposes related workflow tabs: feed, suggestions, in-progress,
+captures, browser.
+
+Original Verstak2 desktop mock rendered only:
+
+- heading `Activity`;
+- text `Global activity feed`.
+
+Current desktop shell/mock now mirrors the official Activity plugin's core
+visible workflow: scoped empty state, event count, stored event rows, clear
+action, and worklog suggestions. Remaining work is to expose real activity
+ingestion and Journal import from the visible app flow, not just prove the
+surface contract in mock E2E.
+
+### 5. Browser Inbox / Capture Flow
+
+Old Verstak "Неразобранное" has:
+
+- a clear name for unprocessed captures;
+- explanatory text;
+- an immediate visible action: paste from clipboard.
+
+Original Verstak2 desktop mock rendered only:
+
+- heading `Browser Inbox`;
+- text `Global browser inbox`.
+
+Current desktop shell/mock now mirrors the official Browser Inbox plugin's core
+visible workflow: scoped empty state, capture count, stored capture rows,
+detail metadata, and visible conversion/remove actions. Remaining work is to
+make the real capture ingestion path and extension pairing visible from the
+app.
+
+### 6. Command Palette
+
+Verstak2 command palette opens and is keyboard-accessible. Current visible
+commands are only Platform Test commands. It is useful infrastructure, but not
+yet a meaningful user launcher.
+
+Expected near-term commands:
+
+- open/create workspace;
+- search workspace;
+- create note;
+- create file;
+- open Browser Inbox;
+- open Activity;
+- sync now / sync settings;
+- plugin/settings only after user tasks.
+
+### 7. Status Bar
+
+Status bar is currently the largest immediate UX blocker.
+
+Observed:
+
+- permanent lower panel shows plugin errors;
+- error cards overlap/consume workspace area;
+- messages expose internal plugin/component/bundle details;
+- normal user status is visually dominated by red plugin failure content.
+
+The old version keeps sync/settings status quiet and secondary. Verstak2 should
+follow that principle: status should be compact, actionable, and non-blocking.
+Developer diagnostics belong behind an explicit diagnostics surface.
+
+## Priority Plan
+
+### DONE - Remove User-Facing Internal Errors From Main Workspace
+
+Goal: no normal user screen should be dominated by plugin bundle errors.
+
+Status: implemented in `verstak-desktop` and verified by
+`frontend/e2e/ux-p0.spec.js` plus `frontend/e2e/status-bar.spec.js`.
+
+Actions:
+
+- Fix Platform Test status contribution:
+  - manifest/component mismatch around `openDiagnostics` vs available bundle
+    components.
+- Fix Sync status contribution:
+  - empty frontend bundle content for `SyncStatusBar`.
+- Change status bar error rendering:
+  - compact "Plugin issue" badge;
+  - details only on click;
+  - cap height so it cannot cover workspace content.
+
+Verification:
+
+- `frontend/e2e/status-bar.spec.js` passes.
+- First workspace screenshot has no large red error cards.
+
+### DONE - Make Workspace The Default User Landing
+
+Goal: after vault opens, user lands in a productive workspace or Today-style
+overview, not Plugin Manager.
+
+Status: implemented in `verstak-desktop`; current mock flow starts in the first
+workspace and keeps Plugin Manager reachable through settings.
+
+Actions:
+
+- If a vault has workspaces, open the last active workspace.
+- If no workspace exists, show a first-run workspace creation screen.
+- Move Plugin Manager out of the primary default route:
+  - keep accessible through Settings;
+  - optionally expose via command palette.
+
+Verification:
+
+- Initial app screen shows workspace or useful overview.
+- Plugin Manager remains reachable but is not the first user-facing surface.
+
+### PARTIAL - Restore Old "Today / Inbox / Activity" Workflow Shape
+
+Goal: preserve the old product's user workflow while keeping Verstak2 plugin
+architecture.
+
+Status: first shell-level Today surface is implemented in `verstak-desktop`.
+Workspace now opens with `Today` before plugin tools, showing captures, recent
+activity, worklog suggestions, and quick actions. The Today "Open Inbox" action
+switches into the workspace Browser Inbox tool, and Files remains stable after
+Workbench open/back/close flows.
+
+Remaining gap: this is still a thin aggregation layer. Activity, Browser Inbox,
+and Journal exist as plugin-backed surfaces, but the old product's richer
+"what should I do now?" flow needs real capture/activity/journal data density
+and stronger empty-state actions. Current architecture has the ingredients:
+
+- `verstak.activity` stores scoped activity and exposes worklog suggestion
+  command `verstak.activity.suggestWorklog`;
+- `verstak.browser-inbox` stores scoped captures and can convert captures into
+  notes, links, and files;
+- `verstak.journal` stores worklog entries and can import Activity suggestions;
+- `GlobalSearch` indexes workspaces, tools, files, Browser Inbox, Activity, and
+  Journal plugin settings.
+
+Actions:
+
+- Expand the user-level `Today` surface with richer real data.
+- Surface and prioritize:
+  - recent activity;
+  - unprocessed captures;
+  - in-progress work;
+  - worklog suggestions;
+  - quick create actions.
+- Keep implementation plugin-driven, but present as one coherent workflow.
+- Add first-class commands for opening Today, Inbox, Activity, and creating
+  work items.
+
+Verification:
+
+- User can answer "what should I do now?" from the first screen.
+- Browser captures and activity are visible without opening Plugin Manager.
+- `frontend/e2e/ux-today.spec.js` covers Today-first startup and the Today to
+  Browser Inbox quick-action path.
+
+### PARTIAL - Make Activity A Real Visible Workflow
+
+Goal: Activity should look useful even with no events and should connect events
+to worklog reconstruction.
+
+Status: partially implemented. The real Activity plugin has scoped storage,
+event subscriptions, worklog suggestion generation, and a command contribution
+for `verstak.activity.suggestWorklog`. The desktop E2E/mock surface now mirrors
+the core visible workflow: scoped empty state, event count, stored event rows,
+clear action, and worklog suggestions.
+
+Remaining UX work is mostly around real activity ingestion from app actions,
+Journal import/review, and making suggestions actionable from Today/Activity
+rather than merely visible.
+
+Actions:
+
+- Keep empty-state copy explaining that file changes, browser captures, and
+  conversions will appear here.
+- Add visible actions for:
+  - import worklog suggestion to Journal;
+  - filter by source/type;
+  - open related file/capture from an activity row.
+- Connect Today worklog suggestions to Activity/Journal actions.
+
+Verification:
+
+- Empty Activity explains what will appear.
+- Stored events render with source/type/summary.
+- Worklog suggestions are visible from activity events.
+- `frontend/e2e/activity.spec.js` covers the desktop shell/mock contract.
+
+### PARTIAL - Make Browser Inbox A Real Visible Workflow
+
+Goal: Browser Inbox should look usable even when empty.
+
+Status: partially implemented. The real Browser Inbox plugin has storage,
+event subscriptions, scoped capture lists, domain binding, and Create Note /
+Create Link / Create File actions for selected captures. The desktop E2E/mock
+surface now mirrors the core visible workflow: scoped empty state, capture
+count, stored capture list, detail metadata, and Create Note / Create Link /
+Create File / Remove actions. Today also opens this workspace tool directly.
+
+Remaining UX work is mostly around actual primary capture actions, extension
+pairing/settings visibility, and making the real capture ingestion path easy to
+exercise from the app.
+
+Actions:
+
+- Keep empty-state copy explaining capture flow.
+- Add primary actions:
+  - paste from clipboard;
+  - open browser extension pairing/settings;
+  - create note/link/file from selected capture when data exists.
+- Show domain/workspace binding state if configured.
+
+Verification:
+
+- Empty Browser Inbox explains the capture flow.
+- Stored captures render with visible metadata and conversion actions.
+- Captures can be converted from the visible UI in the real plugin.
+- `frontend/e2e/browser-inbox.spec.js` covers the desktop shell/mock contract.
+
+### DONE - Fix Files Toolbar Visual Affordance
+
+Goal: toolbar buttons must be visually recognizable, not identical dark boxes.
+
+Status: implemented and verified by `frontend/e2e/ux-p0.spec.js` and the full
+Files E2E suite. Files now uses readable dates and understandable action
+controls; editor/preview height regressions are covered by passing E2E.
+
+Actions:
+
+- Ensure Lucide icons render with sufficient contrast and size.
+- Add tooltips for icon-only buttons.
+- Disable unavailable actions visibly instead of showing identical active
+  squares.
+- Keep layout dense, but make grouping clear: navigation, create, selected item
+  actions, clipboard, filter/sort.
+
+Verification:
+
+- Screenshot shows recognizable icons.
+- Buttons have accessible names and hover tooltips.
+- File open editor/preview height returns above E2E threshold.
+
+### PARTIAL - Make Command Palette User-Oriented
+
+Goal: command palette should be a power-user entry point for real tasks.
+
+Status: partial. Command Palette works, executes active plugin commands, and
+now promotes shell workflow commands above diagnostics: Open Today, Open Files,
+Open Activity, Open Browser Inbox, Open Plugin Manager, Create Markdown File,
+Create Text File, Sync Now, and Open Sync Settings. Remaining command coverage
+gaps are capture actions, richer note templates, Journal import/review, and
+hiding test diagnostics from production-like mode.
+
+Actions:
+
+- Register remaining user commands from Browser Inbox, Activity, Search, and
+  Journal.
+- Keep user commands ranked above diagnostics/test commands.
+- Hide test/plugin diagnostics from production-like mode.
+
+Verification:
+
+- `Ctrl+K` shows open Today/Files/Activity/Inbox commands before diagnostics.
+- `Ctrl+K` can start markdown/text file creation through the visible Files
+  workflow.
+- `Ctrl+K` can run Sync Now and open Sync settings.
+- `frontend/e2e/command-palette.spec.js` covers shell command ranking and the
+  Open Activity, create-file, and sync command paths.
+
+### DONE - Reduce Plugin Manager Density
+
+Goal: Plugin Manager should remain useful but stop looking like the product's
+main screen.
+
+Status: implemented enough for the current roadmap. Plugin cards now show a
+short default surface and hide API version, root, capabilities, optional
+requires, and permissions under `Technical details`.
+
+Actions:
+
+- Split default view into simple plugin list:
+  - name;
+  - enabled/disabled;
+  - short description;
+  - settings;
+  - disable/enable.
+- Put capabilities, permissions, roots, and contribution details behind
+  expandable "Developer details".
+
+Verification:
+
+- Plugin Manager fits more plugins per viewport.
+- Non-developer user can safely enable/disable/configure without reading
+  internal contracts.
+
+## Next Review Steps
+
+1. Design and implement the user-level Home/Today surface.
+2. Re-run:
+   - `GOFLAGS=-tags=webkit2_41 ./scripts/check.sh`
+   - `npm --prefix frontend run test:e2e`
+3. Re-capture the same screenshots as "after" evidence.
+4. Run real Wails GUI smoke with:
+   - `wails dev -tags webkit2_41`
+5. Do a second audit focused on:
+   - first-run/open vault;
+   - real filesystem vault;
+   - Browser extension capture;
+   - native window/WebKitGTK rendering differences.