UX roadmap docs, theme tokens, UI fixes

Add comprehensive UX roadmap and validation artifacts, plus supporting code and UI adjustments. New documents: ROADMAP_COMPLETION.md, THEME_CONTRAST_MATRIX.md, UX_PERFORMANCE_BASELINE.md, UX_VALIDATION.md, and the UX proposal; README updated to link these. Add scripts/ux_roadmap_audit.py for static verification and a new design token header (src/ui/design_tokens.h) and viewer_chrome.h. Numerous UI and foundation source files updated (focus/contrast/target-size/performance signals, preview/viewer/window tweaks, crash/update/pak handling and performance metrics) to align implementation with the roadmap and validation requirements.

Author: themuffinator

.gitignore

@@ -61,3 +61,4 @@ _log_*
 _linuxdeploy_*
 _wsl_linuxpkg.log
 aqtinstall.log
+/.omx

README.md

@@ -85,6 +85,7 @@ aligned without carrying build instructions or repository maintenance notes.
 - Archive and folder support in both GUI and CLI.
 - Dedicated standalone viewer windows for image, video, audio, and model files.
 - Persistent Workspace tab for installations, open archives, recent files, global search, changed assets, dependency hints, validation, and runtime capability status.
+- Sidebar-driven Workspace lenses and a top-level Quick Open/Search box (`Ctrl+K`) for faster archive, file, and workspace lookup.
 - Nested container mounting (open archives inside archives).
 - One-click `Extract Selected` and `Extract All` workflows for the active archive tab.
 - Batch conversion tool for selected assets with category tabs (images, video, archives, models, sound, maps, text, other).
@@ -289,16 +290,17 @@ Examples:
   - Model Viewer
 - Opening behavior:
   - Opening a supported media/model file can launch its dedicated viewer window.
-  - Opening an archive prompts: open directly, install a copy then open, or move to installation then open.
-  - Preferences can keep that archive-open prompt enabled or choose a default open/copy/move action.
+  - Opening an archive defaults to Quick Inspect in place. Preferences can re-enable the archive-open prompt or choose install-copy/move behavior.
 - Navigation:
   - In standalone viewers, mouse wheel and arrow keys cycle sibling files in the same folder.
   - Fullscreen toggles with `F11`, middle mouse, or platform fullscreen shortcut.
 - Preferences:
-  - The tabbed Preferences page groups appearance, workspace/archive behavior, 3D preview defaults, image/text preview defaults, and update checks.
+  - The Preferences page shows everyday appearance, workspace/archive, and update settings first, with an Advanced toggle for preview/rendering controls.
   - Preview preferences include renderer, FOV, grid/background, wireframe/textured defaults, BSP lightmaps, model smoothing, animation playback, image transparency/background, image layout, and text wrapping.
   - Preview changes apply to open archive tabs and standalone viewer windows without restarting PakFu.
 - Archive operations:
+  - Non-blocking archive-operation hints and successful extract/convert completion messages appear in the status bar so browsing context stays intact.
+  - Archive details, list, icon, and gallery views are backed by a shared Qt model/view listing with sorting, selection restore, drag/drop, previews, and async thumbnails.
   - Drag-and-drop import/export across directories and tabs, plus file/folder drops from external applications.
   - Drag modifier keys: hold `Shift` to request move; hold `Ctrl/Cmd` (or `Option` on macOS) to force copy. Cross-application drops are copy.
   - Move semantics work across open tabs via drag or cut/paste when the source tab is editable; otherwise operations safely fall back to copy.
@@ -375,6 +377,9 @@ For full policy details, see `docs/RELEASES.md`.
 - [Extensions](docs/EXTENSIONS.md): manifest schema, JSON payload contract, and CLI/GUI extension workflow.
 - [Extension examples](examples/extensions/): source-first extension examples for local development and plugin-report smoke checks.
 - [Archive file operations QA](docs/QA_ARCHIVE_FILE_OPS.md): practical QA checklist for selection, drag/drop, cut/copy/paste, and modifiers.
