fix: improve comment wording for spell check

## Summary of the Pull Request

This PR enables pointer-invoked context menus for list items when the
list contains at least one item, including the primary item.

The command bar "More" button or Ctrl+K hotkey remain unaffected - the
menu is not accessible through those.

<img width="453" height="210" alt="image"
src="https://github.com/user-attachments/assets/af0f38e3-e1e7-4968-9e2d-6d9293785ab1"
/>


<!-- Please review the items on the PR checklist before submitting-->
## PR Checklist

- [x] Closes: #45083
<!-- - [ ] Closes: #yyy (add separate lines for additional resolved
issues) -->
- [ ] **Communication:** I've discussed this with core contributors
already. If the work hasn't been agreed, this work might be rejected
- [ ] **Tests:** Added/updated and all pass
- [ ] **Localization:** All end-user-facing strings can be localized
- [ ] **Dev docs:** Added/updated
- [ ] **New binaries:** Added on the required places
- [ ] [JSON for
signing](https://github.com/microsoft/PowerToys/blob/main/.pipelines/ESRPSigning_core.json)
for new binaries
- [ ] [WXS for
installer](https://github.com/microsoft/PowerToys/blob/main/installer/PowerToysSetup/Product.wxs)
for new binaries and localization folder
- [ ] [YML for CI
pipeline](https://github.com/microsoft/PowerToys/blob/main/.pipelines/ci/templates/build-powertoys-steps.yml)
for new test projects
- [ ] [YML for signed
pipeline](https://github.com/microsoft/PowerToys/blob/main/.pipelines/release.yml)
- [ ] **Documentation updated:** If checked, please file a pull request
on [our docs
repo](https://github.com/MicrosoftDocs/windows-uwp/tree/docs/hub/powertoys)
and link it here: #xxx

<!-- Provide a more detailed description of the PR, other things fixed,
or any additional comments/features here -->
## Detailed Description of the Pull Request / Additional comments

<!-- Describe how you validated the behavior. Add automated tests
wherever possible, but list manual validation steps taken as well -->
## Validation Steps Performed

.github/actions/spell-check/expect.txt

@@ -22,7 +22,6 @@ ADate
 ADDSTRING
 ADDUNDORECORD
 ADifferent
-adjacents
 ADMINS
 adml
 admx
@@ -219,10 +218,11 @@ CIELCh
 cim
 CImage
 cla
-claude
 CLASSDC
+classguid
 classmethod
 CLASSNOTAVAILABLE
+claude
 CLEARTYPE
 clickable
 clickonce
@@ -261,7 +261,6 @@ colorhistory
 colorhistorylimit
 COLORKEY
 colorref
-Convs
 comctl
 comdlg
 comexp
@@ -282,6 +281,7 @@ CONTEXTHELP
 CONTEXTMENUHANDLER
 contractversion
 CONTROLPARENT
+Convs
 copiedcolorrepresentation
 coppied
 copyable
@@ -348,12 +348,14 @@ datareader
 datatracker
 dataversion
 Dayof
+dbcc
 DBID
 DBLCLKS
 DBLEPSILON
 DBPROP
 DBPROPIDSET
 DBPROPSET
+DBT
 DCBA
 DCOM
 DComposition
@@ -371,8 +373,7 @@ DEFAULTICON
 defaultlib
 DEFAULTONLY
 DEFAULTSIZE
-DEFAULTTONEAREST
-Defaulttonearest
+defaulttonearest
 DEFAULTTONULL
 DEFAULTTOPRIMARY
 DEFERERASE
@@ -394,14 +395,19 @@ DESKTOPVERTRES
 devblogs
 devdocs
 devenv
+DEVICEINTERFACE
+devicetype
+DEVINTERFACE
 devmgmt
 DEVMODE
 DEVMODEW
+DEVNODES
 devpal
+DEVTYP
 dfx
 DIALOGEX
-digicert
 diffs
+digicert
 DINORMAL
 DISABLEASACTIONKEY
 DISABLENOSCROLL
@@ -544,7 +550,6 @@ fdx
 FErase
 fesf
 FFFF
-FInc
 Figma
 FILEEXPLORER
 fileexploreraddons
@@ -565,6 +570,7 @@ FILESYSPATH
 Filetime
 FILEVERSION
 FILTERMODE
+FInc
 findfast
 findmymouse
 FIXEDFILEINFO
@@ -666,13 +672,14 @@ HCRYPTPROV
 hcursor
 hcwhite
 hdc
+HDEVNOTIFY
 hdr
 hdrop
 hdwwiz
 Helpline
 helptext
-HGFE
 hgdiobj
+HGFE
 hglobal
 hhk
 HHmmssfff
@@ -748,9 +755,9 @@ HWNDPARENT
 HWNDPREV
 hyjiacan
 IAI
+icf
 ICONERROR
 ICONLOCATION
-icf
 IDCANCEL
 IDD
 idk
@@ -841,8 +848,8 @@ jeli
 jfif
 jgeosdfsdsgmkedfgdfgdfgbkmhcgcflmi
 jjw
-JOBOBJECT
 jobject
+JOBOBJECT
 jpe
 jpnime
 Jsons
@@ -886,6 +893,7 @@ Ldr
 LEFTALIGN
 LEFTSCROLLBAR
 LEFTTEXT
+leftclick
 LError
 LEVELID
 LExit
@@ -928,9 +936,9 @@ LOWORD
 lparam
 LPBITMAPINFOHEADER
 LPCFHOOKPROC
+lpch
 LPCITEMIDLIST
 LPCLSID
-lpch
 lpcmi
 LPCMINVOKECOMMANDINFO
 LPCREATESTRUCT
@@ -946,6 +954,7 @@ LPMONITORINFO
 LPOSVERSIONINFOEXW
 LPQUERY
 lprc
+LPrivate
 LPSAFEARRAY
 lpstr
 lpsz
@@ -955,7 +964,6 @@ lptpm
 LPTR
 LPTSTR
 lpv
-LPrivate
 LPW
 lpwcx
 lpwndpl
@@ -999,18 +1007,19 @@ mber
 MBM
 MBR
 Mbuttondown
+mcp
 MDICHILD
 MDL
 mdtext
 mdtxt
 mdwn
 meme
-mcp
 memicmp
 MENUITEMINFO
 MENUITEMINFOW
 MERGECOPY
 MERGEPAINT
+Metacharacter
 metadatamatters
 Metadatas
 metafile
@@ -1040,8 +1049,8 @@ mmi
 mmsys
 mobileredirect
 mockapi
-modelcontextprotocol
 MODALFRAME
+modelcontextprotocol
 MODESPRUNED
 MONITORENUMPROC
 MONITORINFO
@@ -1085,9 +1094,9 @@ MSLLHOOKSTRUCT
 Mso
 msrc
 msstore
+mstsc
 msvcp
 MT
-mstsc
 MTND
 MULTIPLEUSE
 multizone
@@ -1097,11 +1106,11 @@ muxxc
 muxxh
 MVPs
 mvvm
-myorg
-myrepo
 MVVMTK
 MWBEx
 MYICON
+myorg
+myrepo
 NAMECHANGE
 namespaceanddescendants
 nao
@@ -1242,10 +1251,8 @@ opencode
 OPENFILENAME
 openrdp
 opensource
-openxmlformats
-ollama
-onnx
 openurl
+openxmlformats
 OPTIMIZEFORINVOKE
 ORPHANEDDIALOGTITLE
 ORSCANS
@@ -1462,7 +1469,6 @@ rbhid
 Rbuttondown
 rclsid
 RCZOOMIT
-remotedesktop
 rdp
 RDW
 READMODE
@@ -1491,6 +1497,7 @@ remappings
 REMAPSUCCESSFUL
 REMAPUNSUCCESSFUL
 Remotable
+remotedesktop
 remoteip
 Removelnk
 renamable
@@ -1524,8 +1531,8 @@ RIGHTSCROLLBAR
 riid
 RKey
 RNumber
-rop
 rollups
+rop
 ROUNDSMALL
 ROWSETEXT
 rpcrt
@@ -1764,8 +1771,7 @@ SVGIO
 svgz
 SVSI
 SWFO
-SWP
-Swp
+swp
 SWPNOSIZE
 SWPNOZORDER
 SWRESTORE
@@ -1784,8 +1790,7 @@ SYSKEY
 syskeydown
 SYSKEYUP
 SYSLIB
-SYSMENU
-Sysmenu
+sysmenu
 systemai
 SYSTEMAPPS
 SYSTEMMODAL
@@ -1889,9 +1894,9 @@ uitests
 UITo
 ULONGLONG
 Ultrawide
-ums
 UMax
 UMin
+ums
 uncompilable
 UNCPRIORITY
 UNDNAME

.github/instructions/common-libraries.instructions.md

@@ -0,0 +1,61 @@
+---
+description: 'Guidelines for shared libraries including logging, IPC, settings, DPI, telemetry, and utilities consumed by multiple modules'
+applyTo: 'src/common/**'
+---
+
+# Common Libraries – Shared Code Guidance
+
+Guidelines for modifying shared code in `src/common/`. Changes here can have wide-reaching impact across the entire PowerToys codebase.
+
+## Scope
+
+- Logging infrastructure (`src/common/logger/`)
+- IPC primitives and named pipe utilities
+- Settings serialization and management
+- DPI awareness and scaling utilities
+- Telemetry helpers
+- General utilities (JSON parsing, string helpers, etc.)
+
+## Guidelines
+
+### API Stability
+
+- Avoid breaking public headers/APIs; if changed, search & update all callers
+- Coordinate ABI-impacting struct/class layout changes; keep binary compatibility
+- When modifying public interfaces, grep the entire codebase for usages
+
+### Performance
+
+- Watch perf in hot paths (hooks, timers, serialization)
+- Avoid avoidable allocations in frequently called code
+- Profile changes that touch performance-sensitive areas
+
+### Dependencies
+
+- Ask before adding third-party deps or changing serialization formats
+- New dependencies must be MIT-licensed or approved by PM team
+- Add any new external packages to `NOTICE.md`
+
+### Logging
+
+- C++ logging uses spdlog (`Logger::info`, `Logger::warn`, `Logger::error`, `Logger::debug`)
+- Initialize with `init_logger()` early in startup
+- Keep hot paths quiet – no logging in tight loops or hooks
+
+## Acceptance Criteria
+
+- No unintended ABI breaks
+- No noisy logs in hot paths
+- New non-obvious symbols briefly commented
+- All callers updated when interfaces change
+
+## Code Style
+
+- **C++**: Follow `.clang-format` in `src/`; use Modern C++ patterns per C++ Core Guidelines
+- **C#**: Follow `src/.editorconfig`; enforce StyleCop.Analyzers
+
+## Validation
+
+- Build: `tools\build\build.cmd` from `src/common/` folder
+- Verify no ABI breaks: grep for changed function/struct names across codebase
+- Check logs: ensure no new logging in performance-critical paths

.github/instructions/runner-settings-ui.instructions.md

@@ -0,0 +1,68 @@
+---
+description: 'Guidelines for Runner and Settings UI components that communicate via named pipes and manage module lifecycle'
+applyTo: 'src/runner/**,src/settings-ui/**'
+---
+
+# Runner & Settings UI – Core Components Guidance
+
+Guidelines for modifying the Runner (tray/module loader) and Settings UI (configuration app). These components communicate via Windows Named Pipes using JSON messages.
+
+## Runner (`src/runner/`)
+
+### Scope
+
+- Module bootstrap, hotkey management, settings bridge, update/elevation handling
+
+### Guidelines
+
+- If IPC/JSON contracts change, mirror updates in `src/settings-ui/**`
+- Keep module discovery in `src/runner/main.cpp` in sync when adding/removing modules
+- Keep startup lean: avoid blocking/network calls in early init path
+- Preserve GPO & elevation behaviors; confirm no regression in policy handling
+- Ask before modifying update workflow or elevation logic
+
+### Acceptance Criteria
+
+- Stable startup, consistent contracts, no unnecessary logging noise
+
+## Settings UI (`src/settings-ui/`)
+
+### Scope
+
+- WinUI/WPF UI, communicates with Runner over named pipes; manages persisted settings schema
+
+### Guidelines
+
+- Don't break settings schema silently; add migration when shape changes
+- If IPC/JSON contracts change, align with `src/runner/**` implementation
+- Keep UI responsive: marshal to UI thread for UI-bound operations
+- Reuse existing styles/resources; avoid duplicate theme keys
+- Add/adjust migration or serialization tests when changing persisted settings
+
+### Acceptance Criteria
+
+- Schema integrity preserved, responsive UI, consistent contracts, no style duplication
+
+## Shared Concerns
+
+### IPC Contract Changes
+
+When modifying the JSON message format between Runner and Settings UI:
+
+1. Update both `src/runner/` and `src/settings-ui/` in the same PR
+2. Preserve backward compatibility where possible
+3. Add migration logic for settings schema changes
+4. Test both directions of communication
+
+### Code Style
+
+- **C++ (Runner)**: Follow `.clang-format` in `src/`
+- **C# (Settings UI)**: Follow `src/.editorconfig`, use StyleCop.Analyzers
+- **XAML**: Use XamlStyler or run `.\.pipelines\applyXamlStyling.ps1 -Main`
+
+## Validation
+
+- Build Runner: `tools\build\build.cmd` from `src/runner/`
+- Build Settings UI: `tools\build\build.cmd` from `src/settings-ui/`
+- Test IPC: Launch both Runner and Settings UI, verify communication works
+- Schema changes: Run serialization tests if settings shape changed

.github/prompts/create-commit-title.prompt.md

@@ -1,6 +1,5 @@
 ---
 agent: 'agent'
-model: 'GPT-5.1-Codex-Max'
 description: 'Generate an 80-character git commit title for the local diff'
 ---
 

.github/prompts/create-pr-summary.prompt.md

@@ -1,6 +1,5 @@
 ---
 agent: 'agent'
-model: 'GPT-5.1-Codex-Max'
 description: 'Generate a PowerToys-ready pull request description from the local diff'
 ---
 

.github/prompts/fix-issue.prompt.md

@@ -1,6 +1,5 @@
 ---
 agent: 'agent'
-model: 'GPT-5.1-Codex-Max'
 description: 'Execute the fix for a GitHub issue using the previously generated implementation plan'
 ---
 

.github/prompts/fix-pr-active-comments.prompt.md

@@ -0,0 +1,70 @@
+---
+description: 'Fix active pull request comments with scoped changes'
+name: 'fix-pr-active-comments'
+agent: 'agent'
+argument-hint: 'PR number or active PR URL'
+---
+
+# Fix Active PR Comments
+
+## Mission
+Resolve active pull request comments by applying only simple fixes. For complex refactors, write a plan instead of changing code.
+
+## Scope & Preconditions
+- You must have an active pull request context or a provided PR number.
+- Only implement simple changes. Do not implement large refactors.
+- If required context is missing, request it and stop.
+
+## Inputs
+- Required: ${input:pr_number:PR number or URL}
+- Optional: ${input:comment_scope:files or areas to focus on}
+- Optional: ${input:fixing_guidelines:additional fixing guidelines from the user}
+
+## Workflow
+1. Locate all active (unresolved) PR review comments for the given PR.
+2. For each comment, classify the change scope:
+   - Simple change: limited edits, localized fix, low risk, no broad redesign.
+   - Large refactor: multi-file redesign, architecture change, or risky behavior change.
+3. For each large refactor request:
+   - Do not modify code.
+   - Write a planning document to Generated Files/prReview/${input:pr_number}/fixPlan/.
+4. For each simple change request:
+   - Implement the fix with minimal edits.
+   - Run quick checks if needed.
+   - Commit and push the change.
+5. For comments that seem invalid, unclear, or not applicable (even if simple):
+   - Do not change code.
+   - Add the item to a summary table in Generated Files/prReview/${input:pr_number}/fixPlan/overview.md.
+   - Consult back to the end user in a friendly, polite tone.
+6. Respond to each comment that you fixed:
+   - Reply in the active conversation.
+   - Use a polite or friendly tone.
+   - Keep the response under 200 words.
+   - Resolve the comment after replying.
+
+## Output Expectations
+- Simple fixes: code changes committed and pushed.
+- Large refactors: a plan file saved to Generated Files/prReview/${input:pr_number}/fixPlan/.
+- Invalid or unclear comments: captured in Generated Files/prReview/${input:pr_number}/fixPlan/overview.md.
+- Each fixed comment has a reply under 200 words and is resolved.
+
+## Plan File Template
+Use this template for each large refactor item:
+
+# Fix Plan: <short title>
+
+## Context
+- Comment link:
+- Impacted areas:
+
+## Overview Table Template
+Use this table in Generated Files/prReview/${input:pr_number}/fixPlan/overview.md:
+
+| Comment link | Summary | Reason not applied | Suggested follow-up |
+| --- | --- | --- | --- |
+|  |  |  |  |
+
+## Quality Assurance
+- Verify plan file path exists.
+- Ensure no code changes were made for large refactor items.
+- Confirm replies are under 200 words and comments are resolved.

.github/prompts/fix-spelling.prompt.md

@@ -1,6 +1,5 @@
 ---
 agent: 'agent'
-model: 'GPT-5.1-Codex-Max'
 description: 'Resolve Code scanning / check-spelling comments on the active PR'
 ---
 

.github/prompts/review-issue.prompt.md

@@ -1,6 +1,5 @@
 ---
 agent: 'agent'
-model: 'GPT-5.1-Codex-Max'
 description: 'Review a GitHub issue, score it (0-100), and generate an implementation plan'
 ---
 

.github/prompts/review-pr.prompt.md

@@ -1,6 +1,5 @@
 ---
 agent: 'agent'
-model: 'GPT-5.1-Codex-Max'
 description: 'Perform a comprehensive PR review with per-step Markdown and machine-readable outputs'
 ---
 

AGENTS.md

@@ -0,0 +1,165 @@
+---
+description: 'Top-level AI contributor guidance for developing PowerToys - a collection of Windows productivity utilities'
+applyTo: '**'
+---
+
+# PowerToys – AI Contributor Guide
+
+This is the top-level guidance for AI contributions to PowerToys. Keep changes atomic, follow existing patterns, and cite exact paths in PRs.
+
+## Overview
+
+PowerToys is a set of utilities for power users to tune and streamline their Windows experience.
+
+| Area | Location | Description |
+|------|----------|-------------|
+| Runner | `src/runner/` | Main executable, tray icon, module loader, hotkey management |
+| Settings UI | `src/settings-ui/` | WinUI/WPF configuration app communicating via named pipes |
+| Modules | `src/modules/` | Individual PowerToys utilities (each in its own subfolder) |
+| Common Libraries | `src/common/` | Shared code: logging, IPC, settings, DPI, telemetry, utilities |
+| Build Tools | `tools/build/` | Build scripts and automation |
+| Documentation | `doc/devdocs/` | Developer documentation |
+| Installer | `installer/` | WiX-based installer projects |
+
+For architecture details and module types, see [Architecture Overview](doc/devdocs/core/architecture.md).
+
+## Conventions
+
+For detailed coding conventions, see:
+- [Coding Guidelines](doc/devdocs/development/guidelines.md) – Dependencies, testing, PR management
+- [Coding Style](doc/devdocs/development/style.md) – Formatting, C++/C#/XAML style rules
+- [Logging](doc/devdocs/development/logging.md) – C++ spdlog and C# Logger usage
+
+### Component-Specific Instructions
+
+These instruction files are automatically applied when working in their respective areas:
+- [Runner & Settings UI](.github/instructions/runner-settings-ui.instructions.md) – IPC contracts, schema migrations
+- [Common Libraries](.github/instructions/common-libraries.instructions.md) – ABI stability, shared code guidelines
+
+## Build
+
+### Prerequisites
+
+- Visual Studio 2022 17.4+
+- Windows 10 1803+ (April 2018 Update or newer)
+- Initialize submodules once: `git submodule update --init --recursive`
+
+### Build Commands
+
+| Task | Command |
+|------|---------|
+| First build / NuGet restore | `tools\build\build-essentials.cmd` |
+| Build current folder | `tools\build\build.cmd` |
+| Build with options | `build.ps1 -Platform x64 -Configuration Release` |
+
+### Build Discipline
+
+1. One terminal per operation (build → test). Do not switch or open new ones mid-flow
+2. After making changes, `cd` to the project folder that changed (`.csproj`/`.vcxproj`)
+3. Use scripts to build: `tools/build/build.ps1` or `tools/build/build.cmd`
+4. For first build or missing NuGet packages, run `build-essentials.cmd` first
+5. **Exit code 0 = success; non-zero = failure** – treat this as absolute
+6. On failure, read the errors log: `build.<config>.<platform>.errors.log`
+7. Do not start tests or launch Runner until the build succeeds
+
+### Build Logs
+
+Located next to the solution/project being built:
+- `build.<configuration>.<platform>.errors.log` – errors only (check this first)
+- `build.<configuration>.<platform>.all.log` – full log
+- `build.<configuration>.<platform>.trace.binlog` – for MSBuild Structured Log Viewer
+
+For complete details, see [Build Guidelines](tools/build/BUILD-GUIDELINES.md).
+
+## Tests
+
+### Test Discovery
+
+- Find test projects by product code prefix (e.g., `FancyZones`, `AdvancedPaste`)
+- Look for sibling folders or 1-2 levels up named `<Product>*UnitTests` or `<Product>*UITests`
+
+### Running Tests
+
+1. **Build the test project first**, wait for exit code 0
+2. Run via VS Test Explorer (`Ctrl+E, T`) or `vstest.console.exe` with filters
+3. **Avoid `dotnet test`** in this repo – use VS Test Explorer or vstest.console.exe
+
+### Test Types
+
+| Type | Requirements | Setup |
+|------|--------------|-------|
+| Unit Tests | Standard dev environment | None |
+| UI Tests | WinAppDriver v1.2.1, Developer Mode | Install from [WinAppDriver releases](https://github.com/microsoft/WinAppDriver/releases/tag/v1.2.1) |
+| Fuzz Tests | OneFuzz, .NET 8 | See [Fuzzing Tests](doc/devdocs/tools/fuzzingtesting.md) |
+
+### Test Discipline
+
+1. Add or adjust tests when changing behavior
+2. If tests skipped, state why (e.g., comment-only change, string rename)
+3. New modules handling file I/O or user input **must** implement fuzzing tests
+
+### Special Requirements
+
+- **Mouse Without Borders**: Requires 2+ physical computers (not VMs)
+- **Multi-monitor utilities**: Test with 2+ monitors, different DPI settings
+
+For UI test setup details, see [UI Tests](doc/devdocs/development/ui-tests.md).
+
+## Boundaries
+
+### Ask for Clarification When
+
+- Ambiguous spec after scanning relevant docs
+- Cross-module impact (shared enum/struct) is unclear
+- Security, elevation, or installer changes involved
+- GPO or policy handling modifications needed
+
+### Areas Requiring Extra Care
+
+| Area | Concern | Reference |
+|------|---------|-----------|
+| `src/common/` | ABI breaks | [Common Libraries Instructions](.github/instructions/common-libraries.instructions.md) |
+| `src/runner/`, `src/settings-ui/` | IPC contracts, schema | [Runner & Settings UI Instructions](.github/instructions/runner-settings-ui.instructions.md) |
+| Installer files | Release impact | Careful review required |
+| Elevation/GPO logic | Security | Confirm no regression in policy handling |
+
+### What NOT to Do
+
+- Don't merge incomplete features into main (use feature branches)
+- Don't break IPC/JSON contracts without updating both runner and settings-ui
+- Don't add noisy logs in hot paths
+- Don't introduce third-party deps without PM approval and `NOTICE.md` update
+
+## Validation Checklist
+
+Before finishing, verify:
+
+- [ ] Build clean with exit code 0
+- [ ] Tests updated and passing locally
+- [ ] No unintended ABI breaks or schema changes
+- [ ] IPC contracts consistent between runner and settings-ui
+- [ ] New dependencies added to `NOTICE.md`
+- [ ] PR is atomic (one logical change), with issue linked
+
+## Documentation Index
+
+### Core Architecture
+- [Architecture Overview](doc/devdocs/core/architecture.md)
+- [Runner](doc/devdocs/core/runner.md)
+- [Settings System](doc/devdocs/core/settings/readme.md)
+- [Module Interface](doc/devdocs/modules/interface.md)
+
+### Development
+- [Coding Guidelines](doc/devdocs/development/guidelines.md)
+- [Coding Style](doc/devdocs/development/style.md)
+- [Logging](doc/devdocs/development/logging.md)
+- [UI Tests](doc/devdocs/development/ui-tests.md)
+- [Fuzzing Tests](doc/devdocs/tools/fuzzingtesting.md)
+
+### Build & Tools
+- [Build Guidelines](tools/build/BUILD-GUIDELINES.md)
+- [Tools Overview](doc/devdocs/tools/readme.md)
+
+### Instructions (Auto-Applied)
+- [Runner & Settings UI](.github/instructions/runner-settings-ui.instructions.md)
+- [Common Libraries](.github/instructions/common-libraries.instructions.md)

Directory.Packages.props

@@ -63,7 +63,7 @@
     <PackageVersion Include="Microsoft.SemanticKernel.Connectors.MistralAI" Version="1.66.0-alpha" />
     <PackageVersion Include="Microsoft.SemanticKernel.Connectors.Ollama" Version="1.66.0-alpha" />
     <PackageVersion Include="Microsoft.Toolkit.Uwp.Notifications" Version="7.1.2" />
-    <PackageVersion Include="Microsoft.Web.WebView2" Version="1.0.3405.78" />
+    <PackageVersion Include="Microsoft.Web.WebView2" Version="1.0.3179.45" />
     <!-- Package Microsoft.Win32.SystemEvents added as a hack for being able to exclude the runtime assets so they don't conflict with 8.0.1. This is a dependency of System.Drawing.Common but the 8.0.1 version wasn't published to nuget. -->
     <PackageVersion Include="Microsoft.Win32.SystemEvents" Version="9.0.10" />
     <PackageVersion Include="Microsoft.WindowsPackageManager.ComInterop" Version="1.10.340" />
@@ -77,8 +77,10 @@
     <PackageVersion Include="Microsoft.Windows.CsWinRT" Version="2.2.0" />
     <PackageVersion Include="Microsoft.Windows.ImplementationLibrary" Version="1.0.231216.1"/>
     <PackageVersion Include="Microsoft.Windows.SDK.BuildTools" Version="10.0.26100.6901" />
-    <PackageVersion Include="Microsoft.WindowsAppSDK" Version="2.0.0-experimental4" />
-    <PackageVersion Include="Microsoft.WindowsAppSDK.AI" Version="2.0.130-experimental" />
+    <PackageVersion Include="Microsoft.WindowsAppSDK" Version="1.8.251106002" />
+    <PackageVersion Include="Microsoft.WindowsAppSDK.Foundation" Version="1.8.251104000" />
+    <PackageVersion Include="Microsoft.WindowsAppSDK.AI" Version="1.8.39" />
+    <PackageVersion Include="Microsoft.WindowsAppSDK.Runtime" Version="1.8.251106002" />
     <PackageVersion Include="Microsoft.Xaml.Behaviors.WinUI.Managed" Version="2.0.9" />
     <PackageVersion Include="Microsoft.Xaml.Behaviors.Wpf" Version="1.1.39" />
     <PackageVersion Include="ModernWpfUI" Version="0.9.4" />

SEMANTIC_SEARCH_API_SUMMARY.md

@@ -1,244 +0,0 @@
-# Windows App SDK Semantic Search API 总结
-
-## 1. 环境与依赖
-
-| 项目 | 版本/值 |
-|------|---------|
-| **Windows App SDK** | `2.0.0-experimental3` |
-| **.NET** | `net9.0-windows10.0.26100.0` |
-| **AI Search NuGet** | `Microsoft.WindowsAppSDK.AI` (2.0.57-experimental) |
-| **命名空间** | `Microsoft.Windows.AI.Search.Experimental.AppContentIndex` |
-| **应用类型** | WinUI 3 MSIX 打包应用 |
-
----
-
-## 2. 核心 API
-
-### 2.1 索引管理
-```csharp
-// 创建/打开索引
-var result = AppContentIndexer.GetOrCreateIndex("indexName");
-if (result.Succeeded) {
-    _indexer = result.Indexer;
-    // result.Status: CreatedNew | OpenedExisting
-}
-
-// 等待索引能力就绪
-await _indexer.WaitForIndexCapabilitiesAsync();
-
-// 等待索引空闲（建索引完成）
-await _indexer.WaitForIndexingIdleAsync(TimeSpan.FromSeconds(120));
-
-// 清理
-_indexer.RemoveAll();  // 删除所有索引
-_indexer.Remove(id);   // 删除单个
-_indexer.Dispose();
-```
-
-### 2.2 添加内容到索引
-```csharp
-// 索引文本 → 自动建立 TextLexical + TextSemantic 索引
-IndexableAppContent textContent = AppManagedIndexableAppContent.CreateFromString(id, text);
-_indexer.AddOrUpdate(textContent);
-
-// 索引图片 → 自动建立 ImageSemantic + ImageOcr 索引
-IndexableAppContent imageContent = AppManagedIndexableAppContent.CreateFromBitmap(id, softwareBitmap);
-_indexer.AddOrUpdate(imageContent);
-```
-
-### 2.3 查询
-```csharp
-// 文本查询
-TextQueryOptions options = new TextQueryOptions {
-    Language = "en-US",                          // 可选
-    MatchScope = QueryMatchScope.Unconstrained,  // 匹配范围
-    TextMatchType = TextLexicalMatchType.Fuzzy   // Fuzzy | Exact
-};
-AppIndexTextQuery query = _indexer.CreateTextQuery(searchText, options);
-IReadOnlyList<TextQueryMatch> matches = query.GetNextMatches(5);
-
-// 图片查询
-ImageQueryOptions imgOptions = new ImageQueryOptions {
-    MatchScope = QueryMatchScope.Unconstrained,
-    ImageOcrTextMatchType = TextLexicalMatchType.Fuzzy
-};
-AppIndexImageQuery imgQuery = _indexer.CreateImageQuery(searchText, imgOptions);
-IReadOnlyList<ImageQueryMatch> imgMatches = imgQuery.GetNextMatches(5);
-```
-
-### 2.4 能力检查（只读）
-```csharp
-IndexCapabilities capabilities = _indexer.GetIndexCapabilities();
-
-bool textLexicalOK = capabilities.GetCapabilityState(IndexCapability.TextLexical)
-    .InitializationStatus == IndexCapabilityInitializationStatus.Initialized;
-bool textSemanticOK = capabilities.GetCapabilityState(IndexCapability.TextSemantic)
-    .InitializationStatus == IndexCapabilityInitializationStatus.Initialized;
-bool imageSemanticOK = capabilities.GetCapabilityState(IndexCapability.ImageSemantic)
-    .InitializationStatus == IndexCapabilityInitializationStatus.Initialized;
-bool imageOcrOK = capabilities.GetCapabilityState(IndexCapability.ImageOcr)
-    .InitializationStatus == IndexCapabilityInitializationStatus.Initialized;
-```
-
----
-
-## 3. 四种索引能力
-
-| 能力 | 说明 | 触发方式 |
-|------|------|----------|
-| `TextLexical` | 词法/关键词搜索 | CreateFromString() 自动 |
-| `TextSemantic` | AI 语义搜索 (Embedding) | CreateFromString() 自动 |
-| `ImageSemantic` | 图像语义搜索 | CreateFromBitmap() 自动 |
-| `ImageOcr` | 图片 OCR 文字搜索 | CreateFromBitmap() 自动 |
-
----
-
-## 4. 可控选项（有限）
-
-### TextQueryOptions
-| 属性 | 类型 | 说明 |
-|------|------|------|
-| `Language` | string | 查询语言（可选，如 "en-US"）|
-| `MatchScope` | QueryMatchScope | Unconstrained / Region / ContentItem |
-| `TextMatchType` | TextLexicalMatchType | **Fuzzy** / Exact（仅影响 Lexical）|
-
-### ImageQueryOptions
-| 属性 | 类型 | 说明 |
-|------|------|------|
-| `MatchScope` | QueryMatchScope | Unconstrained / Region / ContentItem |
-| `ImageOcrTextMatchType` | TextLexicalMatchType | **Fuzzy** / Exact（仅影响 OCR）|
-
-### 枚举值说明
-
-**QueryMatchScope:**
-- `Unconstrained` - 无约束，同时使用 Lexical + Semantic
-- `Region` - 限制在特定区域
-- `ContentItem` - 限制在单个内容项
-
-**TextLexicalMatchType:**
-- `Fuzzy` - 模糊匹配，允许拼写错误、近似词
-- `Exact` - 精确匹配，必须完全一致
-
----
-
-## 5. 关键限制 ⚠️
-
-| 限制 | 说明 |
-|------|------|
-| **不能单独指定 Semantic/Lexical** | 系统自动同时使用所有可用能力 |
-| **Fuzzy/Exact 只影响 Lexical** | 对 Semantic 搜索无效 |
-| **能力检查是只读的** | `GetIndexCapabilities()` 只能查看，不能控制 |
-| **无相似度阈值** | 不能设置 Semantic 匹配的阈值 |
-| **无结果排序控制** | 无法指定按相关度或其他方式排序 |
-| **语言需手动传** | 不会自动检测，需开发者指定 |
-| **无相关度分数** | 查询结果不返回匹配分数 |
-
----
-
-## 6. 典型使用流程
-
-```
-┌─────────────────────────────────────────────────────────┐
-│                    App 启动时                           │
-├─────────────────────────────────────────────────────────┤
-│ 1. GetOrCreateIndex("name")     // 创建/打开索引        │
-│ 2. WaitForIndexCapabilitiesAsync()  // 等待能力就绪     │
-│ 3. GetIndexCapabilities()        // 检查可用能力        │
-│ 4. IndexAll()                    // 索引所有数据        │
-│    ├─ CreateFromString() × N                           │
-│    └─ CreateFromBitmap() × N                           │
-│ 5. WaitForIndexingIdleAsync()    // 等待索引完成        │
-└─────────────────────────────────────────────────────────┘
-                         ↓
-┌─────────────────────────────────────────────────────────┐
-│                    运行时查询                            │
-├─────────────────────────────────────────────────────────┤
-│ 1. CreateTextQuery(text, options)   // 创建查询         │
-│ 2. query.GetNextMatches(N)          // 获取结果         │
-│ 3. 处理 TextQueryMatch / ImageQueryMatch               │
-└─────────────────────────────────────────────────────────┘
-                         ↓
-┌─────────────────────────────────────────────────────────┐
-│                    App 退出时                           │
-├─────────────────────────────────────────────────────────┤
-│ 1. _indexer.RemoveAll()             // 清理索引         │
-│ 2. _indexer.Dispose()               // 释放资源         │
-└─────────────────────────────────────────────────────────┘
-```
-
----
-
-## 7. 查询结果处理
-
-```csharp
-// 文本查询结果
-foreach (var match in textMatches)
-{
-    if (match.ContentKind == QueryMatchContentKind.AppManagedText)
-    {
-        AppManagedTextQueryMatch textResult = (AppManagedTextQueryMatch)match;
-        string contentId = match.ContentId;      // 内容 ID
-        int offset = textResult.TextOffset;      // 匹配文本偏移
-        int length = textResult.TextLength;      // 匹配文本长度
-    }
-}
-
-// 图片查询结果
-foreach (var match in imageMatches)
-{
-    if (match.ContentKind == QueryMatchContentKind.AppManagedImage)
-    {
-        AppManagedImageQueryMatch imageResult = (AppManagedImageQueryMatch)match;
-        string contentId = imageResult.ContentId;  // 图片 ID
-    }
-}
-```
-
----
-
-## 8. 能力变化监听
-
-```csharp
-// 监听索引能力变化
-_indexer.Listener.IndexCapabilitiesChanged += (indexer, capabilities) =>
-{
-    // 重新检查能力状态，更新 UI
-    LoadAppIndexCapabilities();
-};
-```
-
----
-
-## 9. 结论
-
-这是一个**高度封装的黑盒 API**：
-
-### 优点 ✅
-- 简单易用，几行代码即可实现搜索
-- 自动处理 Lexical + Semantic
-- 支持文本和图片多模态搜索
-- 系统级集成，无需额外部署模型
-
-### 缺点 ❌
-- 无法精细控制搜索类型
-- 不能只用 Semantic Search
-- 选项有限，缺乏高级配置
-- 实验性 API，可能变更
-
-### 替代方案
-**如果需要纯 Semantic Search（向量搜索）**，建议：
-- 直接使用 Embedding 模型生成向量
-- 配合向量数据库（Azure Cosmos DB、FAISS、Qdrant 等）
-
----
-
-## 10. 相关 NuGet 包
-
-```xml
-<PackageReference Include="Microsoft.WindowsAppSDK" Version="2.0.0-experimental3" />
-<PackageReference Include="Microsoft.WindowsAppSDK.AI" Version="2.0.57-experimental" />
-```
-
----
-
-*文档生成日期: 2026-01-21*

doc/devdocs/sparse-package-investigation.md

@@ -1,325 +0,0 @@
-# Sparse Package + WinUI 3 调查报告
-
-## 背景
-
-PowerToys 希望使用 Windows App SDK 的 Semantic Search API (`AppContentIndexer.GetOrCreateIndex`) 来实现语义搜索功能。该 API 要求应用具有 **Package Identity**。
-
-## 问题现象
-
-### 1. Semantic Search API 调用失败
-
-在 [SemanticSearchIndex.cs](../../src/common/Common.Search/SemanticSearch/SemanticSearchIndex.cs) 中调用 `AppContentIndexer.GetOrCreateIndex(_indexName)` 时，抛出 COM 异常：
-
-```
-System.Runtime.InteropServices.COMException (0x80004005): Error HRESULT E_FAIL has been returned from a call to a COM component.
-   at WinRT.ExceptionHelpers.<ThrowExceptionForHR>g__Throw|39_0(Int32 hr)
-   at Microsoft.Windows.AI.Search.AppContentIndexer.GetOrCreateIndex(String indexName)
-```
-
-### 2. API 要求
-
-根据 [Windows App SDK 文档](https://learn.microsoft.com/en-us/windows/ai/apis/content-search)，Semantic Search API 需要：
-- Windows 11 24H2 或更高版本
-- NPU 硬件支持
-- **Package Identity**（应用需要有 MSIX 包标识）
-
-## Sparse Package 方案
-
-### 什么是 Sparse Package
-
-Sparse Package（稀疏包）是一种为非打包（unpackaged）Win32 应用提供 Package Identity 的技术，无需完整的 MSIX 打包。
-
-参考：[Grant package identity by packaging with external location](https://learn.microsoft.com/en-us/windows/apps/desktop/modernize/grant-identity-to-nonpackaged-apps)
-
-### 实现架构
-
-```
-PowerToysSparse.msix (仅包含 manifest 和图标)
-    │
-    ├── AppxManifest.xml  (声明应用和依赖)
-    ├── Square44x44Logo.png
-    ├── Square150x150Logo.png
-    └── StoreLogo.png
-
-ExternalLocation (指向实际应用目录)
-    │
-    └── ARM64\Debug\
-        ├── PowerToys.Settings.exe
-        ├── PowerToys.Settings.pri
-        └── ... (其他应用文件)
-```
-
-### 关键组件
-
-| 文件 | 位置 | 作用 |
-|------|------|------|
-| AppxManifest.xml | src/PackageIdentity/ | 定义 sparse package 的应用、依赖和能力 |
-| app.manifest | src/settings-ui/Settings.UI/ | 嵌入 exe 中，声明与 sparse package 的关联 |
-| BuildSparsePackage.ps1 | src/PackageIdentity/ | 构建和签名脚本 |
-
-### Publisher 配置
-
-**重要**：app.manifest 和 AppxManifest.xml 中的 Publisher 必须匹配。
-
-| 环境 | Publisher |
-|------|-----------|
-| 开发环境 | `CN=PowerToys Dev, O=PowerToys, L=Redmond, S=Washington, C=US` |
-| 生产环境 | `CN=Microsoft Corporation, O=Microsoft Corporation, L=Redmond, S=Washington, C=US` |
-
-BuildSparsePackage.ps1 会在本地构建时**自动**将 AppxManifest.xml 的 Publisher 替换为开发环境值，无需手动修改源码。
-
-## 当前问题：WinUI 3 + Sparse Package 崩溃
-
-### 现象
-
-当 Settings.exe（WinUI 3 应用）通过 sparse package 启动时，立即崩溃：
-
-```
-Microsoft.UI.Xaml.Markup.XamlParseException (-2144665590):
-Cannot locate resource from 'ms-appx:///Microsoft.UI.Xaml/Themes/themeresources.xaml'. [Line: 11 Position: 40]
-```
-
-### 新观察（2026-01-25）
-
-对齐 WinAppSDK 版本并恢复 app-local 运行时后，仍可复现**更早期**的崩溃（未写入 Settings 日志）：
-
-- Application Error / WER（AUMID 启动）：
-  - Faulting module: `CoreMessagingXP.dll`
-  - Exception code: `0xc0000602`
-  - Faulting module path: `C:\PowerToys\ARM64\Debug\WinUI3Apps\CoreMessagingXP.dll`
-- 暂时移除 `CoreMessagingXP.dll` 后，出现 .NET Runtime 1026：
-  - `COMException (0x80040111): ClassFactory cannot supply requested class`
-  - 发生在 `Microsoft.UI.Xaml.Application.Start(...)`
-
-这说明 **“themeresources.xaml 无法解析”并不是唯一/必现的失败模式**，app-local 运行时在 sparse identity 下可能存在更底层的初始化问题。
-
-### 新观察（2026-01-25 晚间）
-
-framework-dependent + bootstrap 方向有实质进展：
-
-- 设置 `WindowsAppSDKSelfContained=false`（仅在 `UseSparseIdentity=true` 时生效）
-- 添加 `WindowsAppSDKBootstrapAutoInitializeOptions_OnPackageIdentity_NoOp=true`
-- **从 ExternalLocation 根目录与 `WinUI3Apps` 目录移除 app-local WinAppSDK 运行时文件**
-  - 尤其是 `CoreMessagingXP.dll`，否则会优先加载并导致 `0xc0000602`
-- **保留/放回 bootstrap DLL**
-  - 必需：`Microsoft.WindowsAppRuntime.Bootstrap.Net.dll`
-  - 建议同时保留：`Microsoft.WindowsAppRuntime.Bootstrap.dll`
-
-按以上处理后，Settings 通过 AUMID 启动不再崩溃，日志写入恢复。
-
-### 根本原因分析
-
-1. **ms-appx:/// URI 机制**
-   - WinUI 3 使用 `ms-appx:///` URI 加载 XAML 资源
-   - 这个 URI scheme 依赖于 MSIX 包的资源索引系统
-
-2. **框架资源位置**
-   - `themeresources.xaml` 等主题资源在 Windows App Runtime 框架包中
-   - 框架包位置：`C:\Program Files\WindowsApps\Microsoft.WindowsAppRuntime.2.0-experimental4_*\`（应与 WinAppSDK 版本匹配）
-   - 资源编译在框架包的 `resources.pri` 中
-
-3. **WinAppSDK 版本/依赖不一致（更可能的原因）**
-   - 仓库当前引用 `Microsoft.WindowsAppSDK` **2.0.0-experimental4**（见 `Directory.Packages.props`）
-   - Sparse manifest 仍依赖 **Microsoft.WindowsAppRuntime.2.0-experimental3**（`MinVersion=0.676.658.0`）
-   - 通过包标识启动时会走框架包资源图，如果依赖版本不匹配，WinUI 资源解析可能失败，从而触发上述 `XamlParseException`
-   - 需要先对齐依赖版本，再判断是否是 sparse 本身限制
-
-4. **app-local 运行时在 sparse identity 下崩溃（已观测）**
-   - 即使对齐 WinAppSDK 版本，也可能在 `CoreMessagingXP.dll` 处崩溃（`0xc0000602`）
-   - 此时 Settings 日志不一定写入，需查看 Application Event Log
-
-4. **Sparse Package 的限制（待验证）**
-   - 之前推断 `ms-appx:///` 在 sparse package 下无法解析框架依赖资源
-   - 但在修正依赖版本之前无法下结论
-
-### 对比：WPF 应用可以工作
-
-WPF 应用（如 ImageResizer）使用 sparse package 时**可以正常工作**，因为：
-- WPF 不依赖 `ms-appx:///` URI
-- WPF 资源加载使用不同的机制
-
-## 已尝试的解决方案
-
-| 方案 | 结果 | 原因 |
-|------|------|------|
-| 复制 PRI 文件到根目录 | ❌ 失败 | `ms-appx:///` 不查找本地 PRI |
-| 复制 themeresources 到本地 | ❌ 失败 | 资源在 PRI 中，不是独立文件 |
-| 修改 Settings OutputPath 到根目录 | ❌ 失败 | 问题不在于应用资源位置 |
-| 复制框架 resources.pri | ❌ 失败 | `ms-appx:///` 机制问题 |
-| 对齐 WindowsAppRuntime 依赖版本 | ⏳ 待验证 | 先排除依赖不一致导致的资源解析失败 |
-| app-local 运行时（self-contained）+ sparse identity | ❌ 失败 | Application Error: `CoreMessagingXP.dll` / `0xc0000602` |
-| 移除 `CoreMessagingXP.dll` | ❌ 失败 | .NET Runtime 1026: `ClassFactory cannot supply requested class` |
-| framework-dependent + bootstrap + 清理 ExternalLocation 中 app-local 运行时 | ✅ 成功 | 需保留 `Microsoft.WindowsAppRuntime.Bootstrap*.dll` |
-| 将 resources.pri 打进 sparse MSIX | ✅ 成功 | MRT 可从包内 resources.pri 正常解析字符串 |
-
-## 当前代码状态
-
-### 已修正（建议保留）
-
-1. **Settings.UI 输出路径**
-   - 文件：`src/settings-ui/Settings.UI/PowerToys.Settings.csproj`
-   - 修改：恢复为 `WinUI3Apps`（避免破坏 runner/installer/脚本路径假设）
-
-2. **AppxManifest.xml 的 Executable 路径**
-   - 文件：`src/PackageIdentity/AppxManifest.xml`
-   - 修改：恢复为 `WinUI3Apps\PowerToys.Settings.exe`
-
-3. **AppxManifest.xml 的 WindowsAppRuntime 依赖**
-   - 文件：`src/PackageIdentity/AppxManifest.xml`
-   - 修改：更新为 `Microsoft.WindowsAppRuntime.2.0-experimental4`，`MinVersion=0.738.2207.0`（与 `Microsoft.WindowsAppSDK.Runtime` 2.0.0-experimental4 对齐）
-
-### 未修改（源码中保持生产配置）
-
-- AppxManifest.xml 的 Publisher 保持 Microsoft Corporation（脚本会自动替换）
-
-### 验证步骤（建议）
-
-1. **确认 WindowsAppRuntime 版本已安装**
-   - `Get-AppxPackage -Name Microsoft.WindowsAppRuntime.2.0-experimental4`
-   - 如缺失，可从 NuGet 缓存安装：  
-     `Add-AppxPackage -Path "$env:USERPROFILE\.nuget\packages\microsoft.windowsappsdk.runtime\2.0.0-experimental4\tools\MSIX\win10-x64\Microsoft.WindowsAppRuntime.2.0-experimental4.msix"`
-
-2. **构建并注册 sparse package**
-   - `.\src\PackageIdentity\BuildSparsePackage.ps1 -Platform x64 -Configuration Debug`
-   - `Add-AppxPackage -Path ".\x64\Debug\PowerToysSparse.msix" -ExternalLocation ".\x64\Debug"`
-
-3. **用包标识启动 Settings**
-   - AUMID：`Microsoft.PowerToys.SparseApp!PowerToys.SettingsUI`
-   - 预期：不再触发 `themeresources.xaml` 解析错误
-
-## 可能的解决方向
-
-### 方向 1：等待 Windows App SDK 修复
-
-- 可能是 Windows App SDK 的已知限制或 bug
-- 需要在 GitHub issues 中搜索或提交新 issue
-
-### 方向 2：使用完整 MSIX 打包
-
-- 不使用 sparse package，而是完整打包
-- 影响：改变部署模型，增加复杂性
-
-### 方向 3：创建非 WinUI 3 的 Helper 进程
-
-- 创建一个 Console App 或 WPF App 作为 helper
-- 该 helper 具有 package identity，专门调用 Semantic Search API
-- Settings 通过 IPC 与 helper 通信
-- 优点：不影响现有 Settings 架构
-
-### 方向 4：进一步调查 ms-appx:/// 解析
-
-- 研究是否有配置选项让 sparse package 正确解析框架资源
-- 可能需要深入 Windows App SDK 源码或联系微软
-
-### 方向 5：切换为 framework-dependent + Bootstrap（待验证）
-
-- 设置 `WindowsAppSDKSelfContained=false` 并**重新构建** Settings
-- 确保外部目录不再携带 app-local WinAppSDK 运行时
-- 让 `Bootstrap.TryInitialize(...)` 生效，走框架包动态依赖
-
-## 可复现的工作流（已验证 2026-01-25）
-
-目标：Settings 使用 sparse identity 启动，WinUI 资源/字符串正常加载。
-
-### 1) 构建 Settings（framework-dependent + bootstrap no-op）
-
-在 `PowerToys.Settings.csproj` 中添加（仅在 `UseSparseIdentity=true` 时生效）：
-
-```
-<PropertyGroup Condition="'$(UseSparseIdentity)'=='true'">
-  <WindowsAppSDKSelfContained>false</WindowsAppSDKSelfContained>
-  <WindowsAppSDKBootstrapAutoInitializeOptions_OnPackageIdentity_NoOp>true</WindowsAppSDKBootstrapAutoInitializeOptions_OnPackageIdentity_NoOp>
-</PropertyGroup>
-```
-
-构建：
-
-```
-MSBuild.exe src\settings-ui\Settings.UI\PowerToys.Settings.csproj /p:Platform=ARM64 /p:Configuration=Debug /p:UseSparseIdentity=true /m:1 /p:CL_MPCount=1 /nodeReuse:false
-```
-
-### 2) 清理 ExternalLocation 的 app-local WinAppSDK 运行时
-
-**必须移除** app-local WinAppSDK 运行时文件，否则会优先加载并崩溃（`CoreMessagingXP.dll` / `0xc0000602`）。
-
-需清理的目录：
-- `ARM64\Debug`（ExternalLocation 根）
-- `ARM64\Debug\WinUI3Apps`
-
-建议只移除 app-local WinAppSDK 相关文件（保留业务 DLL）。
-
-**保留/放回 bootstrap DLL（必要）：**
-- `Microsoft.WindowsAppRuntime.Bootstrap.dll`
-- `Microsoft.WindowsAppRuntime.Bootstrap.Net.dll`
-
-### 3) 生成与包名一致的 resources.pri
-
-关键点：resources.pri 的 **ResourceMap name 必须与包名一致**。
-
-使用 `makepri.exe new` 生成，确保 `/mn` 指向 sparse 包的 `AppxManifest.xml`：
-
-```
-makepri.exe new ^
-  /pr C:\PowerToys\src\settings-ui\Settings.UI ^
-  /cf C:\PowerToys\src\settings-ui\Settings.UI\obj\ARM64\Debug\priconfig.xml ^
-  /mn C:\PowerToys\src\PackageIdentity\AppxManifest.xml ^
-  /of C:\PowerToys\ARM64\Debug\resources.pri ^
-  /o
-```
-
-### 4) 将 resources.pri 打进 sparse MSIX
-
-在 `BuildSparsePackage.ps1` 中把 `resources.pri` 放入 staging（脚本已更新）：
-- 优先取 `ARM64\Debug\resources.pri`
-- 如果不存在则回退 `ARM64\Debug\WinUI3Apps\PowerToys.Settings.pri`
-
-重新打包：
-
-```
-.\src\PackageIdentity\BuildSparsePackage.ps1 -Platform ARM64 -Configuration Debug
-```
-
-### 5) 重新注册 sparse 包（如需先卸载）
-
-如果因为内容变更被阻止，先卸载再安装：
-
-```
-Get-AppxPackage -Name Microsoft.PowerToys.SparseApp | Remove-AppxPackage
-Add-AppxPackage -Path .\ARM64\Debug\PowerToysSparse.msix -ExternalLocation .\ARM64\Debug -ForceApplicationShutdown
-```
-
-### 6) 启动 Settings（验证）
-
-```
-Start-Process "shell:AppsFolder\Microsoft.PowerToys.SparseApp_djwsxzxb4ksa8!PowerToys.SettingsUI"
-```
-
-验证要点：
-- Settings 正常启动，UI 文本显示
-- 日志正常写入：`%LOCALAPPDATA%\Microsoft\PowerToys\Settings\Logs\0.0.1.0\`
-
-### 备注（可选）
-
-如果出现 `ms-appx:///CommunityToolkit...` 资源缺失，可将对应的 `.pri`（从 NuGet 缓存）复制到 `ARM64\Debug\WinUI3Apps`，但在 **resources.pri 已正确打包** 后通常不再需要。
-
-## 待确认事项
-
-1. [ ] WinUI 3 + Sparse Package 的兼容性问题是否有官方文档说明？
-2. [ ] 是否有其他项目成功实现 WinUI 3 + Sparse Package？
-3. [ ] Windows App SDK GitHub 上是否有相关 issue？
-4. [ ] 修正依赖版本后，Settings 是否能在 sparse identity 下正常启动？
-5. [ ] framework-dependent（Bootstrap）方式是否能在 sparse identity 下启动？
-
-## 相关文件
-
-- [SemanticSearchIndex.cs](../../src/common/Common.Search/SemanticSearch/SemanticSearchIndex.cs) - Semantic Search 实现
-- [AppxManifest.xml](../../src/PackageIdentity/AppxManifest.xml) - Sparse package manifest
-- [BuildSparsePackage.ps1](../../src/PackageIdentity/BuildSparsePackage.ps1) - 构建脚本
-- [app.manifest](../../src/settings-ui/Settings.UI/app.manifest) - Settings 应用 manifest
-- [PowerToys.Settings.csproj](../../src/settings-ui/Settings.UI/PowerToys.Settings.csproj) - Settings 项目文件
-
-## 参考链接
-
-- [Grant package identity by packaging with external location](https://learn.microsoft.com/en-us/windows/apps/desktop/modernize/grant-identity-to-nonpackaged-apps)
-- [Windows App SDK - Content Search API](https://learn.microsoft.com/en-us/windows/ai/apis/content-search)
-- [Windows App SDK GitHub Issues](https://github.com/microsoft/WindowsAppSDK/issues)

doc/specs/common-search-library.md

@@ -1,496 +0,0 @@
-# Common.Search Library Specification
-
-## Overview
-
-本文档描述 `Common.Search` 库的重构设计，目标是提供一个通用的、可插拔的搜索框架，支持多种搜索引擎实现（Fuzzy Match、Semantic Search 等）。
-
-## Goals
-
-1. **解耦** - 搜索引擎与数据源完全解耦
-2. **可插拔** - 支持替换不同的搜索引擎实现
-3. **泛型** - 不绑定特定业务类型（如 SettingEntry）
-4. **可组合** - 支持多引擎组合（即时 Fuzzy + 延迟 Semantic）
-5. **可复用** - 可被 PowerToys 多个模块使用
-
-## Architecture
-
-```
-┌─────────────────────────────────────────────────────────────────┐
-│                      Consumer (e.g., Settings.UI)               │
-├─────────────────────────────────────────────────────────────────┤
-│  SettingsDataProvider        ← 业务特定的数据加载               │
-│  SettingsSearchService       ← 业务特定的搜索服务               │
-│  SettingEntry : ISearchable  ← 业务实体实现搜索契约             │
-└─────────────────────────────────────────────────────────────────┘
-                              │ uses
-                              ▼
-┌─────────────────────────────────────────────────────────────────┐
-│                      Common.Search (Library)                    │
-├─────────────────────────────────────────────────────────────────┤
-│                                                                 │
-│  ┌─────────────────────────────────────────────────────────┐   │
-│  │                    Core Abstractions                     │   │
-│  ├─────────────────────────────────────────────────────────┤   │
-│  │  ISearchable              ← 可搜索内容契约               │   │
-│  │  ISearchEngine<T>         ← 搜索引擎接口                 │   │
-│  │  SearchResult<T>          ← 统一结果模型                 │   │
-│  │  SearchOptions            ← 搜索选项                     │   │
-│  └─────────────────────────────────────────────────────────┘   │
-│                                                                 │
-│  ┌─────────────────────────────────────────────────────────┐   │
-│  │                    Implementations                       │   │
-│  ├─────────────────────────────────────────────────────────┤   │
-│  │  FuzzSearch/                                             │   │
-│  │  ├── FuzzSearchEngine<T>  ← 内存 Fuzzy 搜索              │   │
-│  │  ├── StringMatcher        ← 现有的模糊匹配算法           │   │
-│  │  └── MatchResult          ← Fuzzy 匹配结果               │   │
-│  │                                                          │   │
-│  │  SemanticSearch/                                         │   │
-│  │  ├── SemanticSearchEngine ← Windows AI Search 封装       │   │
-│  │  └── SemanticSearchCapabilities                          │   │
-│  │                                                          │   │
-│  │  CompositeSearch/                                        │   │
-│  │  └── CompositeSearchEngine<T> ← 多引擎组合               │   │
-│  └─────────────────────────────────────────────────────────┘   │
-│                                                                 │
-└─────────────────────────────────────────────────────────────────┘
-```
-
-## Core Interfaces
-
-### ISearchable
-
-定义可搜索内容的最小契约。
-
-```csharp
-namespace Common.Search;
-
-/// <summary>
-/// Defines a searchable item that can be indexed and searched.
-/// </summary>
-public interface ISearchable
-{
-    /// <summary>
-    /// Gets the unique identifier for this item.
-    /// </summary>
-    string Id { get; }
-
-    /// <summary>
-    /// Gets the primary searchable text (e.g., title, header).
-    /// </summary>
-    string SearchableText { get; }
-
-    /// <summary>
-    /// Gets optional secondary searchable text (e.g., description).
-    /// Returns null if not available.
-    /// </summary>
-    string? SecondarySearchableText { get; }
-}
-```
-
-### ISearchEngine&lt;T&gt;
-
-搜索引擎核心接口。
-
-```csharp
-namespace Common.Search;
-
-/// <summary>
-/// Defines a pluggable search engine that can index and search items.
-/// </summary>
-/// <typeparam name="T">The type of items to search, must implement ISearchable.</typeparam>
-public interface ISearchEngine<T> : IDisposable
-    where T : ISearchable
-{
-    /// <summary>
-    /// Gets a value indicating whether the engine is ready to search.
-    /// </summary>
-    bool IsReady { get; }
-
-    /// <summary>
-    /// Gets the engine capabilities.
-    /// </summary>
-    SearchEngineCapabilities Capabilities { get; }
-
-    /// <summary>
-    /// Initializes the search engine.
-    /// </summary>
-    Task InitializeAsync(CancellationToken cancellationToken = default);
-
-    /// <summary>
-    /// Indexes a single item.
-    /// </summary>
-    Task IndexAsync(T item, CancellationToken cancellationToken = default);
-
-    /// <summary>
-    /// Indexes multiple items in batch.
-    /// </summary>
-    Task IndexBatchAsync(IEnumerable<T> items, CancellationToken cancellationToken = default);
-
-    /// <summary>
-    /// Removes an item from the index by its ID.
-    /// </summary>
-    Task RemoveAsync(string id, CancellationToken cancellationToken = default);
-
-    /// <summary>
-    /// Clears all indexed items.
-    /// </summary>
-    Task ClearAsync(CancellationToken cancellationToken = default);
-
-    /// <summary>
-    /// Searches for items matching the query.
-    /// </summary>
-    Task<IReadOnlyList<SearchResult<T>>> SearchAsync(
-        string query,
-        SearchOptions? options = null,
-        CancellationToken cancellationToken = default);
-}
-```
-
-### SearchResult&lt;T&gt;
-
-统一的搜索结果模型。
-
-```csharp
-namespace Common.Search;
-
-/// <summary>
-/// Represents a search result with the matched item and scoring information.
-/// </summary>
-public sealed class SearchResult<T>
-    where T : ISearchable
-{
-    /// <summary>
-    /// Gets the matched item.
-    /// </summary>
-    public required T Item { get; init; }
-
-    /// <summary>
-    /// Gets the relevance score (higher is more relevant).
-    /// </summary>
-    public required double Score { get; init; }
-
-    /// <summary>
-    /// Gets the type of match that produced this result.
-    /// </summary>
-    public required SearchMatchKind MatchKind { get; init; }
-
-    /// <summary>
-    /// Gets the match details for highlighting (optional).
-    /// </summary>
-    public IReadOnlyList<MatchSpan>? MatchSpans { get; init; }
-}
-
-/// <summary>
-/// Represents a span of matched text for highlighting.
-/// </summary>
-public readonly record struct MatchSpan(int Start, int Length);
-
-/// <summary>
-/// Specifies the kind of match that produced a search result.
-/// </summary>
-public enum SearchMatchKind
-{
-    /// <summary>Exact text match.</summary>
-    Exact,
-
-    /// <summary>Fuzzy/approximate text match.</summary>
-    Fuzzy,
-
-    /// <summary>Semantic/AI-based match.</summary>
-    Semantic,
-
-    /// <summary>Combined match from multiple engines.</summary>
-    Composite,
-}
-```
-
-### SearchOptions
-
-搜索配置选项。
-
-```csharp
-namespace Common.Search;
-
-/// <summary>
-/// Options for configuring search behavior.
-/// </summary>
-public sealed class SearchOptions
-{
-    /// <summary>
-    /// Gets or sets the maximum number of results to return.
-    /// Default is 20.
-    /// </summary>
-    public int MaxResults { get; set; } = 20;
-
-    /// <summary>
-    /// Gets or sets the minimum score threshold (0.0 to 1.0).
-    /// Results below this score are filtered out.
-    /// Default is 0.0 (no filtering).
-    /// </summary>
-    public double MinScore { get; set; } = 0.0;
-
-    /// <summary>
-    /// Gets or sets the language hint for the search (e.g., "en-US").
-    /// </summary>
-    public string? Language { get; set; }
-
-    /// <summary>
-    /// Gets or sets a value indicating whether to include match spans for highlighting.
-    /// Default is false.
-    /// </summary>
-    public bool IncludeMatchSpans { get; set; } = false;
-}
-```
-
-### SearchEngineCapabilities
-
-引擎能力描述。
-
-```csharp
-namespace Common.Search;
-
-/// <summary>
-/// Describes the capabilities of a search engine.
-/// </summary>
-public sealed class SearchEngineCapabilities
-{
-    /// <summary>
-    /// Gets a value indicating whether the engine supports fuzzy matching.
-    /// </summary>
-    public bool SupportsFuzzyMatch { get; init; }
-
-    /// <summary>
-    /// Gets a value indicating whether the engine supports semantic search.
-    /// </summary>
-    public bool SupportsSemanticSearch { get; init; }
-
-    /// <summary>
-    /// Gets a value indicating whether the engine persists the index to disk.
-    /// </summary>
-    public bool PersistsIndex { get; init; }
-
-    /// <summary>
-    /// Gets a value indicating whether the engine supports incremental indexing.
-    /// </summary>
-    public bool SupportsIncrementalIndex { get; init; }
-
-    /// <summary>
-    /// Gets a value indicating whether the engine supports match span highlighting.
-    /// </summary>
-    public bool SupportsMatchSpans { get; init; }
-}
-```
-
-## Implementations
-
-### FuzzSearchEngine&lt;T&gt;
-
-基于现有 StringMatcher 的内存搜索引擎。
-
-**特点：**
-- 纯内存，无持久化
-- 即时响应（毫秒级）
-- 支持 match spans 高亮
-- 基于字符的模糊匹配
-
-**Capabilities：**
-```csharp
-new SearchEngineCapabilities
-{
-    SupportsFuzzyMatch = true,
-    SupportsSemanticSearch = false,
-    PersistsIndex = false,
-    SupportsIncrementalIndex = true,
-    SupportsMatchSpans = true,
-}
-```
-
-### SemanticSearchEngine
-
-基于 Windows App SDK AI Search API 的语义搜索引擎。
-
-**特点：**
-- 系统管理的持久化索引
-- AI 驱动的语义理解
-- 需要模型初始化（可能较慢）
-- 可能不可用（依赖系统支持）
-
-**Capabilities：**
-```csharp
-new SearchEngineCapabilities
-{
-    SupportsFuzzyMatch = true,  // API 同时提供 lexical + semantic
-    SupportsSemanticSearch = true,
-    PersistsIndex = true,
-    SupportsIncrementalIndex = true,
-    SupportsMatchSpans = false,  // API 不返回详细位置
-}
-```
-
-**注意：** SemanticSearchEngine 不是泛型的，因为它需要将内容转换为字符串存入系统索引。实现时通过 `ISearchable` 接口提取文本。
-
-### CompositeSearchEngine&lt;T&gt;
-
-组合多个搜索引擎，支持 fallback 和结果合并。
-
-```csharp
-namespace Common.Search;
-
-/// <summary>
-/// A search engine that combines results from multiple engines.
-/// </summary>
-public sealed class CompositeSearchEngine<T> : ISearchEngine<T>
-    where T : ISearchable
-{
-    /// <summary>
-    /// Strategy for combining results from multiple engines.
-    /// </summary>
-    public enum CombineStrategy
-    {
-        /// <summary>Use first ready engine only.</summary>
-        FirstReady,
-
-        /// <summary>Merge results from all ready engines.</summary>
-        MergeAll,
-
-        /// <summary>Use primary, fallback to secondary if primary not ready.</summary>
-        PrimaryWithFallback,
-    }
-}
-```
-
-**典型用法：** Fuzzy 作为即时响应，Semantic 准备好后增强结果。
-
-## Directory Structure
-
-```
-src/common/Common.Search/
-├── Common.Search.csproj
-├── GlobalSuppressions.cs
-├── ISearchable.cs
-├── ISearchEngine.cs
-├── SearchResult.cs
-├── SearchOptions.cs
-├── SearchEngineCapabilities.cs
-├── SearchMatchKind.cs
-├── MatchSpan.cs
-│
-├── FuzzSearch/
-│   ├── FuzzSearchEngine.cs
-│   ├── StringMatcher.cs         (existing)
-│   ├── MatchOption.cs           (existing)
-│   ├── MatchResult.cs           (existing)
-│   └── SearchPrecisionScore.cs  (existing)
-│
-├── SemanticSearch/
-│   ├── SemanticSearchEngine.cs
-│   ├── SemanticSearchCapabilities.cs
-│   └── SemanticSearchAdapter.cs  (adapts ISearchable to Windows API)
-│
-└── CompositeSearch/
-    └── CompositeSearchEngine.cs
-```
-
-## Consumer Usage (Settings.UI)
-
-### SettingEntry 实现 ISearchable
-
-```csharp
-// Settings.UI.Library/SettingEntry.cs
-public struct SettingEntry : ISearchable
-{
-    // Existing properties...
-
-    // ISearchable implementation
-    public string Id => ElementUid ?? $"{PageTypeName}|{ElementName}";
-    public string SearchableText => Header ?? string.Empty;
-    public string? SecondarySearchableText => Description;
-}
-```
-
-### SettingsSearchService
-
-```csharp
-// Settings.UI/Services/SettingsSearchService.cs
-public sealed class SettingsSearchService : IDisposable
-{
-    private readonly ISearchEngine<SettingEntry> _engine;
-
-    public SettingsSearchService(ISearchEngine<SettingEntry> engine)
-    {
-        _engine = engine;
-    }
-
-    public async Task InitializeAsync(IEnumerable<SettingEntry> entries)
-    {
-        await _engine.InitializeAsync();
-        await _engine.IndexBatchAsync(entries);
-    }
-
-    public async Task<List<SettingEntry>> SearchAsync(string query, CancellationToken ct = default)
-    {
-        var results = await _engine.SearchAsync(query, cancellationToken: ct);
-        return results.Select(r => r.Item).ToList();
-    }
-}
-```
-
-### Startup Configuration
-
-```csharp
-// Option 1: Fuzzy only (default, immediate)
-var engine = new FuzzSearchEngine<SettingEntry>();
-
-// Option 2: Semantic only (requires Windows AI)
-var engine = new SemanticSearchAdapter<SettingEntry>("PowerToysSettings");
-
-// Option 3: Composite (best of both worlds)
-var engine = new CompositeSearchEngine<SettingEntry>(
-    primary: new SemanticSearchAdapter<SettingEntry>("PowerToysSettings"),
-    fallback: new FuzzSearchEngine<SettingEntry>(),
-    strategy: CombineStrategy.PrimaryWithFallback
-);
-
-var searchService = new SettingsSearchService(engine);
-await searchService.InitializeAsync(settingEntries);
-```
-
-## Migration Plan
-
-### Phase 1: Core Abstractions
-1. 创建 `ISearchable`, `ISearchEngine<T>`, `SearchResult<T>` 等核心接口
-2. 保持现有 FuzzSearch 代码不变
-
-### Phase 2: FuzzSearchEngine&lt;T&gt;
-1. 创建泛型 `FuzzSearchEngine<T>` 实现
-2. 内部复用现有 `StringMatcher`
-
-### Phase 3: SemanticSearchEngine
-1. 完善现有 `SemanticSearchEngine` 实现
-2. 创建 `SemanticSearchAdapter<T>` 桥接泛型接口
-
-### Phase 4: Settings.UI Migration
-1. `SettingEntry` 实现 `ISearchable`
-2. 创建 `SettingsSearchService`
-3. 迁移 `SearchIndexService` 到新架构
-4. 保持 API 兼容，逐步废弃旧方法
-
-### Phase 5: CompositeSearchEngine (Optional)
-1. 实现组合引擎
-2. 支持 Fuzzy + Semantic 混合搜索
-
-## Open Questions
-
-1. **是否需要支持图片搜索？** 当前 SemanticSearchEngine 支持 `IndexImage`，但 `ISearchable` 只有文本。如果需要图片，可能需要 `IImageSearchable` 扩展。
-
-2. **结果去重策略？** CompositeEngine 合并结果时，同一个 Item 可能被多个引擎匹配，如何去重和合并分数？
-
-3. **异步 vs 同步？** FuzzSearch 完全可以同步执行，但接口统一用 `Task` 是否合适？考虑提供同步重载？
-
-4. **索引更新策略？** 当 Settings 内容变化时（例如用户切换语言），如何高效更新索引？
-
----
-
-*Document Version: 1.0*
-*Last Updated: 2026-01-21*

src/ActionRunner/actionRunner.cpp

@@ -104,6 +104,66 @@ int WINAPI WinMain(HINSTANCE, HINSTANCE, LPSTR, int)
             }
         }
     }
+    else if (action == RUN_AS_USER || action == RUN_AS_ADMIN)
+    {
+        // Handle "Run as different user" and "Run as administrator" actions.
+        // This is used by Command Palette to work around WinUI3/MSIX packaging limitations
+        // where ShellExecute with "runas user"/"runas" verbs doesn't work properly from packaged apps.
+        int nextArg = 2;
+
+        std::wstring_view target;
+        std::wstring_view workingDir;
+
+        while (nextArg < nArgs)
+        {
+            if (std::wstring_view(args[nextArg]) == L"-target" && nextArg + 1 < nArgs)
+            {
+                target = args[nextArg + 1];
+                nextArg += 2;
+            }
+            else if (std::wstring_view(args[nextArg]) == L"-workingDir" && nextArg + 1 < nArgs)
+            {
+                workingDir = args[nextArg + 1];
+                nextArg += 2;
+            }
+            else
+            {
+                nextArg++;
+            }
+        }
+
+        if (target.empty())
+        {
+            Logger::error(L"ActionRunner: {} called without -target argument", action);
+            return 1;
+        }
+
+        Logger::trace(L"ActionRunner: {} target='{}' workingDir='{}'", action, target, workingDir);
+
+        SHELLEXECUTEINFOW sei = { sizeof(sei) };
+        sei.fMask = SEE_MASK_FLAG_NO_UI;
+        sei.lpFile = target.data();
+        sei.lpDirectory = workingDir.empty() ? nullptr : workingDir.data();
+        sei.lpVerb = (action == RUN_AS_ADMIN) ? L"runas" : L"runasuser";
+        sei.nShow = SW_SHOWNORMAL;
+
+        if (!ShellExecuteExW(&sei))
+        {
+            DWORD error = GetLastError();
+            if (error == ERROR_CANCELLED)
+            {
+                // User cancelled the UAC/credential dialog - this is expected behavior
+                Logger::trace(L"ActionRunner: User cancelled {} dialog for '{}'", action, target);
+            }
+            else
+            {
+                Logger::error(L"ActionRunner: ShellExecuteEx failed for {} '{}': error {}", action, target, error);
+            }
+            return static_cast<int>(error);
+        }
+
+        Logger::trace(L"ActionRunner: Successfully launched '{}' with {}", target, action);
+    }
 
     return 0;
 }

src/PackageIdentity/AppxManifest.xml

@@ -29,7 +29,6 @@
   </Resources>
   <Dependencies>
     <TargetDeviceFamily Name="Windows.Desktop" MinVersion="10.0.19000.0" MaxVersionTested="10.0.26226.0" />
-    <PackageDependency Name="Microsoft.WindowsAppRuntime.2.0-experimental4" MinVersion="0.738.2207.0" Publisher="CN=Microsoft Corporation, O=Microsoft Corporation, L=Redmond, S=Washington, C=US" />
   </Dependencies>
   <Capabilities>
     <Capability Name="internetClient" />
@@ -81,7 +80,6 @@
       <Extensions>
         <com:Extension Category="windows.comServer">
           <com:ComServer>
-
             <com:ExeServer Executable="Microsoft.CmdPal.Ext.PowerToys.exe" Arguments="-RegisterProcessAsComServer" DisplayName="PowerToys Command Palette Extension">
               <com:Class Id="7EC02C7D-8F98-4A2E-9F23-B58C2C2F2B17" DisplayName="PowerToys Command Palette Extension" />
             </com:ExeServer>

src/PackageIdentity/BuildSparsePackage.ps1

@@ -320,19 +320,6 @@ try {
             }
         }
     }
-
-    # Include resources.pri in the sparse MSIX if available to enable MRT in packaged mode.
-    # Prefer a prebuilt resources.pri in output root; fall back to Settings pri.
-    $resourcesPriSource = Join-Path $outDir "resources.pri"
-    if (-not (Test-Path $resourcesPriSource)) {
-        $resourcesPriSource = Join-Path $outDir "WinUI3Apps\\PowerToys.Settings.pri"
-    }
-    if (Test-Path $resourcesPriSource) {
-        Copy-Item -Path $resourcesPriSource -Destination (Join-Path $stagingDir "resources.pri") -Force -ErrorAction SilentlyContinue
-        Write-BuildLog "Including resources.pri from: $resourcesPriSource" -Level Info
-    } else {
-        Write-BuildLog "resources.pri not found; strings may be missing in sparse identity." -Level Warning
-    }
     
     # Ensure publisher matches the dev certificate for local builds
     $manifestStagingPath = Join-Path $stagingDir 'AppxManifest.xml'

src/common/Common.Search/Common.Search.csproj

@@ -4,16 +4,5 @@
 
   <PropertyGroup>
     <ImplicitUsings>enable</ImplicitUsings>
-    <Nullable>enable</Nullable>
-    <WarningsNotAsErrors>$(WarningsNotAsErrors);CS8305</WarningsNotAsErrors>
   </PropertyGroup>
-
-  <ItemGroup>
-    <PackageReference Include="Microsoft.WindowsAppSDK" />
-    <PackageReference Include="Microsoft.WindowsAppSDK.AI" />
-  </ItemGroup>
-
-  <ItemGroup>
-    <ProjectReference Include="..\ManagedCommon\ManagedCommon.csproj" />
-  </ItemGroup>
 </Project>

src/common/Common.Search/FuzzSearch/FuzzSearchEngine`1.cs

@@ -1,306 +0,0 @@
-// Copyright (c) Microsoft Corporation
-// The Microsoft Corporation licenses this file to you under the MIT license.
-// See the LICENSE file in the project root for more information.
-
-using System.Collections.Concurrent;
-using System.Globalization;
-using System.Text;
-
-namespace Common.Search.FuzzSearch;
-
-/// <summary>
-/// A search engine that uses fuzzy string matching for search.
-/// </summary>
-/// <typeparam name="T">The type of items to search.</typeparam>
-public sealed class FuzzSearchEngine<T> : ISearchEngine<T>
-    where T : ISearchable
-{
-    private readonly object _lockObject = new();
-    private readonly Dictionary<string, T> _itemsById = new();
-    private readonly Dictionary<string, (string PrimaryNorm, string? SecondaryNorm)> _normalizedCache = new();
-    private bool _isReady;
-    private bool _disposed;
-
-    /// <inheritdoc/>
-    public bool IsReady
-    {
-        get
-        {
-            lock (_lockObject)
-            {
-                return _isReady;
-            }
-        }
-    }
-
-    /// <inheritdoc/>
-    public SearchEngineCapabilities Capabilities { get; } = new()
-    {
-        SupportsFuzzyMatch = true,
-        SupportsSemanticSearch = false,
-        PersistsIndex = false,
-        SupportsIncrementalIndex = true,
-        SupportsMatchSpans = true,
-    };
-
-    /// <inheritdoc/>
-    public Task InitializeAsync(CancellationToken cancellationToken = default)
-    {
-        lock (_lockObject)
-        {
-            _isReady = true;
-        }
-
-        return Task.CompletedTask;
-    }
-
-    /// <inheritdoc/>
-    public Task IndexAsync(T item, CancellationToken cancellationToken = default)
-    {
-        ArgumentNullException.ThrowIfNull(item);
-        ThrowIfDisposed();
-
-        lock (_lockObject)
-        {
-            _itemsById[item.Id] = item;
-            _normalizedCache[item.Id] = (
-                NormalizeString(item.SearchableText),
-                item.SecondarySearchableText != null ? NormalizeString(item.SecondarySearchableText) : null
-            );
-        }
-
-        return Task.CompletedTask;
-    }
-
-    /// <inheritdoc/>
-    public Task IndexBatchAsync(IEnumerable<T> items, CancellationToken cancellationToken = default)
-    {
-        ArgumentNullException.ThrowIfNull(items);
-        ThrowIfDisposed();
-
-        lock (_lockObject)
-        {
-            foreach (var item in items)
-            {
-                if (cancellationToken.IsCancellationRequested)
-                {
-                    break;
-                }
-
-                _itemsById[item.Id] = item;
-                _normalizedCache[item.Id] = (
-                    NormalizeString(item.SearchableText),
-                    item.SecondarySearchableText != null ? NormalizeString(item.SecondarySearchableText) : null
-                );
-            }
-        }
-
-        return Task.CompletedTask;
-    }
-
-    /// <inheritdoc/>
-    public Task RemoveAsync(string id, CancellationToken cancellationToken = default)
-    {
-        ArgumentException.ThrowIfNullOrWhiteSpace(id);
-        ThrowIfDisposed();
-
-        lock (_lockObject)
-        {
-            _itemsById.Remove(id);
-            _normalizedCache.Remove(id);
-        }
-
-        return Task.CompletedTask;
-    }
-
-    /// <inheritdoc/>
-    public Task ClearAsync(CancellationToken cancellationToken = default)
-    {
-        ThrowIfDisposed();
-
-        lock (_lockObject)
-        {
-            _itemsById.Clear();
-            _normalizedCache.Clear();
-        }
-
-        return Task.CompletedTask;
-    }
-
-    /// <inheritdoc/>
-    public Task<IReadOnlyList<SearchResult<T>>> SearchAsync(
-        string query,
-        SearchOptions? options = null,
-        CancellationToken cancellationToken = default)
-    {
-        ThrowIfDisposed();
-
-        if (string.IsNullOrWhiteSpace(query))
-        {
-            return Task.FromResult<IReadOnlyList<SearchResult<T>>>(Array.Empty<SearchResult<T>>());
-        }
-
-        options ??= new SearchOptions();
-        var normalizedQuery = NormalizeString(query);
-
-        List<KeyValuePair<string, T>> snapshot;
-        lock (_lockObject)
-        {
-            if (_itemsById.Count == 0)
-            {
-                return Task.FromResult<IReadOnlyList<SearchResult<T>>>(Array.Empty<SearchResult<T>>());
-            }
-
-            snapshot = _itemsById.ToList();
-        }
-
-        var bag = new ConcurrentBag<SearchResult<T>>();
-        var po = new ParallelOptions
-        {
-            CancellationToken = cancellationToken,
-            MaxDegreeOfParallelism = Math.Max(1, Environment.ProcessorCount - 1),
-        };
-
-        try
-        {
-            Parallel.ForEach(snapshot, po, kvp =>
-            {
-                var (primaryNorm, secondaryNorm) = GetNormalizedTexts(kvp.Key);
-
-                var primaryResult = StringMatcher.FuzzyMatch(normalizedQuery, primaryNorm);
-                double score = primaryResult.Score;
-                List<int>? matchData = primaryResult.MatchData;
-
-                if (!string.IsNullOrEmpty(secondaryNorm))
-                {
-                    var secondaryResult = StringMatcher.FuzzyMatch(normalizedQuery, secondaryNorm);
-                    if (secondaryResult.Success && secondaryResult.Score * 0.8 > score)
-                    {
-                        score = secondaryResult.Score * 0.8;
-                        matchData = null; // Secondary matches don't have primary text spans
-                    }
-                }
-
-                if (score > options.MinScore)
-                {
-                    var result = new SearchResult<T>
-                    {
-                        Item = kvp.Value,
-                        Score = score,
-                        MatchKind = SearchMatchKind.Fuzzy,
-                        MatchSpans = options.IncludeMatchSpans && matchData != null
-                            ? ConvertToMatchSpans(matchData)
-                            : null,
-                    };
-
-                    bag.Add(result);
-                }
-            });
-        }
-        catch (OperationCanceledException)
-        {
-            return Task.FromResult<IReadOnlyList<SearchResult<T>>>(Array.Empty<SearchResult<T>>());
-        }
-
-        var results = bag
-            .OrderByDescending(r => r.Score)
-            .Take(options.MaxResults)
-            .ToList();
-
-        return Task.FromResult<IReadOnlyList<SearchResult<T>>>(results);
-    }
-
-    /// <inheritdoc/>
-    public void Dispose()
-    {
-        if (_disposed)
-        {
-            return;
-        }
-
-        lock (_lockObject)
-        {
-            _itemsById.Clear();
-            _normalizedCache.Clear();
-            _isReady = false;
-        }
-
-        _disposed = true;
-    }
-
-    private (string PrimaryNorm, string? SecondaryNorm) GetNormalizedTexts(string id)
-    {
-        lock (_lockObject)
-        {
-            if (_normalizedCache.TryGetValue(id, out var cached))
-            {
-                return cached;
-            }
-        }
-
-        return (string.Empty, null);
-    }
-
-    private static IReadOnlyList<MatchSpan> ConvertToMatchSpans(List<int> matchData)
-    {
-        if (matchData == null || matchData.Count == 0)
-        {
-            return Array.Empty<MatchSpan>();
-        }
-
-        // Convert individual match indices to spans
-        var spans = new List<MatchSpan>();
-        var sortedIndices = matchData.OrderBy(i => i).ToList();
-
-        int start = sortedIndices[0];
-        int length = 1;
-
-        for (int i = 1; i < sortedIndices.Count; i++)
-        {
-            if (sortedIndices[i] == sortedIndices[i - 1] + 1)
-            {
-                // Consecutive index, extend the span
-                length++;
-            }
-            else
-            {
-                // Gap found, save current span and start new one
-                spans.Add(new MatchSpan(start, length));
-                start = sortedIndices[i];
-                length = 1;
-            }
-        }
-
-        // Add the last span
-        spans.Add(new MatchSpan(start, length));
-
-        return spans;
-    }
-
-    private static string NormalizeString(string? input)
-    {
-        if (string.IsNullOrEmpty(input))
-        {
-            return string.Empty;
-        }
-
-        var normalized = input.ToLowerInvariant().Normalize(NormalizationForm.FormKD);
-        var sb = new StringBuilder(normalized.Length);
-
-        foreach (var c in normalized)
-        {
-            var category = CharUnicodeInfo.GetUnicodeCategory(c);
-            if (category != UnicodeCategory.NonSpacingMark)
-            {
-                sb.Append(c);
-            }
-        }
-
-        return sb.ToString();
-    }
-
-    private void ThrowIfDisposed()
-    {
-        ObjectDisposedException.ThrowIf(_disposed, this);
-    }
-}

src/common/Common.Search/FuzzSearch/StringMatcher.cs

@@ -25,9 +25,9 @@ public class StringMatcher
     /// 6. Move onto the next substring's characters until all substrings are checked.
     /// 7. Consider success and move onto scoring if every char or substring without whitespaces matched
     /// </summary>
-    public static MatchResult FuzzyMatch(string query, string stringToCompare, MatchOption? opt = null)
+    public static MatchResult FuzzyMatch(string query, string stringToCompare, MatchOption opt = null)
     {
-        opt ??= new MatchOption();
+        opt = opt ?? new MatchOption();
 
         if (string.IsNullOrEmpty(stringToCompare))
         {

src/common/Common.Search/GlobalSuppressions.cs

@@ -11,10 +11,6 @@ using System.Diagnostics.CodeAnalysis;
 [assembly: SuppressMessage("StyleCop.CSharp.NamingRules", "SA1309:Field names should not begin with underscore", Justification = "coding style", Scope = "member", Target = "~F:Common.Search.MatchResult._rawScore")]
 [assembly: SuppressMessage("StyleCop.CSharp.NamingRules", "SA1309:Field names should not begin with underscore", Justification = "coding style", Scope = "member", Target = "~F:Common.Search.StringMatcher._defaultMatchOption")]
 [assembly: SuppressMessage("StyleCop.CSharp.NamingRules", "SA1309:Field names should not begin with underscore", Justification = "coding style", Scope = "member", Target = "~F:Common.Search.StringMatcher._instance")]
-[assembly: SuppressMessage("StyleCop.CSharp.NamingRules", "SA1309:Field names should not begin with underscore", Justification = "coding style", Scope = "member", Target = "~F:Common.Search.SemanticSearch.SemanticSearchIndex._indexName")]
-[assembly: SuppressMessage("StyleCop.CSharp.NamingRules", "SA1309:Field names should not begin with underscore", Justification = "coding style", Scope = "member", Target = "~F:Common.Search.SemanticSearch.SemanticSearchIndex._indexer")]
-[assembly: SuppressMessage("StyleCop.CSharp.NamingRules", "SA1309:Field names should not begin with underscore", Justification = "coding style", Scope = "member", Target = "~F:Common.Search.SemanticSearch.SemanticSearchIndex._disposed")]
-[assembly: SuppressMessage("StyleCop.CSharp.NamingRules", "SA1309:Field names should not begin with underscore", Justification = "coding style", Scope = "member", Target = "~F:Common.Search.SemanticSearch.SemanticSearchIndex._capabilities")]
 [assembly: SuppressMessage("StyleCop.CSharp.ReadabilityRules", "SA1101:Prefix local calls with this", Justification = "coding style", Scope = "member", Target = "~M:Common.Search.MatchResult.#ctor(System.Boolean,Common.Search.SearchPrecisionScore)")]
 [assembly: SuppressMessage("StyleCop.CSharp.ReadabilityRules", "SA1101:Prefix local calls with this", Justification = "coding style", Scope = "member", Target = "~M:Common.Search.MatchResult.#ctor(System.Boolean,Common.Search.SearchPrecisionScore,System.Collections.Generic.List{System.Int32},System.Int32)")]
 [assembly: SuppressMessage("Compiler", "CS8618:Non-nullable field must contain a non-null value when exiting constructor. Consider adding the 'required' modifier or declaring as nullable.", Justification = "Coding style", Scope = "member", Target = "~F:Common.Search.StringMatcher._instance")]

src/common/Common.Search/ISearchEngine`1.cs

@@ -1,73 +0,0 @@
-// Copyright (c) Microsoft Corporation
-// The Microsoft Corporation licenses this file to you under the MIT license.
-// See the LICENSE file in the project root for more information.
-
-namespace Common.Search;
-
-/// <summary>
-/// Defines a pluggable search engine that can index and search items.
-/// </summary>
-/// <typeparam name="T">The type of items to search, must implement ISearchable.</typeparam>
-public interface ISearchEngine<T> : IDisposable
-    where T : ISearchable
-{
-    /// <summary>
-    /// Gets a value indicating whether the engine is ready to search.
-    /// </summary>
-    bool IsReady { get; }
-
-    /// <summary>
-    /// Gets the engine capabilities.
-    /// </summary>
-    SearchEngineCapabilities Capabilities { get; }
-
-    /// <summary>
-    /// Initializes the search engine.
-    /// </summary>
-    /// <param name="cancellationToken">Cancellation token.</param>
-    /// <returns>A task representing the async operation.</returns>
-    Task InitializeAsync(CancellationToken cancellationToken = default);
-
-    /// <summary>
-    /// Indexes a single item.
-    /// </summary>
-    /// <param name="item">The item to index.</param>
-    /// <param name="cancellationToken">Cancellation token.</param>
-    /// <returns>A task representing the async operation.</returns>
-    Task IndexAsync(T item, CancellationToken cancellationToken = default);
-
-    /// <summary>
-    /// Indexes multiple items in batch.
-    /// </summary>
-    /// <param name="items">The items to index.</param>
-    /// <param name="cancellationToken">Cancellation token.</param>
-    /// <returns>A task representing the async operation.</returns>
-    Task IndexBatchAsync(IEnumerable<T> items, CancellationToken cancellationToken = default);
-
-    /// <summary>
-    /// Removes an item from the index by its ID.
-    /// </summary>
-    /// <param name="id">The ID of the item to remove.</param>
-    /// <param name="cancellationToken">Cancellation token.</param>
-    /// <returns>A task representing the async operation.</returns>
-    Task RemoveAsync(string id, CancellationToken cancellationToken = default);
-
-    /// <summary>
-    /// Clears all indexed items.
-    /// </summary>
-    /// <param name="cancellationToken">Cancellation token.</param>
-    /// <returns>A task representing the async operation.</returns>
-    Task ClearAsync(CancellationToken cancellationToken = default);
-
-    /// <summary>
-    /// Searches for items matching the query.
-    /// </summary>
-    /// <param name="query">The search query.</param>
-    /// <param name="options">Optional search options.</param>
-    /// <param name="cancellationToken">Cancellation token.</param>
-    /// <returns>A list of search results ordered by relevance.</returns>
-    Task<IReadOnlyList<SearchResult<T>>> SearchAsync(
-        string query,
-        SearchOptions? options = null,
-        CancellationToken cancellationToken = default);
-}

src/common/Common.Search/ISearchable.cs

@@ -1,27 +0,0 @@
-// Copyright (c) Microsoft Corporation
-// The Microsoft Corporation licenses this file to you under the MIT license.
-// See the LICENSE file in the project root for more information.
-
-namespace Common.Search;
-
-/// <summary>
-/// Defines a searchable item that can be indexed and searched.
-/// </summary>
-public interface ISearchable
-{
-    /// <summary>
-    /// Gets the unique identifier for this item.
-    /// </summary>
-    string Id { get; }
-
-    /// <summary>
-    /// Gets the primary searchable text (e.g., title, header).
-    /// </summary>
-    string SearchableText { get; }
-
-    /// <summary>
-    /// Gets optional secondary searchable text (e.g., description).
-    /// Returns null if not available.
-    /// </summary>
-    string? SecondarySearchableText { get; }
-}

src/common/Common.Search/MatchSpan.cs

@@ -1,12 +0,0 @@
-// Copyright (c) Microsoft Corporation
-// The Microsoft Corporation licenses this file to you under the MIT license.
-// See the LICENSE file in the project root for more information.
-
-namespace Common.Search;
-
-/// <summary>
-/// Represents a span of matched text for highlighting.
-/// </summary>
-/// <param name="Start">The starting index of the match.</param>
-/// <param name="Length">The length of the match.</param>
-public readonly record struct MatchSpan(int Start, int Length);

src/common/Common.Search/SearchEngineCapabilities.cs

@@ -1,36 +0,0 @@
-// Copyright (c) Microsoft Corporation
-// The Microsoft Corporation licenses this file to you under the MIT license.
-// See the LICENSE file in the project root for more information.
-
-namespace Common.Search;
-
-/// <summary>
-/// Describes the capabilities of a search engine.
-/// </summary>
-public sealed class SearchEngineCapabilities
-{
-    /// <summary>
-    /// Gets a value indicating whether the engine supports fuzzy matching.
-    /// </summary>
-    public bool SupportsFuzzyMatch { get; init; }
-
-    /// <summary>
-    /// Gets a value indicating whether the engine supports semantic search.
-    /// </summary>
-    public bool SupportsSemanticSearch { get; init; }
-
-    /// <summary>
-    /// Gets a value indicating whether the engine persists the index to disk.
-    /// </summary>
-    public bool PersistsIndex { get; init; }
-
-    /// <summary>
-    /// Gets a value indicating whether the engine supports incremental indexing.
-    /// </summary>
-    public bool SupportsIncrementalIndex { get; init; }
-
-    /// <summary>
-    /// Gets a value indicating whether the engine supports match span highlighting.
-    /// </summary>
-    public bool SupportsMatchSpans { get; init; }
-}

src/common/Common.Search/SearchError.cs

@@ -1,134 +0,0 @@
-// Copyright (c) Microsoft Corporation
-// The Microsoft Corporation licenses this file to you under the MIT license.
-// See the LICENSE file in the project root for more information.
-
-namespace Common.Search;
-
-/// <summary>
-/// Represents an error that occurred during a search operation.
-/// </summary>
-public sealed class SearchError
-{
-    /// <summary>
-    /// Initializes a new instance of the <see cref="SearchError"/> class.
-    /// </summary>
-    /// <param name="code">The error code.</param>
-    /// <param name="message">The error message.</param>
-    /// <param name="details">Optional additional details.</param>
-    /// <param name="exception">Optional exception that caused the error.</param>
-    public SearchError(SearchErrorCode code, string message, string? details = null, Exception? exception = null)
-    {
-        Code = code;
-        Message = message;
-        Details = details;
-        Exception = exception;
-        Timestamp = DateTime.UtcNow;
-    }
-
-    /// <summary>
-    /// Gets the error code.
-    /// </summary>
-    public SearchErrorCode Code { get; }
-
-    /// <summary>
-    /// Gets the error message.
-    /// </summary>
-    public string Message { get; }
-
-    /// <summary>
-    /// Gets additional details about the error.
-    /// </summary>
-    public string? Details { get; }
-
-    /// <summary>
-    /// Gets the exception that caused the error, if any.
-    /// </summary>
-    public Exception? Exception { get; }
-
-    /// <summary>
-    /// Gets the timestamp when the error occurred.
-    /// </summary>
-    public DateTime Timestamp { get; }
-
-    /// <summary>
-    /// Creates an error for initialization failure.
-    /// </summary>
-    /// <param name="indexName">The name of the index.</param>
-    /// <param name="details">Optional details.</param>
-    /// <param name="exception">Optional exception.</param>
-    /// <returns>A new SearchError instance.</returns>
-    public static SearchError InitializationFailed(string indexName, string? details = null, Exception? exception = null)
-        => new(SearchErrorCode.InitializationFailed, $"Failed to initialize search index '{indexName}'.", details, exception);
-
-    /// <summary>
-    /// Creates an error for indexing failure.
-    /// </summary>
-    /// <param name="contentId">The ID of the content that failed to index.</param>
-    /// <param name="details">Optional details.</param>
-    /// <param name="exception">Optional exception.</param>
-    /// <returns>A new SearchError instance.</returns>
-    public static SearchError IndexingFailed(string contentId, string? details = null, Exception? exception = null)
-        => new(SearchErrorCode.IndexingFailed, $"Failed to index content '{contentId}'.", details, exception);
-
-    /// <summary>
-    /// Creates an error for search query failure.
-    /// </summary>
-    /// <param name="query">The search query that failed.</param>
-    /// <param name="details">Optional details.</param>
-    /// <param name="exception">Optional exception.</param>
-    /// <returns>A new SearchError instance.</returns>
-    public static SearchError SearchFailed(string query, string? details = null, Exception? exception = null)
-        => new(SearchErrorCode.SearchFailed, $"Search query '{query}' failed.", details, exception);
-
-    /// <summary>
-    /// Creates an error for engine not ready.
-    /// </summary>
-    /// <param name="operation">The operation that was attempted.</param>
-    /// <returns>A new SearchError instance.</returns>
-    public static SearchError EngineNotReady(string operation)
-        => new(SearchErrorCode.EngineNotReady, $"Search engine is not ready. Operation '{operation}' cannot be performed.");
-
-    /// <summary>
-    /// Creates an error for capability unavailable.
-    /// </summary>
-    /// <param name="capability">The capability that is unavailable.</param>
-    /// <param name="details">Optional details.</param>
-    /// <returns>A new SearchError instance.</returns>
-    public static SearchError CapabilityUnavailable(string capability, string? details = null)
-        => new(SearchErrorCode.CapabilityUnavailable, $"Search capability '{capability}' is not available.", details);
-
-    /// <summary>
-    /// Creates an error for timeout.
-    /// </summary>
-    /// <param name="operation">The operation that timed out.</param>
-    /// <param name="timeout">The timeout duration.</param>
-    /// <returns>A new SearchError instance.</returns>
-    public static SearchError Timeout(string operation, TimeSpan timeout)
-        => new(SearchErrorCode.Timeout, $"Operation '{operation}' timed out after {timeout.TotalSeconds:F1} seconds.");
-
-    /// <summary>
-    /// Creates an error for an unexpected error.
-    /// </summary>
-    /// <param name="operation">The operation that failed.</param>
-    /// <param name="exception">The exception that occurred.</param>
-    /// <returns>A new SearchError instance.</returns>
-    public static SearchError Unexpected(string operation, Exception exception)
-        => new(SearchErrorCode.Unexpected, $"Unexpected error during '{operation}'.", exception.Message, exception);
-
-    /// <inheritdoc/>
-    public override string ToString()
-    {
-        var result = $"[{Code}] {Message}";
-        if (!string.IsNullOrEmpty(Details))
-        {
-            result += $" Details: {Details}";
-        }
-
-        if (Exception != null)
-        {
-            result += $" Exception: {Exception.GetType().Name}: {Exception.Message}";
-        }
-
-        return result;
-    }
-}

src/common/Common.Search/SearchErrorCode.cs

@@ -1,51 +0,0 @@
-// Copyright (c) Microsoft Corporation
-// The Microsoft Corporation licenses this file to you under the MIT license.
-// See the LICENSE file in the project root for more information.
-
-namespace Common.Search;
-
-/// <summary>
-/// Defines error codes for search operations.
-/// </summary>
-public enum SearchErrorCode
-{
-    /// <summary>
-    /// No error occurred.
-    /// </summary>
-    None = 0,
-
-    /// <summary>
-    /// The search engine failed to initialize.
-    /// </summary>
-    InitializationFailed = 1,
-
-    /// <summary>
-    /// Failed to index content.
-    /// </summary>
-    IndexingFailed = 2,
-
-    /// <summary>
-    /// The search query failed to execute.
-    /// </summary>
-    SearchFailed = 3,
-
-    /// <summary>
-    /// The search engine is not ready to perform the operation.
-    /// </summary>
-    EngineNotReady = 4,
-
-    /// <summary>
-    /// A required capability is not available.
-    /// </summary>
-    CapabilityUnavailable = 5,
-
-    /// <summary>
-    /// The operation timed out.
-    /// </summary>
-    Timeout = 6,
-
-    /// <summary>
-    /// An unexpected error occurred.
-    /// </summary>
-    Unexpected = 99,
-}

src/common/Common.Search/SearchMatchKind.cs

@@ -1,31 +0,0 @@
-// Copyright (c) Microsoft Corporation
-// The Microsoft Corporation licenses this file to you under the MIT license.
-// See the LICENSE file in the project root for more information.
-
-namespace Common.Search;
-
-/// <summary>
-/// Specifies the kind of match that produced a search result.
-/// </summary>
-public enum SearchMatchKind
-{
-    /// <summary>
-    /// Exact text match.
-    /// </summary>
-    Exact,
-
-    /// <summary>
-    /// Fuzzy/approximate text match.
-    /// </summary>
-    Fuzzy,
-
-    /// <summary>
-    /// Semantic/AI-based match.
-    /// </summary>
-    Semantic,
-
-    /// <summary>
-    /// Combined match from multiple engines.
-    /// </summary>
-    Composite,
-}

src/common/Common.Search/SearchOperationResult.cs

@@ -1,53 +0,0 @@
-// Copyright (c) Microsoft Corporation
-// The Microsoft Corporation licenses this file to you under the MIT license.
-// See the LICENSE file in the project root for more information.
-
-namespace Common.Search;
-
-/// <summary>
-/// Represents the result of a search operation that may have errors.
-/// </summary>
-public sealed class SearchOperationResult
-{
-    private SearchOperationResult(bool success, SearchError? error = null)
-    {
-        IsSuccess = success;
-        Error = error;
-    }
-
-    /// <summary>
-    /// Gets a value indicating whether the operation was successful.
-    /// </summary>
-    public bool IsSuccess { get; }
-
-    /// <summary>
-    /// Gets a value indicating whether the operation failed.
-    /// </summary>
-    public bool IsFailure => !IsSuccess;
-
-    /// <summary>
-    /// Gets the error if the operation failed, null otherwise.
-    /// </summary>
-    public SearchError? Error { get; }
-
-    /// <summary>
-    /// Creates a successful result.
-    /// </summary>
-    /// <returns>A successful SearchOperationResult.</returns>
-    public static SearchOperationResult Success() => new(true);
-
-    /// <summary>
-    /// Creates a failed result with the specified error.
-    /// </summary>
-    /// <param name="error">The error that caused the failure.</param>
-    /// <returns>A failed SearchOperationResult.</returns>
-    public static SearchOperationResult Failure(SearchError error)
-    {
-        ArgumentNullException.ThrowIfNull(error);
-        return new SearchOperationResult(false, error);
-    }
-
-    /// <inheritdoc/>
-    public override string ToString()
-        => IsSuccess ? "Success" : $"Failure: {Error}";
-}

src/common/Common.Search/SearchOperationResult1.cs

@@ -1,87 +0,0 @@
-// Copyright (c) Microsoft Corporation
-// The Microsoft Corporation licenses this file to you under the MIT license.
-// See the LICENSE file in the project root for more information.
-
-using System.Diagnostics.CodeAnalysis;
-
-#pragma warning disable SA1649 // File name should match first type name - Generic type file naming convention
-
-namespace Common.Search;
-
-/// <summary>
-/// Represents the result of a search operation that returns a value and may have errors.
-/// </summary>
-/// <typeparam name="T">The type of the result value.</typeparam>
-public sealed class SearchOperationResult<T>
-{
-    private SearchOperationResult(bool success, T? value, SearchError? error)
-    {
-        IsSuccess = success;
-        Value = value;
-        Error = error;
-    }
-
-    /// <summary>
-    /// Gets a value indicating whether the operation was successful.
-    /// </summary>
-    public bool IsSuccess { get; }
-
-    /// <summary>
-    /// Gets a value indicating whether the operation failed.
-    /// </summary>
-    public bool IsFailure => !IsSuccess;
-
-    /// <summary>
-    /// Gets the result value if the operation was successful.
-    /// </summary>
-    public T? Value { get; }
-
-    /// <summary>
-    /// Gets the error if the operation failed, null otherwise.
-    /// </summary>
-    public SearchError? Error { get; }
-
-    /// <summary>
-    /// Gets the value or a default if the operation failed.
-    /// </summary>
-    /// <param name="defaultValue">The default value to return if the operation failed.</param>
-    /// <returns>The value if successful, otherwise the default value.</returns>
-    public T GetValueOrDefault(T defaultValue) => IsSuccess && Value is not null ? Value : defaultValue;
-
-    /// <inheritdoc/>
-    public override string ToString()
-        => IsSuccess ? $"Success: {Value}" : $"Failure: {Error}";
-
-    /// <summary>
-    /// Creates a successful result with the specified value.
-    /// </summary>
-    /// <param name="value">The result value.</param>
-    /// <returns>A successful SearchOperationResult.</returns>
-    [SuppressMessage("Design", "CA1000:Do not declare static members on generic types", Justification = "Factory method pattern is the idiomatic way to create instances of generic result types")]
-    public static SearchOperationResult<T> Success(T value) => new(true, value, null);
-
-    /// <summary>
-    /// Creates a failed result with the specified error.
-    /// </summary>
-    /// <param name="error">The error that caused the failure.</param>
-    /// <returns>A failed SearchOperationResult.</returns>
-    [SuppressMessage("Design", "CA1000:Do not declare static members on generic types", Justification = "Factory method pattern is the idiomatic way to create instances of generic result types")]
-    public static SearchOperationResult<T> Failure(SearchError error)
-    {
-        ArgumentNullException.ThrowIfNull(error);
-        return new SearchOperationResult<T>(false, default, error);
-    }
-
-    /// <summary>
-    /// Creates a failed result with the specified error and a fallback value.
-    /// </summary>
-    /// <param name="error">The error that caused the failure.</param>
-    /// <param name="fallbackValue">A fallback value to use despite the failure.</param>
-    /// <returns>A failed SearchOperationResult with a fallback value.</returns>
-    [SuppressMessage("Design", "CA1000:Do not declare static members on generic types", Justification = "Factory method pattern is the idiomatic way to create instances of generic result types")]
-    public static SearchOperationResult<T> FailureWithFallback(SearchError error, T fallbackValue)
-    {
-        ArgumentNullException.ThrowIfNull(error);
-        return new SearchOperationResult<T>(false, fallbackValue, error);
-    }
-}

src/common/Common.Search/SearchOptions.cs

@@ -1,35 +0,0 @@
-// Copyright (c) Microsoft Corporation
-// The Microsoft Corporation licenses this file to you under the MIT license.
-// See the LICENSE file in the project root for more information.
-
-namespace Common.Search;
-
-/// <summary>
-/// Options for configuring search behavior.
-/// </summary>
-public sealed class SearchOptions
-{
-    /// <summary>
-    /// Gets or sets the maximum number of results to return.
-    /// Default is 20.
-    /// </summary>
-    public int MaxResults { get; set; } = 20;
-
-    /// <summary>
-    /// Gets or sets the minimum score threshold.
-    /// Results below this score are filtered out.
-    /// Default is 0.0 (no filtering).
-    /// </summary>
-    public double MinScore { get; set; }
-
-    /// <summary>
-    /// Gets or sets the language hint for the search (e.g., "en-US").
-    /// </summary>
-    public string? Language { get; set; }
-
-    /// <summary>
-    /// Gets or sets a value indicating whether to include match spans for highlighting.
-    /// Default is false.
-    /// </summary>
-    public bool IncludeMatchSpans { get; set; }
-}

src/common/Common.Search/SearchResult`1.cs

@@ -1,33 +0,0 @@
-// Copyright (c) Microsoft Corporation
-// The Microsoft Corporation licenses this file to you under the MIT license.
-// See the LICENSE file in the project root for more information.
-
-namespace Common.Search;
-
-/// <summary>
-/// Represents a search result with the matched item and scoring information.
-/// </summary>
-/// <typeparam name="T">The type of the matched item.</typeparam>
-public sealed class SearchResult<T>
-    where T : ISearchable
-{
-    /// <summary>
-    /// Gets the matched item.
-    /// </summary>
-    public required T Item { get; init; }
-
-    /// <summary>
-    /// Gets the relevance score (higher is more relevant).
-    /// </summary>
-    public required double Score { get; init; }
-
-    /// <summary>
-    /// Gets the type of match that produced this result.
-    /// </summary>
-    public required SearchMatchKind MatchKind { get; init; }
-
-    /// <summary>
-    /// Gets the match details for highlighting (optional).
-    /// </summary>
-    public IReadOnlyList<MatchSpan>? MatchSpans { get; init; }
-}

src/common/Common.Search/SemanticSearch/SemanticSearchCapabilities.cs

@@ -1,46 +0,0 @@
-// Copyright (c) Microsoft Corporation
-// The Microsoft Corporation licenses this file to you under the MIT license.
-// See the LICENSE file in the project root for more information.
-
-namespace Common.Search.SemanticSearch;
-
-/// <summary>
-/// Represents the capabilities of the semantic search index.
-/// </summary>
-public class SemanticSearchCapabilities
-{
-    /// <summary>
-    /// Gets or sets a value indicating whether text lexical (keyword) search is available.
-    /// </summary>
-    public bool TextLexicalAvailable { get; set; }
-
-    /// <summary>
-    /// Gets or sets a value indicating whether text semantic (AI embedding) search is available.
-    /// </summary>
-    public bool TextSemanticAvailable { get; set; }
-
-    /// <summary>
-    /// Gets or sets a value indicating whether image semantic search is available.
-    /// </summary>
-    public bool ImageSemanticAvailable { get; set; }
-
-    /// <summary>
-    /// Gets or sets a value indicating whether image OCR search is available.
-    /// </summary>
-    public bool ImageOcrAvailable { get; set; }
-
-    /// <summary>
-    /// Gets a value indicating whether any search capability is available.
-    /// </summary>
-    public bool AnyAvailable => TextLexicalAvailable || TextSemanticAvailable || ImageSemanticAvailable || ImageOcrAvailable;
-
-    /// <summary>
-    /// Gets a value indicating whether text search (lexical or semantic) is available.
-    /// </summary>
-    public bool TextSearchAvailable => TextLexicalAvailable || TextSemanticAvailable;
-
-    /// <summary>
-    /// Gets a value indicating whether image search (semantic or OCR) is available.
-    /// </summary>
-    public bool ImageSearchAvailable => ImageSemanticAvailable || ImageOcrAvailable;
-}

src/common/Common.Search/SemanticSearch/SemanticSearchContentKind.cs

@@ -1,21 +0,0 @@
-// Copyright (c) Microsoft Corporation
-// The Microsoft Corporation licenses this file to you under the MIT license.
-// See the LICENSE file in the project root for more information.
-
-namespace Common.Search.SemanticSearch;
-
-/// <summary>
-/// Specifies the kind of content in a semantic search result.
-/// </summary>
-public enum SemanticSearchContentKind
-{
-    /// <summary>
-    /// Text content.
-    /// </summary>
-    Text,
-
-    /// <summary>
-    /// Image content.
-    /// </summary>
-    Image,
-}

src/common/Common.Search/SemanticSearch/SemanticSearchEngine`1.cs

@@ -1,406 +0,0 @@
-// Copyright (c) Microsoft Corporation
-// The Microsoft Corporation licenses this file to you under the MIT license.
-// See the LICENSE file in the project root for more information.
-
-using ManagedCommon;
-
-namespace Common.Search.SemanticSearch;
-
-/// <summary>
-/// A semantic search engine that implements the common search interface.
-/// </summary>
-/// <typeparam name="T">The type of items to search.</typeparam>
-public sealed class SemanticSearchEngine<T> : ISearchEngine<T>
-    where T : ISearchable
-{
-    private readonly SemanticSearchIndex _index;
-    private readonly Dictionary<string, T> _itemsById = new();
-    private readonly object _lockObject = new();
-    private bool _disposed;
-
-    /// <summary>
-    /// Initializes a new instance of the <see cref="SemanticSearchEngine{T}"/> class.
-    /// </summary>
-    /// <param name="indexName">The name of the search index.</param>
-    public SemanticSearchEngine(string indexName)
-    {
-        Logger.LogDebug($"[SemanticSearchEngine] Creating engine. IndexName={indexName}, ItemType={typeof(T).Name}");
-        _index = new SemanticSearchIndex(indexName);
-    }
-
-    /// <inheritdoc/>
-    public bool IsReady => _index.IsInitialized;
-
-    /// <inheritdoc/>
-    public SearchEngineCapabilities Capabilities { get; } = new()
-    {
-        SupportsFuzzyMatch = true,
-        SupportsSemanticSearch = true,
-        PersistsIndex = true,
-        SupportsIncrementalIndex = true,
-        SupportsMatchSpans = false,
-    };
-
-    /// <summary>
-    /// Gets the underlying semantic search capabilities.
-    /// </summary>
-    public SemanticSearchCapabilities? SemanticCapabilities => _index.Capabilities;
-
-    /// <summary>
-    /// Gets the last error that occurred during a search operation, or null if no error occurred.
-    /// </summary>
-    public SearchError? LastError => _index.LastError;
-
-    /// <summary>
-    /// Occurs when the semantic search capabilities change.
-    /// </summary>
-    public event EventHandler<SemanticSearchCapabilities>? CapabilitiesChanged
-    {
-        add => _index.CapabilitiesChanged += value;
-        remove => _index.CapabilitiesChanged -= value;
-    }
-
-    /// <inheritdoc/>
-    public async Task InitializeAsync(CancellationToken cancellationToken = default)
-    {
-        ThrowIfDisposed();
-        Logger.LogInfo($"[SemanticSearchEngine] InitializeAsync starting. ItemType={typeof(T).Name}");
-        var result = await _index.InitializeAsync().ConfigureAwait(false);
-
-        if (result.IsFailure)
-        {
-            Logger.LogWarning($"[SemanticSearchEngine] InitializeAsync failed. ItemType={typeof(T).Name}, Error={result.Error?.Message}");
-        }
-        else
-        {
-            Logger.LogInfo($"[SemanticSearchEngine] InitializeAsync completed. ItemType={typeof(T).Name}");
-        }
-
-        // Note: We don't throw here to maintain backward compatibility,
-        // but callers can check LastError for details if initialization failed.
-    }
-
-    /// <summary>
-    /// Initializes the search engine and returns the result with error details if any.
-    /// </summary>
-    /// <param name="cancellationToken">Cancellation token.</param>
-    /// <returns>A result indicating success or failure with error details.</returns>
-    public async Task<SearchOperationResult> InitializeWithResultAsync(CancellationToken cancellationToken = default)
-    {
-        ThrowIfDisposed();
-        return await _index.InitializeAsync().ConfigureAwait(false);
-    }
-
-    /// <inheritdoc/>
-    public Task IndexAsync(T item, CancellationToken cancellationToken = default)
-    {
-        ArgumentNullException.ThrowIfNull(item);
-        ThrowIfDisposed();
-
-        var text = BuildSearchableText(item);
-        if (string.IsNullOrWhiteSpace(text))
-        {
-            Logger.LogDebug($"[SemanticSearchEngine] IndexAsync skipped (empty text). Id={item.Id}");
-            return Task.CompletedTask;
-        }
-
-        lock (_lockObject)
-        {
-            _itemsById[item.Id] = item;
-        }
-
-        Logger.LogDebug($"[SemanticSearchEngine] IndexAsync. Id={item.Id}, TextLength={text.Length}");
-
-        // Note: Errors are captured in LastError for external logging
-        _ = _index.IndexText(item.Id, text);
-        return Task.CompletedTask;
-    }
-
-    /// <summary>
-    /// Indexes a single item and returns the result with error details if any.
-    /// </summary>
-    /// <param name="item">The item to index.</param>
-    /// <param name="cancellationToken">Cancellation token.</param>
-    /// <returns>A result indicating success or failure with error details.</returns>
-    public Task<SearchOperationResult> IndexWithResultAsync(T item, CancellationToken cancellationToken = default)
-    {
-        ArgumentNullException.ThrowIfNull(item);
-        ThrowIfDisposed();
-
-        var text = BuildSearchableText(item);
-        if (string.IsNullOrWhiteSpace(text))
-        {
-            return Task.FromResult(SearchOperationResult.Success());
-        }
-
-        lock (_lockObject)
-        {
-            _itemsById[item.Id] = item;
-        }
-
-        return Task.FromResult(_index.IndexText(item.Id, text));
-    }
-
-    /// <inheritdoc/>
-    public Task IndexBatchAsync(IEnumerable<T> items, CancellationToken cancellationToken = default)
-    {
-        ArgumentNullException.ThrowIfNull(items);
-        ThrowIfDisposed();
-
-        var batch = new List<(string Id, string Text)>();
-
-        lock (_lockObject)
-        {
-            foreach (var item in items)
-            {
-                if (cancellationToken.IsCancellationRequested)
-                {
-                    Logger.LogDebug($"[SemanticSearchEngine] IndexBatchAsync cancelled. ItemsProcessed={batch.Count}");
-                    break;
-                }
-
-                var text = BuildSearchableText(item);
-                if (!string.IsNullOrWhiteSpace(text))
-                {
-                    _itemsById[item.Id] = item;
-                    batch.Add((item.Id, text));
-                }
-            }
-        }
-
-        Logger.LogInfo($"[SemanticSearchEngine] IndexBatchAsync. BatchSize={batch.Count}");
-
-        // Note: Errors are captured in LastError for external logging
-        _ = _index.IndexTextBatch(batch);
-        return Task.CompletedTask;
-    }
-
-    /// <summary>
-    /// Indexes multiple items in batch and returns the result with error details if any.
-    /// </summary>
-    /// <param name="items">The items to index.</param>
-    /// <param name="cancellationToken">Cancellation token.</param>
-    /// <returns>A result indicating success or failure with error details.</returns>
-    public Task<SearchOperationResult> IndexBatchWithResultAsync(IEnumerable<T> items, CancellationToken cancellationToken = default)
-    {
-        ArgumentNullException.ThrowIfNull(items);
-        ThrowIfDisposed();
-
-        var batch = new List<(string Id, string Text)>();
-
-        lock (_lockObject)
-        {
-            foreach (var item in items)
-            {
-                if (cancellationToken.IsCancellationRequested)
-                {
-                    break;
-                }
-
-                var text = BuildSearchableText(item);
-                if (!string.IsNullOrWhiteSpace(text))
-                {
-                    _itemsById[item.Id] = item;
-                    batch.Add((item.Id, text));
-                }
-            }
-        }
-
-        return Task.FromResult(_index.IndexTextBatch(batch));
-    }
-
-    /// <inheritdoc/>
-    public Task RemoveAsync(string id, CancellationToken cancellationToken = default)
-    {
-        ArgumentException.ThrowIfNullOrWhiteSpace(id);
-        ThrowIfDisposed();
-
-        lock (_lockObject)
-        {
-            _itemsById.Remove(id);
-        }
-
-        Logger.LogDebug($"[SemanticSearchEngine] RemoveAsync. Id={id}");
-
-        // Note: Errors are captured in LastError for external logging
-        _ = _index.Remove(id);
-        return Task.CompletedTask;
-    }
-
-    /// <inheritdoc/>
-    public Task ClearAsync(CancellationToken cancellationToken = default)
-    {
-        ThrowIfDisposed();
-
-        int count;
-        lock (_lockObject)
-        {
-            count = _itemsById.Count;
-            _itemsById.Clear();
-        }
-
-        Logger.LogInfo($"[SemanticSearchEngine] ClearAsync. ItemsCleared={count}");
-
-        // Note: Errors are captured in LastError for external logging
-        _ = _index.RemoveAll();
-        return Task.CompletedTask;
-    }
-
-    /// <inheritdoc/>
-    public Task<IReadOnlyList<SearchResult<T>>> SearchAsync(
-        string query,
-        SearchOptions? options = null,
-        CancellationToken cancellationToken = default)
-    {
-        ThrowIfDisposed();
-
-        if (string.IsNullOrWhiteSpace(query))
-        {
-            Logger.LogDebug($"[SemanticSearchEngine] SearchAsync skipped (empty query).");
-            return Task.FromResult<IReadOnlyList<SearchResult<T>>>(Array.Empty<SearchResult<T>>());
-        }
-
-        options ??= new SearchOptions();
-        Logger.LogDebug($"[SemanticSearchEngine] SearchAsync starting. Query={query}, MaxResults={options.MaxResults}");
-
-        var semanticOptions = new SemanticSearchOptions
-        {
-            MaxResults = options.MaxResults,
-            Language = options.Language,
-            MatchScope = SemanticSearchMatchScope.Unconstrained,
-            TextMatchType = SemanticSearchTextMatchType.Fuzzy,
-        };
-
-        var searchResult = _index.SearchText(query, semanticOptions);
-
-        // Note: Errors are captured in LastError for external logging
-        var matches = searchResult.Value ?? Array.Empty<SemanticSearchResult>();
-        var results = new List<SearchResult<T>>();
-
-        lock (_lockObject)
-        {
-            foreach (var match in matches)
-            {
-                if (_itemsById.TryGetValue(match.ContentId, out var item))
-                {
-                    results.Add(new SearchResult<T>
-                    {
-                        Item = item,
-                        Score = 100.0, // Semantic search doesn't return scores, use fixed value
-                        MatchKind = SearchMatchKind.Semantic,
-                        MatchSpans = null,
-                    });
-                }
-            }
-        }
-
-        Logger.LogDebug($"[SemanticSearchEngine] SearchAsync completed. Query={query}, Matches={matches.Count}, Results={results.Count}");
-        return Task.FromResult<IReadOnlyList<SearchResult<T>>>(results);
-    }
-
-    /// <summary>
-    /// Searches for items matching the query and returns the result with error details if any.
-    /// </summary>
-    /// <param name="query">The search query.</param>
-    /// <param name="options">Optional search options.</param>
-    /// <param name="cancellationToken">Cancellation token.</param>
-    /// <returns>A result containing search results or error details.</returns>
-    public Task<SearchOperationResult<IReadOnlyList<SearchResult<T>>>> SearchWithResultAsync(
-        string query,
-        SearchOptions? options = null,
-        CancellationToken cancellationToken = default)
-    {
-        ThrowIfDisposed();
-
-        if (string.IsNullOrWhiteSpace(query))
-        {
-            return Task.FromResult(SearchOperationResult<IReadOnlyList<SearchResult<T>>>.Success(Array.Empty<SearchResult<T>>()));
-        }
-
-        options ??= new SearchOptions();
-
-        var semanticOptions = new SemanticSearchOptions
-        {
-            MaxResults = options.MaxResults,
-            Language = options.Language,
-            MatchScope = SemanticSearchMatchScope.Unconstrained,
-            TextMatchType = SemanticSearchTextMatchType.Fuzzy,
-        };
-
-        var searchResult = _index.SearchText(query, semanticOptions);
-        var matches = searchResult.Value ?? Array.Empty<SemanticSearchResult>();
-        var results = new List<SearchResult<T>>();
-
-        lock (_lockObject)
-        {
-            foreach (var match in matches)
-            {
-                if (_itemsById.TryGetValue(match.ContentId, out var item))
-                {
-                    results.Add(new SearchResult<T>
-                    {
-                        Item = item,
-                        Score = 100.0,
-                        MatchKind = SearchMatchKind.Semantic,
-                        MatchSpans = null,
-                    });
-                }
-            }
-        }
-
-        if (searchResult.IsFailure)
-        {
-            return Task.FromResult(SearchOperationResult<IReadOnlyList<SearchResult<T>>>.FailureWithFallback(searchResult.Error!, results));
-        }
-
-        return Task.FromResult(SearchOperationResult<IReadOnlyList<SearchResult<T>>>.Success(results));
-    }
-
-    /// <summary>
-    /// Waits for the indexing process to complete.
-    /// </summary>
-    /// <param name="timeout">The maximum time to wait.</param>
-    /// <returns>A task representing the async operation.</returns>
-    public async Task WaitForIndexingCompleteAsync(TimeSpan timeout)
-    {
-        ThrowIfDisposed();
-        await _index.WaitForIndexingCompleteAsync(timeout).ConfigureAwait(false);
-    }
-
-    /// <inheritdoc/>
-    public void Dispose()
-    {
-        if (_disposed)
-        {
-            return;
-        }
-
-        Logger.LogDebug($"[SemanticSearchEngine] Disposing. ItemType={typeof(T).Name}");
-        _index.Dispose();
-
-        lock (_lockObject)
-        {
-            _itemsById.Clear();
-        }
-
-        _disposed = true;
-    }
-
-    private static string BuildSearchableText(T item)
-    {
-        var primary = item.SearchableText ?? string.Empty;
-        var secondary = item.SecondarySearchableText;
-
-        if (string.IsNullOrWhiteSpace(secondary))
-        {
-            return primary;
-        }
-
-        return $"{primary} {secondary}";
-    }
-
-    private void ThrowIfDisposed()
-    {
-        ObjectDisposedException.ThrowIf(_disposed, this);
-    }
-}

src/common/Common.Search/SemanticSearch/SemanticSearchIndex.cs

@@ -1,455 +0,0 @@
-// Copyright (c) Microsoft Corporation
-// The Microsoft Corporation licenses this file to you under the MIT license.
-// See the LICENSE file in the project root for more information.
-
-using ManagedCommon;
-using Microsoft.Windows.Search.AppContentIndex;
-using Windows.Graphics.Imaging;
-using SearchOperationResult = Common.Search.SearchOperationResult;
-using SearchOperationResultT = Common.Search.SearchOperationResult<System.Collections.Generic.IReadOnlyList<Common.Search.SemanticSearch.SemanticSearchResult>>;
-
-namespace Common.Search.SemanticSearch;
-
-/// <summary>
-/// A semantic search engine powered by Windows App SDK AI Search APIs.
-/// Provides text and image indexing with lexical and semantic search capabilities.
-/// </summary>
-public sealed class SemanticSearchIndex : IDisposable
-{
-    private readonly string _indexName;
-    private AppContentIndexer? _indexer;
-    private bool _disposed;
-    private SemanticSearchCapabilities? _capabilities;
-
-    /// <summary>
-    /// Initializes a new instance of the <see cref="SemanticSearchIndex"/> class.
-    /// </summary>
-    /// <param name="indexName">The name of the search index.</param>
-    public SemanticSearchIndex(string indexName)
-    {
-        ArgumentException.ThrowIfNullOrWhiteSpace(indexName);
-        _indexName = indexName;
-    }
-
-    /// <summary>
-    /// Gets the last error that occurred during an operation, or null if no error occurred.
-    /// </summary>
-    public SearchError? LastError { get; private set; }
-
-    /// <summary>
-    /// Occurs when the index capabilities change.
-    /// </summary>
-    public event EventHandler<SemanticSearchCapabilities>? CapabilitiesChanged;
-
-    /// <summary>
-    /// Gets a value indicating whether the search engine is initialized.
-    /// </summary>
-    public bool IsInitialized => _indexer != null;
-
-    /// <summary>
-    /// Gets the current index capabilities, or null if not initialized.
-    /// </summary>
-    public SemanticSearchCapabilities? Capabilities => _capabilities;
-
-    /// <summary>
-    /// Initializes the search engine and creates or opens the index.
-    /// </summary>
-    /// <returns>A task that represents the asynchronous operation. Returns a result indicating success or failure with error details.</returns>
-    public async Task<SearchOperationResult> InitializeAsync()
-    {
-        ThrowIfDisposed();
-        LastError = null;
-
-        if (_indexer != null)
-        {
-            Logger.LogDebug($"[SemanticSearchIndex] Already initialized. IndexName={_indexName}");
-            return SearchOperationResult.Success();
-        }
-
-        Logger.LogInfo($"[SemanticSearchIndex] Initializing. IndexName={_indexName}");
-
-        try
-        {
-            var result = AppContentIndexer.GetOrCreateIndex(_indexName);
-            if (!result.Succeeded)
-            {
-                var errorDetails = $"Succeeded={result.Succeeded}, ExtendedError={result.ExtendedError}";
-                Logger.LogError($"[SemanticSearchIndex] GetOrCreateIndex failed. IndexName={_indexName}, {errorDetails}");
-                LastError = SearchError.InitializationFailed(_indexName, errorDetails);
-                return SearchOperationResult.Failure(LastError);
-            }
-
-            _indexer = result.Indexer;
-
-            // Wait for index capabilities to be ready
-            Logger.LogDebug($"[SemanticSearchIndex] Waiting for index capabilities. IndexName={_indexName}");
-            await _indexer.WaitForIndexCapabilitiesAsync();
-
-            // Load capabilities
-            _capabilities = LoadCapabilities();
-            Logger.LogInfo($"[SemanticSearchIndex] Initialized successfully. IndexName={_indexName}, TextLexical={_capabilities.TextLexicalAvailable}, TextSemantic={_capabilities.TextSemanticAvailable}, ImageSemantic={_capabilities.ImageSemanticAvailable}, ImageOcr={_capabilities.ImageOcrAvailable}");
-
-            // Subscribe to capability changes
-            _indexer.Listener.IndexCapabilitiesChanged += OnIndexCapabilitiesChanged;
-
-            return SearchOperationResult.Success();
-        }
-        catch (Exception ex)
-        {
-            Logger.LogError($"[SemanticSearchIndex] Initialization failed with exception. IndexName={_indexName}", ex);
-            LastError = SearchError.InitializationFailed(_indexName, ex.Message, ex);
-            return SearchOperationResult.Failure(LastError);
-        }
-    }
-
-    /// <summary>
-    /// Waits for the indexing process to complete.
-    /// </summary>
-    /// <param name="timeout">The maximum time to wait for indexing to complete.</param>
-    /// <returns>A task that represents the asynchronous operation.</returns>
-    public async Task WaitForIndexingCompleteAsync(TimeSpan timeout)
-    {
-        ThrowIfDisposed();
-        ThrowIfNotInitialized();
-
-        await _indexer!.WaitForIndexingIdleAsync(timeout);
-    }
-
-    /// <summary>
-    /// Gets the current index capabilities.
-    /// </summary>
-    /// <returns>The current capabilities of the search index.</returns>
-    public SemanticSearchCapabilities GetCapabilities()
-    {
-        ThrowIfDisposed();
-        ThrowIfNotInitialized();
-
-        return _capabilities ?? LoadCapabilities();
-    }
-
-    /// <summary>
-    /// Adds or updates text content in the index.
-    /// </summary>
-    /// <param name="id">The unique identifier for the content.</param>
-    /// <param name="text">The text content to index.</param>
-    /// <returns>A result indicating success or failure with error details.</returns>
-    public SearchOperationResult IndexText(string id, string text)
-    {
-        ThrowIfDisposed();
-        ThrowIfNotInitialized();
-        ArgumentException.ThrowIfNullOrWhiteSpace(id);
-        ArgumentException.ThrowIfNullOrWhiteSpace(text);
-
-        try
-        {
-            var content = AppManagedIndexableAppContent.CreateFromString(id, text);
-            _indexer!.AddOrUpdate(content);
-            return SearchOperationResult.Success();
-        }
-        catch (Exception ex)
-        {
-            Logger.LogError($"[SemanticSearchIndex] IndexText failed. Id={id}", ex);
-            LastError = SearchError.IndexingFailed(id, ex.Message, ex);
-            return SearchOperationResult.Failure(LastError);
-        }
-    }
-
-    /// <summary>
-    /// Adds or updates multiple text contents in the index.
-    /// </summary>
-    /// <param name="items">A collection of id-text pairs to index.</param>
-    /// <returns>A result indicating success or failure with error details. Contains the first error encountered if any.</returns>
-    public SearchOperationResult IndexTextBatch(IEnumerable<(string Id, string Text)> items)
-    {
-        ThrowIfDisposed();
-        ThrowIfNotInitialized();
-        ArgumentNullException.ThrowIfNull(items);
-
-        SearchError? firstError = null;
-
-        foreach (var (id, text) in items)
-        {
-            if (!string.IsNullOrWhiteSpace(id) && !string.IsNullOrWhiteSpace(text))
-            {
-                try
-                {
-                    var content = AppManagedIndexableAppContent.CreateFromString(id, text);
-                    _indexer!.AddOrUpdate(content);
-                }
-                catch (Exception ex)
-                {
-                    Logger.LogError($"[SemanticSearchIndex] IndexTextBatch item failed. Id={id}", ex);
-                    firstError ??= SearchError.IndexingFailed(id, ex.Message, ex);
-                }
-            }
-        }
-
-        if (firstError != null)
-        {
-            LastError = firstError;
-            return SearchOperationResult.Failure(firstError);
-        }
-
-        return SearchOperationResult.Success();
-    }
-
-    /// <summary>
-    /// Adds or updates image content in the index.
-    /// </summary>
-    /// <param name="id">The unique identifier for the image.</param>
-    /// <param name="bitmap">The image bitmap to index.</param>
-    /// <returns>A result indicating success or failure with error details.</returns>
-    public SearchOperationResult IndexImage(string id, SoftwareBitmap bitmap)
-    {
-        ThrowIfDisposed();
-        ThrowIfNotInitialized();
-        ArgumentException.ThrowIfNullOrWhiteSpace(id);
-        ArgumentNullException.ThrowIfNull(bitmap);
-
-        try
-        {
-            var content = AppManagedIndexableAppContent.CreateFromBitmap(id, bitmap);
-            _indexer!.AddOrUpdate(content);
-            return SearchOperationResult.Success();
-        }
-        catch (Exception ex)
-        {
-            Logger.LogError($"[SemanticSearchIndex] IndexImage failed. Id={id}", ex);
-            LastError = SearchError.IndexingFailed(id, ex.Message, ex);
-            return SearchOperationResult.Failure(LastError);
-        }
-    }
-
-    /// <summary>
-    /// Removes content from the index by its identifier.
-    /// </summary>
-    /// <param name="id">The unique identifier of the content to remove.</param>
-    /// <returns>A result indicating success or failure with error details.</returns>
-    public SearchOperationResult Remove(string id)
-    {
-        ThrowIfDisposed();
-        ThrowIfNotInitialized();
-        ArgumentException.ThrowIfNullOrWhiteSpace(id);
-
-        try
-        {
-            _indexer!.Remove(id);
-            return SearchOperationResult.Success();
-        }
-        catch (Exception ex)
-        {
-            Logger.LogError($"[SemanticSearchIndex] Remove failed. Id={id}", ex);
-            LastError = SearchError.Unexpected("Remove", ex);
-            return SearchOperationResult.Failure(LastError);
-        }
-    }
-
-    /// <summary>
-    /// Removes all content from the index.
-    /// </summary>
-    /// <returns>A result indicating success or failure with error details.</returns>
-    public SearchOperationResult RemoveAll()
-    {
-        ThrowIfDisposed();
-        ThrowIfNotInitialized();
-
-        try
-        {
-            _indexer!.RemoveAll();
-            return SearchOperationResult.Success();
-        }
-        catch (Exception ex)
-        {
-            Logger.LogError($"[SemanticSearchIndex] RemoveAll failed.", ex);
-            LastError = SearchError.Unexpected("RemoveAll", ex);
-            return SearchOperationResult.Failure(LastError);
-        }
-    }
-
-    /// <summary>
-    /// Searches for text content in the index.
-    /// </summary>
-    /// <param name="searchText">The text to search for.</param>
-    /// <param name="options">Optional search options.</param>
-    /// <returns>A result containing search results or error details.</returns>
-    public SearchOperationResultT SearchText(string searchText, SemanticSearchOptions? options = null)
-    {
-        ThrowIfDisposed();
-        ThrowIfNotInitialized();
-        ArgumentException.ThrowIfNullOrWhiteSpace(searchText);
-
-        options ??= new SemanticSearchOptions();
-
-        try
-        {
-            var queryOptions = new TextQueryOptions
-            {
-                MatchScope = ConvertMatchScope(options.MatchScope),
-                TextMatchType = ConvertTextMatchType(options.TextMatchType),
-            };
-
-            if (!string.IsNullOrEmpty(options.Language))
-            {
-                queryOptions.Language = options.Language;
-            }
-
-            var query = _indexer!.CreateTextQuery(searchText, queryOptions);
-            var matches = query.GetNextMatches(options.MaxResults);
-
-            return SearchOperationResultT.Success(ConvertTextMatches(matches));
-        }
-        catch (Exception ex)
-        {
-            Logger.LogError($"[SemanticSearchIndex] SearchText failed. Query={searchText}", ex);
-            LastError = SearchError.SearchFailed(searchText, ex.Message, ex);
-            return SearchOperationResultT.FailureWithFallback(LastError, Array.Empty<SemanticSearchResult>());
-        }
-    }
-
-    /// <summary>
-    /// Searches for image content in the index using text.
-    /// </summary>
-    /// <param name="searchText">The text to search for in images.</param>
-    /// <param name="options">Optional search options.</param>
-    /// <returns>A result containing search results or error details.</returns>
-    public SearchOperationResultT SearchImages(string searchText, SemanticSearchOptions? options = null)
-    {
-        ThrowIfDisposed();
-        ThrowIfNotInitialized();
-        ArgumentException.ThrowIfNullOrWhiteSpace(searchText);
-
-        options ??= new SemanticSearchOptions();
-
-        try
-        {
-            var queryOptions = new ImageQueryOptions
-            {
-                MatchScope = ConvertMatchScope(options.MatchScope),
-                ImageOcrTextMatchType = ConvertTextMatchType(options.TextMatchType),
-            };
-
-            var query = _indexer!.CreateImageQuery(searchText, queryOptions);
-            var matches = query.GetNextMatches(options.MaxResults);
-
-            return SearchOperationResultT.Success(ConvertImageMatches(matches));
-        }
-        catch (Exception ex)
-        {
-            Logger.LogError($"[SemanticSearchIndex] SearchImages failed. Query={searchText}", ex);
-            LastError = SearchError.SearchFailed(searchText, ex.Message, ex);
-            return SearchOperationResultT.FailureWithFallback(LastError, Array.Empty<SemanticSearchResult>());
-        }
-    }
-
-    /// <inheritdoc/>
-    public void Dispose()
-    {
-        if (_disposed)
-        {
-            return;
-        }
-
-        if (_indexer != null)
-        {
-            _indexer.Listener.IndexCapabilitiesChanged -= OnIndexCapabilitiesChanged;
-            _indexer.Dispose();
-            _indexer = null;
-        }
-
-        _disposed = true;
-    }
-
-    private SemanticSearchCapabilities LoadCapabilities()
-    {
-        var capabilities = _indexer!.GetIndexCapabilities();
-
-        return new SemanticSearchCapabilities
-        {
-            TextLexicalAvailable = IsCapabilityInitialized(capabilities, IndexCapability.TextLexical),
-            TextSemanticAvailable = IsCapabilityInitialized(capabilities, IndexCapability.TextSemantic),
-            ImageSemanticAvailable = IsCapabilityInitialized(capabilities, IndexCapability.ImageSemantic),
-            ImageOcrAvailable = IsCapabilityInitialized(capabilities, IndexCapability.ImageOcr),
-        };
-    }
-
-    private static bool IsCapabilityInitialized(IndexCapabilities capabilities, IndexCapability capability)
-    {
-        var state = capabilities.GetCapabilityState(capability);
-        return state.InitializationStatus == IndexCapabilityInitializationStatus.Initialized;
-    }
-
-    private void OnIndexCapabilitiesChanged(AppContentIndexer indexer, IndexCapabilities capabilities)
-    {
-        _capabilities = LoadCapabilities();
-        Logger.LogInfo($"[SemanticSearchIndex] Capabilities changed. IndexName={_indexName}, TextLexical={_capabilities.TextLexicalAvailable}, TextSemantic={_capabilities.TextSemanticAvailable}, ImageSemantic={_capabilities.ImageSemanticAvailable}, ImageOcr={_capabilities.ImageOcrAvailable}");
-        CapabilitiesChanged?.Invoke(this, _capabilities);
-    }
-
-    private static QueryMatchScope ConvertMatchScope(SemanticSearchMatchScope scope)
-    {
-        return scope switch
-        {
-            SemanticSearchMatchScope.Unconstrained => QueryMatchScope.Unconstrained,
-            SemanticSearchMatchScope.Region => QueryMatchScope.Region,
-            SemanticSearchMatchScope.ContentItem => QueryMatchScope.ContentItem,
-            _ => QueryMatchScope.Unconstrained,
-        };
-    }
-
-    private static TextLexicalMatchType ConvertTextMatchType(SemanticSearchTextMatchType matchType)
-    {
-        return matchType switch
-        {
-            SemanticSearchTextMatchType.Fuzzy => TextLexicalMatchType.Fuzzy,
-            SemanticSearchTextMatchType.Exact => TextLexicalMatchType.Exact,
-            _ => TextLexicalMatchType.Fuzzy,
-        };
-    }
-
-    private static IReadOnlyList<SemanticSearchResult> ConvertTextMatches(IReadOnlyList<TextQueryMatch> matches)
-    {
-        var results = new List<SemanticSearchResult>();
-
-        foreach (var match in matches)
-        {
-            var result = new SemanticSearchResult(match.ContentId, SemanticSearchContentKind.Text);
-
-            if (match.ContentKind == QueryMatchContentKind.AppManagedText &&
-                match is AppManagedTextQueryMatch textMatch)
-            {
-                result.TextOffset = textMatch.TextOffset;
-                result.TextLength = textMatch.TextLength;
-            }
-
-            results.Add(result);
-        }
-
-        return results;
-    }
-
-    private static IReadOnlyList<SemanticSearchResult> ConvertImageMatches(IReadOnlyList<ImageQueryMatch> matches)
-    {
-        var results = new List<SemanticSearchResult>();
-
-        foreach (var match in matches)
-        {
-            var result = new SemanticSearchResult(match.ContentId, SemanticSearchContentKind.Image);
-            results.Add(result);
-        }
-
-        return results;
-    }
-
-    private void ThrowIfDisposed()
-    {
-        ObjectDisposedException.ThrowIf(_disposed, this);
-    }
-
-    private void ThrowIfNotInitialized()
-    {
-        if (_indexer == null)
-        {
-            throw new InvalidOperationException("Search engine is not initialized. Call InitializeAsync() first.");
-        }
-    }
-}

src/common/Common.Search/SemanticSearch/SemanticSearchMatchScope.cs

@@ -1,26 +0,0 @@
-// Copyright (c) Microsoft Corporation
-// The Microsoft Corporation licenses this file to you under the MIT license.
-// See the LICENSE file in the project root for more information.
-
-namespace Common.Search.SemanticSearch;
-
-/// <summary>
-/// Specifies the scope for semantic search matching.
-/// </summary>
-public enum SemanticSearchMatchScope
-{
-    /// <summary>
-    /// No constraints, uses both Lexical and Semantic matching.
-    /// </summary>
-    Unconstrained,
-
-    /// <summary>
-    /// Restrict matching to a specific region.
-    /// </summary>
-    Region,
-
-    /// <summary>
-    /// Restrict matching to a single content item.
-    /// </summary>
-    ContentItem,
-}

src/common/Common.Search/SemanticSearch/SemanticSearchOptions.cs

@@ -1,31 +0,0 @@
-// Copyright (c) Microsoft Corporation
-// The Microsoft Corporation licenses this file to you under the MIT license.
-// See the LICENSE file in the project root for more information.
-
-namespace Common.Search.SemanticSearch;
-
-/// <summary>
-/// Options for configuring semantic search queries.
-/// </summary>
-public class SemanticSearchOptions
-{
-    /// <summary>
-    /// Gets or sets the language for the search query (e.g., "en-US").
-    /// </summary>
-    public string? Language { get; set; }
-
-    /// <summary>
-    /// Gets or sets the match scope for the search.
-    /// </summary>
-    public SemanticSearchMatchScope MatchScope { get; set; } = SemanticSearchMatchScope.Unconstrained;
-
-    /// <summary>
-    /// Gets or sets the text match type for lexical matching.
-    /// </summary>
-    public SemanticSearchTextMatchType TextMatchType { get; set; } = SemanticSearchTextMatchType.Fuzzy;
-
-    /// <summary>
-    /// Gets or sets the maximum number of results to return.
-    /// </summary>
-    public int MaxResults { get; set; } = 10;
-}

src/common/Common.Search/SemanticSearch/SemanticSearchResult.cs

@@ -1,42 +0,0 @@
-// Copyright (c) Microsoft Corporation
-// The Microsoft Corporation licenses this file to you under the MIT license.
-// See the LICENSE file in the project root for more information.
-
-namespace Common.Search.SemanticSearch;
-
-/// <summary>
-/// Represents a search result from the semantic search engine.
-/// </summary>
-public class SemanticSearchResult
-{
-    /// <summary>
-    /// Initializes a new instance of the <see cref="SemanticSearchResult"/> class.
-    /// </summary>
-    /// <param name="contentId">The unique identifier of the matched content.</param>
-    /// <param name="contentKind">The kind of content matched (text or image).</param>
-    public SemanticSearchResult(string contentId, SemanticSearchContentKind contentKind)
-    {
-        ContentId = contentId;
-        ContentKind = contentKind;
-    }
-
-    /// <summary>
-    /// Gets the unique identifier of the matched content.
-    /// </summary>
-    public string ContentId { get; }
-
-    /// <summary>
-    /// Gets the kind of content that was matched.
-    /// </summary>
-    public SemanticSearchContentKind ContentKind { get; }
-
-    /// <summary>
-    /// Gets or sets the text offset where the match was found (for text matches only).
-    /// </summary>
-    public int TextOffset { get; set; }
-
-    /// <summary>
-    /// Gets or sets the length of the matched text (for text matches only).
-    /// </summary>
-    public int TextLength { get; set; }
-}

src/common/Common.Search/SemanticSearch/SemanticSearchTextMatchType.cs

@@ -1,21 +0,0 @@
-// Copyright (c) Microsoft Corporation
-// The Microsoft Corporation licenses this file to you under the MIT license.
-// See the LICENSE file in the project root for more information.
-
-namespace Common.Search.SemanticSearch;
-
-/// <summary>
-/// Specifies the type of text matching for lexical searches.
-/// </summary>
-public enum SemanticSearchTextMatchType
-{
-    /// <summary>
-    /// Fuzzy matching allows spelling errors and approximate words.
-    /// </summary>
-    Fuzzy,
-
-    /// <summary>
-    /// Exact matching requires exact text matches.
-    /// </summary>
-    Exact,
-}

src/gpo/assets/PowerToys.admx

@@ -1,11 +1,11 @@
 <?xml version="1.0" encoding="utf-8"?>
 <!-- Copyright (c) Microsoft Corporation.
      Licensed under the MIT License. -->
-<policyDefinitions xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" revision="1.18" schemaVersion="1.0" xmlns="http://schemas.microsoft.com/GroupPolicy/2006/07/PolicyDefinitions">
+<policyDefinitions xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" revision="1.19" schemaVersion="1.0" xmlns="http://schemas.microsoft.com/GroupPolicy/2006/07/PolicyDefinitions">
   <policyNamespaces>
     <target prefix="powertoys" namespace="Microsoft.Policies.PowerToys" />
   </policyNamespaces>
-  <resources minRequiredRevision="1.18"/><!-- Last changed with PowerToys v0.96.0 -->
+  <resources minRequiredRevision="1.19"/><!-- Last changed with PowerToys v0.97.0 -->
   <supportedOn>
     <definitions>
       <definition name="SUPPORTED_POWERTOYS_0_64_0" displayName="$(string.SUPPORTED_POWERTOYS_0_64_0)"/>
@@ -27,6 +27,7 @@
       <definition name="SUPPORTED_POWERTOYS_0_89_0" displayName="$(string.SUPPORTED_POWERTOYS_0_89_0)"/>
       <definition name="SUPPORTED_POWERTOYS_0_90_0" displayName="$(string.SUPPORTED_POWERTOYS_0_90_0)"/>
       <definition name="SUPPORTED_POWERTOYS_0_96_0" displayName="$(string.SUPPORTED_POWERTOYS_0_96_0)"/>
+      <definition name="SUPPORTED_POWERTOYS_0_97_0" displayName="$(string.SUPPORTED_POWERTOYS_0_97_0)"/>
       <definition name="SUPPORTED_POWERTOYS_0_64_0_TO_0_87_1" displayName="$(string.SUPPORTED_POWERTOYS_0_64_0_TO_0_87_1)"/>
     </definitions>
   </supportedOn>
@@ -338,6 +339,16 @@
         <decimal value="0" />
       </disabledValue>
     </policy>
+    <policy name="ConfigureEnabledUtilityCursorWrap" class="Both" displayName="$(string.ConfigureEnabledUtilityCursorWrap)" explainText="$(string.ConfigureEnabledUtilityDescription)" key="Software\Policies\PowerToys" valueName="ConfigureEnabledUtilityCursorWrap">
+      <parentCategory ref="PowerToys" />
+      <supportedOn ref="SUPPORTED_POWERTOYS_0_97_0" />
+      <enabledValue>
+        <decimal value="1" />
+      </enabledValue>
+      <disabledValue>
+        <decimal value="0" />
+      </disabledValue>
+    </policy>
     <policy name="ConfigureEnabledUtilityFindMyMouse" class="Both" displayName="$(string.ConfigureEnabledUtilityFindMyMouse)" explainText="$(string.ConfigureEnabledUtilityDescription)" key="Software\Policies\PowerToys" valueName="ConfigureEnabledUtilityFindMyMouse">
       <parentCategory ref="PowerToys" />
       <supportedOn ref="SUPPORTED_POWERTOYS_0_64_0" />

src/gpo/assets/en-US/PowerToys.adml

@@ -1,7 +1,7 @@
 <?xml version="1.0" encoding="utf-8"?>
 <!-- Copyright (c) Microsoft Corporation.
      Licensed under the MIT License. -->
-<policyDefinitionResources xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" revision="1.18" schemaVersion="1.0" xmlns="http://schemas.microsoft.com/GroupPolicy/2006/07/PolicyDefinitions">
+<policyDefinitionResources xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" revision="1.19" schemaVersion="1.0" xmlns="http://schemas.microsoft.com/GroupPolicy/2006/07/PolicyDefinitions">
   <displayName>PowerToys</displayName>
   <description>PowerToys</description>
   <resources>
@@ -34,6 +34,7 @@
       <string id="SUPPORTED_POWERTOYS_0_89_0">PowerToys version 0.89.0 or later</string>
       <string id="SUPPORTED_POWERTOYS_0_90_0">PowerToys version 0.90.0 or later</string>
       <string id="SUPPORTED_POWERTOYS_0_96_0">PowerToys version 0.96.0 or later</string>
+      <string id="SUPPORTED_POWERTOYS_0_97_0">PowerToys version 0.97.0 or later</string>
       <string id="SUPPORTED_POWERTOYS_0_64_0_TO_0_87_1">From PowerToys version 0.64.0 until PowerToys version 0.87.1</string>
 
       <string id="ConfigureAllUtilityGlobalEnabledStateDescription">This policy configures the enabled state for all PowerToys utilities.
@@ -266,6 +267,7 @@ If you don't configure this policy, the user will be able to control the setting
       <string id="ConfigureEnabledUtilityKeyboardManager">Keyboard Manager: Configure enabled state</string>
       <string id="ConfigureEnabledUtilityFindMyMouse">Find My Mouse: Configure enabled state</string>
       <string id="ConfigureEnabledUtilityMouseHighlighter">Mouse Highlighter: Configure enabled state</string>
+      <string id="ConfigureEnabledUtilityCursorWrap">CursorWrap: Configure enabled state</string>
       <string id="ConfigureEnabledUtilityMouseJump">Mouse Jump: Configure enabled state</string>
       <string id="ConfigureEnabledUtilityMousePointerCrosshairs">Mouse Pointer Crosshairs: Configure enabled state</string>
       <string id="ConfigureEnabledUtilityMouseWithoutBorders">Mouse Without Borders: Configure enabled state</string>

src/modules/MouseUtils/CursorWrap/CursorWrap.vcxproj

@@ -84,14 +84,17 @@
     </ClCompile>
   </ItemDefinitionGroup>
   <ItemGroup>
+    <ClInclude Include="CursorWrapCore.h" />
     <ClInclude Include="CursorWrapTests.h" />
+    <ClInclude Include="MonitorTopology.h" />
     <ClInclude Include="pch.h" />
     <ClInclude Include="trace.h" />
     <ClInclude Include="resource.h" />
   </ItemGroup>
   <ItemGroup>
+    <ClCompile Include="CursorWrapCore.cpp" />
     <ClCompile Include="dllmain.cpp" />
-
+    <ClCompile Include="MonitorTopology.cpp" />
     <ClCompile Include="pch.cpp">
       <PrecompiledHeader Condition="'$(UsePrecompiledHeaders)' != 'false'">Create</PrecompiledHeader>
     </ClCompile>

src/modules/MouseUtils/CursorWrap/CursorWrapCore.cpp

@@ -0,0 +1,268 @@
+// Copyright (c) Microsoft Corporation
+// The Microsoft Corporation licenses this file to you under the MIT license.
+// See the LICENSE file in the project root for more information.
+
+#include "pch.h"
+#include "CursorWrapCore.h"
+#include "../../../common/logger/logger.h"
+#include <sstream>
+#include <iomanip>
+#include <ctime>
+
+CursorWrapCore::CursorWrapCore()
+{
+}
+
+#ifdef _DEBUG
+std::wstring CursorWrapCore::GenerateTopologyJSON() const
+{
+    std::wostringstream json;
+
+    // Get current time
+    auto now = std::time(nullptr);
+    std::tm tm{};
+    localtime_s(&tm, &now);
+
+    wchar_t computerName[MAX_COMPUTERNAME_LENGTH + 1] = {0};
+    DWORD size = MAX_COMPUTERNAME_LENGTH + 1;
+    GetComputerNameW(computerName, &size);
+
+    wchar_t userName[256] = {0};
+    size = 256;
+    GetUserNameW(userName, &size);
+
+    json << L"{\n";
+    json << L"  \"captured_at\": \"" << std::put_time(&tm, L"%Y-%m-%dT%H:%M:%S%z") << L"\",\n";
+    json << L"  \"computer_name\": \"" << computerName << L"\",\n";
+    json << L"  \"user_name\": \"" << userName << L"\",\n";
+    json << L"  \"monitor_count\": " << m_monitors.size() << L",\n";
+    json << L"  \"monitors\": [\n";
+
+    for (size_t i = 0; i < m_monitors.size(); ++i)
+    {
+        const auto& monitor = m_monitors[i];
+
+        // Get DPI for this monitor
+        UINT dpiX = 96, dpiY = 96;
+        POINT center = {
+            (monitor.rect.left + monitor.rect.right) / 2,
+            (monitor.rect.top + monitor.rect.bottom) / 2
+        };
+        HMONITOR hMon = MonitorFromPoint(center, MONITOR_DEFAULTTONEAREST);
+        if (hMon)
+        {
+            // Try GetDpiForMonitor (requires linking Shcore.lib)
+            using GetDpiForMonitorFunc = HRESULT (WINAPI *)(HMONITOR, int, UINT*, UINT*);
+            HMODULE shcore = LoadLibraryW(L"Shcore.dll");
+            if (shcore)
+            {
+                auto getDpi = reinterpret_cast<GetDpiForMonitorFunc>(GetProcAddress(shcore, "GetDpiForMonitor"));
+                if (getDpi)
+                {
+                    getDpi(hMon, 0, &dpiX, &dpiY); // MDT_EFFECTIVE_DPI = 0
+                }
+                FreeLibrary(shcore);
+            }
+        }
+
+        int scalingPercent = static_cast<int>((dpiX / 96.0) * 100);
+
+        json << L"    {\n";
+        json << L"      \"left\": " << monitor.rect.left << L",\n";
+        json << L"      \"top\": " << monitor.rect.top << L",\n";
+        json << L"      \"right\": " << monitor.rect.right << L",\n";
+        json << L"      \"bottom\": " << monitor.rect.bottom << L",\n";
+        json << L"      \"width\": " << (monitor.rect.right - monitor.rect.left) << L",\n";
+        json << L"      \"height\": " << (monitor.rect.bottom - monitor.rect.top) << L",\n";
+        json << L"      \"dpi\": " << dpiX << L",\n";
+        json << L"      \"scaling_percent\": " << scalingPercent << L",\n";
+        json << L"      \"primary\": " << (monitor.isPrimary ? L"true" : L"false") << L",\n";
+        json << L"      \"monitor_id\": " << monitor.monitorId << L"\n";
+        json << L"    }";
+        if (i < m_monitors.size() - 1)
+        {
+            json << L",";
+        }
+        json << L"\n";
+    }
+
+    json << L"  ]\n";
+    json << L"}";
+
+    return json.str();
+}
+#endif
+
+void CursorWrapCore::UpdateMonitorInfo()
+{
+    size_t previousMonitorCount = m_monitors.size();
+    Logger::info(L"======= UPDATE MONITOR INFO START =======");
+    Logger::info(L"Previous monitor count: {}", previousMonitorCount);
+
+    m_monitors.clear();
+
+    EnumDisplayMonitors(nullptr, nullptr, [](HMONITOR hMonitor, HDC, LPRECT, LPARAM lParam) -> BOOL {
+        auto* self = reinterpret_cast<CursorWrapCore*>(lParam);
+
+        MONITORINFO mi{};
+        mi.cbSize = sizeof(MONITORINFO);
+        if (GetMonitorInfo(hMonitor, &mi))
+        {
+            MonitorInfo info{};
+            info.hMonitor = hMonitor; // Store handle for direct comparison later
+            info.rect = mi.rcMonitor;
+            info.isPrimary = (mi.dwFlags & MONITORINFOF_PRIMARY) != 0;
+            info.monitorId = static_cast<int>(self->m_monitors.size());
+            self->m_monitors.push_back(info);
+            
+            Logger::info(L"Enumerated monitor {}: hMonitor={}, rect=({},{},{},{}), primary={}",
+                info.monitorId, reinterpret_cast<uintptr_t>(hMonitor),
+                mi.rcMonitor.left, mi.rcMonitor.top, mi.rcMonitor.right, mi.rcMonitor.bottom,
+                info.isPrimary ? L"yes" : L"no");
+        }
+
+        return TRUE;
+    }, reinterpret_cast<LPARAM>(this));
+
+    if (previousMonitorCount != m_monitors.size())
+    {
+        Logger::info(L"*** MONITOR CONFIGURATION CHANGED: {} -> {} monitors ***", 
+            previousMonitorCount, m_monitors.size());
+    }
+
+    m_topology.Initialize(m_monitors);
+
+    // Log monitor configuration summary
+    Logger::info(L"Monitor configuration updated: {} monitor(s)", m_monitors.size());
+    for (size_t i = 0; i < m_monitors.size(); ++i)
+    {
+        const auto& m = m_monitors[i];
+        int width = m.rect.right - m.rect.left;
+        int height = m.rect.bottom - m.rect.top;
+        Logger::info(L"  Monitor {}: {}x{} at ({}, {}){}",
+            i, width, height, m.rect.left, m.rect.top,
+            m.isPrimary ? L" [PRIMARY]" : L"");
+    }
+    Logger::info(L"  Detected {} outer edges for cursor wrapping", m_topology.GetOuterEdges().size());
+
+    // Detect and log monitor gaps
+    auto gaps = m_topology.DetectMonitorGaps();
+    if (!gaps.empty())
+    {
+        Logger::warn(L"Monitor configuration has coordinate gaps that may prevent wrapping:");
+        for (const auto& gap : gaps)
+        {
+            Logger::warn(L"  Gap between Monitor {} and Monitor {}: {}px horizontal gap, {}px vertical overlap",
+                gap.monitor1Index, gap.monitor2Index, gap.horizontalGap, gap.verticalOverlap);
+        }
+        Logger::warn(L"  If monitors appear snapped in Display Settings but show gaps here:");
+        Logger::warn(L"  1. Try dragging monitors apart and snapping them back together");
+        Logger::warn(L"  2. Update your GPU drivers");
+    }
+
+    Logger::info(L"======= UPDATE MONITOR INFO END =======");
+}
+
+POINT CursorWrapCore::HandleMouseMove(const POINT& currentPos, bool disableWrapDuringDrag, int wrapMode)
+{
+    // Check if wrapping should be disabled during drag
+    if (disableWrapDuringDrag && (GetAsyncKeyState(VK_LBUTTON) & 0x8000))
+    {
+#ifdef _DEBUG
+        OutputDebugStringW(L"[CursorWrap] [DRAG] Left mouse button down - skipping wrap\n");
+#endif
+        return currentPos;
+    }
+
+    // Convert int wrapMode to WrapMode enum
+    WrapMode mode = static_cast<WrapMode>(wrapMode);
+
+#ifdef _DEBUG
+    {
+        std::wostringstream oss;
+        oss << L"[CursorWrap] [MOVE] Cursor at (" << currentPos.x << L", " << currentPos.y << L")";
+
+        // Get current monitor and identify which one
+        HMONITOR currentMonitor = MonitorFromPoint(currentPos, MONITOR_DEFAULTTONEAREST);
+        RECT monitorRect;
+        if (m_topology.GetMonitorRect(currentMonitor, monitorRect))
+        {
+            // Find monitor ID
+            int monitorId = -1;
+            for (const auto& monitor : m_monitors)
+            {
+                if (monitor.rect.left == monitorRect.left &&
+                    monitor.rect.top == monitorRect.top &&
+                    monitor.rect.right == monitorRect.right &&
+                    monitor.rect.bottom == monitorRect.bottom)
+                {
+                    monitorId = monitor.monitorId;
+                    break;
+                }
+            }
+            oss << L" on Monitor " << monitorId << L" [" << monitorRect.left << L".." << monitorRect.right
+                << L", " << monitorRect.top << L".." << monitorRect.bottom << L"]";
+        }
+        else
+        {
+            oss << L" (beyond monitor bounds)";
+        }
+        oss << L"\n";
+        OutputDebugStringW(oss.str().c_str());
+    }
+#endif
+
+    // Get current monitor
+    HMONITOR currentMonitor = MonitorFromPoint(currentPos, MONITOR_DEFAULTTONEAREST);
+
+    // Check if cursor is on an outer edge (filtered by wrap mode)
+    EdgeType edgeType;
+    if (!m_topology.IsOnOuterEdge(currentMonitor, currentPos, edgeType, mode))
+    {
+#ifdef _DEBUG
+        static bool lastWasNotOuter = false;
+        if (!lastWasNotOuter)
+        {
+            OutputDebugStringW(L"[CursorWrap] [MOVE] Not on outer edge - no wrapping\n");
+            lastWasNotOuter = true;
+        }
+#endif
+        return currentPos; // Not on an outer edge
+    }
+
+#ifdef _DEBUG
+    {
+        const wchar_t* edgeStr = L"Unknown";
+        switch (edgeType)
+        {
+        case EdgeType::Left: edgeStr = L"Left"; break;
+        case EdgeType::Right: edgeStr = L"Right"; break;
+        case EdgeType::Top: edgeStr = L"Top"; break;
+        case EdgeType::Bottom: edgeStr = L"Bottom"; break;
+        }
+        std::wostringstream oss;
+        oss << L"[CursorWrap] [EDGE] Detected outer " << edgeStr << L" edge at (" << currentPos.x << L", " << currentPos.y << L")\n";
+        OutputDebugStringW(oss.str().c_str());
+    }
+#endif
+
+    // Calculate wrap destination
+    POINT newPos = m_topology.GetWrapDestination(currentMonitor, currentPos, edgeType);
+
+#ifdef _DEBUG
+    if (newPos.x != currentPos.x || newPos.y != currentPos.y)
+    {
+        std::wostringstream oss;
+        oss << L"[CursorWrap] [WRAP] Position change: (" << currentPos.x << L", " << currentPos.y
+            << L") -> (" << newPos.x << L", " << newPos.y << L")\n";
+        oss << L"[CursorWrap] [WRAP] Delta: (" << (newPos.x - currentPos.x) << L", " << (newPos.y - currentPos.y) << L")\n";
+        OutputDebugStringW(oss.str().c_str());
+    }
+    else
+    {
+        OutputDebugStringW(L"[CursorWrap] [WRAP] No position change (same-monitor wrap?)\n");
+    }
+#endif
+
+    return newPos;
+}

src/modules/MouseUtils/CursorWrap/CursorWrapCore.h

@@ -0,0 +1,33 @@
+// Copyright (c) Microsoft Corporation
+// The Microsoft Corporation licenses this file to you under the MIT license.
+// See the LICENSE file in the project root for more information.
+
+#pragma once
+#include <windows.h>
+#include <vector>
+#include <string>
+#include "MonitorTopology.h"
+
+// Core cursor wrapping engine
+class CursorWrapCore
+{
+public:
+    CursorWrapCore();
+
+    void UpdateMonitorInfo();
+    
+    // Handle mouse move with wrap mode filtering
+    // wrapMode: 0=Both, 1=VerticalOnly, 2=HorizontalOnly
+    POINT HandleMouseMove(const POINT& currentPos, bool disableWrapDuringDrag, int wrapMode);
+
+    const std::vector<MonitorInfo>& GetMonitors() const { return m_monitors; }
+    const MonitorTopology& GetTopology() const { return m_topology; }
+
+private:
+#ifdef _DEBUG
+    std::wstring GenerateTopologyJSON() const;
+#endif
+
+    std::vector<MonitorInfo> m_monitors;
+    MonitorTopology m_topology;
+};

src/modules/MouseUtils/CursorWrap/MonitorTopology.cpp

@@ -0,0 +1,546 @@
+// Copyright (c) Microsoft Corporation
+// The Microsoft Corporation licenses this file to you under the MIT license.
+// See the LICENSE file in the project root for more information.
+
+#include "pch.h"
+#include "MonitorTopology.h"
+#include "../../../common/logger/logger.h"
+#include <algorithm>
+#include <cmath>
+
+void MonitorTopology::Initialize(const std::vector<MonitorInfo>& monitors)
+{
+    Logger::info(L"======= TOPOLOGY INITIALIZATION START =======");
+    Logger::info(L"Initializing edge-based topology for {} monitors", monitors.size());
+
+    m_monitors = monitors;
+    m_outerEdges.clear();
+    m_edgeMap.clear();
+
+    if (monitors.empty())
+    {
+        Logger::warn(L"No monitors provided to Initialize");
+        return;
+    }
+
+    // Log monitor details
+    for (size_t i = 0; i < monitors.size(); ++i)
+    {
+        const auto& m = monitors[i];
+        Logger::info(L"Monitor {}: hMonitor={}, rect=({},{},{},{}), primary={}",
+            i, reinterpret_cast<uintptr_t>(m.hMonitor),
+            m.rect.left, m.rect.top, m.rect.right, m.rect.bottom,
+            m.isPrimary ? L"yes" : L"no");
+    }
+
+    BuildEdgeMap();
+    IdentifyOuterEdges();
+
+    Logger::info(L"Found {} outer edges", m_outerEdges.size());
+    for (const auto& edge : m_outerEdges)
+    {
+        const wchar_t* typeStr = L"Unknown";
+        switch (edge.type)
+        {
+        case EdgeType::Left: typeStr = L"Left"; break;
+        case EdgeType::Right: typeStr = L"Right"; break;
+        case EdgeType::Top: typeStr = L"Top"; break;
+        case EdgeType::Bottom: typeStr = L"Bottom"; break;
+        }
+        Logger::info(L"Outer edge: Monitor {} {} at position {}, range [{}, {}]",
+            edge.monitorIndex, typeStr, edge.position, edge.start, edge.end);
+    }
+    Logger::info(L"======= TOPOLOGY INITIALIZATION COMPLETE =======");
+}
+
+void MonitorTopology::BuildEdgeMap()
+{
+    // Create edges for each monitor using monitor index (not HMONITOR)
+    // This is important because HMONITOR handles can change when monitors are
+    // added/removed dynamically, but indices remain stable within a single
+    // topology configuration
+    for (size_t idx = 0; idx < m_monitors.size(); ++idx)
+    {
+        const auto& monitor = m_monitors[idx];
+        int monitorIndex = static_cast<int>(idx);
+
+        // Left edge
+        MonitorEdge leftEdge;
+        leftEdge.monitorIndex = monitorIndex;
+        leftEdge.type = EdgeType::Left;
+        leftEdge.position = monitor.rect.left;
+        leftEdge.start = monitor.rect.top;
+        leftEdge.end = monitor.rect.bottom;
+        leftEdge.isOuter = true; // Will be updated in IdentifyOuterEdges
+        m_edgeMap[{monitorIndex, EdgeType::Left}] = leftEdge;
+      
+        // Right edge
+        MonitorEdge rightEdge;
+        rightEdge.monitorIndex = monitorIndex;
+        rightEdge.type = EdgeType::Right;
+        rightEdge.position = monitor.rect.right - 1;
+        rightEdge.start = monitor.rect.top;
+        rightEdge.end = monitor.rect.bottom;
+        rightEdge.isOuter = true;
+        m_edgeMap[{monitorIndex, EdgeType::Right}] = rightEdge;
+
+        // Top edge
+        MonitorEdge topEdge;
+        topEdge.monitorIndex = monitorIndex;
+        topEdge.type = EdgeType::Top;
+        topEdge.position = monitor.rect.top;
+        topEdge.start = monitor.rect.left;
+        topEdge.end = monitor.rect.right;
+        topEdge.isOuter = true;
+        m_edgeMap[{monitorIndex, EdgeType::Top}] = topEdge;
+
+        // Bottom edge
+        MonitorEdge bottomEdge;
+        bottomEdge.monitorIndex = monitorIndex;
+        bottomEdge.type = EdgeType::Bottom;
+        bottomEdge.position = monitor.rect.bottom - 1;
+        bottomEdge.start = monitor.rect.left;
+        bottomEdge.end = monitor.rect.right;
+        bottomEdge.isOuter = true;
+        m_edgeMap[{monitorIndex, EdgeType::Bottom}] = bottomEdge;
+    }
+}
+
+void MonitorTopology::IdentifyOuterEdges()
+{
+    const int tolerance = 50;
+    
+    // Check each edge against all other edges to find adjacent ones
+    for (auto& [key1, edge1] : m_edgeMap)
+    {
+        for (const auto& [key2, edge2] : m_edgeMap)
+        {
+            if (edge1.monitorIndex == edge2.monitorIndex)
+            {
+                continue; // Same monitor
+            }
+
+            // Check if edges are adjacent
+            if (EdgesAreAdjacent(edge1, edge2, tolerance))
+            {
+                edge1.isOuter = false;
+                break; // This edge has an adjacent monitor
+            }
+        }
+
+        if (edge1.isOuter)
+        {
+            m_outerEdges.push_back(edge1);
+        }
+    }
+}
+
+bool MonitorTopology::EdgesAreAdjacent(const MonitorEdge& edge1, const MonitorEdge& edge2, int tolerance) const
+{
+    // Edges must be opposite types to be adjacent
+    bool oppositeTypes = false;
+
+    if ((edge1.type == EdgeType::Left && edge2.type == EdgeType::Right) ||
+        (edge1.type == EdgeType::Right && edge2.type == EdgeType::Left) ||
+        (edge1.type == EdgeType::Top && edge2.type == EdgeType::Bottom) ||
+        (edge1.type == EdgeType::Bottom && edge2.type == EdgeType::Top))
+    {
+        oppositeTypes = true;
+    }
+
+    if (!oppositeTypes)
+    {
+        return false;
+    }
+
+    // Check if positions are within tolerance
+    if (abs(edge1.position - edge2.position) > tolerance)
+    {
+        return false;
+    }
+
+    // Check if perpendicular ranges overlap
+    int overlapStart = max(edge1.start, edge2.start);
+    int overlapEnd = min(edge1.end, edge2.end);
+
+    return overlapEnd > overlapStart + tolerance;
+}
+
+bool MonitorTopology::IsOnOuterEdge(HMONITOR monitor, const POINT& cursorPos, EdgeType& outEdgeType, WrapMode wrapMode) const
+{
+    RECT monitorRect;
+    if (!GetMonitorRect(monitor, monitorRect))
+    {
+        Logger::warn(L"IsOnOuterEdge: GetMonitorRect failed for monitor handle {}", reinterpret_cast<uintptr_t>(monitor));
+        return false;
+    }
+
+    // Get monitor index for edge map lookup
+    int monitorIndex = GetMonitorIndex(monitor);
+    if (monitorIndex < 0)
+    {
+        Logger::warn(L"IsOnOuterEdge: Monitor index not found for handle {} at cursor ({}, {})", 
+            reinterpret_cast<uintptr_t>(monitor), cursorPos.x, cursorPos.y);
+        return false; // Monitor not found in our list
+    }
+
+    // Check each edge type
+    const int edgeThreshold = 1;
+
+    // At corners, multiple edges may match - collect all candidates and try each
+    // to find one with a valid wrap destination
+    std::vector<EdgeType> candidateEdges;
+
+    // Left edge - only if mode allows horizontal wrapping
+    if ((wrapMode == WrapMode::Both || wrapMode == WrapMode::HorizontalOnly) &&
+        cursorPos.x <= monitorRect.left + edgeThreshold)
+    {
+        auto it = m_edgeMap.find({monitorIndex, EdgeType::Left});
+        if (it != m_edgeMap.end() && it->second.isOuter)
+        {
+            candidateEdges.push_back(EdgeType::Left);
+        }
+    }
+
+    // Right edge - only if mode allows horizontal wrapping
+    if ((wrapMode == WrapMode::Both || wrapMode == WrapMode::HorizontalOnly) &&
+        cursorPos.x >= monitorRect.right - 1 - edgeThreshold)
+    {
+        auto it = m_edgeMap.find({monitorIndex, EdgeType::Right});
+        if (it != m_edgeMap.end())
+        {
+            if (it->second.isOuter)
+            {
+                candidateEdges.push_back(EdgeType::Right);
+            }
+            // Debug: Log why right edge isn't outer
+            else
+            {
+                Logger::trace(L"IsOnOuterEdge: Monitor {} right edge is NOT outer (inner edge)", monitorIndex);
+            }
+        }
+    }
+
+    // Top edge - only if mode allows vertical wrapping
+    if ((wrapMode == WrapMode::Both || wrapMode == WrapMode::VerticalOnly) &&
+        cursorPos.y <= monitorRect.top + edgeThreshold)
+    {
+        auto it = m_edgeMap.find({monitorIndex, EdgeType::Top});
+        if (it != m_edgeMap.end() && it->second.isOuter)
+        {
+            candidateEdges.push_back(EdgeType::Top);
+        }
+    }
+
+    // Bottom edge - only if mode allows vertical wrapping
+    if ((wrapMode == WrapMode::Both || wrapMode == WrapMode::VerticalOnly) &&
+        cursorPos.y >= monitorRect.bottom - 1 - edgeThreshold)
+    {
+        auto it = m_edgeMap.find({monitorIndex, EdgeType::Bottom});
+        if (it != m_edgeMap.end() && it->second.isOuter)
+        {
+            candidateEdges.push_back(EdgeType::Bottom);
+        }
+    }
+
+    if (candidateEdges.empty())
+    {
+        return false;
+    }
+
+    // Try each candidate edge and return first with valid wrap destination
+    for (EdgeType candidate : candidateEdges)
+    {
+        MonitorEdge oppositeEdge = FindOppositeOuterEdge(candidate,
+            (candidate == EdgeType::Left || candidate == EdgeType::Right) ? cursorPos.y : cursorPos.x);
+
+        if (oppositeEdge.monitorIndex >= 0)
+        {
+            outEdgeType = candidate;
+            return true;
+        }
+    }
+
+    return false;
+}
+
+POINT MonitorTopology::GetWrapDestination(HMONITOR fromMonitor, const POINT& cursorPos, EdgeType edgeType) const
+{
+    // Get monitor index for edge map lookup
+    int monitorIndex = GetMonitorIndex(fromMonitor);
+    if (monitorIndex < 0)
+    {
+        return cursorPos; // Monitor not found
+    }
+
+    auto it = m_edgeMap.find({monitorIndex, edgeType});
+    if (it == m_edgeMap.end())
+    {
+        return cursorPos; // Edge not found
+    }
+
+    const MonitorEdge& fromEdge = it->second;
+
+    // Calculate relative position on current edge (0.0 to 1.0)
+    double relativePos = GetRelativePosition(fromEdge,
+        (edgeType == EdgeType::Left || edgeType == EdgeType::Right) ? cursorPos.y : cursorPos.x);
+
+    // Find opposite outer edge
+    MonitorEdge oppositeEdge = FindOppositeOuterEdge(edgeType,
+        (edgeType == EdgeType::Left || edgeType == EdgeType::Right) ? cursorPos.y : cursorPos.x);
+
+    if (oppositeEdge.monitorIndex < 0)
+    {
+        // No opposite edge found, wrap within same monitor
+        RECT monitorRect;
+        if (GetMonitorRect(fromMonitor, monitorRect))
+        {
+            POINT result = cursorPos;
+            switch (edgeType)
+            {
+            case EdgeType::Left:
+                result.x = monitorRect.right - 2;
+                break;
+            case EdgeType::Right:
+                result.x = monitorRect.left + 1;
+                break;
+            case EdgeType::Top:
+                result.y = monitorRect.bottom - 2;
+                break;
+            case EdgeType::Bottom:
+                result.y = monitorRect.top + 1;
+                break;
+            }
+            return result;
+        }
+        return cursorPos;
+    }
+
+    // Calculate target position on opposite edge
+    POINT result;
+
+    if (edgeType == EdgeType::Left || edgeType == EdgeType::Right)
+    {
+        // Horizontal edge -> vertical movement
+        result.x = oppositeEdge.position;
+        result.y = GetAbsolutePosition(oppositeEdge, relativePos);
+    }
+    else
+    {
+        // Vertical edge -> horizontal movement
+        result.y = oppositeEdge.position;
+        result.x = GetAbsolutePosition(oppositeEdge, relativePos);
+    }
+
+    return result;
+}
+
+MonitorEdge MonitorTopology::FindOppositeOuterEdge(EdgeType fromEdge, int relativePosition) const
+{
+    EdgeType targetType;
+    bool findMax; // true = find max position, false = find min position
+
+    switch (fromEdge)
+    {
+    case EdgeType::Left:
+        targetType = EdgeType::Right;
+        findMax = true;
+        break;
+    case EdgeType::Right:
+        targetType = EdgeType::Left;
+        findMax = false;
+        break;
+    case EdgeType::Top:
+        targetType = EdgeType::Bottom;
+        findMax = true;
+        break;
+    case EdgeType::Bottom:
+        targetType = EdgeType::Top;
+        findMax = false;
+        break;
+    default:
+        return { .monitorIndex = -1 }; // Invalid edge type
+    }
+
+    MonitorEdge result = { .monitorIndex = -1 }; // -1 indicates not found
+    int extremePosition = findMax ? INT_MIN : INT_MAX;
+
+    for (const auto& edge : m_outerEdges)
+    {
+        if (edge.type != targetType)
+        {
+            continue;
+        }
+
+        // Check if this edge overlaps with the relative position
+        if (relativePosition >= edge.start && relativePosition <= edge.end)
+        {
+            if ((findMax && edge.position > extremePosition) ||
+                (!findMax && edge.position < extremePosition))
+            {
+                extremePosition = edge.position;
+                result = edge;
+            }
+        }
+    }
+
+    return result;
+}
+
+double MonitorTopology::GetRelativePosition(const MonitorEdge& edge, int coordinate) const
+{
+    if (edge.end == edge.start)
+    {
+        return 0.5; // Avoid division by zero
+    }
+
+    int clamped = max(edge.start, min(coordinate, edge.end));
+    // Use int64_t to avoid overflow warning C26451
+    int64_t numerator = static_cast<int64_t>(clamped) - static_cast<int64_t>(edge.start);
+    int64_t denominator = static_cast<int64_t>(edge.end) - static_cast<int64_t>(edge.start);
+    return static_cast<double>(numerator) / static_cast<double>(denominator);
+}
+
+int MonitorTopology::GetAbsolutePosition(const MonitorEdge& edge, double relativePosition) const
+{
+    // Use int64_t to prevent arithmetic overflow during subtraction and multiplication
+    int64_t range = static_cast<int64_t>(edge.end) - static_cast<int64_t>(edge.start);
+    int64_t offset = static_cast<int64_t>(relativePosition * static_cast<double>(range));
+    // Clamp result to int range before returning
+    int64_t result = static_cast<int64_t>(edge.start) + offset;
+    return static_cast<int>(result);
+}
+
+std::vector<MonitorTopology::GapInfo> MonitorTopology::DetectMonitorGaps() const
+{
+    std::vector<GapInfo> gaps;
+    const int gapThreshold = 50; // Same as ADJACENCY_TOLERANCE
+
+    // Check each pair of monitors
+    for (size_t i = 0; i < m_monitors.size(); ++i)
+    {
+        for (size_t j = i + 1; j < m_monitors.size(); ++j)
+        {
+            const auto& m1 = m_monitors[i];
+            const auto& m2 = m_monitors[j];
+
+            // Check vertical overlap
+            int vOverlapStart = max(m1.rect.top, m2.rect.top);
+            int vOverlapEnd = min(m1.rect.bottom, m2.rect.bottom);
+            int vOverlap = vOverlapEnd - vOverlapStart;
+
+            if (vOverlap <= 0)
+            {
+                continue; // No vertical overlap, skip
+            }
+
+            // Check horizontal gap
+            int hGap = min(abs(m1.rect.right - m2.rect.left), abs(m2.rect.right - m1.rect.left));
+
+            if (hGap > gapThreshold)
+            {
+                GapInfo gap;
+                gap.monitor1Index = static_cast<int>(i);
+                gap.monitor2Index = static_cast<int>(j);
+                gap.horizontalGap = hGap;
+                gap.verticalOverlap = vOverlap;
+                gaps.push_back(gap);
+            }
+        }
+    }
+
+    return gaps;
+}
+
+HMONITOR MonitorTopology::GetMonitorFromPoint(const POINT& pt) const
+{
+    return MonitorFromPoint(pt, MONITOR_DEFAULTTONEAREST);
+}
+
+bool MonitorTopology::GetMonitorRect(HMONITOR monitor, RECT& rect) const
+{
+    // First try direct HMONITOR comparison
+    for (const auto& monitorInfo : m_monitors)
+    {
+        if (monitorInfo.hMonitor == monitor)
+        {
+            rect = monitorInfo.rect;
+            return true;
+        }
+    }
+
+    // Fallback: If direct comparison fails, try matching by current monitor info
+    MONITORINFO mi{};
+    mi.cbSize = sizeof(MONITORINFO);
+    if (GetMonitorInfo(monitor, &mi))
+    {
+        for (const auto& monitorInfo : m_monitors)
+        {
+            if (monitorInfo.rect.left == mi.rcMonitor.left &&
+                monitorInfo.rect.top == mi.rcMonitor.top &&
+                monitorInfo.rect.right == mi.rcMonitor.right &&
+                monitorInfo.rect.bottom == mi.rcMonitor.bottom)
+            {
+                rect = monitorInfo.rect;
+                return true;
+            }
+        }
+    }
+    
+    return false;
+}
+
+HMONITOR MonitorTopology::GetMonitorFromRect(const RECT& rect) const
+{
+    return MonitorFromRect(&rect, MONITOR_DEFAULTTONEAREST);
+}
+
+int MonitorTopology::GetMonitorIndex(HMONITOR monitor) const
+{
+    // First try direct HMONITOR comparison (fast and accurate)
+    for (size_t i = 0; i < m_monitors.size(); ++i)
+    {
+        if (m_monitors[i].hMonitor == monitor)
+        {
+            return static_cast<int>(i);
+        }
+    }
+
+    // Fallback: If direct comparison fails (e.g., handle changed after display reconfiguration),
+    // try matching by position. Get the monitor's current rect and find matching stored rect.
+    MONITORINFO mi{};
+    mi.cbSize = sizeof(MONITORINFO);
+    if (GetMonitorInfo(monitor, &mi))
+    {
+        for (size_t i = 0; i < m_monitors.size(); ++i)
+        {
+            // Match by rect bounds
+            if (m_monitors[i].rect.left == mi.rcMonitor.left &&
+                m_monitors[i].rect.top == mi.rcMonitor.top &&
+                m_monitors[i].rect.right == mi.rcMonitor.right &&
+                m_monitors[i].rect.bottom == mi.rcMonitor.bottom)
+            {
+                Logger::trace(L"GetMonitorIndex: Found monitor {} via rect fallback (handle changed from {} to {})", 
+                    i, reinterpret_cast<uintptr_t>(m_monitors[i].hMonitor), reinterpret_cast<uintptr_t>(monitor));
+                return static_cast<int>(i);
+            }
+        }
+        
+        // Log all stored monitors vs the requested one for debugging
+        Logger::warn(L"GetMonitorIndex: No match found. Requested monitor rect=({},{},{},{})",
+            mi.rcMonitor.left, mi.rcMonitor.top, mi.rcMonitor.right, mi.rcMonitor.bottom);
+        for (size_t i = 0; i < m_monitors.size(); ++i)
+        {
+            Logger::warn(L"  Stored monitor {}: rect=({},{},{},{})",
+                i, m_monitors[i].rect.left, m_monitors[i].rect.top, 
+                m_monitors[i].rect.right, m_monitors[i].rect.bottom);
+        }
+    }
+    else
+    {
+        Logger::warn(L"GetMonitorIndex: GetMonitorInfo failed for handle {}", reinterpret_cast<uintptr_t>(monitor));
+    }
+
+    return -1; // Not found
+}
+

src/modules/MouseUtils/CursorWrap/MonitorTopology.h

@@ -0,0 +1,106 @@
+// Copyright (c) Microsoft Corporation
+// The Microsoft Corporation licenses this file to you under the MIT license.
+// See the LICENSE file in the project root for more information.
+
+#pragma once
+#include <windows.h>
+#include <vector>
+#include <map>
+
+// Monitor information structure
+struct MonitorInfo
+{
+    HMONITOR hMonitor; // Direct handle for accurate lookup after display changes
+    RECT rect;
+    bool isPrimary;
+    int monitorId;
+};
+
+// Edge type enumeration
+enum class EdgeType
+{
+    Left = 0,
+    Right = 1,
+    Top = 2,
+    Bottom = 3
+};
+
+// Wrap mode enumeration (matches Settings UI dropdown)
+enum class WrapMode
+{
+    Both = 0,           // Wrap in both directions
+    VerticalOnly = 1,   // Only wrap top/bottom
+    HorizontalOnly = 2  // Only wrap left/right
+};
+
+// Represents a single edge of a monitor
+struct MonitorEdge
+{
+    int monitorIndex;  // Index into m_monitors (stable across display changes)
+    EdgeType type;
+    int start;      // For vertical edges: Y start; horizontal: X start
+    int end;        // For vertical edges: Y end; horizontal: X end
+    int position;   // For vertical edges: X coord; horizontal: Y coord
+    bool isOuter;   // True if no adjacent monitor touches this edge
+};
+
+// Monitor topology helper - manages edge-based monitor layout
+struct MonitorTopology
+{
+    void Initialize(const std::vector<MonitorInfo>& monitors);
+
+    // Check if cursor is on an outer edge of the given monitor
+    // wrapMode filters which edges are considered (Both, VerticalOnly, HorizontalOnly)
+    bool IsOnOuterEdge(HMONITOR monitor, const POINT& cursorPos, EdgeType& outEdgeType, WrapMode wrapMode) const;
+
+    // Get the wrap destination point for a cursor on an outer edge
+    POINT GetWrapDestination(HMONITOR fromMonitor, const POINT& cursorPos, EdgeType edgeType) const;
+
+    // Get monitor at point (helper)
+    HMONITOR GetMonitorFromPoint(const POINT& pt) const;
+
+    // Get monitor rectangle (helper)
+    bool GetMonitorRect(HMONITOR monitor, RECT& rect) const;
+
+    // Get outer edges collection (for debugging)
+    const std::vector<MonitorEdge>& GetOuterEdges() const { return m_outerEdges; }
+
+    // Detect gaps between monitors that should be snapped together
+    struct GapInfo {
+        int monitor1Index;
+        int monitor2Index;
+        int horizontalGap;
+        int verticalOverlap;
+    };
+    std::vector<GapInfo> DetectMonitorGaps() const;
+
+private:
+    std::vector<MonitorInfo> m_monitors;
+    std::vector<MonitorEdge> m_outerEdges;
+
+    // Map from (monitor index, edge type) to edge info
+    // Using monitor index instead of HMONITOR because HMONITOR handles can change
+    // when monitors are added/removed dynamically
+    std::map<std::pair<int, EdgeType>, MonitorEdge> m_edgeMap;
+
+    // Helper to resolve HMONITOR to monitor index at runtime
+    int GetMonitorIndex(HMONITOR monitor) const;
+
+    // Helper to get consistent HMONITOR from RECT
+    HMONITOR GetMonitorFromRect(const RECT& rect) const;
+    
+    void BuildEdgeMap();
+    void IdentifyOuterEdges();
+
+    // Check if two edges are adjacent (within tolerance)
+    bool EdgesAreAdjacent(const MonitorEdge& edge1, const MonitorEdge& edge2, int tolerance = 50) const;
+
+    // Find the opposite outer edge for wrapping
+    MonitorEdge FindOppositeOuterEdge(EdgeType fromEdge, int relativePosition) const;
+
+    // Calculate relative position along an edge (0.0 to 1.0)
+    double GetRelativePosition(const MonitorEdge& edge, int coordinate) const;
+
+    // Convert relative position to absolute coordinate on target edge
+    int GetAbsolutePosition(const MonitorEdge& edge, double relativePosition) const;
+};

src/modules/alwaysontop/AlwaysOnTop/AlwaysOnTop.cpp

@@ -153,21 +153,9 @@ LRESULT AlwaysOnTop::WndProc(HWND window, UINT message, WPARAM wparam, LPARAM lp
 {
     if (message == WM_HOTKEY)
     {
-        int hotkeyId = static_cast<int>(wparam);
         if (HWND fw{ GetForegroundWindow() })
         {
-            if (hotkeyId == static_cast<int>(HotkeyId::Pin))
-            {
-                ProcessCommand(fw);
-            }
-            else if (hotkeyId == static_cast<int>(HotkeyId::IncreaseOpacity))
-            {
-                AdjustTransparency(fw, Settings::transparencyStep);
-            }
-            else if (hotkeyId == static_cast<int>(HotkeyId::DecreaseOpacity))
-            {
-                AdjustTransparency(fw, -Settings::transparencyStep);
-            }
+            ProcessCommand(fw);
         }
     }
     else if (message == WM_PRIV_SETTINGS_CHANGED)
@@ -203,11 +191,6 @@ void AlwaysOnTop::ProcessCommand(HWND window)
                 m_topmostWindows.erase(iter);
             }
 
-            // Restore transparency when unpinning
-            RemoveTransparency(window);
-            m_windowOriginalLayeredState.erase(window);
-            m_windowTransparency.erase(window);
-
             Trace::AlwaysOnTop::UnpinWindow();
         }
     }
@@ -217,7 +200,6 @@ void AlwaysOnTop::ProcessCommand(HWND window)
         {
             soundType = Sound::Type::On;
             AssignBorder(window);
-            
             Trace::AlwaysOnTop::PinWindow();
         }
     }
@@ -287,22 +269,11 @@ void AlwaysOnTop::RegisterHotkey() const
 {
     if (m_useCentralizedLLKH)
     {
-        // All hotkeys are handled by centralized LLKH
         return;
     }
 
-    // Register hotkeys only when not using centralized LLKH
     UnregisterHotKey(m_window, static_cast<int>(HotkeyId::Pin));
-    UnregisterHotKey(m_window, static_cast<int>(HotkeyId::IncreaseOpacity));
-    UnregisterHotKey(m_window, static_cast<int>(HotkeyId::DecreaseOpacity));
-
-    // Register pin hotkey
     RegisterHotKey(m_window, static_cast<int>(HotkeyId::Pin), AlwaysOnTopSettings::settings().hotkey.get_modifiers(), AlwaysOnTopSettings::settings().hotkey.get_code());
-
-    // Register transparency hotkeys using the same modifiers as the pin hotkey
-    UINT modifiers = AlwaysOnTopSettings::settings().hotkey.get_modifiers();
-    RegisterHotKey(m_window, static_cast<int>(HotkeyId::IncreaseOpacity), modifiers, VK_OEM_PLUS);
-    RegisterHotKey(m_window, static_cast<int>(HotkeyId::DecreaseOpacity), modifiers, VK_OEM_MINUS);
 }
 
 void AlwaysOnTop::RegisterLLKH()
@@ -314,8 +285,6 @@ void AlwaysOnTop::RegisterLLKH()
 	
     m_hPinEvent = CreateEventW(nullptr, false, false, CommonSharedConstants::ALWAYS_ON_TOP_PIN_EVENT);
     m_hTerminateEvent = CreateEventW(nullptr, false, false, CommonSharedConstants::ALWAYS_ON_TOP_TERMINATE_EVENT);
-    m_hIncreaseOpacityEvent = CreateEventW(nullptr, false, false, CommonSharedConstants::ALWAYS_ON_TOP_INCREASE_OPACITY_EVENT);
-    m_hDecreaseOpacityEvent = CreateEventW(nullptr, false, false, CommonSharedConstants::ALWAYS_ON_TOP_DECREASE_OPACITY_EVENT);
 
     if (!m_hPinEvent)
     {
@@ -329,54 +298,30 @@ void AlwaysOnTop::RegisterLLKH()
         return;
     }
 
-    if (!m_hIncreaseOpacityEvent)
-    {
-        Logger::warn(L"Failed to create increaseOpacityEvent. {}", get_last_error_or_default(GetLastError()));
-    }
-
-    if (!m_hDecreaseOpacityEvent)
-    {
-        Logger::warn(L"Failed to create decreaseOpacityEvent. {}", get_last_error_or_default(GetLastError()));
-    }
-
-    HANDLE handles[4] = { m_hPinEvent,
-                          m_hTerminateEvent,
-                          m_hIncreaseOpacityEvent,
-                          m_hDecreaseOpacityEvent };
+    HANDLE handles[2] = { m_hPinEvent,
+                          m_hTerminateEvent };
 
     m_thread = std::thread([this, handles]() {
         MSG msg;
         while (m_running)
         {
-            DWORD dwEvt = MsgWaitForMultipleObjects(4, handles, false, INFINITE, QS_ALLINPUT);
+            DWORD dwEvt = MsgWaitForMultipleObjects(2, handles, false, INFINITE, QS_ALLINPUT);
             if (!m_running)
             {
                 break;
             }
             switch (dwEvt)
             {
-            case WAIT_OBJECT_0: // Pin event
+            case WAIT_OBJECT_0:
                 if (HWND fw{ GetForegroundWindow() })
                 {
                     ProcessCommand(fw);
                 }
                 break;
-            case WAIT_OBJECT_0 + 1: // Terminate event
+            case WAIT_OBJECT_0 + 1:
                 PostThreadMessage(m_mainThreadId, WM_QUIT, 0, 0);
                 break;
-            case WAIT_OBJECT_0 + 2: // Increase opacity event
-                if (HWND fw{ GetForegroundWindow() })
-                {
-                    AdjustTransparency(fw, Settings::transparencyStep);
-                }
-                break;
-            case WAIT_OBJECT_0 + 3: // Decrease opacity event
-                if (HWND fw{ GetForegroundWindow() })
-                {
-                    AdjustTransparency(fw, -Settings::transparencyStep);
-                }
-                break;
-            case WAIT_OBJECT_0 + 4: // Message queue
+            case WAIT_OBJECT_0 + 2:
                 if (PeekMessageW(&msg, nullptr, 0, 0, PM_REMOVE))
                 {
                     TranslateMessage(&msg);
@@ -425,13 +370,9 @@ void AlwaysOnTop::UnpinAll()
         {
             Logger::error(L"Unpinning topmost window failed");
         }
-        // Restore transparency when unpinning all
-        RemoveTransparency(topWindow);
     }
 
     m_topmostWindows.clear();
-    m_windowTransparency.clear();
-    m_windowOriginalLayeredState.clear();
 }
 
 void AlwaysOnTop::CleanUp()
@@ -515,8 +456,6 @@ void AlwaysOnTop::HandleWinHookEvent(WinHookEvent* data) noexcept
     for (const auto window : toErase)
     {
         m_topmostWindows.erase(window);
-        m_windowTransparency.erase(window);
-        m_windowOriginalLayeredState.erase(window);
     }
 
     switch (data->event)
@@ -617,182 +556,4 @@ void AlwaysOnTop::RefreshBorders()
             }
         }
     }
-}
-
-// Transparency adjustment methods
-HWND AlwaysOnTop::GetTransparencyTarget(HWND window)
-{
-    if (!window || !IsWindow(window))
-    {
-        return nullptr;
-    }
-
-    // Only allow transparency adjustment on tracked/pinned windows
-    if (!IsTracked(window) && !IsPinned(window))
-    {
-        return nullptr;
-    }
-
-    // Use GA_ROOTOWNER to get the root owner window
-    HWND targetWindow = GetAncestor(window, GA_ROOTOWNER);
-    if (!targetWindow)
-    {
-        targetWindow = window;
-    }
-
-    // Filter out desktop, shell, invisible windows
-    if (targetWindow == GetDesktopWindow() || targetWindow == GetShellWindow())
-    {
-        return nullptr;
-    }
-    if (!IsWindowVisible(targetWindow))
-    {
-        return nullptr;
-    }
-
-    return targetWindow;
-}
-
-void AlwaysOnTop::AdjustTransparency(HWND window, int delta)
-{
-    HWND targetWindow = GetTransparencyTarget(window);
-    if (!targetWindow)
-    {
-        return;
-    }
-
-    auto it = m_windowTransparency.find(targetWindow);
-    int currentTransparency = (it != m_windowTransparency.end()) ? it->second : Settings::maxTransparencyPercentage;
-    int newTransparency = (std::max)(Settings::minTransparencyPercentage, 
-                                     (std::min)(Settings::maxTransparencyPercentage, currentTransparency + delta));
-
-    if (newTransparency != currentTransparency)
-    {
-        SetTransparency(targetWindow, newTransparency);
-
-        if (AlwaysOnTopSettings::settings().enableSound)
-        {
-            m_sound.Play(delta > 0 ? Sound::Type::IncreaseOpacity : Sound::Type::DecreaseOpacity);
-        }
-
-        Logger::trace(L"Transparency adjusted to {}%", newTransparency);
-    }
-}
-
-void AlwaysOnTop::SetTransparency(HWND window, int percentage)
-{
-    if (!window || !IsWindow(window))
-    {
-        return;
-    }
-    
-    percentage = (std::max)(Settings::minTransparencyPercentage, 
-                            (std::min)(Settings::maxTransparencyPercentage, percentage));
-
-    m_windowTransparency[window] = percentage;
-
-    if (percentage == Settings::maxTransparencyPercentage)
-    {
-        RemoveTransparency(window);
-        return;
-    }
-
-    LONG exStyle = GetWindowLong(window, GWL_EXSTYLE);
-    bool isCurrentlyLayered = (exStyle & WS_EX_LAYERED) != 0;
-
-    // Cache original state on first transparency application
-    if (m_windowOriginalLayeredState.find(window) == m_windowOriginalLayeredState.end())
-    {
-        WindowLayeredState state;
-        state.hadLayeredStyle = isCurrentlyLayered;
-        
-        if (isCurrentlyLayered)
-        {
-            BYTE alpha = 255;
-            COLORREF colorKey = 0;
-            DWORD flags = 0;
-            if (GetLayeredWindowAttributes(window, &colorKey, &alpha, &flags))
-            {
-                state.originalAlpha = alpha;
-                state.usedColorKey = (flags & LWA_COLORKEY) != 0;
-                state.colorKey = colorKey;
-            }
-            else
-            {
-                Logger::warn(L"GetLayeredWindowAttributes failed for layered window, skipping");
-                return;
-            }
-        }
-        m_windowOriginalLayeredState[window] = state;
-    }
-
-    // Clear WS_EX_LAYERED first to ensure SetLayeredWindowAttributes works
-    if (isCurrentlyLayered)
-    {
-        SetWindowLong(window, GWL_EXSTYLE, exStyle & ~WS_EX_LAYERED);
-        SetWindowPos(window, nullptr, 0, 0, 0, 0, SWP_NOMOVE | SWP_NOSIZE | SWP_NOZORDER | SWP_FRAMECHANGED);
-        exStyle = GetWindowLong(window, GWL_EXSTYLE);
-    }
-
-    BYTE alphaValue = static_cast<BYTE>((255 * percentage) / 100);
-    SetWindowLong(window, GWL_EXSTYLE, exStyle | WS_EX_LAYERED);
-    SetLayeredWindowAttributes(window, 0, alphaValue, LWA_ALPHA);
-}
-
-void AlwaysOnTop::RemoveTransparency(HWND window)
-{
-    if (!window || !IsWindow(window))
-    {
-        return;
-    }
-
-    LONG exStyle = GetWindowLong(window, GWL_EXSTYLE);
-    auto it = m_windowOriginalLayeredState.find(window);
-    
-    if (it != m_windowOriginalLayeredState.end())
-    {
-        const auto& originalState = it->second;
-        
-        if (originalState.hadLayeredStyle)
-        {
-            // Window originally had WS_EX_LAYERED - restore original attributes
-            // Clear and re-add to ensure clean state
-            if (exStyle & WS_EX_LAYERED)
-            {
-                SetWindowLong(window, GWL_EXSTYLE, exStyle & ~WS_EX_LAYERED);
-                exStyle = GetWindowLong(window, GWL_EXSTYLE);
-            }
-            SetWindowLong(window, GWL_EXSTYLE, exStyle | WS_EX_LAYERED);
-            
-            // Restore original alpha and/or color key
-            DWORD flags = LWA_ALPHA;
-            if (originalState.usedColorKey)
-            {
-                flags |= LWA_COLORKEY;
-            }
-            SetLayeredWindowAttributes(window, originalState.colorKey, originalState.originalAlpha, flags);
-            SetWindowPos(window, nullptr, 0, 0, 0, 0, SWP_NOMOVE | SWP_NOSIZE | SWP_NOZORDER | SWP_FRAMECHANGED);
-        }
-        else
-        {
-            // Window originally didn't have WS_EX_LAYERED - remove it completely
-            if (exStyle & WS_EX_LAYERED)
-            {
-                SetLayeredWindowAttributes(window, 0, 255, LWA_ALPHA);
-                SetWindowLong(window, GWL_EXSTYLE, exStyle & ~WS_EX_LAYERED);
-                SetWindowPos(window, nullptr, 0, 0, 0, 0, SWP_NOMOVE | SWP_NOSIZE | SWP_NOZORDER | SWP_FRAMECHANGED);
-            }
-        }
-        
-        m_windowOriginalLayeredState.erase(it);
-    }
-    else
-    {
-        // Fallback: no cached state, just remove layered style
-        if (exStyle & WS_EX_LAYERED)
-        {
-            SetLayeredWindowAttributes(window, 0, 255, LWA_ALPHA);
-            SetWindowLong(window, GWL_EXSTYLE, exStyle & ~WS_EX_LAYERED);
-        }
-    }
 }

src/modules/alwaysontop/AlwaysOnTop/AlwaysOnTop.h

@@ -10,7 +10,6 @@
 
 #include <common/hooks/WinHookEvent.h>
 #include <common/notifications/NotificationUtil.h>
-#include <common/utils/window.h>
 
 class AlwaysOnTop : public SettingsObserver
 {
@@ -39,8 +38,6 @@ private:
     enum class HotkeyId : int
     {
         Pin = 1,
-        IncreaseOpacity = 2,
-        DecreaseOpacity = 3,
     };
 
     static inline AlwaysOnTop* s_instance = nullptr;
@@ -51,21 +48,8 @@ private:
     HWND m_window{ nullptr };
     HINSTANCE m_hinstance;
     std::map<HWND, std::unique_ptr<WindowBorder>> m_topmostWindows{};
-    std::map<HWND, int> m_windowTransparency{}; // Track transparency per window (20-100)
-    
-    // Store original window layered state for proper restoration
-    struct WindowLayeredState {
-        bool hadLayeredStyle = false;
-        BYTE originalAlpha = 255;
-        bool usedColorKey = false;
-        COLORREF colorKey = 0;
-    };
-    std::map<HWND, WindowLayeredState> m_windowOriginalLayeredState{};
-    
     HANDLE m_hPinEvent;
     HANDLE m_hTerminateEvent;
-    HANDLE m_hIncreaseOpacityEvent;
-    HANDLE m_hDecreaseOpacityEvent;
     DWORD m_mainThreadId;
     std::thread m_thread;
     const bool m_useCentralizedLLKH;
@@ -94,12 +78,6 @@ private:
     bool AssignBorder(HWND window);
     void RefreshBorders();
 
-    // Transparency methods
-    HWND GetTransparencyTarget(HWND window);
-    void AdjustTransparency(HWND window, int delta);
-    void SetTransparency(HWND window, int percentage);
-    void RemoveTransparency(HWND window);
-
     virtual void SettingsUpdate(SettingId type) override;
 
     static void CALLBACK WinHookProc(HWINEVENTHOOK winEventHook,

src/modules/cmdpal/Core/Microsoft.CmdPal.Core.ViewModels/ContextMenuViewModel.cs

@@ -53,7 +53,7 @@ public partial class ContextMenuViewModel : ObservableObject,
     {
         if (SelectedItem is not null)
         {
-            if (SelectedItem.MoreCommands.Count() > 1)
+            if (SelectedItem.PrimaryCommand is not null || SelectedItem.HasMoreCommands)
             {
                 ContextMenuStack.Clear();
                 PushContextStack(SelectedItem.AllCommands);

src/modules/cmdpal/ExtensionTemplate/TemplateCmdPalExtension/Directory.Packages.props

@@ -5,12 +5,12 @@
   <ItemGroup>
     <PackageVersion Include="Microsoft.CommandPalette.Extensions" Version="0.5.250829002" />
     <PackageVersion Include="Microsoft.CodeAnalysis.NetAnalyzers" Version="9.0.0-preview.24508.2" />
-    <PackageVersion Include="Microsoft.Web.WebView2" Version="1.0.3405.78" />
+    <PackageVersion Include="Microsoft.Web.WebView2" Version="1.0.2903.40" />
     <PackageVersion Include="Microsoft.Windows.CsWin32" Version="0.3.183" />
     <PackageVersion Include="Microsoft.Windows.CsWinRT" Version="2.2.0" />
     <PackageVersion Include="Microsoft.Windows.SDK.BuildTools" Version="10.0.26100.4188" />
     <PackageVersion Include="Microsoft.Windows.SDK.BuildTools.MSIX" Version="1.7.20250829.1" />
-    <PackageVersion Include="Microsoft.WindowsAppSDK" Version="2.0.0-experimental3" />
+    <PackageVersion Include="Microsoft.WindowsAppSDK" Version="1.8.250907003" />
     <PackageVersion Include="Shmuelie.WinRTServer" Version="2.1.1" />
     <PackageVersion Include="StyleCop.Analyzers" Version="1.2.0-beta.556" />
     <PackageVersion Include="System.Text.Json" Version="9.0.8" />

src/modules/cmdpal/Microsoft.CmdPal.Ext.PowerToys.slnf

@@ -0,0 +1,26 @@
+{
+  "solution": {
+    "path": "..\\..\\..\\PowerToys.slnx",
+    "projects": [
+      "src\\common\\Common.Search\\Common.Search.csproj",
+      "src\\common\\Common.UI\\Common.UI.csproj",
+      "src\\common\\ManagedCommon\\ManagedCommon.csproj",
+      "src\\common\\ManagedTelemetry\\Telemetry\\ManagedTelemetry.csproj",
+      "src\\common\\PowerToys.ModuleContracts\\PowerToys.ModuleContracts.csproj",
+      "src\\common\\SettingsAPI\\SettingsAPI.vcxproj",
+      "src\\common\\interop\\PowerToys.Interop.vcxproj",
+      "src\\common\\logger\\logger.vcxproj",
+      "src\\common\\version\\version.vcxproj",
+      "src\\logging\\logging.vcxproj",
+      "src\\modules\\MouseUtils\\MouseJump.Common\\MouseJump.Common.csproj",
+      "src\\modules\\Workspaces\\Workspaces.ModuleServices\\Workspaces.ModuleServices.csproj",
+      "src\\modules\\Workspaces\\WorkspacesCsharpLibrary\\WorkspacesCsharpLibrary.csproj",
+      "src\\modules\\ZoomIt\\ZoomItSettingsInterop\\ZoomItSettingsInterop.vcxproj",
+      "src\\modules\\awake\\Awake.ModuleServices\\Awake.ModuleServices.csproj",
+      "src\\modules\\cmdpal\\ext\\Microsoft.CmdPal.Ext.PowerToys\\Microsoft.CmdPal.Ext.PowerToys.csproj",
+      "src\\modules\\colorPicker\\ColorPicker.ModuleServices\\ColorPicker.ModuleServices.csproj",
+      "src\\modules\\fancyzones\\FancyZonesEditorCommon\\FancyZonesEditorCommon.csproj",
+      "src\\settings-ui\\Settings.UI.Library\\Settings.UI.Library.csproj"
+    ]
+  }
+}

src/modules/cmdpal/Microsoft.CmdPal.UI/Controls/CommandBar.xaml.cs

@@ -44,13 +44,14 @@ public sealed partial class CommandBar : UserControl,
 
     public void Receive(OpenContextMenuMessage message)
     {
-        if (!ViewModel.ShouldShowContextMenu)
-        {
-            return;
-        }
-
         if (message.Element is null)
         {
+            // This is invoked from the "More" button on the command bar
+            if (!ViewModel.ShouldShowContextMenu)
+            {
+                return;
+            }
+
             _ = DispatcherQueue.TryEnqueue(
                 () =>
                 {
@@ -65,6 +66,7 @@ public sealed partial class CommandBar : UserControl,
         }
         else
         {
+            // This is invoked from a specific element
             _ = DispatcherQueue.TryEnqueue(
             () =>
             {

src/modules/cmdpal/ext/Microsoft.CmdPal.Ext.Apps/AppListItem.cs

@@ -17,12 +17,25 @@ public sealed partial class AppListItem : ListItem
 {
     private readonly AppCommand _appCommand;
     private readonly AppItem _app;
-    private readonly Lazy<Details> _details;
     private readonly Lazy<Task<IconInfo?>> _iconLoadTask;
+    private readonly Lazy<Task<Details>> _detailsLoadTask;
 
     private InterlockedBoolean _isLoadingIcon;
+    private InterlockedBoolean _isLoadingDetails;
 
-    public override IDetails? Details { get => _details.Value; set => base.Details = value; }
+    public override IDetails? Details
+    {
+        get
+        {
+            if (_isLoadingDetails.Set())
+            {
+                _ = LoadDetailsAsync();
+            }
+
+            return base.Details;
+        }
+        set => base.Details = value;
+    }
 
     public override IIconInfo? Icon
     {
@@ -52,16 +65,22 @@ public sealed partial class AppListItem : ListItem
 
         MoreCommands = AddPinCommands(_app.Commands!, isPinned);
 
-        _details = new Lazy<Details>(() =>
-        {
-            var t = BuildDetails();
-            t.Wait();
-            return t.Result;
-        });
-
+        _detailsLoadTask = new Lazy<Task<Details>>(BuildDetails);
         _iconLoadTask = new Lazy<Task<IconInfo?>>(async () => await FetchIcon(useThumbnails));
     }
 
+    private async Task LoadDetailsAsync()
+    {
+        try
+        {
+            Details = await _detailsLoadTask.Value;
+        }
+        catch (Exception ex)
+        {
+            Logger.LogWarning($"Failed to load details for {AppIdentifier}\n{ex}");
+        }
+    }
+
     private async Task LoadIconAsync()
     {
         try

src/modules/cmdpal/ext/Microsoft.CmdPal.Ext.Apps/Commands/RunAsAdminCommand.cs

@@ -4,6 +4,7 @@
 
 using System;
 using System.Diagnostics;
+using System.IO;
 using System.Threading.Tasks;
 using Microsoft.CmdPal.Ext.Apps.Properties;
 using Microsoft.CmdPal.Ext.Apps.Utils;
@@ -33,6 +34,7 @@ internal sealed partial class RunAsAdminCommand : InvokableCommand
         {
             if (packaged)
             {
+                // For UWP/packaged apps, use shell:AppsFolder which works from packaged context
                 var command = "shell:AppsFolder\\" + target;
                 command = Environment.ExpandEnvironmentVariables(command.Trim());
 
@@ -43,9 +45,37 @@ internal sealed partial class RunAsAdminCommand : InvokableCommand
             }
             else
             {
-                var info = ShellCommand.GetProcessStartInfo(target, parentDir, string.Empty, ShellCommand.RunAsType.Administrator);
+                // For Win32 apps, use ActionRunner helper process to work around WinUI3/MSIX packaging limitation.
+                // When running from a packaged app, ShellExecute with "runas" verb may fail for certain apps
+                // (e.g., apps launched via .lnk shortcuts). ActionRunner runs outside the MSIX container,
+                // so it can properly invoke the UAC dialog.
+                var actionRunnerPath = ActionRunnerHelper.GetActionRunnerPath();
 
-                Process.Start(info);
+                if (string.IsNullOrEmpty(actionRunnerPath))
+                {
+                    // Fallback to direct Process.Start if ActionRunner is not found
+                    ExtensionHost.LogMessage($"ActionRunner not found, falling back to direct Process.Start for '{target}'");
+                    var info = ShellCommand.GetProcessStartInfo(target, parentDir, string.Empty, ShellCommand.RunAsType.Administrator);
+                    Process.Start(info);
+                    return;
+                }
+
+                var args = $"-run-as-admin -target \"{target}\"";
+                if (!string.IsNullOrEmpty(parentDir))
+                {
+                    args += $" -workingDir \"{parentDir}\"";
+                }
+
+                var processInfo = new ProcessStartInfo
+                {
+                    FileName = actionRunnerPath,
+                    Arguments = args,
+                    UseShellExecute = false,
+                    CreateNoWindow = true,
+                };
+
+                ExtensionHost.LogMessage($"Launching '{target}' as administrator via ActionRunner");
+                Process.Start(processInfo);
             }
         });
     }

src/modules/cmdpal/ext/Microsoft.CmdPal.Ext.Apps/Commands/RunAsUserCommand.cs

@@ -4,6 +4,7 @@
 
 using System;
 using System.Diagnostics;
+using System.IO;
 using System.Threading.Tasks;
 using Microsoft.CmdPal.Ext.Apps.Properties;
 using Microsoft.CmdPal.Ext.Apps.Utils;
@@ -29,9 +30,38 @@ internal sealed partial class RunAsUserCommand : InvokableCommand
     {
         await Task.Run(() =>
         {
-            var info = ShellCommand.GetProcessStartInfo(target, parentDir, string.Empty, ShellCommand.RunAsType.OtherUser);
+            // Use ActionRunner helper process to work around WinUI3/MSIX packaging limitation.
+            // When running from a packaged app, ShellExecute with the "runas user" verb causes
+            // CredentialUIBroker.exe to spawn infinitely without showing the credential dialog.
+            // ActionRunner runs outside the MSIX container, so it can properly invoke the credential UI.
+            var actionRunnerPath = ActionRunnerHelper.GetActionRunnerPath();
 
-            Process.Start(info);
+            if (string.IsNullOrEmpty(actionRunnerPath))
+            {
+                // Fallback to direct Process.Start if ActionRunner is not found
+                // This may not work in packaged context, but provides a fallback for development
+                ExtensionHost.LogMessage($"ActionRunner not found, falling back to direct Process.Start for '{target}'");
+                var info = ShellCommand.GetProcessStartInfo(target, parentDir, string.Empty, ShellCommand.RunAsType.OtherUser);
+                Process.Start(info);
+                return;
+            }
+
+            var args = $"-run-as-user -target \"{target}\"";
+            if (!string.IsNullOrEmpty(parentDir))
+            {
+                args += $" -workingDir \"{parentDir}\"";
+            }
+
+            var processInfo = new ProcessStartInfo
+            {
+                FileName = actionRunnerPath,
+                Arguments = args,
+                UseShellExecute = false,
+                CreateNoWindow = true,
+            };
+
+            ExtensionHost.LogMessage($"Launching '{target}' as different user via ActionRunner");
+            Process.Start(processInfo);
         });
     }
 

src/modules/cmdpal/ext/Microsoft.CmdPal.Ext.Apps/Utils/ActionRunnerHelper.cs

@@ -0,0 +1,53 @@
+// Copyright (c) Microsoft Corporation
+// The Microsoft Corporation licenses this file to you under the MIT license.
+// See the LICENSE file in the project root for more information.
+
+using System.IO;
+using ManagedCommon;
+
+namespace Microsoft.CmdPal.Ext.Apps.Utils;
+
+/// <summary>
+/// Helper class to locate and invoke the PowerToys ActionRunner executable.
+/// ActionRunner is used to work around WinUI3/MSIX packaging limitations where
+/// certain shell operations (like "Run as different user" or "Run as administrator")
+/// don't work properly from within a packaged app context.
+/// </summary>
+internal static class ActionRunnerHelper
+{
+    private const string ActionRunnerExeName = "PowerToys.ActionRunner.exe";
+
+    private static string? _cachedPath;
+
+    /// <summary>
+    /// Gets the path to the ActionRunner executable.
+    /// </summary>
+    /// <returns>The full path to ActionRunner.exe, or null if not found.</returns>
+    public static string? GetActionRunnerPath()
+    {
+        if (_cachedPath != null)
+        {
+            return _cachedPath;
+        }
+
+        _cachedPath = FindActionRunnerPath();
+        return _cachedPath;
+    }
+
+    private static string? FindActionRunnerPath()
+    {
+        // Use the standard PowerToys path resolver to find the installation directory.
+        // This handles registry lookups for installed versions and debug builds correctly.
+        var installPath = PowerToysPathResolver.GetPowerToysInstallPath();
+        if (!string.IsNullOrEmpty(installPath))
+        {
+            var actionRunnerPath = Path.Combine(installPath, ActionRunnerExeName);
+            if (File.Exists(actionRunnerPath))
+            {
+                return actionRunnerPath;
+            }
+        }
+
+        return null;
+    }
+}

src/modules/peek/Peek.UI/PeekXAML/MainWindow.xaml.cs

@@ -197,16 +197,10 @@ namespace Peek.UI
 
             ViewModel.Initialize(selectedItem);
 
-            // If no files were found (e.g., in virtual folders like Home/Recent), show an error
+            // If no files were found (e.g., user is typing in rename/search box, or in virtual folders),
+            // don't show anything - just return silently to avoid stealing focus
             if (ViewModel.CurrentItem == null)
             {
-                Logger.LogInfo("Peek: No files found to preview, showing error.");
-                var errorMessage = ResourceLoaderInstance.ResourceLoader.GetString("NoFilesSelected");
-                ViewModel.ShowError(errorMessage);
-
-                // Still show the window so user can see the warning
-                this.Show();
-                WindowHelpers.BringToForeground(this.GetWindowHandle());
                 return;
             }
 

src/modules/powerrename/lib/PowerRenameRegEx.cpp

@@ -33,23 +33,27 @@ static std::wstring SanitizeAndNormalize(const std::wstring& input)
 
     // Normalize to NFC (Precomposed).
     // Get the size needed for the normalized string, including null terminator.
-    int size = NormalizeString(NormalizationC, sanitized.c_str(), -1, nullptr, 0);
-    if (size <= 0)
+    int sizeEstimate = NormalizeString(NormalizationC, sanitized.c_str(), -1, nullptr, 0);
+    if (sizeEstimate <= 0)
     {
         return sanitized; // Return unaltered if normalization fails.
     }
 
     // Perform the normalization.
     std::wstring normalized;
-    normalized.resize(size);
-    NormalizeString(NormalizationC, sanitized.c_str(), -1, &normalized[0], size);
+    normalized.resize(sizeEstimate);
+    int actualSize = NormalizeString(NormalizationC, sanitized.c_str(), -1, &normalized[0], sizeEstimate);
 
-    // Remove the explicit null terminator added by NormalizeString.
-    if (!normalized.empty() && normalized.back() == L'\0')
+    if (actualSize <= 0)
     {
-        normalized.pop_back();
+        // Normalization failed, return sanitized string.
+        return sanitized;
     }
 
+    // Resize to actual size minus the null terminator.
+    // actualSize includes the null terminator when input length is -1.
+    normalized.resize(static_cast<size_t>(actualSize) - 1);
+
     return normalized;
 }
 

src/modules/powerrename/unittests/CommonRegExTests.h

@@ -695,6 +695,38 @@ TEST_METHOD(VerifyUnicodeAndWhitespaceNormalizationRegex)
     VerifyNormalizationHelper(UseRegularExpressions);
 }
 
+TEST_METHOD(VerifyRegexMetacharacterDollarSign)
+{
+    CComPtr<IPowerRenameRegEx> renameRegEx;
+    Assert::IsTrue(CPowerRenameRegEx::s_CreateInstance(&renameRegEx) == S_OK);
+    DWORD flags = UseRegularExpressions;
+    Assert::IsTrue(renameRegEx->PutFlags(flags) == S_OK);
+
+    PWSTR result = nullptr;
+    Assert::IsTrue(renameRegEx->PutSearchTerm(L"$") == S_OK);
+    Assert::IsTrue(renameRegEx->PutReplaceTerm(L"_end") == S_OK);
+    unsigned long index = {};
+    Assert::IsTrue(renameRegEx->Replace(L"test.txt", &result, index) == S_OK);
+    Assert::AreEqual(L"test.txt_end", result);
+    CoTaskMemFree(result);
+}
+
+TEST_METHOD(VerifyRegexMetacharacterCaret)
+{
+    CComPtr<IPowerRenameRegEx> renameRegEx;
+    Assert::IsTrue(CPowerRenameRegEx::s_CreateInstance(&renameRegEx) == S_OK);
+    DWORD flags = UseRegularExpressions;
+    Assert::IsTrue(renameRegEx->PutFlags(flags) == S_OK);
+
+    PWSTR result = nullptr;
+    Assert::IsTrue(renameRegEx->PutSearchTerm(L"^") == S_OK);
+    Assert::IsTrue(renameRegEx->PutReplaceTerm(L"start_") == S_OK);
+    unsigned long index = {};
+    Assert::IsTrue(renameRegEx->Replace(L"test.txt", &result, index) == S_OK);
+    Assert::AreEqual(L"start_test.txt", result);
+    CoTaskMemFree(result);
+}
+
 #ifndef TESTS_PARTIAL
 };
 }

src/runner/ActionRunnerUtils.h

@@ -6,4 +6,6 @@
 namespace cmdArg
 {
     const inline wchar_t* RUN_NONELEVATED = L"-run-non-elevated";
+    const inline wchar_t* RUN_AS_USER = L"-run-as-user";
+    const inline wchar_t* RUN_AS_ADMIN = L"-run-as-admin";
 }

src/runner/Resources.resx

@@ -173,6 +173,10 @@
     <value>Settings\tDouble-click</value>
     <comment>Don't localize "\t" as that is what separates the click portion to be right aligned in the menu.</comment>
   </data>
+  <data name="SETTINGS_MENU_TEXT_LEFTCLICK" xml:space="preserve">
+    <value>Settings\tLeft-click</value>
+    <comment>Don't localize "\t" as that is what separates the click portion to be right aligned in the menu. This is shown when Quick Access is disabled.</comment>
+  </data>
   <data name="DOCUMENTATION_MENU_TEXT" xml:space="preserve">
     <value>Documentation</value>
   </data>

src/runner/settings_window.cpp

@@ -3,7 +3,6 @@
 #include <Sddl.h>
 #include <sstream>
 #include <aclapi.h>
-#include <shobjidl.h>
 
 #include "powertoy_module.h"
 #include <common/interop/two_way_pipe_message_ipc.h>
@@ -65,74 +64,6 @@ json::JsonObject get_all_settings()
     return result;
 }
 
-namespace
-{
-    constexpr wchar_t SettingsApplicationId[] = L"PowerToys.SettingsUI";
-    constexpr wchar_t SparseAppFamilyDev[] = L"Microsoft.PowerToys.SparseApp_djwsxzxb4ksa8";
-    constexpr wchar_t SparseAppFamilyStore[] = L"Microsoft.PowerToys.SparseApp_8wekyb3d8bbwe";
-
-    bool try_activate_settings_with_identity(const std::wstring& arguments, PROCESS_INFORMATION& process_info)
-    {
-        HRESULT hr = CoInitializeEx(nullptr, COINIT_APARTMENTTHREADED);
-        const bool should_uninit = SUCCEEDED(hr);
-        if (hr == RPC_E_CHANGED_MODE)
-        {
-            hr = S_OK;
-        }
-
-        if (FAILED(hr))
-        {
-            Logger::warn(L"Settings: CoInitializeEx failed. hr=0x{:x}", hr);
-            return false;
-        }
-
-        IApplicationActivationManager* activation_manager = nullptr;
-        hr = CoCreateInstance(CLSID_ApplicationActivationManager,
-                              nullptr,
-                              CLSCTX_INPROC_SERVER,
-                              IID_PPV_ARGS(&activation_manager));
-        if (FAILED(hr))
-        {
-            Logger::warn(L"Settings: CoCreateInstance(ApplicationActivationManager) failed. hr=0x{:x}", hr);
-            if (should_uninit)
-            {
-                CoUninitialize();
-            }
-            return false;
-        }
-
-        auto try_activate = [&](const wchar_t* family) -> bool {
-            std::wstring aumid = std::wstring(family) + L"!" + SettingsApplicationId;
-            DWORD pid = 0;
-            HRESULT hr_activate = activation_manager->ActivateApplication(aumid.c_str(),
-                                                                          arguments.c_str(),
-                                                                          AO_NONE,
-                                                                          &pid);
-            if (SUCCEEDED(hr_activate) && pid != 0)
-            {
-                process_info = {};
-                process_info.dwProcessId = pid;
-                process_info.hProcess = OpenProcess(SYNCHRONIZE | PROCESS_QUERY_LIMITED_INFORMATION, FALSE, pid);
-                Logger::info(L"Settings: Activated via AUMID {} (pid {}).", aumid, pid);
-                return true;
-            }
-
-            Logger::warn(L"Settings: ActivateApplication failed for {}. hr=0x{:x}", aumid, hr_activate);
-            return false;
-        };
-
-        const bool activated = try_activate(SparseAppFamilyDev) || try_activate(SparseAppFamilyStore);
-
-        activation_manager->Release();
-        if (should_uninit)
-        {
-            CoUninitialize();
-        }
-
-        return activated;
-    }
-}
-
 std::optional<std::wstring> dispatch_json_action_to_module(const json::JsonObject& powertoys_configs)
 {
     std::optional<std::wstring> result;
@@ -591,34 +522,15 @@ void run_settings_window(bool show_oobe_window, bool show_scoobe_window, std::op
                                                settings_showOobe,
                                                settings_showScoobe,
                                                settings_containsSettingsWindow);
-    std::wstring activation_args = fmt::format(L"{} {} {} {} {} {} {} {} {}",
-                                               powertoys_pipe_name,
-                                               settings_pipe_name,
-                                               std::to_wstring(powertoys_pid),
-                                               settings_theme,
-                                               settings_elevatedStatus,
-                                               settings_isUserAnAdmin,
-                                               settings_showOobe,
-                                               settings_showScoobe,
-                                               settings_containsSettingsWindow);
 
     if (settings_window.has_value())
     {
         executable_args.append(L" ");
         executable_args.append(settings_window.value());
-        activation_args.append(L" ");
-        activation_args.append(settings_window.value());
     }
 
     BOOL process_created = false;
 
-    // Prefer activating via package identity so the package graph (framework deps) is applied.
-    if (try_activate_settings_with_identity(activation_args, process_info))
-    {
-        process_created = true;
-        g_isLaunchInProgress = false;
-    }
-
     // Commented out to fix #22659
     // Running settings non-elevated and modules elevated when PowerToys is running elevated results
     // in settings making changes in one file (non-elevated user dir) and modules are reading settings

src/runner/trace.cpp

@@ -81,3 +81,36 @@ void Trace::UpdateDownloadCompleted(bool success, const std::wstring& version)
         TraceLoggingBoolean(TRUE, "UTCReplace_AppSessionGuid"),
         TraceLoggingKeyword(PROJECT_KEYWORD_MEASURE));
 }
+
+void Trace::TrayIconLeftClick(bool quickAccessEnabled)
+{
+    TraceLoggingWriteWrapper(
+        g_hProvider,
+        "TrayIcon_LeftClick",
+        TraceLoggingBoolean(quickAccessEnabled, "QuickAccessEnabled"),
+        ProjectTelemetryPrivacyDataTag(ProjectTelemetryTag_ProductAndServicePerformance),
+        TraceLoggingBoolean(TRUE, "UTCReplace_AppSessionGuid"),
+        TraceLoggingKeyword(PROJECT_KEYWORD_MEASURE));
+}
+
+void Trace::TrayIconDoubleClick(bool quickAccessEnabled)
+{
+    TraceLoggingWriteWrapper(
+        g_hProvider,
+        "TrayIcon_DoubleClick",
+        TraceLoggingBoolean(quickAccessEnabled, "QuickAccessEnabled"),
+        ProjectTelemetryPrivacyDataTag(ProjectTelemetryTag_ProductAndServicePerformance),
+        TraceLoggingBoolean(TRUE, "UTCReplace_AppSessionGuid"),
+        TraceLoggingKeyword(PROJECT_KEYWORD_MEASURE));
+}
+
+void Trace::TrayIconRightClick(bool quickAccessEnabled)
+{
+    TraceLoggingWriteWrapper(
+        g_hProvider,
+        "TrayIcon_RightClick",
+        TraceLoggingBoolean(quickAccessEnabled, "QuickAccessEnabled"),
+        ProjectTelemetryPrivacyDataTag(ProjectTelemetryTag_ProductAndServicePerformance),
+        TraceLoggingBoolean(TRUE, "UTCReplace_AppSessionGuid"),
+        TraceLoggingKeyword(PROJECT_KEYWORD_MEASURE));
+}

src/runner/trace.h

@@ -13,4 +13,9 @@ public:
     // Auto-update telemetry
     static void UpdateCheckCompleted(bool success, bool updateAvailable, const std::wstring& fromVersion, const std::wstring& toVersion);
     static void UpdateDownloadCompleted(bool success, const std::wstring& version);
+
+    // Tray icon interaction telemetry
+    static void TrayIconLeftClick(bool quickAccessEnabled);
+    static void TrayIconDoubleClick(bool quickAccessEnabled);
+    static void TrayIconRightClick(bool quickAccessEnabled);
 };

src/runner/tray_icon.cpp

@@ -7,6 +7,7 @@
 #include "centralized_kb_hook.h"
 #include "quick_access_host.h"
 #include "hotkey_conflict_detector.h"
+#include "trace.h"
 #include <Windows.h>
 
 #include <common/utils/resources.h>
@@ -40,6 +41,7 @@ namespace
     bool double_click_timer_running = false;
     bool double_clicked = false;
     POINT tray_icon_click_point;
+    std::optional<bool> last_quick_access_state; // Track the last known Quick Access state
 
     static ThemeListener theme_listener;
     static bool theme_adaptive_enabled = false;
@@ -130,6 +132,9 @@ void click_timer_elapsed()
     double_click_timer_running = false;
     if (!double_clicked)
     {
+        // Log telemetry for single click (confirmed it's not a double click)
+        Trace::TrayIconLeftClick(get_general_settings().enableQuickAccess);
+
         if (get_general_settings().enableQuickAccess)
         {
             open_quick_access_flyout_window();
@@ -195,6 +200,21 @@ LRESULT __stdcall tray_icon_window_proc(HWND window, UINT message, WPARAM wparam
             case WM_RBUTTONUP:
             case WM_CONTEXTMENU:
             {
+                bool quick_access_enabled = get_general_settings().enableQuickAccess;
+
+                // Log telemetry
+                Trace::TrayIconRightClick(quick_access_enabled);
+
+                // Reload menu if Quick Access state has changed or is first time
+                if (h_menu && (!last_quick_access_state.has_value() || quick_access_enabled != last_quick_access_state.value()))
+                {
+                    DestroyMenu(h_menu);
+                    h_menu = nullptr;
+                    h_sub_menu = nullptr;
+                }
+
+                last_quick_access_state = quick_access_enabled;
+
                 if (!h_menu)
                 {
                     h_menu = LoadMenu(reinterpret_cast<HINSTANCE>(&__ImageBase), MAKEINTRESOURCE(ID_TRAY_MENU));
@@ -202,17 +222,39 @@ LRESULT __stdcall tray_icon_window_proc(HWND window, UINT message, WPARAM wparam
                 if (h_menu)
                 {
                     static std::wstring settings_menuitem_label = GET_RESOURCE_STRING(IDS_SETTINGS_MENU_TEXT);
+                    static std::wstring settings_menuitem_label_leftclick = GET_RESOURCE_STRING(IDS_SETTINGS_MENU_TEXT_LEFTCLICK);
                     static std::wstring close_menuitem_label = GET_RESOURCE_STRING(IDS_CLOSE_MENU_TEXT);
                     static std::wstring submit_bug_menuitem_label = GET_RESOURCE_STRING(IDS_SUBMIT_BUG_TEXT);
                     static std::wstring documentation_menuitem_label = GET_RESOURCE_STRING(IDS_DOCUMENTATION_MENU_TEXT);
                     static std::wstring quick_access_menuitem_label = GET_RESOURCE_STRING(IDS_QUICK_ACCESS_MENU_TEXT);
-                    change_menu_item_text(ID_SETTINGS_MENU_COMMAND, settings_menuitem_label.data());
+
+                    // Update Settings menu text based on Quick Access state
+                    if (quick_access_enabled)
+                    {
+                        change_menu_item_text(ID_SETTINGS_MENU_COMMAND, settings_menuitem_label.data());
+                    }
+                    else
+                    {
+                        change_menu_item_text(ID_SETTINGS_MENU_COMMAND, settings_menuitem_label_leftclick.data());
+                    }
+
                     change_menu_item_text(ID_CLOSE_MENU_COMMAND, close_menuitem_label.data());
                     change_menu_item_text(ID_REPORT_BUG_COMMAND, submit_bug_menuitem_label.data());
                     bool bug_report_disabled = is_bug_report_running();
                     EnableMenuItem(h_sub_menu, ID_REPORT_BUG_COMMAND, MF_BYCOMMAND | (bug_report_disabled ? MF_GRAYED : MF_ENABLED));
                     change_menu_item_text(ID_DOCUMENTATION_MENU_COMMAND, documentation_menuitem_label.data());
                     change_menu_item_text(ID_QUICK_ACCESS_MENU_COMMAND, quick_access_menuitem_label.data());
+
+                    // Hide or show Quick Access menu item based on setting
+                    if (!h_sub_menu)
+                    {
+                        h_sub_menu = GetSubMenu(h_menu, 0);
+                    }
+                    if (!quick_access_enabled)
+                    {
+                        // Remove Quick Access menu item when disabled
+                        DeleteMenu(h_sub_menu, ID_QUICK_ACCESS_MENU_COMMAND, MF_BYCOMMAND);
+                    }
                 }
                 if (!h_sub_menu)
                 {
@@ -243,6 +285,9 @@ LRESULT __stdcall tray_icon_window_proc(HWND window, UINT message, WPARAM wparam
             }
             case WM_LBUTTONDBLCLK:
             {
+                // Log telemetry
+                Trace::TrayIconDoubleClick(get_general_settings().enableQuickAccess);
+
                 double_clicked = true;
                 open_settings_window(std::nullopt);
                 break;

src/settings-ui/Settings.UI.Library/AdvancedPastePasteAsFileAction.cs

@@ -34,21 +34,21 @@ public sealed class AdvancedPastePasteAsFileAction : Observable, IAdvancedPasteA
     public AdvancedPasteAdditionalAction PasteAsTxtFile
     {
         get => _pasteAsTxtFile;
-        init => Set(ref _pasteAsTxtFile, value);
+        init => Set(ref _pasteAsTxtFile, value ?? new());
     }
 
     [JsonPropertyName(PropertyNames.PasteAsPngFile)]
     public AdvancedPasteAdditionalAction PasteAsPngFile
     {
         get => _pasteAsPngFile;
-        init => Set(ref _pasteAsPngFile, value);
+        init => Set(ref _pasteAsPngFile, value ?? new());
     }
 
     [JsonPropertyName(PropertyNames.PasteAsHtmlFile)]
     public AdvancedPasteAdditionalAction PasteAsHtmlFile
     {
         get => _pasteAsHtmlFile;
-        init => Set(ref _pasteAsHtmlFile, value);
+        init => Set(ref _pasteAsHtmlFile, value ?? new());
     }
 
     [JsonIgnore]

src/settings-ui/Settings.UI.Library/AdvancedPasteProperties.cs

@@ -93,11 +93,11 @@ namespace Microsoft.PowerToys.Settings.UI.Library
 
         [JsonPropertyName("custom-actions")]
         [CmdConfigureIgnoreAttribute]
-        public AdvancedPasteCustomActions CustomActions { get; init; }
+        public AdvancedPasteCustomActions CustomActions { get; set; }
 
         [JsonPropertyName("additional-actions")]
         [CmdConfigureIgnoreAttribute]
-        public AdvancedPasteAdditionalActions AdditionalActions { get; init; }
+        public AdvancedPasteAdditionalActions AdditionalActions { get; set; }
 
         [JsonPropertyName("paste-ai-configuration")]
         [CmdConfigureIgnoreAttribute]

src/settings-ui/Settings.UI.Library/AdvancedPasteTranscodeAction.cs

@@ -32,14 +32,14 @@ public sealed class AdvancedPasteTranscodeAction : Observable, IAdvancedPasteAct
     public AdvancedPasteAdditionalAction TranscodeToMp3
     {
         get => _transcodeToMp3;
-        init => Set(ref _transcodeToMp3, value);
+        init => Set(ref _transcodeToMp3, value ?? new());
     }
 
     [JsonPropertyName(PropertyNames.TranscodeToMp4)]
     public AdvancedPasteAdditionalAction TranscodeToMp4
     {
         get => _transcodeToMp4;
-        init => Set(ref _transcodeToMp4, value);
+        init => Set(ref _transcodeToMp4, value ?? new());
     }
 
     [JsonIgnore]

src/settings-ui/Settings.UI.Library/CursorWrapProperties.cs

@@ -22,11 +22,15 @@ namespace Microsoft.PowerToys.Settings.UI.Library
         [JsonPropertyName("disable_wrap_during_drag")]
         public BoolProperty DisableWrapDuringDrag { get; set; }
 
+        [JsonPropertyName("wrap_mode")]
+        public IntProperty WrapMode { get; set; }
+
         public CursorWrapProperties()
         {
             ActivationShortcut = DefaultActivationShortcut;
             AutoActivate = new BoolProperty(false);
             DisableWrapDuringDrag = new BoolProperty(true);
+            WrapMode = new IntProperty(0); // 0=Both (default), 1=VerticalOnly, 2=HorizontalOnly
         }
     }
 }

src/settings-ui/Settings.UI.Library/CursorWrapSettings.cs

@@ -47,7 +47,16 @@ namespace Microsoft.PowerToys.Settings.UI.Library
         // This can be utilized in the future if the settings.json file is to be modified/deleted.
         public bool UpgradeSettingsConfiguration()
         {
-            return false;
+            bool settingsUpgraded = false;
+
+            // Add WrapMode property if it doesn't exist (for users upgrading from older versions)
+            if (Properties.WrapMode == null)
+            {
+                Properties.WrapMode = new IntProperty(0); // Default to Both
+                settingsUpgraded = true;
+            }
+
+            return settingsUpgraded;
         }
     }
 }

src/settings-ui/Settings.UI.Library/SettingEntry.cs

@@ -2,10 +2,6 @@
 // The Microsoft Corporation licenses this file to you under the MIT license.
 // See the LICENSE file in the project root for more information.
 
-#nullable enable
-
-using Common.Search;
-
 namespace Settings.UI.Library
 {
     public enum EntryType
@@ -15,7 +11,7 @@ namespace Settings.UI.Library
         SettingsExpander,
     }
 
-    public struct SettingEntry : ISearchable
+    public struct SettingEntry
     {
         public EntryType Type { get; set; }
 
@@ -33,23 +29,16 @@ namespace Settings.UI.Library
 
         public string Icon { get; set; }
 
-        public SettingEntry(EntryType type, string header, string pageTypeName, string elementName, string elementUid, string? parentElementName = null, string? description = null, string? icon = null)
+        public SettingEntry(EntryType type, string header, string pageTypeName, string elementName, string elementUid, string parentElementName = null, string description = null, string icon = null)
         {
             Type = type;
             Header = header;
             PageTypeName = pageTypeName;
             ElementName = elementName;
             ElementUid = elementUid;
-            ParentElementName = parentElementName ?? string.Empty;
-            Description = description ?? string.Empty;
-            Icon = icon ?? string.Empty;
+            ParentElementName = parentElementName;
+            Description = description;
+            Icon = icon;
         }
-
-        // ISearchable implementation
-        public readonly string Id => ElementUid ?? $"{PageTypeName}|{ElementName}";
-
-        public readonly string SearchableText => Header ?? string.Empty;
-
-        public readonly string? SecondarySearchableText => Description;
     }
 }

src/settings-ui/Settings.UI.Library/SettingSearchResult.cs

@@ -1,25 +0,0 @@
-// Copyright (c) Microsoft Corporation
-// The Microsoft Corporation licenses this file to you under the MIT license.
-// See the LICENSE file in the project root for more information.
-
-#nullable enable
-
-using System.Collections.Generic;
-using Common.Search;
-
-namespace Settings.UI.Library
-{
-    /// <summary>
-    /// Represents a search result for a settings entry with scoring metadata.
-    /// </summary>
-    public sealed class SettingSearchResult
-    {
-        public required SettingEntry Entry { get; init; }
-
-        public required double Score { get; init; }
-
-        public required SearchMatchKind MatchKind { get; init; }
-
-        public IReadOnlyList<MatchSpan>? MatchSpans { get; init; }
-    }
-}

src/settings-ui/Settings.UI.Library/Settings.UI.Library.csproj

@@ -23,7 +23,6 @@
         <ProjectReference Include="..\..\common\ManagedCommon\ManagedCommon.csproj" />
         <ProjectReference Include="..\..\common\ManagedTelemetry\Telemetry\ManagedTelemetry.csproj" />
         <ProjectReference Include="..\..\modules\MouseUtils\MouseJump.Common\MouseJump.Common.csproj" />
-        <ProjectReference Include="..\..\common\Common.Search\Common.Search.csproj" />
     </ItemGroup>
 
     <ItemGroup>

src/settings-ui/Settings.UI.UnitTests/Services/SettingsSearchTests.cs

@@ -1,76 +0,0 @@
-// Copyright (c) Microsoft Corporation
-// The Microsoft Corporation licenses this file to you under the MIT license.
-// See the LICENSE file in the project root for more information.
-
-using System.Collections.Generic;
-using System.Threading.Tasks;
-using Common.Search.FuzzSearch;
-using Microsoft.PowerToys.Settings.UI.Services;
-using Microsoft.VisualStudio.TestTools.UnitTesting;
-using Settings.UI.Library;
-
-namespace Microsoft.PowerToys.Settings.UI.UnitTests.Services
-{
-    [TestClass]
-    [DoNotParallelize]
-    public class SettingsSearchTests
-    {
-        [TestMethod]
-        public void LoadIndexFromJson_ReturnsEntries()
-        {
-            const string json = @"
-[
-  {
-    ""type"": 0,
-    ""header"": ""General"",
-    ""pageTypeName"": ""GeneralPage"",
-    ""elementName"": """",
-    ""elementUid"": ""General_Page"",
-    ""parentElementName"": """",
-    ""description"": ""General settings"",
-    ""icon"": """"
-  },
-  {
-    ""type"": 1,
-    ""header"": ""Mouse Utilities"",
-    ""pageTypeName"": ""MouseUtilsPage"",
-    ""elementName"": ""MouseUtilsSetting"",
-    ""elementUid"": ""MouseUtils_Setting"",
-    ""parentElementName"": """",
-    ""description"": ""Adjust mouse settings"",
-    ""icon"": """"
-  }
-]
-";
-
-            var entries = SettingsSearch.LoadIndexFromJson(json);
-
-            Assert.AreEqual(2, entries.Count);
-            Assert.AreEqual(EntryType.SettingsPage, entries[0].Type);
-            Assert.AreEqual("GeneralPage", entries[0].PageTypeName);
-            Assert.AreEqual("MouseUtilsPage", entries[1].PageTypeName);
-        }
-
-        [TestMethod]
-        public async Task InitializeIndexAsync_InitializesSearchAndReturnsResults()
-        {
-            var entries = new List<SettingEntry>
-            {
-                new(EntryType.SettingsPage, "General", "GeneralPage", string.Empty, "General_Page"),
-                new(EntryType.SettingsCard, "Mouse Utilities", "MouseUtilsPage", "MouseUtilsSetting", "MouseUtils_Setting", description: "Adjust mouse settings"),
-            };
-
-            using var search = new SettingsSearch(new FuzzSearchEngine<SettingEntry>());
-            await search.InitializeIndexAsync(entries);
-
-            Assert.IsTrue(search.IsReady);
-
-            var results = await search.SearchAsync("mouse", options: null);
-
-            Assert.IsTrue(results.Count > 0);
-            Assert.AreEqual("Mouse Utilities", results[0].Entry.Header);
-            Assert.IsTrue(results[0].Score > 0);
-            Assert.IsNotNull(results[0].MatchSpans);
-        }
-    }
-}

src/settings-ui/Settings.UI/PowerToys.Settings.csproj

@@ -3,10 +3,6 @@
 	<Import Project="..\..\Common.Dotnet.CsWinRT.props" />
 	<Import Project="..\..\Common.SelfContained.props" />
 
-	<PropertyGroup Condition="'$(UseSparseIdentity)'==''">
-		<UseSparseIdentity>true</UseSparseIdentity>
-	</PropertyGroup>
-
 	<PropertyGroup>
 		<OutputType>WinExe</OutputType>
 		<RootNamespace>Microsoft.PowerToys.Settings.UI</RootNamespace>
@@ -18,15 +14,11 @@
 		<AppendRuntimeIdentifierToOutputPath>false</AppendRuntimeIdentifierToOutputPath>
 		<ApplicationIcon>Assets\Settings\icon.ico</ApplicationIcon>
 		<WindowsAppSDKSelfContained>true</WindowsAppSDKSelfContained>
+		<!-- OutputPath looks like this because it has to be called both by settings and publish.cmd -->
 		<OutputPath>..\..\..\$(Platform)\$(Configuration)\WinUI3Apps</OutputPath>
 		<!-- MRT from windows app sdk will search for a pri file with the same name of the module before defaulting to resources.pri -->
 		<ProjectPriFileName>PowerToys.Settings.pri</ProjectPriFileName>
 	</PropertyGroup>
-	<!-- Framework-dependent for sparse identity + no-op bootstrap when identity exists -->
-	<PropertyGroup Condition="'$(UseSparseIdentity)'=='true'">
-		<WindowsAppSDKSelfContained>false</WindowsAppSDKSelfContained>
-		<WindowsAppSDKBootstrapAutoInitializeOptions_OnPackageIdentity_NoOp>true</WindowsAppSDKBootstrapAutoInitializeOptions_OnPackageIdentity_NoOp>
-	</PropertyGroup>
 	<ItemGroup>
 		<None Remove="Assets\Settings\Icons\Models\Azure.svg" />
 		<None Remove="Assets\Settings\Icons\Models\FoundryLocal.svg" />
@@ -223,4 +215,4 @@
 		<Message Importance="high" Text="[Settings] Building XamlIndexBuilder prior to compile. Views='$(MSBuildProjectDirectory)\SettingsXAML\Views' Out='$(GeneratedJsonFile)'" />
 		<MSBuild Projects="..\Settings.UI.XamlIndexBuilder\Settings.UI.XamlIndexBuilder.csproj" Targets="Build" Properties="Configuration=$(Configuration);Platform=Any CPU;TargetFramework=net9.0;XamlViewsDir=$(MSBuildProjectDirectory)\SettingsXAML\Views;GeneratedJsonFile=$(GeneratedJsonFile)" />
 	</Target>
-</Project>
+</Project>

src/settings-ui/Settings.UI/Services/SearchIndexService.cs

@@ -0,0 +1,338 @@
+// Copyright (c) Microsoft Corporation
+// The Microsoft Corporation licenses this file to you under the MIT license.
+// See the LICENSE file in the project root for more information.
+
+using System;
+using System.Collections.Concurrent;
+using System.Collections.Generic;
+using System.Collections.Immutable;
+using System.Diagnostics;
+using System.Globalization;
+using System.IO;
+using System.Linq;
+using System.Reflection;
+using System.Text;
+using System.Text.Json;
+using System.Threading;
+using System.Threading.Tasks;
+using Common.Search.FuzzSearch;
+using Microsoft.PowerToys.Settings.UI.Helpers;
+using Microsoft.PowerToys.Settings.UI.Views;
+using Microsoft.Windows.ApplicationModel.Resources;
+using Settings.UI.Library;
+
+namespace Microsoft.PowerToys.Settings.UI.Services
+{
+    public static class SearchIndexService
+    {
+        private static readonly object _lockObject = new();
+        private static readonly Dictionary<string, string> _pageNameCache = [];
+        private static readonly Dictionary<string, (string HeaderNorm, string DescNorm)> _normalizedTextCache = new();
+        private static readonly Dictionary<string, Type> _pageTypeCache = new();
+        private static ImmutableArray<SettingEntry> _index = [];
+        private static bool _isIndexBuilt;
+        private static bool _isIndexBuilding;
+        private const string PrebuiltIndexResourceName = "Microsoft.PowerToys.Settings.UI.Assets.search.index.json";
+        private static JsonSerializerOptions _serializerOptions = new() { PropertyNameCaseInsensitive = true };
+
+        public static ImmutableArray<SettingEntry> Index
+        {
+            get
+            {
+                lock (_lockObject)
+                {
+                    return _index;
+                }
+            }
+        }
+
+        public static bool IsIndexReady
+        {
+            get
+            {
+                lock (_lockObject)
+                {
+                    return _isIndexBuilt;
+                }
+            }
+        }
+
+        public static void BuildIndex()
+        {
+            lock (_lockObject)
+            {
+                if (_isIndexBuilt || _isIndexBuilding)
+                {
+                    return;
+                }
+
+                _isIndexBuilding = true;
+
+                // Clear caches on rebuild
+                _normalizedTextCache.Clear();
+                _pageTypeCache.Clear();
+            }
+
+            try
+            {
+                var builder = ImmutableArray.CreateBuilder<SettingEntry>();
+                LoadIndexFromPrebuiltData(builder);
+
+                lock (_lockObject)
+                {
+                    _index = builder.ToImmutable();
+                    _isIndexBuilt = true;
+                    _isIndexBuilding = false;
+                }
+            }
+            catch (Exception ex)
+            {
+                Debug.WriteLine($"[SearchIndexService] CRITICAL ERROR building search index: {ex.Message}\n{ex.StackTrace}");
+                lock (_lockObject)
+                {
+                    _isIndexBuilding = false;
+                    _isIndexBuilt = false;
+                }
+            }
+        }
+
+        private static void LoadIndexFromPrebuiltData(ImmutableArray<SettingEntry>.Builder builder)
+        {
+            var assembly = Assembly.GetExecutingAssembly();
+            var resourceLoader = ResourceLoaderInstance.ResourceLoader;
+            SettingEntry[] metadataList;
+
+            Debug.WriteLine($"[SearchIndexService] Attempting to load prebuilt index from: {PrebuiltIndexResourceName}");
+
+            try
+            {
+                using Stream stream = assembly.GetManifestResourceStream(PrebuiltIndexResourceName);
+                if (stream == null)
+                {
+                    Debug.WriteLine($"[SearchIndexService] ERROR: Embedded resource '{PrebuiltIndexResourceName}' not found. Ensure it's correctly embedded and the name matches.");
+                    return;
+                }
+
+                using StreamReader reader = new(stream);
+                string json = reader.ReadToEnd();
+                if (string.IsNullOrWhiteSpace(json))
+                {
+                    Debug.WriteLine("[SearchIndexService] ERROR: Embedded resource was empty.");
+                    return;
+                }
+
+                metadataList = JsonSerializer.Deserialize<SettingEntry[]>(json, _serializerOptions);
+            }
+            catch (Exception ex)
+            {
+                Debug.WriteLine($"[SearchIndexService] ERROR: Failed to load or deserialize prebuilt index: {ex.Message}");
+                return;
+            }
+
+            if (metadataList == null || metadataList.Length == 0)
+            {
+                Debug.WriteLine("[SearchIndexService] Prebuilt index is empty or deserialization failed.");
+                return;
+            }
+
+            foreach (ref var metadata in metadataList.AsSpan())
+            {
+                if (metadata.Type == EntryType.SettingsPage)
+                {
+                    (metadata.Header, metadata.Description) = GetLocalizedModuleTitleAndDescription(resourceLoader, metadata.ElementUid);
+                }
+                else
+                {
+                    (metadata.Header, metadata.Description) = GetLocalizedSettingHeaderAndDescription(resourceLoader, metadata.ElementUid);
+                }
+
+                if (string.IsNullOrEmpty(metadata.Header))
+                {
+                    continue;
+                }
+
+                builder.Add(metadata);
+
+                // Cache the page name mapping for SettingsPage entries
+                if (metadata.Type == EntryType.SettingsPage && !string.IsNullOrEmpty(metadata.Header))
+                {
+                    _pageNameCache[metadata.PageTypeName] = metadata.Header;
+                }
+            }
+
+            Debug.WriteLine($"[SearchIndexService] Finished loading index. Total entries: {builder.Count}");
+        }
+
+        private static (string Header, string Description) GetLocalizedSettingHeaderAndDescription(ResourceLoader resourceLoader, string elementUid)
+        {
+            string header = GetString(resourceLoader, $"{elementUid}/Header");
+            string description = GetString(resourceLoader, $"{elementUid}/Description");
+
+            if (string.IsNullOrEmpty(header))
+            {
+                header = GetString(resourceLoader, $"{elementUid}/Content");
+            }
+
+            return (header, description);
+        }
+
+        private static (string Title, string Description) GetLocalizedModuleTitleAndDescription(ResourceLoader resourceLoader, string elementUid)
+        {
+            string title = GetString(resourceLoader, $"{elementUid}/ModuleTitle");
+            string description = GetString(resourceLoader, $"{elementUid}/ModuleDescription");
+
+            return (title, description);
+        }
+
+        private static string GetString(ResourceLoader rl, string key)
+        {
+            try
+            {
+                string value = rl.GetString(key);
+                return string.IsNullOrWhiteSpace(value) ? string.Empty : value;
+            }
+            catch (Exception)
+            {
+                return string.Empty;
+            }
+        }
+
+        public static List<SettingEntry> Search(string query)
+        {
+            return Search(query, CancellationToken.None);
+        }
+
+        public static List<SettingEntry> Search(string query, CancellationToken token)
+        {
+            if (string.IsNullOrWhiteSpace(query))
+            {
+                return [];
+            }
+
+            var currentIndex = Index;
+            if (currentIndex.IsEmpty)
+            {
+                Debug.WriteLine("[SearchIndexService] Search called but index is empty.");
+                return [];
+            }
+
+            var normalizedQuery = NormalizeString(query);
+            var bag = new ConcurrentBag<(SettingEntry Hit, double Score)>();
+            var po = new ParallelOptions
+            {
+                CancellationToken = token,
+                MaxDegreeOfParallelism = Math.Max(1, Environment.ProcessorCount - 1),
+            };
+
+            try
+            {
+                Parallel.ForEach(currentIndex, po, entry =>
+                {
+                    var (headerNorm, descNorm) = GetNormalizedTexts(entry);
+                    var captionScoreResult = StringMatcher.FuzzyMatch(normalizedQuery, headerNorm);
+                    double score = captionScoreResult.Score;
+
+                    if (!string.IsNullOrEmpty(descNorm))
+                    {
+                        var descriptionScoreResult = StringMatcher.FuzzyMatch(normalizedQuery, descNorm);
+                        if (descriptionScoreResult.Success)
+                        {
+                            score = Math.Max(score, descriptionScoreResult.Score * 0.8);
+                        }
+                    }
+
+                    if (score > 0)
+                    {
+                        var pageType = GetPageTypeFromName(entry.PageTypeName);
+                        if (pageType != null)
+                        {
+                            bag.Add((entry, score));
+                        }
+                    }
+                });
+            }
+            catch (OperationCanceledException)
+            {
+                return [];
+            }
+
+            return bag
+                .OrderByDescending(r => r.Score)
+                .Select(r => r.Hit)
+                .ToList();
+        }
+
+        private static Type GetPageTypeFromName(string pageTypeName)
+        {
+            if (string.IsNullOrEmpty(pageTypeName))
+            {
+                return null;
+            }
+
+            lock (_lockObject)
+            {
+                if (_pageTypeCache.TryGetValue(pageTypeName, out var cached))
+                {
+                    return cached;
+                }
+
+                var assembly = typeof(GeneralPage).Assembly;
+                var type = assembly.GetType($"Microsoft.PowerToys.Settings.UI.Views.{pageTypeName}");
+                _pageTypeCache[pageTypeName] = type;
+                return type;
+            }
+        }
+
+        private static (string HeaderNorm, string DescNorm) GetNormalizedTexts(SettingEntry entry)
+        {
+            if (entry.ElementUid == null && entry.Header == null)
+            {
+                return (NormalizeString(entry.Header), NormalizeString(entry.Description));
+            }
+
+            var key = entry.ElementUid ?? $"{entry.PageTypeName}|{entry.ElementName}";
+            lock (_lockObject)
+            {
+                if (_normalizedTextCache.TryGetValue(key, out var cached))
+                {
+                    return cached;
+                }
+            }
+
+            var headerNorm = NormalizeString(entry.Header);
+            var descNorm = NormalizeString(entry.Description);
+            lock (_lockObject)
+            {
+                _normalizedTextCache[key] = (headerNorm, descNorm);
+            }
+
+            return (headerNorm, descNorm);
+        }
+
+        private static string NormalizeString(string input)
+        {
+            if (string.IsNullOrEmpty(input))
+            {
+                return string.Empty;
+            }
+
+            var normalized = input.ToLowerInvariant().Normalize(NormalizationForm.FormKD);
+            var stringBuilder = new StringBuilder();
+            foreach (var c in normalized)
+            {
+                var unicodeCategory = CharUnicodeInfo.GetUnicodeCategory(c);
+                if (unicodeCategory != UnicodeCategory.NonSpacingMark)
+                {
+                    stringBuilder.Append(c);
+                }
+            }
+
+            return stringBuilder.ToString();
+        }
+
+        public static string GetLocalizedPageName(string pageTypeName)
+        {
+            return _pageNameCache.TryGetValue(pageTypeName, out string cachedName) ? cachedName : string.Empty;
+        }
+    }
+}

src/settings-ui/Settings.UI/Services/SettingsSearch.cs

@@ -1,434 +0,0 @@
-// Copyright (c) Microsoft Corporation
-// The Microsoft Corporation licenses this file to you under the MIT license.
-// See the LICENSE file in the project root for more information.
-
-using System;
-using System.Collections.Generic;
-using System.Collections.Immutable;
-using System.Diagnostics;
-using System.IO;
-using System.Reflection;
-using System.Text.Json;
-using System.Threading;
-using System.Threading.Tasks;
-using Common.Search;
-using Common.Search.SemanticSearch;
-using ManagedCommon;
-using Microsoft.PowerToys.Settings.UI.Helpers;
-using Microsoft.PowerToys.Settings.UI.Views;
-using Microsoft.Windows.ApplicationModel.Resources;
-using Settings.UI.Library;
-
-namespace Microsoft.PowerToys.Settings.UI.Services
-{
-    public sealed class SettingsSearch : IDisposable
-    {
-        private static readonly Lazy<SettingsSearch> DefaultInstance = new(() => new SettingsSearch());
-
-        private readonly object _lockObject = new();
-        private readonly Dictionary<string, string> _pageNameCache = [];
-        private readonly Dictionary<string, Type> _pageTypeCache = new();
-        private readonly ISearchEngine<SettingEntry> _searchEngine;
-        private ImmutableArray<SettingEntry> _index = [];
-        private bool _isIndexBuilt;
-        private bool _isIndexBuilding;
-        private bool _disposed;
-        private Task _buildTask;
-
-        private const string PrebuiltIndexResourceName = "Microsoft.PowerToys.Settings.UI.Assets.search.index.json";
-        private static readonly JsonSerializerOptions SerializerOptions = new() { PropertyNameCaseInsensitive = true };
-
-        private const string DefaultIndexName = "PowerToys.Settings";
-
-        public SettingsSearch()
-            : this(new SemanticSearchEngine<SettingEntry>(DefaultIndexName))
-        {
-        }
-
-        public SettingsSearch(ISearchEngine<SettingEntry> searchEngine)
-        {
-            ArgumentNullException.ThrowIfNull(searchEngine);
-            _searchEngine = searchEngine;
-        }
-
-        public static SettingsSearch Default => DefaultInstance.Value;
-
-        public ImmutableArray<SettingEntry> Index
-        {
-            get
-            {
-                lock (_lockObject)
-                {
-                    return _index;
-                }
-            }
-        }
-
-        public bool IsReady
-        {
-            get
-            {
-                lock (_lockObject)
-                {
-                    return _isIndexBuilt && _searchEngine.IsReady;
-                }
-            }
-        }
-
-        public Task BuildIndexAsync(CancellationToken cancellationToken = default)
-        {
-            ThrowIfDisposed();
-
-            lock (_lockObject)
-            {
-                if (_isIndexBuilt)
-                {
-                    Logger.LogDebug("[SettingsSearch] BuildIndexAsync skipped: index already built.");
-                    return Task.CompletedTask;
-                }
-
-                if (_isIndexBuilding)
-                {
-                    Logger.LogDebug("[SettingsSearch] BuildIndexAsync skipped: index build already in progress.");
-                    return _buildTask ?? Task.CompletedTask;
-                }
-
-                if (_buildTask != null)
-                {
-                    Logger.LogDebug("[SettingsSearch] BuildIndexAsync skipped: build task already scheduled.");
-                    return _buildTask;
-                }
-
-                Logger.LogInfo("[SettingsSearch] BuildIndexAsync started.");
-                _buildTask = BuildIndexInternalAsync(cancellationToken);
-                return _buildTask;
-            }
-        }
-
-        public async Task InitializeIndexAsync(IEnumerable<SettingEntry> entries, CancellationToken cancellationToken = default)
-        {
-            ArgumentNullException.ThrowIfNull(entries);
-            ThrowIfDisposed();
-
-            var builtIndex = entries is ImmutableArray<SettingEntry> immutableEntries
-                ? immutableEntries
-                : ImmutableArray.CreateRange(entries);
-
-            lock (_lockObject)
-            {
-                _isIndexBuilding = true;
-                _isIndexBuilt = false;
-                _index = builtIndex;
-                _pageNameCache.Clear();
-                _pageTypeCache.Clear();
-            }
-
-            Logger.LogInfo($"[SettingsSearch] Initializing index. Entries={builtIndex.Length}, Engine={_searchEngine.GetType().Name}.");
-            CachePageNames(builtIndex);
-
-            try
-            {
-                if (_searchEngine.IsReady)
-                {
-                    Logger.LogDebug("[SettingsSearch] Clearing existing search engine index.");
-                    await _searchEngine.ClearAsync(cancellationToken).ConfigureAwait(false);
-                }
-                else
-                {
-                    Logger.LogDebug("[SettingsSearch] Initializing search engine.");
-                    await _searchEngine.InitializeAsync(cancellationToken).ConfigureAwait(false);
-                }
-
-                if (!_searchEngine.IsReady)
-                {
-                    Logger.LogWarning("[SettingsSearch] Search engine not ready after initialization. Skipping indexing.");
-                    return;
-                }
-
-                await _searchEngine.IndexBatchAsync(builtIndex, cancellationToken).ConfigureAwait(false);
-
-                lock (_lockObject)
-                {
-                    _isIndexBuilt = true;
-                }
-
-                Logger.LogInfo($"[SettingsSearch] Index initialized. Entries={builtIndex.Length}, EngineReady={_searchEngine.IsReady}.");
-            }
-            catch (Exception ex)
-            {
-                Logger.LogError($"[SettingsSearch] CRITICAL ERROR initializing search engine: {ex.Message}", ex);
-            }
-            finally
-            {
-                lock (_lockObject)
-                {
-                    _isIndexBuilding = false;
-                }
-            }
-        }
-
-        public async Task<IReadOnlyList<SettingSearchResult>> SearchAsync(
-            string query,
-            SearchOptions options = null,
-            CancellationToken token = default)
-        {
-            ThrowIfDisposed();
-
-            if (string.IsNullOrWhiteSpace(query))
-            {
-                return Array.Empty<SettingSearchResult>();
-            }
-
-            if (!IsReady)
-            {
-                Logger.LogWarning("[SettingsSearch] Search called but index is not ready.");
-                return Array.Empty<SettingSearchResult>();
-            }
-
-            var effectiveOptions = options ?? new SearchOptions
-            {
-                MaxResults = Index.Length,
-                IncludeMatchSpans = true,
-            };
-
-            try
-            {
-                var sw = Stopwatch.StartNew();
-                Logger.LogDebug($"[SettingsSearch] Search start. QueryLength={query.Length}, MaxResults={effectiveOptions.MaxResults}.");
-                var results = await Task.Run(
-                    () => _searchEngine.SearchAsync(query, effectiveOptions, token),
-                    token).ConfigureAwait(false);
-                var filtered = FilterValidPageTypes(results);
-                sw.Stop();
-                Logger.LogDebug($"[SettingsSearch] Search complete. Results={filtered.Count}, ElapsedMs={sw.ElapsedMilliseconds}.");
-                return filtered;
-            }
-            catch (OperationCanceledException)
-            {
-                Logger.LogDebug("[SettingsSearch] Search canceled.");
-                return Array.Empty<SettingSearchResult>();
-            }
-        }
-
-        public static IReadOnlyList<SettingEntry> LoadIndexFromJson(string json)
-        {
-            if (string.IsNullOrWhiteSpace(json))
-            {
-                return Array.Empty<SettingEntry>();
-            }
-
-            try
-            {
-                return JsonSerializer.Deserialize<SettingEntry[]>(json, SerializerOptions) ?? Array.Empty<SettingEntry>();
-            }
-            catch (Exception ex)
-            {
-                Logger.LogError($"[SettingsSearch] ERROR: Failed to load index from json: {ex.Message}", ex);
-                return Array.Empty<SettingEntry>();
-            }
-        }
-
-        public string GetLocalizedPageName(string pageTypeName)
-        {
-            lock (_lockObject)
-            {
-                return _pageNameCache.TryGetValue(pageTypeName, out string cachedName) ? cachedName : string.Empty;
-            }
-        }
-
-        public void Dispose()
-        {
-            if (_disposed)
-            {
-                return;
-            }
-
-            _searchEngine.Dispose();
-            _disposed = true;
-        }
-
-        private async Task BuildIndexInternalAsync(CancellationToken cancellationToken)
-        {
-            try
-            {
-                var sw = Stopwatch.StartNew();
-                var entries = LoadIndexFromPrebuiltData();
-                Logger.LogInfo($"[SettingsSearch] Prebuilt index loaded. Entries={entries.Length}.");
-                await InitializeIndexAsync(entries, cancellationToken).ConfigureAwait(false);
-                sw.Stop();
-                Logger.LogInfo($"[SettingsSearch] BuildIndexAsync finished. ElapsedMs={sw.ElapsedMilliseconds}, Ready={IsReady}.");
-            }
-            catch (Exception ex)
-            {
-                Logger.LogError($"[SettingsSearch] CRITICAL ERROR building search index: {ex.Message}", ex);
-            }
-            finally
-            {
-                lock (_lockObject)
-                {
-                    _buildTask = null;
-                }
-            }
-        }
-
-        private void CachePageNames(ImmutableArray<SettingEntry> entries)
-        {
-            lock (_lockObject)
-            {
-                foreach (var entry in entries)
-                {
-                    if (entry.Type == EntryType.SettingsPage && !string.IsNullOrEmpty(entry.Header))
-                    {
-                        _pageNameCache[entry.PageTypeName] = entry.Header;
-                    }
-                }
-            }
-        }
-
-        private ImmutableArray<SettingEntry> LoadIndexFromPrebuiltData()
-        {
-            var assembly = Assembly.GetExecutingAssembly();
-            var resourceLoader = ResourceLoaderInstance.ResourceLoader;
-
-            Logger.LogInfo($"[SettingsSearch] Attempting to load prebuilt index from: {PrebuiltIndexResourceName}");
-
-            string json;
-            try
-            {
-                using Stream stream = assembly.GetManifestResourceStream(PrebuiltIndexResourceName);
-                if (stream == null)
-                {
-                    Logger.LogError($"[SettingsSearch] ERROR: Embedded resource '{PrebuiltIndexResourceName}' not found. Ensure it's correctly embedded and the name matches.");
-                    return ImmutableArray<SettingEntry>.Empty;
-                }
-
-                using StreamReader reader = new(stream);
-                json = reader.ReadToEnd();
-            }
-            catch (Exception ex)
-            {
-                Logger.LogError($"[SettingsSearch] ERROR: Failed to read prebuilt index: {ex.Message}", ex);
-                return ImmutableArray<SettingEntry>.Empty;
-            }
-
-            if (string.IsNullOrWhiteSpace(json))
-            {
-                Logger.LogError("[SettingsSearch] ERROR: Embedded resource was empty.");
-                return ImmutableArray<SettingEntry>.Empty;
-            }
-
-            var metadataList = LoadIndexFromJson(json);
-            if (metadataList == null || metadataList.Count == 0)
-            {
-                Logger.LogWarning("[SettingsSearch] Prebuilt index is empty or deserialization failed.");
-                return ImmutableArray<SettingEntry>.Empty;
-            }
-
-            var builder = ImmutableArray.CreateBuilder<SettingEntry>(metadataList.Count);
-
-            foreach (var metadata in metadataList)
-            {
-                var entry = metadata;
-                if (entry.Type == EntryType.SettingsPage)
-                {
-                    (entry.Header, entry.Description) = GetLocalizedModuleTitleAndDescription(resourceLoader, entry.ElementUid);
-                }
-                else
-                {
-                    (entry.Header, entry.Description) = GetLocalizedSettingHeaderAndDescription(resourceLoader, entry.ElementUid);
-                }
-
-                if (string.IsNullOrEmpty(entry.Header))
-                {
-                    continue;
-                }
-
-                builder.Add(entry);
-            }
-
-            Logger.LogInfo($"[SettingsSearch] Finished loading index. Total entries: {builder.Count}");
-            return builder.ToImmutable();
-        }
-
-        private static (string Header, string Description) GetLocalizedSettingHeaderAndDescription(ResourceLoader resourceLoader, string elementUid)
-        {
-            string header = GetString(resourceLoader, $"{elementUid}/Header");
-            string description = GetString(resourceLoader, $"{elementUid}/Description");
-
-            if (string.IsNullOrEmpty(header))
-            {
-                header = GetString(resourceLoader, $"{elementUid}/Content");
-            }
-
-            return (header, description);
-        }
-
-        private static (string Title, string Description) GetLocalizedModuleTitleAndDescription(ResourceLoader resourceLoader, string elementUid)
-        {
-            string title = GetString(resourceLoader, $"{elementUid}/ModuleTitle");
-            string description = GetString(resourceLoader, $"{elementUid}/ModuleDescription");
-
-            return (title, description);
-        }
-
-        private static string GetString(ResourceLoader rl, string key)
-        {
-            try
-            {
-                string value = rl.GetString(key);
-                return string.IsNullOrWhiteSpace(value) ? string.Empty : value;
-            }
-            catch (Exception)
-            {
-                return string.Empty;
-            }
-        }
-
-        private IReadOnlyList<SettingSearchResult> FilterValidPageTypes(IReadOnlyList<SearchResult<SettingEntry>> results)
-        {
-            var filtered = new List<SettingSearchResult>(results.Count);
-            foreach (var result in results)
-            {
-                var entry = result.Item;
-                if (GetPageTypeFromName(entry.PageTypeName) != null)
-                {
-                    filtered.Add(new SettingSearchResult
-                    {
-                        Entry = entry,
-                        Score = result.Score,
-                        MatchKind = result.MatchKind,
-                        MatchSpans = result.MatchSpans,
-                    });
-                }
-            }
-
-            return filtered;
-        }
-
-        private Type GetPageTypeFromName(string pageTypeName)
-        {
-            if (string.IsNullOrEmpty(pageTypeName))
-            {
-                return null;
-            }
-
-            lock (_lockObject)
-            {
-                if (_pageTypeCache.TryGetValue(pageTypeName, out var cached))
-                {
-                    return cached;
-                }
-
-                var assembly = typeof(GeneralPage).Assembly;
-                var type = assembly.GetType($"Microsoft.PowerToys.Settings.UI.Views.{pageTypeName}");
-                _pageTypeCache[pageTypeName] = type;
-                return type;
-            }
-        }
-
-        private void ThrowIfDisposed()
-        {
-            ObjectDisposedException.ThrowIf(_disposed, this);
-        }
-    }
-}

src/settings-ui/Settings.UI/SettingsXAML/Views/MouseUtilsPage.xaml

@@ -47,6 +47,13 @@
                             <tkcontrols:SettingsCard ContentAlignment="Left" IsEnabled="{x:Bind ViewModel.IsCursorWrapEnabled, Mode=OneWay}">
                                 <CheckBox x:Uid="MouseUtils_CursorWrap_DisableWrapDuringDrag" IsChecked="{x:Bind ViewModel.CursorWrapDisableWrapDuringDrag, Mode=TwoWay}" />
                             </tkcontrols:SettingsCard>
+                            <tkcontrols:SettingsCard Name="MouseUtilsCursorWrapWrapMode" x:Uid="MouseUtils_CursorWrap_WrapMode">
+                                <ComboBox MinWidth="{StaticResource SettingActionControlMinWidth}" SelectedIndex="{x:Bind Path=ViewModel.CursorWrapWrapMode, Mode=TwoWay}">
+                                    <ComboBoxItem x:Uid="MouseUtils_CursorWrap_WrapMode_Both" />
+                                    <ComboBoxItem x:Uid="MouseUtils_CursorWrap_WrapMode_VerticalOnly" />
+                                    <ComboBoxItem x:Uid="MouseUtils_CursorWrap_WrapMode_HorizontalOnly" />
+                                </ComboBox>
+                            </tkcontrols:SettingsCard>
                         </tkcontrols:SettingsExpander.Items>
                     </tkcontrols:SettingsExpander>
                 </controls:SettingsGroup>

src/settings-ui/Settings.UI/SettingsXAML/Views/SearchResultsPage.xaml

@@ -32,12 +32,12 @@
                         IsTabStop="False"
                         ItemsSource="{x:Bind ViewModel.ModuleResults, Mode=OneWay}">
                         <ItemsControl.ItemTemplate>
-                            <DataTemplate x:DataType="models:SettingSearchResult">
+                            <DataTemplate x:DataType="models:SettingEntry">
                                 <tkcontrols:SettingsCard
                                     Margin="0,0,0,2"
                                     Click="ModuleButton_Click"
-                                    Header="{x:Bind Entry.Header}"
-                                    HeaderIcon="{x:Bind Entry.Icon, Converter={StaticResource IconConverter}, ConverterParameter=&#xE8B7;}"
+                                    Header="{x:Bind Header}"
+                                    HeaderIcon="{x:Bind Icon, Converter={StaticResource IconConverter}, ConverterParameter=&#xE8B7;}"
                                     IsClickEnabled="True" />
                             </DataTemplate>
                         </ItemsControl.ItemTemplate>
@@ -52,19 +52,19 @@
                     <ItemsControl.ItemTemplate>
                         <DataTemplate x:DataType="vm:SettingsGroup">
                             <controls:SettingsGroup Header="{x:Bind GroupName}">
-                                    <ItemsControl IsTabStop="False" ItemsSource="{x:Bind Settings}">
-                                        <ItemsControl.ItemTemplate>
-                                            <DataTemplate x:DataType="models:SettingSearchResult">
-                                                <tkcontrols:SettingsCard
-                                                    Margin="0,0,0,2"
-                                                    Click="SettingButton_Click"
-                                                    Description="{x:Bind Entry.Description}"
-                                                    Header="{x:Bind Entry.Header}"
-                                                    HeaderIcon="{x:Bind Entry.Icon, Converter={StaticResource IconConverter}, ConverterParameter=&#xE713;}"
-                                                    IsClickEnabled="True" />
-                                            </DataTemplate>
-                                        </ItemsControl.ItemTemplate>
-                                    </ItemsControl>
+                                <ItemsControl IsTabStop="False" ItemsSource="{x:Bind Settings}">
+                                    <ItemsControl.ItemTemplate>
+                                        <DataTemplate x:DataType="models:SettingEntry">
+                                            <tkcontrols:SettingsCard
+                                                Margin="0,0,0,2"
+                                                Click="SettingButton_Click"
+                                                Description="{x:Bind Description}"
+                                                Header="{x:Bind Header}"
+                                                HeaderIcon="{x:Bind Icon, Converter={StaticResource IconConverter}, ConverterParameter=&#xE713;}"
+                                                IsClickEnabled="True" />
+                                        </DataTemplate>
+                                    </ItemsControl.ItemTemplate>
+                                </ItemsControl>
                             </controls:SettingsGroup>
                         </DataTemplate>
                     </ItemsControl.ItemTemplate>

src/settings-ui/Settings.UI/SettingsXAML/Views/SearchResultsPage.xaml.cs

@@ -44,17 +44,17 @@ namespace Microsoft.PowerToys.Settings.UI.Views
 
         private void ModuleButton_Click(object sender, RoutedEventArgs e)
         {
-            if (sender is SettingsCard card && card.DataContext is SettingSearchResult tagResult)
+            if (sender is SettingsCard card && card.DataContext is SettingEntry tagEntry)
             {
-                NavigateToModule(tagResult.Entry);
+                NavigateToModule(tagEntry);
             }
         }
 
         private void SettingButton_Click(object sender, RoutedEventArgs e)
         {
-            if (sender is SettingsCard card && card.DataContext is SettingSearchResult tagResult)
+            if (sender is SettingsCard card && card.DataContext is SettingEntry tagEntry)
             {
-                NavigateToSetting(tagResult.Entry);
+                NavigateToSetting(tagEntry);
             }
         }
 
@@ -98,9 +98,9 @@ namespace Microsoft.PowerToys.Settings.UI.Views
     {
         public string Query { get; set; }
 
-        public List<SettingSearchResult> Results { get; set; }
+        public List<SettingEntry> Results { get; set; }
 
-        public SearchResultsNavigationParams(string query, List<SettingSearchResult> results)
+        public SearchResultsNavigationParams(string query, List<SettingEntry> results)
         {
             Query = query;
             Results = results;

src/settings-ui/Settings.UI/SettingsXAML/Views/ShellPage.xaml.cs

@@ -8,6 +8,7 @@ using System.Linq;
 using System.Threading;
 using System.Threading.Tasks;
 using Common.Search;
+using Common.Search.FuzzSearch;
 using ManagedCommon;
 using Microsoft.PowerToys.Settings.UI.Controls;
 using Microsoft.PowerToys.Settings.UI.Helpers;
@@ -384,7 +385,11 @@ namespace Microsoft.PowerToys.Settings.UI.Views
 
         private void ShellPage_Loaded(object sender, RoutedEventArgs e)
         {
-            _ = Task.Run(() => SettingsSearch.Default.BuildIndexAsync());
+            Task.Run(() =>
+            {
+                SearchIndexService.BuildIndex();
+            })
+            .ContinueWith(_ => { });
         }
 
         private void NavigationView_DisplayModeChanged(NavigationView sender, NavigationViewDisplayModeChangedEventArgs args)
@@ -422,7 +427,7 @@ namespace Microsoft.PowerToys.Settings.UI.Views
             NativeMethods.SendMessage(hWnd, NativeMethods.WM_COMMAND, ID_CLOSE_MENU_COMMAND, 0);
         }
 
-        private List<SettingSearchResult> _lastSearchResults = new();
+        private List<SettingEntry> _lastSearchResults = new();
         private string _lastQueryText = string.Empty;
 
         private async void SearchBox_TextChanged(AutoSuggestBox sender, AutoSuggestBoxTextChangedEventArgs args)
@@ -465,10 +470,11 @@ namespace Microsoft.PowerToys.Settings.UI.Views
             }
 
             // Query the index on a background thread to avoid blocking UI
-            List<SettingSearchResult> results = null;
+            List<SettingEntry> results = null;
             try
             {
-                results = (await SettingsSearch.Default.SearchAsync(query, options: null, token)).ToList();
+                // If the token is already canceled before scheduling, the task won't start.
+                results = await Task.Run(() => SearchIndexService.Search(query, token), token);
             }
             catch (OperationCanceledException)
             {
@@ -572,7 +578,7 @@ namespace Microsoft.PowerToys.Settings.UI.Views
         }
 
         // Centralized suggestion projection logic used by TextChanged & GotFocus restore.
-        private List<SuggestionItem> BuildSuggestionItems(string query, List<SettingSearchResult> results)
+        private List<SuggestionItem> BuildSuggestionItems(string query, List<SettingEntry> results)
         {
             results ??= new();
             if (results.Count == 0)
@@ -595,17 +601,16 @@ namespace Microsoft.PowerToys.Settings.UI.Views
                 };
             }
 
-            var list = results.Take(5).Select(result =>
+            var list = results.Take(5).Select(e =>
             {
-                var entry = result.Entry;
                 string subtitle = string.Empty;
-                if (entry.Type != EntryType.SettingsPage)
+                if (e.Type != EntryType.SettingsPage)
                 {
-                    subtitle = SettingsSearch.Default.GetLocalizedPageName(entry.PageTypeName);
+                    subtitle = SearchIndexService.GetLocalizedPageName(e.PageTypeName);
                     if (string.IsNullOrEmpty(subtitle))
                     {
-                        subtitle = SettingsSearch.Default.Index
-                            .Where(x => x.Type == EntryType.SettingsPage && x.PageTypeName == entry.PageTypeName)
+                        subtitle = SearchIndexService.Index
+                            .Where(x => x.Type == EntryType.SettingsPage && x.PageTypeName == e.PageTypeName)
                             .Select(x => x.Header)
                             .FirstOrDefault() ?? string.Empty;
                     }
@@ -613,15 +618,12 @@ namespace Microsoft.PowerToys.Settings.UI.Views
 
                 return new SuggestionItem
                 {
-                    Header = entry.Header,
-                    Icon = entry.Icon,
-                    PageTypeName = entry.PageTypeName,
-                    ElementName = entry.ElementName,
-                    ParentElementName = entry.ParentElementName,
+                    Header = e.Header,
+                    Icon = e.Icon,
+                    PageTypeName = e.PageTypeName,
+                    ElementName = e.ElementName,
+                    ParentElementName = e.ParentElementName,
                     Subtitle = subtitle,
-                    Score = result.Score,
-                    MatchKind = result.MatchKind,
-                    MatchSpans = result.MatchSpans ?? Array.Empty<MatchSpan>(),
                     IsShowAll = false,
                 };
             }).ToList();
@@ -653,7 +655,7 @@ namespace Microsoft.PowerToys.Settings.UI.Views
             // Prefer cached results (from live search); if empty, perform a fresh search
             var matched = _lastSearchResults?.Count > 0 && string.Equals(_lastQueryText, queryText, StringComparison.Ordinal)
                 ? _lastSearchResults
-                : (await SettingsSearch.Default.SearchAsync(queryText, options: null)).ToList();
+                : await Task.Run(() => SearchIndexService.Search(queryText));
 
             var searchParams = new SearchResultsNavigationParams(queryText, matched);
             NavigationService.Navigate<SearchResultsPage>(searchParams);

src/settings-ui/Settings.UI/Strings/en-us/Resources.resw

@@ -2728,6 +2728,18 @@ From there, simply click on one of the supported files in the File Explorer and
   <data name="MouseUtils_CursorWrap_AutoActivate.Content" xml:space="preserve">
     <value>Automatically activate on utility startup</value>
   </data>
+  <data name="MouseUtils_CursorWrap_WrapMode.Header" xml:space="preserve">
+    <value>Wrap mode</value>
+  </data>
+  <data name="MouseUtils_CursorWrap_WrapMode_VerticalOnly.Content" xml:space="preserve">
+    <value>Vertical only</value>
+  </data>
+  <data name="MouseUtils_CursorWrap_WrapMode_HorizontalOnly.Content" xml:space="preserve">
+    <value>Horizontal only</value>
+  </data>
+  <data name="MouseUtils_CursorWrap_WrapMode_Both.Content" xml:space="preserve">
+    <value>Vertical and horizontal</value>
+  </data>
   <data name="Oobe_MouseUtils_MousePointerCrosshairs.Text" xml:space="preserve">
     <value>Mouse Pointer Crosshairs</value>
     <comment>Mouse as in the hardware peripheral.</comment>

src/settings-ui/Settings.UI/ViewModels/AdvancedPasteViewModel.cs

@@ -76,16 +76,24 @@ namespace Microsoft.PowerToys.Settings.UI.ViewModels
 
             GeneralSettingsConfig = settingsRepository.SettingsConfig;
 
-            // To obtain the settings configurations of Fancy zones.
-            ArgumentNullException.ThrowIfNull(settingsRepository);
+            // To obtain the settings configurations of Advanced Paste.
+            ArgumentNullException.ThrowIfNull(advancedPasteSettingsRepository);
 
             _dispatcherQueue = DispatcherQueue.GetForCurrentThread();
 
             _settingsUtils = settingsUtils ?? throw new ArgumentNullException(nameof(settingsUtils));
 
-            ArgumentNullException.ThrowIfNull(advancedPasteSettingsRepository);
+            _advancedPasteSettings = advancedPasteSettingsRepository.SettingsConfig ?? throw new ArgumentException("SettingsConfig cannot be null", nameof(advancedPasteSettingsRepository));
 
-            _advancedPasteSettings = advancedPasteSettingsRepository.SettingsConfig;
+            if (_advancedPasteSettings.Properties is null)
+            {
+                throw new ArgumentException("AdvancedPasteSettings.Properties cannot be null", nameof(advancedPasteSettingsRepository));
+            }
+
+            // Ensure AdditionalActions and CustomActions are initialized to prevent null reference exceptions
+            // This handles legacy settings files that may be missing these properties
+            _advancedPasteSettings.Properties.AdditionalActions ??= new AdvancedPasteAdditionalActions();
+            _advancedPasteSettings.Properties.CustomActions ??= new AdvancedPasteCustomActions();
 
             AttachConfigurationHandlers();
 
@@ -93,7 +101,7 @@ namespace Microsoft.PowerToys.Settings.UI.ViewModels
             SendConfigMSG = ipcMSGCallBackFunc;
 
             _additionalActions = _advancedPasteSettings.Properties.AdditionalActions;
-            _customActions = _advancedPasteSettings.Properties.CustomActions.Value;
+            _customActions = _advancedPasteSettings.Properties.CustomActions.Value ?? new ObservableCollection<AdvancedPasteCustomAction>();
 
             SetupSettingsFileWatcher();
 
@@ -469,7 +477,13 @@ namespace Microsoft.PowerToys.Settings.UI.ViewModels
 
         public PasteAIConfiguration PasteAIConfiguration
         {
-            get => _advancedPasteSettings.Properties.PasteAIConfiguration;
+            get
+            {
+                // Ensure PasteAIConfiguration is never null for XAML binding
+                _advancedPasteSettings.Properties.PasteAIConfiguration ??= new PasteAIConfiguration();
+                return _advancedPasteSettings.Properties.PasteAIConfiguration;
+            }
+
             set
             {
                 if (!ReferenceEquals(value, _advancedPasteSettings.Properties.PasteAIConfiguration))

src/settings-ui/Settings.UI/ViewModels/MouseUtilsViewModel.cs

@@ -113,6 +113,9 @@ namespace Microsoft.PowerToys.Settings.UI.ViewModels
             // Null-safe access in case property wasn't upgraded yet - default to TRUE
             _cursorWrapDisableWrapDuringDrag = CursorWrapSettingsConfig.Properties.DisableWrapDuringDrag?.Value ?? true;
 
+            // Null-safe access in case property wasn't upgraded yet - default to 0 (Both)
+            _cursorWrapWrapMode = CursorWrapSettingsConfig.Properties.WrapMode?.Value ?? 0;
+
             int isEnabled = 0;
 
             Utilities.NativeMethods.SystemParametersInfo(Utilities.NativeMethods.SPI_GETCLIENTAREAANIMATION, 0, ref isEnabled, 0);
@@ -1083,6 +1086,34 @@ namespace Microsoft.PowerToys.Settings.UI.ViewModels
             }
         }
 
+        public int CursorWrapWrapMode
+        {
+            get
+            {
+                return _cursorWrapWrapMode;
+            }
+
+            set
+            {
+                if (value != _cursorWrapWrapMode)
+                {
+                    _cursorWrapWrapMode = value;
+
+                    // Ensure the property exists before setting value
+                    if (CursorWrapSettingsConfig.Properties.WrapMode == null)
+                    {
+                        CursorWrapSettingsConfig.Properties.WrapMode = new IntProperty(value);
+                    }
+                    else
+                    {
+                        CursorWrapSettingsConfig.Properties.WrapMode.Value = value;
+                    }
+
+                    NotifyCursorWrapPropertyChanged();
+                }
+            }
+        }
+
         public void NotifyCursorWrapPropertyChanged([CallerMemberName] string propertyName = null)
         {
             OnPropertyChanged(propertyName);
@@ -1154,5 +1185,6 @@ namespace Microsoft.PowerToys.Settings.UI.ViewModels
         private bool _isCursorWrapEnabled;
         private bool _cursorWrapAutoActivate;
         private bool _cursorWrapDisableWrapDuringDrag; // Will be initialized in constructor from settings
+        private int _cursorWrapWrapMode; // 0=Both, 1=VerticalOnly, 2=HorizontalOnly
     }
 }

src/settings-ui/Settings.UI/ViewModels/SearchResultsViewModel.cs

@@ -14,11 +14,11 @@ namespace Microsoft.PowerToys.Settings.UI.ViewModels
 {
     public class SearchResultsViewModel : INotifyPropertyChanged
     {
-        private ObservableCollection<SettingSearchResult> _moduleResults = new();
+        private ObservableCollection<SettingEntry> _moduleResults = new();
         private ObservableCollection<SettingsGroup> _groupedSettingsResults = new();
         private bool _hasNoResults;
 
-        public ObservableCollection<SettingSearchResult> ModuleResults
+        public ObservableCollection<SettingEntry> ModuleResults
         {
             get => _moduleResults;
             set
@@ -48,7 +48,7 @@ namespace Microsoft.PowerToys.Settings.UI.ViewModels
             }
         }
 
-        public void SetSearchResults(string query, List<SettingSearchResult> results)
+        public void SetSearchResults(string query, List<SettingEntry> results)
         {
             if (results == null || results.Count == 0)
             {
@@ -61,8 +61,8 @@ namespace Microsoft.PowerToys.Settings.UI.ViewModels
             HasNoResults = false;
 
             // Separate modules and settings
-            var modules = results.Where(r => r.Entry.Type == EntryType.SettingsPage).ToList();
-            var settings = results.Where(r => r.Entry.Type == EntryType.SettingsCard).ToList();
+            var modules = results.Where(r => r.Type == EntryType.SettingsPage).ToList();
+            var settings = results.Where(r => r.Type == EntryType.SettingsCard).ToList();
 
             // Update module results
             ModuleResults.Clear();
@@ -73,11 +73,11 @@ namespace Microsoft.PowerToys.Settings.UI.ViewModels
 
             // Group settings by their page/module
             var groupedSettings = settings
-                .GroupBy(s => SettingsSearch.Default.GetLocalizedPageName(s.Entry.PageTypeName))
+                .GroupBy(s => SearchIndexService.GetLocalizedPageName(s.PageTypeName))
                 .Select(g => new SettingsGroup
                 {
                     GroupName = g.Key,
-                    Settings = new ObservableCollection<SettingSearchResult>(g),
+                    Settings = new ObservableCollection<SettingEntry>(g),
                 })
                 .ToList();
 
@@ -101,7 +101,7 @@ namespace Microsoft.PowerToys.Settings.UI.ViewModels
 #pragma warning restore SA1402 // File may only contain a single type
     {
         private string _groupName;
-        private ObservableCollection<SettingSearchResult> _settings;
+        private ObservableCollection<SettingEntry> _settings;
 
         public string GroupName
         {
@@ -113,7 +113,7 @@ namespace Microsoft.PowerToys.Settings.UI.ViewModels
             }
         }
 
-        public ObservableCollection<SettingSearchResult> Settings
+        public ObservableCollection<SettingEntry> Settings
         {
             get => _settings;
             set

src/settings-ui/Settings.UI/ViewModels/SuggestionItem.cs

@@ -2,9 +2,6 @@
 // The Microsoft Corporation licenses this file to you under the MIT license.
 // See the LICENSE file in the project root for more information.
 
-using System.Collections.Generic;
-using Common.Search;
-
 namespace Microsoft.PowerToys.Settings.UI.ViewModels
 {
     public sealed partial class SuggestionItem
@@ -21,12 +18,6 @@ namespace Microsoft.PowerToys.Settings.UI.ViewModels
 
         public string Subtitle { get; init; }
 
-        public double Score { get; init; }
-
-        public SearchMatchKind? MatchKind { get; init; }
-
-        public IReadOnlyList<MatchSpan> MatchSpans { get; init; }
-
         public bool IsShowAll { get; init; }
 
         public bool IsNoResults { get; init; }

src/settings-ui/Settings.UI/app.manifest

@@ -2,11 +2,6 @@
 <assembly manifestVersion="1.0" xmlns="urn:schemas-microsoft-com:asm.v1">
   <assemblyIdentity version="1.0.0.0" name="PowerToys.Settings.app"/>
 
-  <msix xmlns="urn:schemas-microsoft-com:msix.v1"
-        packageName="Microsoft.PowerToys.SparseApp"
-        applicationId="PowerToys.SettingsUI"
-        publisher="CN=PowerToys Dev, O=PowerToys, L=Redmond, S=Washington, C=US" />
-
   <application xmlns="urn:schemas-microsoft-com:asm.v3">
     <windowsSettings>
       <!-- The combination of below two tags have the following effect: