chore: import upstream snapshot with attribution

doc/devdocs/common/context-menus.md

@@ -0,0 +1,102 @@
+# PowerToys Context Menu Handlers
+
+This document describes how context menu handlers are implemented in PowerToys, covering both Windows 10 and Windows 11 approaches.
+
+## Context Menu Implementation Types
+
+PowerToys implements two types of context menu handlers:
+
+1. **Old-Style Context Menu Handlers**
+   - Used for Windows 10 compatibility
+   - Registered via registry entries
+   - Implemented as COM objects exposing the `IContextMenu` interface
+   - Registered for specific file extensions
+
+2. **Windows 11 Context Menu Handlers**
+   - Implemented as sparse MSIX packages
+   - Exposing the `IExplorerCommand` interface
+   - Located in `PowerToys\x64\Debug\modules\<module>\<module>.msix`
+   - Registered for all file types and filtered in code
+   - Requires signing to be installed
+
+## Context Menu Handler Registration Approaches
+
+PowerToys modules use two different approaches for registering context menu handlers:
+
+### 1. Dual Registration (e.g., ImageResizer, PowerRename)
+
+- Both old-style and Windows 11 context menu handlers are registered
+- Results in duplicate entries in Windows 11's expanded context menu
+- Ensures functionality even if Windows 11 handler fails to appear
+- Old-style handlers appear in the "Show more options" expanded menu
+
+### 2. Selective Registration (e.g., NewPlus)
+
+- Windows 10: Uses old-style context menu handler
+- Windows 11: Uses new MSIX-based context menu handler
+- Avoids duplicates but can cause issues if Windows 11 handler fails to register
+
+## Windows 11 Context Menu Handler Implementation
+
+### Package Registration
+
+- MSIX packages are defined in `AppManifest.xml` in each context menu project
+- Registration happens in `DllMain` of the module interface DLL when the module is enabled
+- Explorer restart may be required after registration for changes to take effect
+- Registration can be verified with `Get-AppxPackage` PowerShell command:
+  ```powershell
+  Get-AppxPackage -Name *PowerToys*
+  ```
+
+### Technical Implementation
+
+- Handlers implement the `IExplorerCommand` interface
+- Key methods:
+  - `GetState`: Determines visibility based on file type
+  - `Invoke`: Handles the action when the menu item is clicked
+  - `GetTitle`: Provides the text to display in the context menu
+- For selective filtering (showing only for certain file types), the logic is implemented in the `GetState` method
+
+### Example Implementation Flow
+
+1. Build generates an MSIX package from the context menu project
+2. When the module is enabled, PowerToys installs the package using `PackageManager.AddPackageAsync`
+3. The package references the DLL that implements the actual context menu handler
+4. When the user right-clicks, Explorer loads the DLL and calls into its methods
+
+## Debugging Context Menu Handlers
+
+### Debugging Old-Style (Windows 10) Handlers
+
+1. Update the registry to point to your debug build
+2. Restart Explorer
+3. Attach the debugger to explorer.exe
+4. Set breakpoints and test by right-clicking in File Explorer
+
+### Debugging Windows 11 Handlers
+
+1. Build PowerToys to get the MSIX packages
+2. Sign the MSIX package with a self-signed certificate
+3. Replace files in the PowerToys installation directory
+4. Use PowerToys to install the package
+5. Restart Explorer
+6. Run Visual Studio as administrator
+7. Set breakpoints in relevant code
+8. Attach to DllHost.exe process when context menu is triggered
+
+### Debugging Challenges
+
+- Windows 11 handlers require signing and reinstalling for each code change
+- DllHost loads the DLL only when context menu is triggered and unloads after
+- For efficient development, use logging or message boxes instead of breakpoints
+- Consider debugging the Windows 10 handler by removing OS version checks
+
+## Common Issues
+
+- Context menu entries not showing in Windows 11
+  - Usually due to package not being removed/updated properly on PowerToys update
+  - Fix: Uninstall and reinstall the package or restart Explorer
+- Registering packages requires signing
+  - For local testing, create and install a signing certificate
+- Duplicate entries in Windows 11 context menu
+  - By design for some modules to ensure availability if Windows 11 handler fails