feat(ui): refine scan guidance and adaptive layout

[DysektAI]

What changed

• classify quest item needs as active, available now, future-known, or conditional using TarkovTracker progress and json.tarkov.dev task gates
• preserve FIR, kappa, optional-objective, and weapon-hand-in detail without presenting uncertain needs as active
• redesign the scan result card, scanner status, game-mode controls, native title bar, and responsive narrow layout
• add a WebView-to-WPF content-fit bridge so the window grows and retracts with result details while respecting user resizing and monitor work areas
• update all locale catalogs and the relevant agent-context documentation
• add focused quest-classification and presentation regression coverage

Why

The previous single quest-needed total could not distinguish active needs from level-locked, prerequisite-locked, faction-dependent, trader-gated, or otherwise unmodeled requirements. The updated presentation keeps those states explicit and makes the primary scan decision easier to read across normal and narrow windows.

Validation

• dotnet csharpier check .
• scripts/lint-markdown.ps1 and scripts/check-agent-docs.ps1
• scripts/test-agent-docs.ps1 (52 scenarios)
• scripts/test-data-validation.ps1 (33 scenarios)
• dotnet build RatScanner.sln -c Release --no-restore (0 warnings, 0 errors)
• dotnet test RatScanner.sln -c Release --no-build (250 passed)
• npm audit --audit-level=high (0 vulnerabilities)
• transitive .NET package vulnerability audit (0 vulnerabilities)
• live json.tarkov.dev task-contract check
• Windows WPF/WebView smoke: live item search/result, details expansion, sidebar rail/drawer, game-mode indicator, maximize/restore, settings navigation, and fit-driven 720→817→394 px height transitions

---

---

Summary by cubic

Make scan guidance applicability-aware so active quest needs are split from locked or conditional ones, and refine the scan UI and adaptive window sizing for clear results at any size. Recommendation verdicts now distinguish “keep for quest”, “available soon”, “needed later”, and “maybe needed”.

• New Features

  • Classify per-item quest needs via QuestNeedClassifier into active now, available now, future-known, and maybe-needed; uncertain/future needs no longer inflate “needed now”.
  • Drive classification with tracker fields (playerLevel, pmcFaction, failed/invalid) and json.tarkov.dev task gates (min level, faction, prerequisites, trader standing/loyalty, optional flags, Lightkeeper/timed); bump tasks cache to v2 and extend models.
  • Add a WebView↔WPF content-fit bridge (ResizeObserver + MutationObserver) and host ContentFitChanged/ContentFitCleared so the window ratchets its minimum height and grows smoothly while respecting user resizing.
  • Make the sidebar GameModeSwitch the single authority; add a compact toolbar GameModeIndicator that opens the sidebar when collapsed.

• UI Improvements

  • Redesign the result card and narrow layouts; healthy scanner status renders no box and announces changes via a live region.
  • Restyle the native title bar (shorter caption, dark palette), and keep a 1px visible frame with generous resize hit targets.
  • Tighten responsive spacing; refresh theme tokens and all locales, including short freshness strings.

^{Written for commit 95b8a96. Summary will update on new commits.}

[coderabbitai]

📝 Walkthrough

Summary by CodeRabbit

• New Features
  • Added sidebar/compact controls for switching game mode (with a single authoritative selector and a collapsed-state indicator).
  • Improved scan-window sizing to automatically fit content height and animate smoothly while preserving manual resizing.
  • Expanded quest requirement classification with new verdicts, reason buckets, FIR messaging, and quest status chips.
• Improvements
  • Refreshed scan result cards and search UI, including clearer market freshness text and better small-window responsiveness.
  • Updated native title bar styling, theme palette, and scanner status announcements (reduced flashing via debouncing).
  • Extended tracker progress support (new task/progress fields) and enhanced displayed progress details.
• Documentation
  • Updated UI ownership and UI settings flow documentation.
• Tests
  • Added/updated coverage for quest classification logic.

Walkthrough

This PR adds applicability-aware quest classification driven by task gates, updates scan-result verdicts and status chips using quest need reports, introduces content-fit window sizing with animated height constraints, expands game-mode control patterns, debounces scanner status visibility, refreshes themes and native chrome styling, translates new UI labels across seven languages, and includes comprehensive regression tests for classification logic.

Changes

Quest classification and scan presentation

