chore: import upstream snapshot with attribution

doc/devdocs/common/FilePreviewCommon.md

@@ -0,0 +1,86 @@
+# [FilePreviewCommon](/src/common/FilePreviewCommon)
+
+This project contains common code used for previewing and displaying files.
+
+## Monaco preview
+
+Monaco preview enables to display developer files. It is based on [Microsoft's Monaco Editor](https://microsoft.github.io/monaco-editor/) which is maintained by the Visual Studio Code team.
+
+This previewer is used for the File Explorer Dev File Previewer, as well as PowerToys Peek.
+
+For a general overview of how Monaco is used in PowerToys, see the [Monaco Editor documentation](monaco-editor.md).
+
+### Update Monaco Editor
+
+1. Download Monaco editor with [npm](https://www.npmjs.com/): Run `npm i monaco-editor` in the command prompt.
+2. Delete everything except the `min` folder (the minimised code) from the downloaded files.
+3. Copy the `min` folder into the `/src/Monaco/monacoSRC` folder of the PowerToys project.
+4. Generate the JSON file as described in the generate [monaco_languages.json file](#monaco_languagesjson) section.
+
+### Add a new language definition
+
+As an example on how to add a new language definition you can look at the one for [registry files](/src/Monaco/customLanguages/reg.js).
+
+1. Add the new language definition (written with [Monarch](https://microsoft.github.io/monaco-editor/monarch.html)) as a new file to the [folder containing Monaco custom languages](/src/Monaco/customLanguages/) (Remember the file name and the string you used for "idDefinition" as you need it later.). The file should be formatted like in the example below. (Please change `idDefinition` to the name of your language.)
+
+```javascript
+export function idDefinition() {
+    return {
+        ...
+    }
+}
+```
+
+2. Add the following line to the [`monacoSpecialLanguages.js`](/src/Monaco/monacoSpecialLanguages.js) file, after the other import statements:
+
+```javascript
+import { idDefinition } from './customLanguages/file.js';
+```
+
+> Replace file.js with the name of your definition file from step 1. Please replace idDefinition with the string you used in step 1.
+
+3. In the [`monacoSpecialLanguages.js`](/src/Monaco/monacoSpecialLanguages.js) file add the following line into the `registerAdditionalLanguages` function:
+
+```javascript
+registerAdditionalNewLanguage("id", [".fileExtension"], idDefinition(), monaco)
+```
+
+> Replace id and idDefinition with your id and string used in step 1. Replace fileExtension with a set of file extensions you want the language to register to.
+
+  * The id can be anything. Recommended is one of the file extensions. For example "php" or "reg".
+
+4. In case you wish to add a custom color for a token, you can do so by adding the following line to [`customTokenThemeRules.js`](/src/Monaco/customTokenThemeRules.js):
+```javascript
+{token: 'token-name', foreground: 'ff0000'}
+```
+> Replace `token-name` with the name of the token and `ff0000` with the hex code of the desired color.
+> Note: you can also specify a `background` and a `fontStyle` attribute for your token.
+
+* Keep in mind that these rules apply to all languages. Therefore, you should not change the colors of any default tokens. Instead, create new tokens specific to the language you are adding.
+
+5. Execute the steps described in the [monaco_languages.json](#monaco_languagesjson) section.
+
+### Add a new file extension to an existing language
+
+1. In the [`monacoSpecialLanguages.js`](/src/Monaco/monacoSpecialLanguages.js) file add the following line to the `registerAdditionalLanguages` function. (`existingId` is the id of the language you want to add the extension to. You can find these id's in the [`monaco_languages.json`](/src/Monaco/monaco_languages.json) file):
+
+```javascript
+registerAdditionalLanguage("id", [".fileExtension"], "existingId", monaco)
+```
+
+  * If for instance you want to add more extensions to the php language set the id to `phpExt` and the existingId to `php`.
+
+2. Copy the existing language definition into the `languageDefinitions` function in the same file. You can find the existing definitions in the following folder: [`/src/Monaco/monacoSRC/min/vs/basic-languages/`](/src/Monaco/monacoSRC/min/vs/basic-languages/).
+
+3. Execute the steps described in the [monaco_languages.json](#monaco_languagesjson) section.
+
+### monaco_languages.json
+
+[`monaco_languages.json`](/src/Monaco/monaco_languages.json) contains all extensions and IDs for the languages supported by Monaco. The [`MonacoHelper`](/src/common/FilePreviewCommon/MonacoHelper.cs) class and the installer are using this file to register preview handlers for the defined extensions.
+
+After updating Monaco Editor and/or adding a new language you should update the [`monaco_languages.json`](/src/Monaco/monaco_languages.json) file.
+
+1. Run the [`generateLanguagesJson.html`](/src/Monaco/generateLanguagesJson.html) file on a local webserver (as webbrowsers will block certain needed features when running the file locally.)
+  *  This can for example be achieved by using the [Preview Server](https://marketplace.visualstudio.com/items?itemName=yuichinukiyama.vscode-preview-server) extension for Visual Studio Code: Open the file in Visual Studio Code, right click in the code editor and select `vscode-preview-server: Launch on browser`. The file will be opened in a browser.
+2. The browser will download the new `monaco_languages.json` file
+3. Replace the old file with the newly downloaded one in the source code folder.

doc/devdocs/common/common.md

@@ -0,0 +1,102 @@
+# Classes and structures
+
+> This document is outdated and will soon be renewed.
+
+#### class Animation: [header](/src/common/animation.h) [source](/src/common/animation.cpp)
+Animation helper class with two easing-in animations: linear and exponential.
+
+#### class AsyncMessageQueue: [header](/src/common/async_message_queue.h)
+Header-only asynchronous message queue. Used by `TwoWayPipeMessageIPC`.
+
+#### class TwoWayPipeMessageIPC: [header](/src/common/two_way_pipe_message_ipc.h)
+Header-only asynchronous IPC messaging class. Used by the runner to communicate with the settings window.
+
+#### class DPIAware: [header](/src/common/dpi_aware.h) [source](/src/common/dpi_aware.cpp)
+Helper class for creating DPI-aware applications.
+
+#### struct MonitorInfo: [header](/src/common/monitors.h) [source](/src/common/monitors.cpp)
+Class for obtaining information about physical displays connected to the machine.
+
+#### class Settings, class PowerToyValues, class CustomActionObject: [header](/src/common/settings_objects.h) [source](/src/common/settings_objects.cpp)
+Classes used to define settings screens for the PowerToys modules.
+
+#### class Tasklist: [header](/src/common/tasklist_positions.h) [source](/src/common/tasklist_positions.cpp)
+Class that can detect the position of the windows buttons on the taskbar. It also detects which window will react to pressing `WinKey + number`.
+
+#### struct WindowsColors: [header](/src/common/windows_colors.h) [source](/src/common/windows_colors.cpp)
+Class for detecting the current Windows color scheme.
+
+# Helpers
+
+#### Common helpers: [header](/src/common/common.h) [source](/src/common/common.cpp)
+Various helper functions.
+
+#### Settings helpers: [header](/src/common/settings_helpers.h)
+Helper methods for the settings.
+
+#### Start visible helper: [header](/src/common/start_visible.h) [source](/src/common/start_visible.cpp)
+Contains function to test if the Start menu is visible.
+
+# Toast Notifications
+
+#### Notifications API [header](/src/common/notifications.h) [source](/src/common/notifications.cpp)
+To use UWP-style toast notifications, simply include the header and call one of these functions:
+
+```cpp
+    void show_toast(std::wstring_view message);       // #1
+    
+    void show_toast_background_activated(             // #2
+      std::wstring_view message,
+      std::wstring_view background_handler_id,
+      std::vector<std::wstring_view> button_labels);
+```
+We might add more functions in the future if the need arises, e.g. `show_toast_xml` which will accept raw XML for rich customization.
+
+Description:
+- `#1` is for sending simple notifications without any callbacks or buttons
+- `#2` is capable of showing a toast with multiple buttons and background activation
+- `message` is a plain-text argument
+
+Implement a toast activation handler/callback as a function in [handler_functions.cpp](/src/common/notifications_winrt/handler_functions.cpp) and register its `background_handler_id` via `handlers_map`, e.g.:
+
+```cpp
+// Your .cpp where you'd like to show a toast
+
+#include <common/notifications.h>
+
+void some_func() {
+// ...
+  notifications::show_toast_background_activated(
+    L"Toast message!",                                                  // text displayed in a toast
+    L"awesome_toast",                                                   // activation handler id
+    {L"Press me!", L"Also could press me!", L"I'm here to be pressed!"} // buttons in a toast
+  );
+```
+
+```cpp
+// handler_functions.cpp
+void awesome_toast_handler(IBackgroundTaskInstance, const size_t button_id)
+{
+  switch(button_id)
+  {
+    case 0:
+      // handle "Press me!" button click
+    case 1:
+      // handle "Also could press me!" button click
+    case 2:
+      // handle "I'm here to be pressed!" button click
+  }
+}
+
+namespace
+{
+  const std::unordered_map<std::wstring_view, handler_function_t> handlers_map = {
+    // ...other handlers...
+    {L"awesome_toast", awesome_toast_handler}
+  };}
+
+```
+
+Note: since _background activation_ implies that your toast handler will be invoked in a separate process, you can't share data directly from within a handler and your PT process. Also, since PT is currently a Desktop Bridge app, _foreground activation_ is [handled the same as background](https://learn.microsoft.com/windows/uwp/design/shell/tiles-and-notifications/send-local-toast-desktop-cpp-wrl#foreground-vs-background-activation), therefore we don't make a dedicated API for it. You can read more on the [rationale of the current design](https://github.com/microsoft/PowerToys/pull/1178#issue-368768337).
+
+

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

doc/devdocs/common/monaco-editor.md

@@ -0,0 +1,77 @@
+# Monaco Editor in PowerToys
+
+## Overview
+
+Monaco is the text editor that powers Visual Studio Code. In PowerToys, Monaco is integrated as a component to provide advanced text editing capabilities with features like syntax highlighting, line numbering, and intelligent code editing.
+
+## Where Monaco is Used in PowerToys
+
+Monaco is primarily used in:
+- Registry Preview module - For editing registry files
+- File Preview handlers - For syntax highlighting when previewing code files
+- Peek module - For preview a file
+
+## Technical Implementation
+
+Monaco is embedded into PowerToys' WinUI 3 applications using WebView2. This integration allows PowerToys to leverage Monaco's web-based capabilities within desktop applications.
+
+### Directory Structure
+
+The Monaco editor files are located in the relevant module directories. For example, in Registry Preview, Monaco files are bundled with the application resources.
+
+## Versioning and Updates
+
+### Current Version
+
+The current Monaco version can be found in the `loader.js` file, specifically in the variable named `versionMonaco`.
+
+### Update Process
+
+Updating Monaco requires several steps:
+
+1. Download the latest version of Monaco
+2. Replace/override the main folder with the new version
+3. Generate the new Monaco language JSON file
+4. Override the existing JSON file
+
+For detailed step-by-step instructions, see the [FilePreviewCommon documentation](FilePreviewCommon.md#update-monaco-editor).
+
+#### Estimated Time for Update
+
+The Monaco update process typically takes approximately 30 minutes.
+
+#### Reference PRs
+
+When updating Monaco, you can refer to previous Monaco update PRs as examples, as they mostly involve copy-pasting the Monaco source code with minor adjustments.
+
+## Customizing Monaco
+
+### Adding New Language Definitions
+
+Monaco can be customized to support new language definitions for syntax highlighting:
+
+1. Identify the language you want to add
+2. Create or modify the appropriate language definition files
+3. Update the Monaco configuration to recognize the new language
+
+For detailed instructions on adding language definitions, see the [FilePreviewCommon documentation](FilePreviewCommon.md#add-a-new-language-definition).
+
+### Adding File Extensions to Existing Languages
+
+To make Monaco handle additional file extensions using existing language definitions:
+
+1. Locate the language mapping configuration
+2. Add the new file extension to the appropriate language entry
+3. Update the file extension registry
+
+For detailed instructions on adding file extensions, see the [FilePreviewCommon documentation](FilePreviewCommon.md#add-a-new-file-extension-to-an-existing-language).
+
+Example: If Monaco processes TXT files and you want it to preview LOG files the same way, you can add LOG extensions to the TXT language definition.
+
+## Installer Handling
+
+Monaco source files are managed via a script (`Generate-Monaco-wxs.ps1`) that:
+1. Automatically generates the installer manifest to include all Monaco files
+2. Avoids manually listing all Monaco files in the installer configuration
+
+This approach simplifies maintenance and updates of the Monaco editor within PowerToys.

doc/devdocs/common/readme.md

@@ -0,0 +1,7 @@
+# Common
+
+The [common](/src/common) folder contains projects with code, that is used in multiple projects.
+
+## [FilePreviewCommon](FilePreviewCommon.md)
+
+This project contains common code for file previewing.