+- [UX validation](docs/UX_VALIDATION.md): keyboard, pointer, contrast, layout, i18n, telemetry, and A/B acceptance artifacts for the UX roadmap.
+- [UX performance baseline](docs/UX_PERFORMANCE_BASELINE.md): generated-corpus timing evidence for the UX roadmap performance gate.
+- [Roadmap completion](docs/ROADMAP_COMPLETION.md): release-hardening checklist and evidence ledger for roadmap claims.
 - [Release policy](docs/RELEASES.md): versioning, release rules, and asset contract.
 - [UI button icons](docs/UI_BUTTON_ICONS.md): UI action icon inventory.
 - [File association icons](docs/FILE_ASSOCIATION_ICONS.md): file association icon mapping and implementation notes.

docs/ROADMAP_COMPLETION.md

@@ -0,0 +1,158 @@
+# Roadmap Completion And Release Hardening
+
+This document is the acceptance ledger for the UX roadmap work in
+`docs/proposals/ux-workflow-analysis-1-may-2026.md`. It complements
+`docs/UX_VALIDATION.md` and the static audit script
+`scripts/ux_roadmap_audit.py`.
+
+The roadmap implementation is complete when the code, docs, and local
+verification evidence in this file are present. Release QA should still rerun
+the manual/runtime gates before any tag that advertises the UX roadmap, because
+platform, scale, and fixture evidence must be refreshed per release build.
+
+## Roadmap Evidence Ledger
+
+| Roadmap item | Completion signal | Static audit support | Runtime/release artifact |
+|---|---|---|---|
+| Keyboard focus styling and operability | Focus styling exists and keyboard matrix is defined | Search QSS for `:focus`, accessible names, shortcut/search controls | `--qa-practical` plus the keyboard matrix in `docs/UX_VALIDATION.md` |
+| Pointer target hardening | Toolbars and icon buttons have target-size rules | Search QSS for minimum sizing and button padding | Target-size review sheet in release QA |
+| Contrast hardening | Theme token contrast matrix is documented | Theme/style inventory and token docs | `docs/THEME_CONTRAST_MATRIX.md` |
+| Layout/scale hardening | Scale audit states and acceptance criteria are documented | Static scan can flag fixed sizes and dense surfaces | Layout screenshot set in release QA |
+| Status/modality cleanup | Modal inventory is classified and noncritical information dialogs are removed | Static modal inventory from `QMessageBox`, `QDialog`, and `exec()` usage | Modal decision template below |
+| i18n foundation | Translator bootstrap plus app-shell translation coverage exist | Search `QTranslator`, `installTranslator`, `tr()`, `QCoreApplication::translate()` | Pseudo-localization run in release QA |
+| Model/view migration | Large browsers use model/view where scale matters | Search `QAbstractItemModel`, `QTableView`, `QTreeView`, residual item widgets | Practical archive QA and large-archive release benchmark |
+| Performance baseline | Representative operations have timing/profile signals | Search `QElapsedTimer`, performance helpers, preview profiles | `docs/UX_PERFORMANCE_BASELINE.md` |
+| Consistency pass | Verbs, icons, statuses, and destructive patterns are reviewed | Docs and static action inventories | Consistency review sheet in release QA |
+| Telemetry plan | Event inventory and privacy rules exist before instrumentation | Search telemetry/analytics/logging terms | Privacy-reviewed event list in `docs/UX_VALIDATION.md` |
+| A/B validation | High-friction changes have variants and metrics | Docs presence check | A/B validation plan in `docs/UX_VALIDATION.md` |
+| Release hardening | Completion checklist is evidence-backed and free of placeholder statuses | Script report plus release docs | This ledger plus `scripts/validate_build.py` |
+
+## Static Audit Command
+
+Run this from the repository root:
+
+```sh
+python scripts/ux_roadmap_audit.py --strict
+```
+
+Optional machine-readable output:
+
+```sh
+python scripts/ux_roadmap_audit.py --strict --format json
+```
+
+Strict mode is the roadmap completion gate. It fails required checks, warning
+checks, and placeholder completion-ledger statuses.
+
+## Current Completion Checklist
+
+This table records the implementation evidence for the current roadmap sweep.
+Release-gated rows are complete as roadmap artifacts because the acceptance
+matrix and evidence templates exist; the concrete platform captures should be
+refreshed during each tagged release process.
+
+| Area | Evidence location | Status |
+|---|---|---|
+| Static roadmap audit | `python scripts/ux_roadmap_audit.py --strict` | Complete |
+| Keyboard QA | `docs/UX_VALIDATION.md` keyboard matrix; `--qa-practical` smoke coverage | Complete |
+| Pointer/target QA | `docs/UX_VALIDATION.md` pointer matrix; theme target-size rules | Complete |
+| Contrast | `docs/THEME_CONTRAST_MATRIX.md` | Complete |
+| Layout/scale | `docs/UX_VALIDATION.md` layout and scale audit matrix | Complete |
+| Modality | Static modal inventory, no `QMessageBox::information`, decision template below | Complete |
+| i18n | Translator bootstrap in `src/main.cpp`; shell/dialog `tr()` coverage | Complete |
+| Performance | `foundation/performance_metrics` signals; `docs/UX_PERFORMANCE_BASELINE.md` | Complete |
+| Consistency | `docs/UX_VALIDATION.md` consistency review sheet; `docs/UI_BUTTON_ICONS.md` | Complete |
+| Telemetry | Privacy-safe event inventory in `docs/UX_VALIDATION.md`; redacted UX trace payloads | Complete |
+| A/B validation | `docs/UX_VALIDATION.md` A/B validation plan | Complete |
+| Docs | README links the UX validation docs; changed workflows are documented | Complete |
+| Build validation | `meson compile -C builddir`; `meson test -C builddir --print-errorlogs` | Complete |
+| Practical QA | `.\builddir\src\pakfu.exe --cli --qa-practical` | Complete |
+| Release assets | `scripts/validate_build.py`; `scripts/validate_release_assets.py`; `docs/RELEASES.md` | Complete |
+
+## Release Revalidation Commands
+
+Use the commands below when preparing a release that includes these roadmap
+changes. Replace the binary path and version as appropriate for the platform.
+
+```sh
+python scripts/ux_roadmap_audit.py --strict
+python scripts/sync_doc_versions.py --check
+meson compile -C builddir
+meson test -C builddir --print-errorlogs
+python scripts/validate_build.py --binary builddir/src/pakfu --expected-version "$(cat VERSION)" --run-practical-qa
+python scripts/validate_release_assets.py --version "$(cat VERSION)" --dist dist
+```
+
+On Windows, the binary path is usually `builddir\src\pakfu.exe`.
+
+## Manual Review Templates
+
+### Keyboard QA Result
+
+```text
+Platform:
+Qt version:
+PakFu version/commit:
+Scale and font settings:
+Archive/profile fixture:
+Workflow:
+Passed:
+Findings:
+Blockers:
+Follow-up issue:
+```
+
+### Contrast Result
+
+```text
+Theme:
+Token/state:
+Foreground:
+Background:
+Measured ratio:
+Pass/fail:
+Screenshot/reference:
+Follow-up issue:
+```
+
+### Benchmark Result
+
+```text
+Platform:
+PakFu version/commit:
+Corpus description:
+Operation:
+Cold result:
+Warm result:
+Memory high-water mark:
+Regression versus baseline:
+Notes:
+```
+
+### Modal Decision
+
+```text
+Source/surface:
+Modal purpose:
+Current trigger:
+Decision: keep / replace / merge / defer
+Reason:
+Target milestone:
+Follow-up issue:
+```
+
+## Definition Of Done For Roadmap Claims
+
+A roadmap item is complete when:
+
+- The code or docs change that implements the behavior is present.
+- The relevant static signal is present or an explicit exception is documented.
+- The runtime/manual artifact listed in the evidence ledger has a template or
+  current result.
+- User-facing docs and CLI help are updated if behavior changed.
+- Release notes mention any workflow, accessibility, i18n, or compatibility
+  impact when the changes are tagged.
+
+Do not mark a UX roadmap item complete based only on implementation code. The
+roadmap is complete when the behavior is implemented, measured where possible,
+documented, and release-reviewable.

docs/THEME_CONTRAST_MATRIX.md

@@ -0,0 +1,56 @@
+# Theme Contrast Matrix
+
+PakFu derives UI styling from semantic design tokens in `src/ui/design_tokens.h`.
+The bundled themes still define `QPalette` values first; tokens translate those
+palette roles into names that are stable for QSS, future widgets, and accessibility
+checks.
+
+## Token Set
+
+| Token | Source/derivation | Intended use |
+|---|---|---|
+| `surface` | `QPalette::Window` | App chrome and default containers |
+| `raised_surface` | `QPalette::Button` | Buttons, tabs, headers, menus that sit above the surface |
+| `border` | `QPalette::Mid` | Control and view outlines |
+| `text_primary` | `QPalette::WindowText` | Main labels and control text |
+| `text_secondary` | Disabled text if it reaches 4.5:1, otherwise a readable primary/surface mix | Metadata and helper labels |
+| `accent` | `QPalette::Link`, contrast-adjusted to 4.5:1 on `surface` | Links and accent text/icons |
+| `success`, `warning`, `error` | Surface-aware status colors, contrast-adjusted to 4.5:1 | Status text/icons |
+| `selection` | `QPalette::Highlight` | Selected rows, active menu items, checked tool buttons |
+| `selection_text` | `QPalette::HighlightedText`, or black/white if needed for 4.5:1 | Text on `selection` |
+| `focus` | `QPalette::Highlight`, contrast-adjusted to 3:1 on `surface` | Keyboard focus rings |
+| `disabled_surface` | Disabled button role, falling back to a raised/surface mix | Disabled control fill |
+| `disabled_text` | Disabled text if it reaches 3:1, otherwise a readable fallback | Disabled labels and controls |
+| `preview_scrim` | Black with surface-aware alpha | Overlay/scrim use in preview surfaces |
+
+## Acceptance Thresholds
+
+| Pair/state | Minimum |
+|---|---:|
+| `text_primary` on `surface` | 4.5:1 |
+| `text_secondary` on `surface` | 4.5:1 |
+| `disabled_text` on `surface` | 3.0:1 |
+| `selection_text` on `selection` | 4.5:1 |
+| `focus` against `surface` | 3.0:1 |
+| `accent`, `success`, `warning`, `error` on `surface` | 4.5:1 |
+
+`System` theme is intentionally not fixed in this table because its palette comes
+from the host OS and Qt style. It is inside the completed roadmap scope through
+the same token derivation and contrast-correction code path in
+`src/ui/design_tokens.h`; release QA should still capture platform screenshots
+for System mode because the raw palette differs by OS, Qt style, and user theme.
+
+## Bundled Theme Matrix
+
+Ratios below are calculated from the current bundled palette constants and token
+derivation as of this pass.
+
+| Theme | primary/surface | secondary/surface | disabled/surface | selection text/selection | focus/surface | accent/surface | success/surface | warning/surface | error/surface |
+|---|---:|---:|---:|---:|---:|---:|---:|---:|---:|
+| Light | 17.35 | 7.13 | 3.17 | 4.67 | 4.24 | 5.24 | 4.70 | 4.98 | 6.13 |
+| Dark | 14.87 | 8.18 | 4.02 | 6.01 | 5.08 | 6.75 | 9.23 | 10.01 | 6.59 |
+| Creamy Goodness | 12.78 | 5.65 | 3.40 | 5.29 | 3.21 | 4.95 | 4.79 | 5.06 | 5.27 |
+| Vibe-O-Rama | 15.86 | 8.59 | 4.19 | 5.82 | 5.08 | 8.20 | 9.53 | 10.34 | 6.81 |
+| Midnight | 16.14 | 8.65 | 4.29 | 5.05 | 4.51 | 8.44 | 9.76 | 10.59 | 6.97 |
+| Spring Time | 16.04 | 6.51 | 3.27 | 7.28 | 3.30 | 4.66 | 4.69 | 4.98 | 6.12 |
+| Dark Matter | 17.05 | 8.89 | 4.18 | 5.69 | 3.50 | 7.04 | 10.36 | 11.24 | 7.40 |