Layer / File(s)	Summary
Task gate data models and TarkovDev projection src/App/TarkovDev/Models.cs, src/App/TarkovDev/JsonApiModels.cs, src/App/TarkovDevAPI.cs, src/App/FetchModels/TarkovTracker/Progress.cs, src/App/FetchModels/TarkovTracker/UserProgress.cs	Task gains prerequisite, trader requirement, player level, and faction constraints; TaskObjective adds optional flag; TarkovTracker Progress and UserProgress expose task status and player fields; API cache key is versioned to tasks_v2_* to invalidate stale projections.
Quest need classification core src/App/QuestNeedClassifier.cs, src/App/ItemExtensions.cs	QuestNeedClassifier is the single authoritative place for converting task gates plus tracker progress into applicability-aware buckets (active, available, future, conditional) with FIR and weapon hand-in tracking; ItemExtensions refactors task-remaining logic to use the classifier.
Recommendation and view model logic src/App/Presentation/ResultPresentationServices.cs, src/App/Presentation/ScanResultViewModel.cs, src/App/Presentation/ScanResultAdapter.cs	Quest need reports replace requirement breakdowns in RecommendationSelector (producing NeededLater, MaybeNeeded, QuestAvailableSoon recommendation types), ScanResultViewModel (via QuestNeedViewModel), and ScanResultAdapter (populating active/weapon advisory buckets).
Scan result card markup and styling src/App/Pages/App/Index.razor, src/App/Pages/App/Index.razor.css	Scan result card replaces recommendation/market blocks with verdict-driven status chips; market freshness is condensed to short-text plus tooltip; action buttons collapse to overflow menu on narrow widths; responsive layouts adjust at multiple breakpoints.
Localization across seven languages src/App/i18n/{en,es,fr,pl,pt,ru,zh}.json	FIR badge/breakdown labels, verdict/chip text, quest availability timing (NeededLater, MaybeNeeded, QuestAvailableSoon), reason buckets, freshness short-formats, and minimal-UI guidance labels are added across all supported locales.
Classification and presentation tests tests/RatScanner.Tests/QuestNeedClassifierTests.cs, tests/RatScanner.Tests/PresentationServicesTests.cs	Comprehensive regression tests validate task applicability transitions, gate evaluation, objective progress mechanics, constraint satisfaction, and recommendation logic for all quest timing scenarios.

Window sizing, controls, and styling

Layer / File(s)	Summary
Content-fit window sizing src/App/AppStateService.cs, src/App/wwwroot/index.html, src/App/Pages/App/Index.razor, src/App/PageSwitcher.xaml, src/App/PageSwitcher.xaml.cs	Resize and mutation observers report scan-page required/visible heights through application state; PageSwitcher animates constrained window sizing with ease-out timing while preserving user resize ownership via anchor mechanism; includes working-area clamping, fit-height cleanup, and optional flag guards.
Game mode controls and status visibility src/App/Shared/AppLayout.razor, src/App/Shared/GameModeSwitch.razor, src/App/Shared/GameModeIndicator.razor, src/App/Shared/ScannerStatus.razor	Sidebar owns authoritative GameModeSwitch; collapsed layouts show compact GameModeIndicator button that opens sidebar; ScannerStatus debounces non-ready state visibility to prevent flash during init/reload; all components listen to relevant settings/state changes and update reactively.
Theme palette and native chrome src/App/App.xaml, src/App/PageSwitcher.xaml, src/App/Shared/MainLayout.razor, src/App/wwwroot/css/theme.css, src/App/Shared/*.razor.css	Application color palette is refreshed (neutral dark surfaces/borders, accent-based purple, semantic colors); native title bar brush resources and button styles are revised; chrome dimensions and button icon geometry are updated; .sr-only utility class is added for assistive-tech content.

Estimated code review effort: 4 (Complex) | ~70 minutes

Sequence Diagram(s)

sequenceDiagram
  participant ScanPage as Scan Page UI
  participant FitWatch as RatScanner.fitWatch
  participant AppState as AppStateService
  participant PageSwitcher as PageSwitcher
  participant Window as Window
  FitWatch->>ScanPage: observe resize & mutation
  ScanPage->>FitWatch: content changes occur
  FitWatch->>AppState: OnContentFitChanged(requiredHeight, visibleHeight)
  AppState->>PageSwitcher: ContentFitChanged event
  PageSwitcher->>PageSwitcher: compute target height
  PageSwitcher->>Window: animate MinHeight & Height
  Note over Window: ease-out timing<br/>preserve user anchor<br/>clamp to working area

Loading

Possibly related PRs

• tarkovtracker-org/RatScanner#2 — Extends the same AppStateService content-fit event and window-state pipeline introduced earlier.

Suggested labels: size:XXL

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 8.05% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Title check	✅ Passed	The title clearly summarizes the main UI and scan-guidance changes in the PR.
Description check	✅ Passed	The description matches the PR changes and validation work, covering classification, UI redesign, content-fit bridging, docs, and tests.

✨ Finishing Touches 💡 1

📝 Generate docstrings 💡

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch agent/applicability-aware-scan-guidance

---

_{Comment @coderabbitai help to get the list of available commands.}

[DysektAI]

Addressed the CodeRabbit outside-diff weapon-hand-in finding in commit 0cc1ac0: the usability advisory now counts give/build objectives only when the scanned item is a weapon (gun type). Added a regression proving a non-weapon give-item objective still contributes to quest totals without triggering WeaponHandInTotal. Local integrated validation after the full review batch: Release build 0 warnings/errors, 258 tests passed, CSharpier clean, all 7 locale catalogs in exact key parity, 52 agent-doc scenarios passed, 33 RatScannerData scenarios passed, Markdown lint clean, and behavior-tier WPF/WebView validation completed.