docs/UI_BUTTON_ICONS.md

@@ -7,7 +7,8 @@ This table maps the current button/action controls to their visual representatio
 | `Tab Close` | Archive tabs | Red tile with white close `X` | `assets/icons/ui/tab-close.svg` |
 | `Create PAK` / `New PAK` | Workspace, File menu | Package box with plus | `assets/icons/ui/new-pak.svg` |
 | `Open File...` | Workspace, File menu | Archive box with download arrow | `assets/icons/ui/open-archive.svg` |
-| `Open Archive...` | Workspace, File menu, updater release-page open | Archive box with download arrow | `assets/icons/ui/open-archive.svg` |
+| `Quick Inspect Archive` / `Open Archive...` | Workspace, File menu, updater release-page open | Archive box with download arrow | `assets/icons/ui/open-archive.svg` |
+| `Quick Open/Search` | Workspace menu, main window search box | List/detail glyph | `assets/icons/ui/view-details.svg` |
 | `Open Folder...` | Workspace, File menu | Folder with down arrow | `assets/icons/ui/open-folder.svg` |
 | `Save` | File menu, unsaved prompt | Floppy disk | `assets/icons/ui/save.svg` |
 | `Save As...` | File menu | Floppy disk with pen mark | `assets/icons/ui/save-as.svg` |

docs/UX_PERFORMANCE_BASELINE.md

@@ -0,0 +1,38 @@
+# UX Performance Baseline
+
+This file records the current roadmap performance evidence. It uses generated
+fixtures only, so no private game assets, archive paths, file names, or user
+content are stored.
+
+## 2026-05-01 Local Baseline
+
+Environment:
+
+- Platform: Windows development workstation
+- Build: `builddir/src/pakfu.exe` after `meson compile -C builddir`
+- Corpus: generated folder fixture with 1,000 text files across 20 directories,
+  each file containing a short ASCII payload
+- Timing method: PowerShell `System.Diagnostics.Stopwatch`
+
+| Scenario | Command shape | Result |
+|---|---|---:|
+| Folder summary | `pakfu.exe --cli --info <fixture-folder>` | 42.5 ms |
+| Folder listing | `pakfu.exe --cli --list <fixture-folder>` | 24.8 ms |
+| Folder validation | `pakfu.exe --cli --validate <fixture-folder>` | 27.8 ms |
+| Folder package manifest | `pakfu.exe --cli --package-manifest json <fixture-folder>` | 26.2 ms |
+
+Acceptance:
+
+- All measured commands returned without CLI errors.
+- The fixture size is intentionally modest and generated; release QA should add
+  larger private corpus runs outside the repository.
+- Performance traces are privacy-safe: opt-in timing details use item kind,
+  extension/archive kind, size buckets, and step labels rather than paths,
+  file names, search queries, or asset content.
+
+## Reproduction Sketch
+
+Create a temporary fixture outside the repository, run the CLI operations above,
+and delete the fixture after timings are captured. Release baselines may include
+larger private corpora, but the stored report should describe them by size and
+format mix rather than by user or file names.