Fix WSL distribution quoting and add distro dropdown in Settings UI

- Quote distro names with spaces in BuildWslArgs to prevent shell splitting
- Replace TextBox with ComboBox dropdown populated via 'wsl -l -q'
- Fix StyleCop SA1122 violation in _availableWslDistros initializer

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

.github/actions/spell-check/allow/code.txt

@@ -315,6 +315,7 @@ xef
 xes
 PACKAGEVERSIONNUMBER
 APPXMANIFESTVERSION
+PROGMAN
 
 # MRU lists
 CACHEWRITE
@@ -325,6 +326,14 @@ REGSTR
 # Misc Win32 APIs and PInvokes
 INVOKEIDLIST
 MEMORYSTATUSEX
+ABE
+HTCAPTION
+POSCHANGED
+QUERYPOS
+SETAUTOHIDEBAR
+WINDOWPOS
+WINEVENTPROC
+WORKERW
 
 # PowerRename metadata pattern abbreviations (used in tests and regex patterns)
 DDDD
@@ -349,3 +358,6 @@ nostdin
 # Performance counter keys
 engtype
 Nonpaged
+
+# XAML
+Untargeted

doc/devdocs/modules/advancedpaste-python-scripts.md

@@ -0,0 +1,285 @@
+# Advanced Paste – Python Scripts
+
+Advanced Paste supports user-defined Python scripts that transform clipboard content. Scripts are
+discovered automatically from a configurable folder and appear as actions in the Advanced Paste UI.
+
+## Quick start
+
+1. Open the scripts folder — by default `%LOCALAPPDATA%\Microsoft\PowerToys\AdvancedPaste\Scripts`.
+   You can change this in **Settings → Advanced Paste → Python scripts → Scripts folder**.
+2. Drop a `.py` file into the folder.
+3. Define one `advanced_paste_from_<input>_to_<output>` function (see [Writing a script](#writing-a-script)).
+4. Open the Advanced Paste UI (`Win+Shift+V`) — your script will appear in the action list.
+
+> **Important:** Each `.py` file must define exactly one `advanced_paste_from_<input>_to_<output>`
+> function. Scripts with zero or multiple such functions are ignored.
+
+## Writing a script
+
+You write a single Python function whose **name** declares both what clipboard input it accepts
+and what output type it produces.
+No imports from PowerToys are needed — zero setup, zero dependencies on our side.
+
+### Function naming convention
+
+The function name follows the pattern:
+
+```
+advanced_paste_from_<input>_to_<output>(<param>)
+```
+
+**Input types** (what the function receives):
+
+| Input | Parameter | When it runs |
+|-------|-----------|--------------|
+| `text` | `str` — clipboard text | Clipboard has text |
+| `html` | `str` — clipboard HTML | Clipboard has HTML |
+| `image` | `str` — path to temp image file | Clipboard has an image |
+| `audio` | `str` — path to audio file | Clipboard has an audio file |
+| `video` | `str` — path to video file | Clipboard has a video file |
+| `files` | `list[str]` — file paths | Clipboard has files |
+
+**Output types** (what the function produces — declared via `_to_` suffix):
+
+| Output | Effect |
+|--------|--------|
+| `text` | Sets clipboard to text |
+| `html` | Sets clipboard to HTML |
+| `image` | Sets clipboard to image |
+| `audio` | Sets clipboard to audio file |
+| `video` | Sets clipboard to video file |
+| `file` | Sets clipboard to a file |
+| `files` | Sets clipboard to multiple files |
+
+### Return value
+
+The return value is interpreted according to the declared output type:
+
+| Output type | Expected return value |
+|-------------|---------------------|
+| `text` | `str` (or any value — will be converted via `str()`) |
+| `html` | `str` containing HTML |
+| `image` | `str` or `pathlib.Path` pointing to an image file |
+| `file` | `str` or `pathlib.Path` pointing to a file |
+| `files` | `list` of `str`/`pathlib.Path` file paths |
+
+Returning `None` produces an empty result (no-op).
+
+## Examples
+
+### Minimal — uppercase text
+
+```python
+def advanced_paste_from_text_to_text(text):
+    return text.upper()
+```
+
+That's it. No headers required, no imports from PowerToys.
+
+### With optional metadata
+
+```python
+# @advancedpaste:name   Reverse Text
+# @advancedpaste:desc   Reverses clipboard text character by character
+
+def advanced_paste_from_text_to_text(text):
+    return text[::-1]
+```
+
+### Text to HTML
+
+```python
+# @advancedpaste:name   Markdown Table to HTML
+# @advancedpaste:desc   Convert a markdown table to an HTML table
+
+def advanced_paste_from_text_to_html(text):
+    headers = text.splitlines()[0].split("|")
+    return f"<table><tr>{''.join(f'<th>{h.strip()}</th>' for h in headers if h.strip())}</tr></table>"
+```
+
+### Image to text (OCR)
+
+```python
+# @advancedpaste:requires pytesseract
+
+def advanced_paste_from_image_to_text(image_path):
+    import pytesseract
+    return pytesseract.image_to_string(image_path).strip()
+```
+
+### Save text as file
+
+```python
+import os
+from pathlib import Path
+import tempfile
+
+def advanced_paste_from_text_to_file(text):
+    # Use ADVANCED_PASTE_WORK_DIR for WSL compatibility; falls back to temp dir on Windows.
+    out_dir = os.environ.get("ADVANCED_PASTE_WORK_DIR") or tempfile.gettempdir()
+    out = Path(out_dir) / "clipboard.txt"
+    out.write_text(text, encoding="utf-8")
+    return out
+```
+
+### Image processing (image → image)
+
+```python
+import os
+from PIL import Image
+from pathlib import Path
+import tempfile
+
+def advanced_paste_from_image_to_image(image_path):
+    """Convert image to grayscale."""
+    img = Image.open(image_path).convert("L")
+    out_dir = os.environ.get("ADVANCED_PASTE_WORK_DIR") or tempfile.gettempdir()
+    out = Path(out_dir) / "gray.png"
+    img.save(out)
+    return out
+```
+
+### File listing (files → text)
+
+```python
+import os
+
+def advanced_paste_from_files_to_text(file_paths):
+    lines = []
+    for p in file_paths:
+        size = os.path.getsize(p)
+        lines.append(f"{os.path.basename(p)} ({size} bytes)")
+    return "\n".join(lines)
+```
+
+## Header tags
+
+All header tags are **optional**. Tags are placed in comment lines at the top of the script.
+
+| Tag | Description |
+|-----|-------------|
+| `name` | Display name in the Advanced Paste UI. If omitted, the filename is used. |
+| `desc` | Short description / tooltip. |
+| `disabled` | Presence of this tag disables the script (it won't appear in the UI). |
+| `requires` | Declare Python package dependencies (see [Dependencies](#declaring-dependencies)). |
+
+### Example header
+
+```python
+# @advancedpaste:name   My Formatter
+# @advancedpaste:desc   Formats clipboard text as markdown table
+```
+
+To disable a script without deleting it, add:
+
+```python
+# @advancedpaste:disabled
+```
+
+Remove the line to re-enable.
+
+## Declaring dependencies
+
+Use `requires` to declare Python packages the script needs:
+
+```python
+# @advancedpaste:requires PIL=Pillow
+# @advancedpaste:requires cv2=opencv-python-headless numpy requests
+```
+
+Each token is either:
+
+- **`import_name`** — the pip package is assumed to have the same name (e.g. `requests`).
+- **`import_name=pip_package`** — when the import name differs from the pip package
+  (e.g. `cv2=opencv-python-headless`, `PIL=Pillow`).
+
+### Automatic import detection
+
+Advanced Paste also scans the script body for `import` and `from ... import` statements
+and cross-references them against the Python standard library. Any non-stdlib import
+that is not already installed triggers a prompt to install it automatically.
+
+## Security — script trust
+
+The first time a script is executed (or after it has been modified), Advanced Paste
+shows a confirmation dialog. Upon approval the SHA-256 hash of the script is stored.
+Subsequent runs of the unchanged file skip the dialog.
+
+## Error handling
+
+When a script fails, Advanced Paste extracts the Python traceback from stderr and
+displays a user-friendly summary in the UI:
+
+- **ModuleNotFoundError** — identifies the missing module and suggests installing it.
+- **SyntaxError** — shows the file and line number.
+- **Timeout** — shows the configured timeout value (default 30 s; configurable in Settings).
+- **Other errors** — shows the last line of the traceback as a summary, with the full
+  traceback available in the expandable *Details* section.
+
+## Settings
+
+The Python scripts feature uses a **mode selector** (dropdown) with three options:
+
+| Mode | Description |
+|------|-------------|
+| **Disabled** | Python scripts are not active. |
+| **Windows** | Scripts run using a native Windows Python interpreter. |
+| **WSL** | Scripts run inside Windows Subsystem for Linux. |
+
+Each mode maintains its own independent settings (scripts folder, interpreter path, etc.),
+so switching between Windows and WSL does not lose your previous configuration.
+
+### Windows mode settings
+
+| Setting | Description | Default |
+|---------|-------------|---------|
+| Scripts folder | Folder to scan for `.py` scripts. | `%LOCALAPPDATA%\Microsoft\PowerToys\AdvancedPaste\Scripts` |
+| Python interpreter | Path to the Python executable. Leave blank for auto-detection. | *(auto-detect)* |
+
+### WSL mode settings
+
+| Setting | Description | Default |
+|---------|-------------|---------|
+| Scripts folder | Folder to scan for `.py` scripts (Windows path — auto-translated to `/mnt/...`). | `%LOCALAPPDATA%\Microsoft\PowerToys\AdvancedPaste\Scripts` |
+| WSL distribution | Which WSL distro to use (e.g. `Ubuntu`). Leave blank for the default distribution. | *(default)* |
+
+### Scripts list
+
+The Settings page shows a read-only list of discovered scripts. For each script you can see:
+
+- **Name** — from `@advancedpaste:name` tag, or the filename if not set.
+- **Description** — from `@advancedpaste:desc` tag.
+- **Conversion** — the input → output types detected from the function name (e.g. "text → image").
+
+The list is **not editable** from Settings. To change a script's name, description, enabled state,
+or any other metadata, open the script file directly (click the "Open in editor" button) and edit
+the `# @advancedpaste:...` header tags. After saving, click **Refresh** in Settings to reload.
+
+### WSL mode details
+
+When **WSL** mode is selected:
+
+- Scripts are executed via `wsl.exe bash -l -c "python3 ..."` using the configured distribution.
+- The scripts folder remains on the Windows filesystem; paths are automatically translated
+  to `/mnt/c/...` format for WSL access.
+- Package installation uses `pip3 install` inside the WSL environment.
+- Output files from scripts must be written under `/mnt/` (the Windows-mounted filesystem)
+  so they can be accessed from Windows. The runner sets the `ADVANCED_PASTE_WORK_DIR` environment
+  variable to a temp directory under `/mnt/c/...` — use it instead of `tempfile.gettempdir()`
+  when producing file output for cross-platform compatibility.
+
+> **Tip:** If you have Python installed only in WSL (not on Windows), select WSL mode
+> to use your existing WSL Python environment with all its packages.
+
+## Tips
+
+- Each `.py` file must contain exactly one `advanced_paste_from_<input>_to_<output>` function.
+  If you need to handle multiple input types, create separate script files for each.
+- A `.py` file without any matching function is ignored — use this for helper modules
+  that other scripts can import.
+- Scripts can be tested from the command line:
+  ```
+  echo {"format":["text"],"text":"hello"} | python _runner.py my_script.py
+  ```
+- The script's directory is added to `sys.path` at runtime, so you can import sibling `.py`
+  files as helper modules.

src/common/ManagedCommon/ColorFormatHelper.cs

@@ -515,8 +515,7 @@ namespace ManagedCommon
                     return lightnessL.ToString(CultureInfo.InvariantCulture);
                 case "Lc":
                     var (lightnessC, _, _) = ConvertToCIELABColor(color);
-                    lightnessC = Math.Round(lightnessC, 2);
-                    return lightnessC.ToString(CultureInfo.InvariantCulture);
+                    return ColorPercentFormatted(lightnessC, paramFormat, 2);
                 case "Lo":
                     var (lightnessO, _, _) = ConvertToOklabColor(color);
                     lightnessO = Math.Round(lightnessO, 2);
@@ -531,12 +530,10 @@ namespace ManagedCommon
                     return blackness.ToString(CultureInfo.InvariantCulture);
                 case "Ca":
                     var (_, chromaticityA, _) = ConvertToCIELABColor(color);
-                    chromaticityA = Math.Round(chromaticityA, 2);
-                    return chromaticityA.ToString(CultureInfo.InvariantCulture);
+                    return ColorPercentFormatted(chromaticityA, paramFormat, 2);
                 case "Cb":
                     var (_, _, chromaticityB) = ConvertToCIELABColor(color);
-                    chromaticityB = Math.Round(chromaticityB, 2);
-                    return chromaticityB.ToString(CultureInfo.InvariantCulture);
+                    return ColorPercentFormatted(chromaticityB, paramFormat, 2);
                 case "Oa":
                     var (_, chromaticityAOklab, _) = ConvertToOklabColor(color);
                     chromaticityAOklab = Math.Round(chromaticityAOklab, 2);
@@ -595,6 +592,24 @@ namespace ManagedCommon
             }
         }
 
+        private static string ColorPercentFormatted(double colorPercentValue, char paramFormat, int defaultDecimalDigits)
+        {
+            switch (paramFormat)
+            {
+                case 'i':
+                    double roundedColorPercentValue = Math.Round(colorPercentValue);
+                    if (roundedColorPercentValue == 0)
+                    {
+                        // convert -0 to 0
+                        roundedColorPercentValue = 0.0;
+                    }
+
+                    return roundedColorPercentValue.ToString(CultureInfo.InvariantCulture);
+                default:
+                    return Math.Round(colorPercentValue, defaultDecimalDigits).ToString(CultureInfo.InvariantCulture);
+            }
+        }
+
         public static string GetDefaultFormat(string formatName)
         {
             switch (formatName)

src/modules/AdvancedPaste/AdvancedPaste.UnitTests/Mocks/IntegrationTestUserSettings.cs

@@ -57,6 +57,22 @@ internal sealed class IntegrationTestUserSettings : IUserSettings
 
     public PasteAIConfiguration PasteAIConfiguration => _configuration;
 
+    public IReadOnlyList<AdvancedPastePythonScriptAction> PythonScriptActions => Array.Empty<AdvancedPastePythonScriptAction>();
+
+    public string PythonScriptsFolder => string.Empty;
+
+    public string PythonExecutablePath => string.Empty;
+
+    public bool PythonUseWsl => false;
+
+    public string PythonWslDistribution => string.Empty;
+
+    public int PythonScriptTimeoutSeconds => 30;
+
+    public bool IsPythonScriptsEnabled => true;
+
+    public IReadOnlyDictionary<string, string> TrustedScriptHashes => new Dictionary<string, string>();
+
     public event EventHandler Changed;
 
     public Task SetActiveAIProviderAsync(string providerId)
@@ -65,4 +81,8 @@ internal sealed class IntegrationTestUserSettings : IUserSettings
         Changed?.Invoke(this, EventArgs.Empty);
         return Task.CompletedTask;
     }
+
+    public void StoreTrustedScriptHash(string scriptPath, string hash)
+    {
+    }
 }

src/modules/AdvancedPaste/AdvancedPaste.UnitTests/ServicesTests/PythonScriptServiceTests.cs

@@ -0,0 +1,560 @@
+// 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.IO;
+using System.Linq;
+
+using AdvancedPaste.Helpers;
+using AdvancedPaste.Services.PythonScripts;
+using AdvancedPaste.UnitTests.Mocks;
+using Microsoft.VisualStudio.TestTools.UnitTesting;
+
+namespace AdvancedPaste.UnitTests.ServicesTests;
+
+[TestClass]
+public sealed class PythonScriptServiceTests
+{
+    private PythonScriptService _service;
+
+    [TestInitialize]
+    public void Setup()
+    {
+        _service = new PythonScriptService(new IntegrationTestUserSettings());
+    }
+
+    [TestMethod]
+    public void MergeWithAutoDetectedImports_DetectsSimpleImports()
+    {
+        var lines = new[]
+        {
+            "# @advancedpaste:name test",
+            "import requests",
+            "import numpy",
+            "import os",
+            "import sys",
+        };
+
+        var result = PythonScriptService.MergeWithAutoDetectedImports(lines, []);
+
+        Assert.AreEqual(2, result.Count); // requests + numpy; os and sys are stdlib
+        Assert.IsTrue(result.Any(r => r.ImportName == "requests" && r.PipPackage == "requests"));
+        Assert.IsTrue(result.Any(r => r.ImportName == "numpy" && r.PipPackage == "numpy"));
+    }
+
+    [TestMethod]
+    public void MergeWithAutoDetectedImports_DetectsFromImports()
+    {
+        var lines = new[]
+        {
+            "from PIL import Image",
+            "from markitdown import MarkItDown",
+        };
+
+        var result = PythonScriptService.MergeWithAutoDetectedImports(lines, []);
+
+        Assert.AreEqual(2, result.Count);
+        Assert.IsTrue(result.Any(r => r.ImportName == "PIL" && r.PipPackage == "Pillow"));
+        Assert.IsTrue(result.Any(r => r.ImportName == "markitdown" && r.PipPackage == "markitdown"));
+    }
+
+    [TestMethod]
+    public void MergeWithAutoDetectedImports_WellKnownMappings()
+    {
+        var lines = new[]
+        {
+            "import cv2",
+            "import win32clipboard",
+            "import yaml",
+        };
+
+        var result = PythonScriptService.MergeWithAutoDetectedImports(lines, []);
+
+        Assert.AreEqual(3, result.Count);
+        Assert.IsTrue(result.Any(r => r.ImportName == "cv2" && r.PipPackage == "opencv-python"));
+        Assert.IsTrue(result.Any(r => r.ImportName == "win32clipboard" && r.PipPackage == "pywin32"));
+        Assert.IsTrue(result.Any(r => r.ImportName == "yaml" && r.PipPackage == "PyYAML"));
+    }
+
+    [TestMethod]
+    public void MergeWithAutoDetectedImports_ExplicitRequirementsTakePrecedence()
+    {
+        var lines = new[]
+        {
+            "import cv2",
+            "import requests",
+        };
+
+        var explicitReqs = new List<PythonRequirement>
+        {
+            new("cv2", "opencv-python-headless"),
+        };
+
+        var result = PythonScriptService.MergeWithAutoDetectedImports(lines, explicitReqs);
+
+        Assert.AreEqual(2, result.Count);
+
+        // cv2 should use the explicit pip package name, not the well-known mapping
+        var cv2Req = result.First(r => r.ImportName == "cv2");
+        Assert.AreEqual("opencv-python-headless", cv2Req.PipPackage);
+
+        // requests should be auto-detected
+        Assert.IsTrue(result.Any(r => r.ImportName == "requests"));
+    }
+
+    [TestMethod]
+    public void MergeWithAutoDetectedImports_SkipsStdlib()
+    {
+        var lines = new[]
+        {
+            "import os",
+            "import sys",
+            "import json",
+            "import io",
+            "import pathlib",
+            "import tempfile",
+            "import subprocess",
+        };
+
+        var result = PythonScriptService.MergeWithAutoDetectedImports(lines, []);
+
+        Assert.AreEqual(0, result.Count);
+    }
+
+    [TestMethod]
+    public void MergeWithAutoDetectedImports_SkipsComments()
+    {
+        var lines = new[]
+        {
+            "# import requests",
+            "# from PIL import Image",
+            "import json",
+        };
+
+        var result = PythonScriptService.MergeWithAutoDetectedImports(lines, []);
+
+        Assert.AreEqual(0, result.Count);
+    }
+
+    [TestMethod]
+    public void MergeWithAutoDetectedImports_HandlesMultipleImportsOnOneLine()
+    {
+        var lines = new[]
+        {
+            "import requests, numpy, pandas",
+        };
+
+        var result = PythonScriptService.MergeWithAutoDetectedImports(lines, []);
+
+        Assert.AreEqual(3, result.Count);
+        Assert.IsTrue(result.Any(r => r.ImportName == "requests"));
+        Assert.IsTrue(result.Any(r => r.ImportName == "numpy"));
+        Assert.IsTrue(result.Any(r => r.ImportName == "pandas"));
+    }
+
+    [TestMethod]
+    public void MergeWithAutoDetectedImports_HandlesSubmoduleImport()
+    {
+        var lines = new[]
+        {
+            "import win32com.client",
+            "from llama_cpp import Llama",
+        };
+
+        var result = PythonScriptService.MergeWithAutoDetectedImports(lines, []);
+
+        Assert.AreEqual(2, result.Count);
+        Assert.IsTrue(result.Any(r => r.ImportName == "win32com" && r.PipPackage == "pywin32"));
+        Assert.IsTrue(result.Any(r => r.ImportName == "llama_cpp" && r.PipPackage == "llama-cpp-python"));
+    }
+
+    [TestMethod]
+    public void ParsePythonError_ModuleNotFoundError()
+    {
+        var stderr = """
+            Traceback (most recent call last):
+              File "C:\scripts\reverse.py", line 4, in <module>
+                import win32clipboard
+            ModuleNotFoundError: No module named 'win32clipboard'
+            """;
+
+        var (summary, details) = PythonScriptService.ParsePythonError(stderr);
+
+        Assert.IsTrue(summary.Contains("reverse.py"), $"Summary should mention the script: {summary}");
+        Assert.IsTrue(summary.Contains("line 4"), $"Summary should mention the line: {summary}");
+        Assert.IsTrue(summary.Contains("win32clipboard"), $"Summary should mention the module: {summary}");
+        Assert.IsTrue(summary.Contains("pywin32"), $"Summary should suggest pip package: {summary}");
+        Assert.IsTrue(!string.IsNullOrEmpty(details));
+    }
+
+    [TestMethod]
+    public void ParsePythonError_SyntaxError()
+    {
+        var stderr = """
+            File "test.py", line 5
+                def foo(
+                       ^
+            SyntaxError: unexpected EOF while parsing
+            """;
+
+        var (summary, details) = PythonScriptService.ParsePythonError(stderr);
+
+        Assert.IsTrue(summary.Contains("test.py"), $"Summary should mention the script: {summary}");
+        Assert.IsTrue(summary.Contains("line 5"), $"Summary should mention the line: {summary}");
+        Assert.IsTrue(summary.Contains("Python syntax error:"), $"Summary: {summary}");
+        Assert.IsTrue(!string.IsNullOrEmpty(details));
+    }
+
+    [TestMethod]
+    public void ParsePythonError_SyntaxErrorWithColumn()
+    {
+        var stderr = "  File \"script.py\", line 3\n    x = (1 +\n        ^\nSyntaxError: '(' was never closed\n";
+
+        var (summary, details) = PythonScriptService.ParsePythonError(stderr);
+
+        Assert.IsTrue(summary.Contains("script.py"), $"Summary should mention the script: {summary}");
+        Assert.IsTrue(summary.Contains("line 3"), $"Summary should mention the line: {summary}");
+        Assert.IsTrue(summary.Contains("col"), $"Summary should mention the column: {summary}");
+        Assert.IsTrue(summary.Contains("Python syntax error:"), $"Summary: {summary}");
+        Assert.IsTrue(!string.IsNullOrEmpty(details));
+    }
+
+    [TestMethod]
+    public void ParsePythonError_GenericError()
+    {
+        var stderr = """
+            Traceback (most recent call last):
+              File "test.py", line 10, in <module>
+                result = 1 / 0
+            ZeroDivisionError: division by zero
+            """;
+
+        var (summary, details) = PythonScriptService.ParsePythonError(stderr);
+
+        Assert.IsTrue(summary.Contains("test.py"), $"Summary should mention the script: {summary}");
+        Assert.IsTrue(summary.Contains("line 10"), $"Summary should mention the line: {summary}");
+        Assert.IsTrue(summary.Contains("ZeroDivisionError"), $"Summary: {summary}");
+        Assert.IsTrue(!string.IsNullOrEmpty(details));
+    }
+
+    [TestMethod]
+    public void ParsePythonError_NestedTraceback_ShowsLastFrame()
+    {
+        var stderr = """
+            Traceback (most recent call last):
+              File "main.py", line 5, in <module>
+                helper()
+              File "helper.py", line 12, in helper
+                do_work()
+              File "worker.py", line 8, in do_work
+                raise RuntimeError("bad state")
+            RuntimeError: bad state
+            """;
+
+        var (summary, details) = PythonScriptService.ParsePythonError(stderr);
+
+        Assert.IsTrue(summary.Contains("worker.py"), $"Summary should mention the last script in the chain: {summary}");
+        Assert.IsTrue(summary.Contains("line 8"), $"Summary should mention the line of the last frame: {summary}");
+        Assert.IsTrue(summary.Contains("bad state"), $"Summary should contain the error message: {summary}");
+    }
+
+    [TestMethod]
+    public void ParsePythonError_EmptyStderr()
+    {
+        var (summary, details) = PythonScriptService.ParsePythonError(string.Empty);
+
+        Assert.IsTrue(!string.IsNullOrEmpty(summary));
+        Assert.AreEqual(string.Empty, details);
+    }
+
+    [TestMethod]
+    public void ParsePythonError_NoTraceback_PlainStderr()
+    {
+        var stderr = "Something went wrong in the script\n";
+
+        var (summary, details) = PythonScriptService.ParsePythonError(stderr);
+
+        // No File "..." reference, so no location — just the message
+        Assert.IsTrue(summary.Contains("Something went wrong"), $"Summary: {summary}");
+        Assert.IsFalse(summary.Contains("line"), $"Summary should not contain 'line' without a traceback: {summary}");
+    }
+
+    [TestMethod]
+    public void ExtractLastTracebackLocation_BasicTraceback()
+    {
+        var lines = new[]
+        {
+            "Traceback (most recent call last):",
+            "  File \"script.py\", line 10, in <module>",
+            "    result = 1 / 0",
+            "ZeroDivisionError: division by zero",
+        };
+
+        var location = PythonScriptService.ExtractLastTracebackLocation(lines);
+
+        Assert.IsNotNull(location);
+        Assert.AreEqual("script.py", location.Value.FileName);
+        Assert.AreEqual(10, location.Value.Line);
+        Assert.IsNull(location.Value.Column);
+    }
+
+    [TestMethod]
+    public void ExtractLastTracebackLocation_WithCaret()
+    {
+        var lines = new[]
+        {
+            "  File \"test.py\", line 5",
+            "    def foo(",
+            "           ^",
+            "SyntaxError: unexpected EOF while parsing",
+        };
+
+        var location = PythonScriptService.ExtractLastTracebackLocation(lines);
+
+        Assert.IsNotNull(location);
+        Assert.AreEqual("test.py", location.Value.FileName);
+        Assert.AreEqual(5, location.Value.Line);
+        Assert.IsNotNull(location.Value.Column);
+    }
+
+    [TestMethod]
+    public void ExtractLastTracebackLocation_FullPath_ReturnsBasename()
+    {
+        var lines = new[]
+        {
+            "Traceback (most recent call last):",
+            "  File \"C:\\Users\\user\\scripts\\my_script.py\", line 42, in <module>",
+            "    some_call()",
+            "ValueError: invalid value",
+        };
+
+        var location = PythonScriptService.ExtractLastTracebackLocation(lines);
+
+        Assert.IsNotNull(location);
+        Assert.AreEqual("my_script.py", location.Value.FileName);
+        Assert.AreEqual(42, location.Value.Line);
+    }
+
+    [TestMethod]
+    public void ExtractLastTracebackLocation_NoFileLine_ReturnsNull()
+    {
+        var lines = new[]
+        {
+            "Some random error output",
+            "No traceback here",
+        };
+
+        var location = PythonScriptService.ExtractLastTracebackLocation(lines);
+
+        Assert.IsNull(location);
+    }
+
+    [TestMethod]
+    public void ParsePipInstallError_ExtractsErrorLine()
+    {
+        var stderr = """
+            Collecting some-package
+              Downloading some-package-1.0.tar.gz (15 kB)
+            ERROR: Could not find a version that satisfies the requirement some-package (from versions: none)
+            ERROR: No matching distribution found for some-package
+            """;
+
+        var (summary, fullStderr) = PythonScriptService.ParsePipInstallError(stderr);
+
+        Assert.IsTrue(summary.Contains("No matching distribution"), $"Summary should contain the last ERROR line: {summary}");
+        Assert.IsTrue(!string.IsNullOrEmpty(fullStderr));
+    }
+
+    [TestMethod]
+    public void ParsePipInstallError_NoErrorPrefix_UsesLastLine()
+    {
+        var stderr = "permission denied: /usr/lib/python3/dist-packages\n";
+
+        var (summary, fullStderr) = PythonScriptService.ParsePipInstallError(stderr);
+
+        Assert.IsTrue(summary.Contains("permission denied"), $"Summary: {summary}");
+        Assert.IsTrue(!string.IsNullOrEmpty(fullStderr));
+    }
+
+    [TestMethod]
+    public void ParsePipInstallError_EmptyStderr()
+    {
+        var (summary, fullStderr) = PythonScriptService.ParsePipInstallError(string.Empty);
+
+        Assert.AreEqual("unknown error", summary);
+        Assert.AreEqual(string.Empty, fullStderr);
+    }
+
+    [TestMethod]
+    public void ReadMetadata_FunctionNameDeterminesFormat_Text()
+    {
+        // The new interface uses function names like advanced_paste_from_text_to_text(...)
+        // to determine supported formats, not parameter signatures.
+        var scriptPath = CreateTempScript("def advanced_paste_from_text_to_text(text):\n    return text.upper()\n");
+        var metadata = _service.ReadMetadata(scriptPath);
+
+        Assert.IsNotNull(metadata);
+        Assert.AreEqual(Models.ClipboardFormat.Text, metadata.SupportedFormats);
+        Assert.AreEqual("text", metadata.OutputTypeHint);
+        File.Delete(scriptPath);
+    }
+
+    [TestMethod]
+    public void ReadMetadata_FunctionNameDeterminesFormat_Html()
+    {
+        var scriptPath = CreateTempScript("def advanced_paste_from_html_to_text(html: str) -> str:\n    return html\n");
+        var metadata = _service.ReadMetadata(scriptPath);
+
+        Assert.IsNotNull(metadata);
+        Assert.AreEqual(Models.ClipboardFormat.Html, metadata.SupportedFormats);
+        Assert.AreEqual("text", metadata.OutputTypeHint);
+        File.Delete(scriptPath);
+    }
+
+    [TestMethod]
+    public void ReadMetadata_FunctionNameDeterminesFormat_Image()
+    {
+        var scriptPath = CreateTempScript("def advanced_paste_from_image_to_text(image_path):\n    return 'desc'\n");
+        var metadata = _service.ReadMetadata(scriptPath);
+
+        Assert.IsNotNull(metadata);
+        Assert.AreEqual(Models.ClipboardFormat.Image, metadata.SupportedFormats);
+        Assert.AreEqual("text", metadata.OutputTypeHint);
+        File.Delete(scriptPath);
+    }
+
+    [TestMethod]
+    public void ReadMetadata_FunctionNameDeterminesFormat_Files()
+    {
+        var scriptPath = CreateTempScript("def advanced_paste_from_files_to_text(file_paths):\n    return ''\n");
+        var metadata = _service.ReadMetadata(scriptPath);
+
+        Assert.IsNotNull(metadata);
+        Assert.AreEqual(Models.ClipboardFormat.File, metadata.SupportedFormats);
+        Assert.AreEqual("text", metadata.OutputTypeHint);
+        File.Delete(scriptPath);
+    }
+
+    [TestMethod]
+    public void ReadMetadata_OutputTypeHint_Image()
+    {
+        var scriptPath = CreateTempScript("def advanced_paste_from_text_to_image(text):\n    return '/path/img.png'\n");
+        var metadata = _service.ReadMetadata(scriptPath);
+
+        Assert.IsNotNull(metadata);
+        Assert.AreEqual("image", metadata.OutputTypeHint);
+        File.Delete(scriptPath);
+    }
+
+    [TestMethod]
+    public void ReadMetadata_OutputTypeHint_File()
+    {
+        var scriptPath = CreateTempScript("def advanced_paste_from_text_to_file(text):\n    return '/path/out.txt'\n");
+        var metadata = _service.ReadMetadata(scriptPath);
+
+        Assert.IsNotNull(metadata);
+        Assert.AreEqual("file", metadata.OutputTypeHint);
+        File.Delete(scriptPath);
+    }
+
+    [TestMethod]
+    public void ReadMetadata_OutputTypeHint_Files()
+    {
+        var scriptPath = CreateTempScript("def advanced_paste_from_files_to_files(file_paths):\n    return file_paths\n");
+        var metadata = _service.ReadMetadata(scriptPath);
+
+        Assert.IsNotNull(metadata);
+        Assert.AreEqual("files", metadata.OutputTypeHint);
+        File.Delete(scriptPath);
+    }
+
+    [TestMethod]
+    public void ReadMetadata_RejectsMultipleFunctions()
+    {
+        var scriptPath = CreateTempScript(
+            "def advanced_paste_from_text_to_text(text):\n    return text\n\n" +
+            "def advanced_paste_from_html_to_text(html):\n    return html\n");
+        var metadata = _service.ReadMetadata(scriptPath);
+
+        Assert.IsNull(metadata);
+        File.Delete(scriptPath);
+    }
+
+    [TestMethod]
+    public void ReadMetadata_RejectsNoFunction()
+    {
+        var scriptPath = CreateTempScript("def some_other_function(text):\n    return text\n");
+        var metadata = _service.ReadMetadata(scriptPath);
+
+        Assert.IsNull(metadata);
+        File.Delete(scriptPath);
+    }
+
+    [TestMethod]
+    public void ReadMetadata_RejectsOldFormatWithoutTo()
+    {
+        // Old format (advanced_paste_from_text without _to_) should be rejected.
+        var scriptPath = CreateTempScript("def advanced_paste_from_text(text):\n    return text\n");
+        var metadata = _service.ReadMetadata(scriptPath);
+
+        Assert.IsNull(metadata);
+        File.Delete(scriptPath);
+    }
+
+    [TestMethod]
+    public void ReadMetadata_FunctionNameDeterminesFormat_Audio()
+    {
+        var scriptPath = CreateTempScript("def advanced_paste_from_audio_to_text(audio_path):\n    return 'transcribed'\n");
+        var metadata = _service.ReadMetadata(scriptPath);
+
+        Assert.IsNotNull(metadata);
+        Assert.AreEqual(Models.ClipboardFormat.Audio, metadata.SupportedFormats);
+        Assert.AreEqual("text", metadata.OutputTypeHint);
+        File.Delete(scriptPath);
+    }
+
+    [TestMethod]
+    public void ReadMetadata_FunctionNameDeterminesFormat_Video()
+    {
+        var scriptPath = CreateTempScript("def advanced_paste_from_video_to_text(video_path):\n    return 'description'\n");
+        var metadata = _service.ReadMetadata(scriptPath);
+
+        Assert.IsNotNull(metadata);
+        Assert.AreEqual(Models.ClipboardFormat.Video, metadata.SupportedFormats);
+        Assert.AreEqual("text", metadata.OutputTypeHint);
+        File.Delete(scriptPath);
+    }
+
+    [TestMethod]
+    public void ReadMetadata_OutputTypeHint_Audio()
+    {
+        var scriptPath = CreateTempScript("def advanced_paste_from_text_to_audio(text):\n    return '/path/out.mp3'\n");
+        var metadata = _service.ReadMetadata(scriptPath);
+
+        Assert.IsNotNull(metadata);
+        Assert.AreEqual(Models.ClipboardFormat.Text, metadata.SupportedFormats);
+        Assert.AreEqual("audio", metadata.OutputTypeHint);
+        File.Delete(scriptPath);
+    }
+
+    [TestMethod]
+    public void ReadMetadata_OutputTypeHint_Video()
+    {
+        var scriptPath = CreateTempScript("def advanced_paste_from_text_to_video(text):\n    return '/path/out.mp4'\n");
+        var metadata = _service.ReadMetadata(scriptPath);
+
+        Assert.IsNotNull(metadata);
+        Assert.AreEqual(Models.ClipboardFormat.Text, metadata.SupportedFormats);
+        Assert.AreEqual("video", metadata.OutputTypeHint);
+        File.Delete(scriptPath);
+    }
+
+    private static string CreateTempScript(string content)
+    {
+        var path = Path.Combine(Path.GetTempPath(), $"test_script_{Guid.NewGuid():N}.py");
+        File.WriteAllText(path, content);
+        return path;
+    }
+}

src/modules/AdvancedPaste/AdvancedPaste/AdvancedPaste.csproj

@@ -155,5 +155,9 @@
     <Content Include="Assets\AdvancedPaste\SemanticKernel.svg">
       <CopyToOutputDirectory>PreserveNewest</CopyToOutputDirectory>
     </Content>
+
+    <Content Include="Services\PythonScripts\_runner.py">
+      <CopyToOutputDirectory>PreserveNewest</CopyToOutputDirectory>
+    </Content>
   </ItemGroup>
 </Project>

src/modules/AdvancedPaste/AdvancedPaste/AdvancedPasteXAML/App.xaml.cs

@@ -14,6 +14,7 @@ using AdvancedPaste.Helpers;
 using AdvancedPaste.Models;
 using AdvancedPaste.Services;
 using AdvancedPaste.Services.CustomActions;
+using AdvancedPaste.Services.PythonScripts;
 using AdvancedPaste.Settings;
 using AdvancedPaste.ViewModels;
 using ManagedCommon;
@@ -83,6 +84,8 @@ namespace AdvancedPaste
                 services.AddSingleton<IPasteAIProviderFactory, PasteAIProviderFactory>();
                 services.AddSingleton<ICustomActionTransformService, CustomActionTransformService>();
                 services.AddSingleton<IKernelService, AdvancedAIKernelService>();
+                services.AddSingleton<IPythonScriptService, PythonScriptService>();
+                services.AddSingleton<IPythonScriptTrustService, PythonScriptTrustService>();
                 services.AddSingleton<IPasteFormatExecutor, PasteFormatExecutor>();
                 services.AddSingleton<OptionsViewModel>();
             }).Build();

src/modules/AdvancedPaste/AdvancedPaste/AdvancedPasteXAML/Controls/PromptBox.xaml

@@ -755,63 +755,7 @@
                 <animations:OpacityAnimation To="0.0" Duration="0:0:0.167" />
             </animations:Implicit.HideAnimations>
         </TextBlock>
-        <Grid
-            x:Name="ErrorMessageGrid"
-            x:Uid="ErrorMessageGrid"
-            Grid.Row="1"
-            Margin="8,8,0,0"
-            ColumnSpacing="8"
-            Visibility="Collapsed">
-            <Grid.ColumnDefinitions>
-                <ColumnDefinition Width="Auto" />
-                <ColumnDefinition Width="*" />
-            </Grid.ColumnDefinitions>
-            <StackPanel Grid.Column="0" Orientation="Horizontal">
-                <ToolTipService.ToolTip>
-                    <ToolTip VerticalOffset="-105" Visibility="{x:Bind ViewModel.PasteActionError.HasDetails, Mode=OneWay, Converter={StaticResource BoolToVisibilityConverter}}">
-                        <StackPanel
-                            MinWidth="300"
-                            HorizontalAlignment="Stretch"
-                            Orientation="Vertical">
-                            <TextBox
-                                x:Name="AIErrorMessage"
-                                x:Uid="AIErrorMessage"
-                                FontSize="12"
-                                IsReadOnly="True"
-                                Text="{x:Bind ViewModel.PasteActionError.Details, Mode=OneWay}"
-                                TextWrapping="Wrap" />
-                        </StackPanel>
-                    </ToolTip>
-                </ToolTipService.ToolTip>
-                <FontIcon
-                    Margin="0,3,3,0"
-                    VerticalAlignment="Top"
-                    FontSize="12"
-                    Foreground="{ThemeResource AccentTextFillColorPrimaryBrush}"
-                    Glyph="&#xE946;"
-                    Visibility="{x:Bind ViewModel.PasteActionError.HasDetails, Mode=OneWay, Converter={StaticResource BoolToVisibilityConverter}}" />
-                <TextBlock
-                    FontWeight="SemiBold"
-                    Foreground="{ThemeResource SystemFillColorCriticalBrush}"
-                    Style="{StaticResource CaptionTextBlockStyle}"
-                    Text="{x:Bind ViewModel.PasteActionError.Text, Mode=OneWay}" />
-            </StackPanel>
-            <HyperlinkButton
-                x:Uid="SettingsBtn"
-                Grid.Column="1"
-                Margin="0,-1,0,0"
-                Padding="0"
-                HorizontalAlignment="Left"
-                VerticalAlignment="Top"
-                Command="{x:Bind ViewModel.OpenSettingsCommand}"
-                FontSize="12" />
-            <animations:Implicit.ShowAnimations>
-                <animations:OpacityAnimation To="1.0" Duration="0:0:0.6" />
-            </animations:Implicit.ShowAnimations>
-            <animations:Implicit.HideAnimations>
-                <animations:OpacityAnimation To="0.0" Duration="0:0:0.167" />
-            </animations:Implicit.HideAnimations>
-        </Grid>
+        <!--  Error message grid moved to MainPage.xaml so it remains enabled when PromptBox is disabled  -->
         <VisualStateManager.VisualStateGroups>
             <VisualStateGroup x:Name="CommonStates">
                 <VisualState x:Name="DefaultState" />
@@ -832,7 +776,6 @@
                     <VisualState.Setters>
                         <Setter Target="InputTxtBox.BorderBrush" Value="{ThemeResource SystemFillColorCriticalBrush}" />
                         <Setter Target="DisclaimerPresenter.Visibility" Value="Collapsed" />
-                        <Setter Target="ErrorMessageGrid.Visibility" Value="Visible" />
                     </VisualState.Setters>
                 </VisualState>
             </VisualStateGroup>

src/modules/AdvancedPaste/AdvancedPaste/AdvancedPasteXAML/MainWindow.xaml.cs

@@ -43,7 +43,8 @@ namespace AdvancedPaste
                 double GetHeight(int maxCustomActionCount) =>
                     baseHeight +
                     new PasteFormatsToHeightConverter().GetHeight(coreActionCount + _userSettings.AdditionalActions.Count) +
-                    new PasteFormatsToHeightConverter() { MaxItems = maxCustomActionCount }.GetHeight(_optionsViewModel.IsCustomAIServiceEnabled ? _userSettings.CustomActions.Count : 0);
+                    new PasteFormatsToHeightConverter() { MaxItems = maxCustomActionCount }.GetHeight(_optionsViewModel.IsCustomAIServiceEnabled ? _userSettings.CustomActions.Count : 0) +
+                    new PasteFormatsToHeightConverter() { MaxItems = maxCustomActionCount }.GetHeight(_optionsViewModel.PythonScriptPasteFormats.Count);
 
                 MinHeight = GetHeight(1);
                 Height = GetHeight(5);
@@ -59,6 +60,7 @@ namespace AdvancedPaste
                     UpdateHeight();
                 }
             };
+            _optionsViewModel.PythonScriptPasteFormats.CollectionChanged += (_, _) => UpdateHeight();
 
             AppWindow.SetIcon("Assets/AdvancedPaste/AdvancedPaste.ico");
             this.ExtendsContentIntoTitleBar = true;
@@ -141,11 +143,7 @@ namespace AdvancedPaste
         internal void FinishLoading(bool success)
         {
             MainPage.CustomFormatTextBox.IsLoading(false);
-
-            if (success)
-            {
-                VisualStateManager.GoToState(MainPage.CustomFormatTextBox, "DefaultState", true);
-            }
+            VisualStateManager.GoToState(MainPage.CustomFormatTextBox, "DefaultState", true);
         }
     }
 }

src/modules/AdvancedPaste/AdvancedPaste/AdvancedPasteXAML/Pages/MainPage.xaml

@@ -144,6 +144,7 @@
     </Page.KeyboardAccelerators>
     <Grid>
         <Grid.RowDefinitions>
+            <RowDefinition Height="Auto" />
             <RowDefinition Height="Auto" />
             <RowDefinition Height="Auto" />
             <RowDefinition Height="*" />
@@ -250,10 +251,12 @@
             Grid.Row="1"
             Margin="20,0,20,0"
             x:FieldModifier="public"
-            IsEnabled="{x:Bind ViewModel.IsCustomAIServiceEnabled, Mode=OneWay}"
+            IsEnabled="True"
             TabIndex="0">
             <controls:PromptBox.Footer>
-                <StackPanel Orientation="Horizontal">
+                <StackPanel
+                    Orientation="Horizontal"
+                    Visibility="{x:Bind ViewModel.IsCustomAIServiceEnabled, Mode=OneWay, Converter={StaticResource BoolToVisibilityConverter}}">
                     <TextBlock
                         x:Uid="AIMistakeNote"
                         Margin="0,0,2,0"
@@ -299,19 +302,70 @@
                 </StackPanel>
             </controls:PromptBox.Footer>
         </controls:PromptBox>
-        <ScrollViewer Grid.Row="2">
+        <Grid
+            x:Name="ErrorMessageGrid"
+            Grid.Row="2"
+            Margin="20,4,20,0"
+            ColumnSpacing="8"
+            Visibility="{x:Bind ViewModel.PasteActionError.HasText, Mode=OneWay, Converter={StaticResource BoolToVisibilityConverter}}">
+            <Grid.ColumnDefinitions>
+                <ColumnDefinition Width="Auto" />
+                <ColumnDefinition Width="*" />
+                <ColumnDefinition Width="Auto" />
+                <ColumnDefinition Width="Auto" />
+            </Grid.ColumnDefinitions>
+            <FontIcon
+                Grid.Column="0"
+                Margin="0,3,3,0"
+                VerticalAlignment="Top"
+                FontSize="12"
+                Foreground="{ThemeResource AccentTextFillColorPrimaryBrush}"
+                Glyph="&#xE946;"
+                Visibility="{x:Bind ViewModel.PasteActionError.HasDetails, Mode=OneWay, Converter={StaticResource BoolToVisibilityConverter}}" />
+            <TextBlock
+                Grid.Column="1"
+                FontWeight="SemiBold"
+                Foreground="{ThemeResource SystemFillColorCriticalBrush}"
+                Style="{StaticResource CaptionTextBlockStyle}"
+                MaxLines="2"
+                TextTrimming="CharacterEllipsis"
+                TextWrapping="Wrap"
+                Text="{x:Bind ViewModel.PasteActionError.Text, Mode=OneWay}" />
+            <HyperlinkButton
+                x:Name="ShowErrorDetailsBtn"
+                x:Uid="ShowErrorDetailsBtn"
+                Grid.Column="2"
+                Margin="4,-1,0,0"
+                Padding="0"
+                HorizontalAlignment="Left"
+                VerticalAlignment="Top"
+                Click="ShowErrorDetailsBtn_Click"
+                FontSize="12"
+                Visibility="{x:Bind ViewModel.PasteActionError.HasDetails, Mode=OneWay, Converter={StaticResource BoolToVisibilityConverter}}" />
+            <HyperlinkButton
+                x:Uid="SettingsBtn"
+                Grid.Column="3"
+                Margin="0,-1,0,0"
+                Padding="0"
+                HorizontalAlignment="Left"
+                VerticalAlignment="Top"
+                Command="{x:Bind ViewModel.OpenSettingsCommand}"
+                FontSize="12" />
+        </Grid>
+        <ScrollViewer Grid.Row="3">
             <Grid RowSpacing="4">
                 <Grid.RowDefinitions>
-                    <RowDefinition Height="{x:Bind ViewModel.StandardPasteFormats.Count, Mode=OneWay, Converter={StaticResource standardPasteFormatsToHeightConverter}}" />
                     <RowDefinition Height="Auto" />
-                    <RowDefinition Height="*" MinHeight="{x:Bind ViewModel.CustomActionPasteFormats.Count, Mode=OneWay, Converter={StaticResource customActionsToMinHeightConverter}}" />
+                    <RowDefinition Height="Auto" />
+                    <RowDefinition Height="Auto" />
+                    <RowDefinition Height="Auto" />
+                    <RowDefinition Height="Auto" />
                     <RowDefinition Height="Auto" />
                     <RowDefinition Height="Auto" />
                 </Grid.RowDefinitions>
                 <ListView
                     x:Name="PasteOptionsListView"
                     Grid.Row="0"
-                    VerticalAlignment="Bottom"
                     IsItemClickEnabled="True"
                     ItemClick="PasteFormat_ItemClick"
                     ItemContainerTransitions="{x:Null}"
@@ -341,6 +395,27 @@
                     ScrollViewer.VerticalScrollMode="Disabled"
                     SelectionMode="None"
                     TabIndex="2" />
+
+                <Rectangle
+                    Grid.Row="3"
+                    Height="1"
+                    HorizontalAlignment="Stretch"
+                    Fill="{ThemeResource DividerStrokeColorDefaultBrush}"
+                    Visibility="{x:Bind ViewModel.PythonScriptPasteFormats.Count, Mode=OneWay, Converter={StaticResource countToVisibilityConverter}}" />
+
+                <ListView
+                    x:Name="PythonScriptsListView"
+                    Grid.Row="4"
+                    VerticalAlignment="Top"
+                    IsItemClickEnabled="True"
+                    ItemClick="PasteFormat_ItemClick"
+                    ItemContainerTransitions="{x:Null}"
+                    ItemTemplateSelector="{StaticResource PasteFormatTemplateSelector}"
+                    ItemsSource="{x:Bind ViewModel.PythonScriptPasteFormats, Mode=OneWay}"
+                    ScrollViewer.VerticalScrollBarVisibility="Disabled"
+                    ScrollViewer.VerticalScrollMode="Disabled"
+                    SelectionMode="None"
+                    TabIndex="3" />
             </Grid>
         </ScrollViewer>
     </Grid>

src/modules/AdvancedPaste/AdvancedPaste/AdvancedPasteXAML/Pages/MainPage.xaml.cs

@@ -208,5 +208,43 @@ namespace AdvancedPaste.Pages
                 Clipboard.SetHistoryItemAsContent(item.Item);
             }
         }
+
+        private async void ShowErrorDetailsBtn_Click(object sender, RoutedEventArgs e)
+        {
+            var details = ViewModel.PasteActionError?.Details;
+            if (string.IsNullOrEmpty(details))
+            {
+                return;
+            }
+
+            var scrollViewer = new ScrollViewer
+            {
+                MaxHeight = 400,
+                MinWidth = 400,
+                HorizontalScrollBarVisibility = ScrollBarVisibility.Disabled,
+                VerticalScrollBarVisibility = ScrollBarVisibility.Auto,
+            };
+
+            var textBlock = new TextBlock
+            {
+                Text = details,
+                TextWrapping = TextWrapping.Wrap,
+                FontFamily = new Microsoft.UI.Xaml.Media.FontFamily("Consolas"),
+                FontSize = 12,
+                IsTextSelectionEnabled = true,
+            };
+
+            scrollViewer.Content = textBlock;
+
+            var dialog = new ContentDialog
+            {
+                Title = ResourceLoaderInstance.ResourceLoader.GetString("ErrorDetailsDialogTitle"),
+                CloseButtonText = ResourceLoaderInstance.ResourceLoader.GetString("ErrorDetailsDialogClose"),
+                Content = scrollViewer,
+                XamlRoot = this.XamlRoot,
+            };
+
+            await dialog.ShowAsync();
+        }
     }
 }

src/modules/AdvancedPaste/AdvancedPaste/Helpers/IUserSettings.cs

@@ -27,8 +27,26 @@ namespace AdvancedPaste.Settings
 
         public PasteAIConfiguration PasteAIConfiguration { get; }
 
+        public IReadOnlyList<AdvancedPastePythonScriptAction> PythonScriptActions { get; }
+
+        public bool IsPythonScriptsEnabled { get; }
+
+        public string PythonScriptsFolder { get; }
+
+        public string PythonExecutablePath { get; }
+
+        public bool PythonUseWsl { get; }
+
+        public string PythonWslDistribution { get; }
+
+        public int PythonScriptTimeoutSeconds { get; }
+
+        public IReadOnlyDictionary<string, string> TrustedScriptHashes { get; }
+
         public event EventHandler Changed;
 
         Task SetActiveAIProviderAsync(string providerId);
+
+        void StoreTrustedScriptHash(string scriptPath, string hash);
     }
 }

src/modules/AdvancedPaste/AdvancedPaste/Helpers/UserSettings.cs

@@ -4,6 +4,7 @@
 
 using System;
 using System.Collections.Generic;
+using System.IO;
 using System.IO.Abstractions;
 using System.Linq;
 using System.Threading;
@@ -25,6 +26,10 @@ namespace AdvancedPaste.Settings
         private readonly Lock _loadingSettingsLock = new();
         private readonly List<PasteFormats> _additionalActions;
         private readonly List<AdvancedPasteCustomAction> _customActions;
+        private readonly List<AdvancedPastePythonScriptAction> _pythonScriptActions;
+        private FileSystemWatcher _scriptFolderWatcher;
+        private CancellationTokenSource _scriptFolderDebounce;
+        private string _watchedScriptsFolder = string.Empty;
 
         private const string AdvancedPasteModuleName = "AdvancedPaste";
         private const int MaxNumberOfRetry = 5;
@@ -48,6 +53,22 @@ namespace AdvancedPaste.Settings
 
         public PasteAIConfiguration PasteAIConfiguration { get; private set; }
 
+        public IReadOnlyList<AdvancedPastePythonScriptAction> PythonScriptActions => _pythonScriptActions;
+
+        public string PythonScriptsFolder { get; private set; }
+
+        public bool IsPythonScriptsEnabled { get; private set; }
+
+        public string PythonExecutablePath { get; private set; }
+
+        public bool PythonUseWsl { get; private set; }
+
+        public string PythonWslDistribution { get; private set; } = string.Empty;
+
+        public int PythonScriptTimeoutSeconds { get; private set; } = 30;
+
+        public IReadOnlyDictionary<string, string> TrustedScriptHashes { get; private set; } = new Dictionary<string, string>();
+
         public UserSettings(IFileSystem fileSystem)
         {
             _settingsUtils = new SettingsUtils(fileSystem);
@@ -57,8 +78,14 @@ namespace AdvancedPaste.Settings
             CloseAfterLosingFocus = false;
             EnableClipboardPreview = true;
             PasteAIConfiguration = new PasteAIConfiguration();
+            PythonScriptsFolder = GetDefaultScriptsFolder();
+            PythonExecutablePath = string.Empty;
+            PythonUseWsl = false;
+            PythonWslDistribution = string.Empty;
+            PythonScriptTimeoutSeconds = 30;
             _additionalActions = [];
             _customActions = [];
+            _pythonScriptActions = [];
             _taskScheduler = TaskScheduler.FromCurrentSynchronizationContext();
 
             LoadSettingsFromJson();
@@ -66,6 +93,14 @@ namespace AdvancedPaste.Settings
             _watcher = Helper.GetFileWatcher(AdvancedPasteModuleName, "settings.json", OnSettingsFileChanged, fileSystem);
         }
 
+        private static string GetDefaultScriptsFolder() =>
+            System.IO.Path.Combine(
+                Environment.GetFolderPath(Environment.SpecialFolder.LocalApplicationData),
+                "Microsoft",
+                "PowerToys",
+                "AdvancedPaste",
+                "Scripts");
+
         private void OnSettingsFileChanged()
         {
             lock (_loadingSettingsLock)
@@ -131,6 +166,42 @@ namespace AdvancedPaste.Settings
                                 _customActions.Clear();
                                 _customActions.AddRange(properties.CustomActions.Value.Where(customAction => customAction.IsShown && customAction.IsValid));
 
+                                var pythonScripts = properties.PythonScripts ?? new AdvancedPastePythonScriptSettings();
+                                pythonScripts.MigrateLegacyIfNeeded();
+
+                                var mode = pythonScripts.Mode ?? "disabled";
+                                IsPythonScriptsEnabled = !string.Equals(mode, "disabled", StringComparison.OrdinalIgnoreCase);
+                                PythonUseWsl = string.Equals(mode, "wsl", StringComparison.OrdinalIgnoreCase);
+
+                                if (PythonUseWsl)
+                                {
+                                    var wslSettings = pythonScripts.WslSettings ?? new PythonScriptWslSettings();
+                                    PythonScriptsFolder = string.IsNullOrWhiteSpace(wslSettings.ScriptsFolder)
+                                        ? GetDefaultScriptsFolder()
+                                        : wslSettings.ScriptsFolder;
+                                    PythonExecutablePath = string.Empty;
+                                    PythonWslDistribution = wslSettings.Distribution ?? string.Empty;
+                                }
+                                else
+                                {
+                                    var winSettings = pythonScripts.WindowsSettings ?? new PythonScriptWindowsSettings();
+                                    PythonScriptsFolder = string.IsNullOrWhiteSpace(winSettings.ScriptsFolder)
+                                        ? GetDefaultScriptsFolder()
+                                        : winSettings.ScriptsFolder;
+                                    PythonExecutablePath = winSettings.PythonExecutablePath ?? string.Empty;
+                                    PythonWslDistribution = string.Empty;
+                                }
+
+                                PythonScriptTimeoutSeconds = pythonScripts.TimeoutSeconds > 0 ? pythonScripts.TimeoutSeconds : 30;
+                                TrustedScriptHashes = new Dictionary<string, string>(
+                                    pythonScripts.TrustedScriptHashes ?? new Dictionary<string, string>(),
+                                    StringComparer.OrdinalIgnoreCase);
+
+                                _pythonScriptActions.Clear();
+                                _pythonScriptActions.AddRange(pythonScripts.Value.Where(a => a.IsShown));
+
+                                UpdateScriptFolderWatcher(PythonScriptsFolder);
+
                                 Changed?.Invoke(this, EventArgs.Empty);
                             }
 
@@ -295,6 +366,102 @@ namespace AdvancedPaste.Settings
             return string.IsNullOrWhiteSpace(filtered) ? "default" : filtered.ToLowerInvariant();
         }
 
+        private void UpdateScriptFolderWatcher(string folderPath)
+        {
+            if (string.Equals(_watchedScriptsFolder, folderPath, StringComparison.OrdinalIgnoreCase))
+            {
+                return;
+            }
+
+            _scriptFolderWatcher?.Dispose();
+            _scriptFolderWatcher = null;
+            _watchedScriptsFolder = folderPath;
+
+            if (string.IsNullOrWhiteSpace(folderPath))
+            {
+                return;
+            }
+
+            try
+            {
+                if (!System.IO.Directory.Exists(folderPath))
+                {
+                    System.IO.Directory.CreateDirectory(folderPath);
+                }
+
+                _scriptFolderWatcher = new FileSystemWatcher(folderPath, "*.py")
+                {
+                    NotifyFilter = NotifyFilters.FileName | NotifyFilters.LastWrite | NotifyFilters.CreationTime,
+                    EnableRaisingEvents = true,
+                    IncludeSubdirectories = false,
+                };
+
+                _scriptFolderWatcher.Changed += OnScriptFolderChanged;
+                _scriptFolderWatcher.Created += OnScriptFolderChanged;
+                _scriptFolderWatcher.Deleted += OnScriptFolderChanged;
+                _scriptFolderWatcher.Renamed += OnScriptFolderChanged;
+            }
+            catch (Exception ex)
+            {
+                Logger.LogError($"Failed to set up script folder watcher for {folderPath}", ex);
+            }
+        }
+
+        private void OnScriptFolderChanged(object sender, FileSystemEventArgs e)
+        {
+            lock (_loadingSettingsLock)
+            {
+                _scriptFolderDebounce?.Cancel();
+                _scriptFolderDebounce = new CancellationTokenSource();
+
+                Task.Delay(TimeSpan.FromMilliseconds(500))
+                    .ContinueWith(
+                        _ =>
+                        {
+                            Task.Factory
+                                .StartNew(
+                                    () => Changed?.Invoke(this, EventArgs.Empty),
+                                    CancellationToken.None,
+                                    TaskCreationOptions.None,
+                                    _taskScheduler)
+                                .Wait();
+                        },
+                        _scriptFolderDebounce.Token,
+                        TaskContinuationOptions.NotOnCanceled,
+                        TaskScheduler.Default);
+            }
+        }
+
+        public void StoreTrustedScriptHash(string scriptPath, string hash)
+        {
+            lock (_loadingSettingsLock)
+            {
+                try
+                {
+                    var settings = _settingsUtils.GetSettingsOrDefault<AdvancedPasteSettings>(AdvancedPasteModuleName);
+                    if (settings?.Properties?.PythonScripts is null)
+                    {
+                        return;
+                    }
+
+                    settings.Properties.PythonScripts.TrustedScriptHashes ??= new Dictionary<string, string>();
+                    settings.Properties.PythonScripts.TrustedScriptHashes[scriptPath] = hash;
+                    settings.Save(_settingsUtils);
+
+                    // Update in-memory cache.
+                    var updated = new Dictionary<string, string>(TrustedScriptHashes, StringComparer.OrdinalIgnoreCase)
+                    {
+                        [scriptPath] = hash,
+                    };
+                    TrustedScriptHashes = updated;
+                }
+                catch (Exception ex)
+                {
+                    Logger.LogError("Failed to store trusted script hash", ex);
+                }
+            }
+        }
+
         public async Task SetActiveAIProviderAsync(string providerId)
         {
             if (string.IsNullOrWhiteSpace(providerId))
@@ -387,6 +554,8 @@ namespace AdvancedPaste.Settings
                 if (disposing)
                 {
                     _cancellationTokenSource?.Dispose();
+                    _scriptFolderDebounce?.Dispose();
+                    _scriptFolderWatcher?.Dispose();
                     _watcher?.Dispose();
                 }
 

src/modules/AdvancedPaste/AdvancedPaste/Models/PasteFormat.cs

@@ -40,6 +40,14 @@ public sealed class PasteFormat
             IsSavedQuery = isSavedQuery,
         };
 
+    public static PasteFormat CreatePythonScriptFormat(string name, string scriptPath, ClipboardFormat availableFormats) =>
+        new(PasteFormats.PythonScript, availableFormats, isAIServiceEnabled: false)
+        {
+            Name = name,
+            Prompt = scriptPath,
+            IsSavedQuery = true,
+        };
+
     public PasteFormatMetadataAttribute Metadata => MetadataDict[Format];
 
     public string IconGlyph => Metadata.IconGlyph;

src/modules/AdvancedPaste/AdvancedPaste/Models/PasteFormats.cs

@@ -122,4 +122,13 @@ public enum PasteFormats
         KernelFunctionDescription = "Takes user instructions and applies them to the current clipboard content (text or image). Use this function for image analysis, description, or transformation tasks beyond simple OCR.",
         RequiresPrompt = true)]
     CustomTextTransformation,
+
+    [PasteFormatMetadata(
+        IsCoreAction = false,
+        IconGlyph = "\uE943",
+        RequiresAIService = false,
+        CanPreview = true,
+        SupportedClipboardFormats = ClipboardFormat.Text | ClipboardFormat.Html | ClipboardFormat.Image | ClipboardFormat.Audio | ClipboardFormat.Video | ClipboardFormat.File,
+        KernelFunctionDescription = "Runs a user-provided Python script on clipboard content.")]
+    PythonScript,
 }

src/modules/AdvancedPaste/AdvancedPaste/Services/PasteFormatExecutor.cs

@@ -1,4 +1,4 @@
-// Copyright (c) Microsoft Corporation
+// 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.
 
@@ -9,15 +9,23 @@ using System.Threading.Tasks;
 using AdvancedPaste.Helpers;
 using AdvancedPaste.Models;
 using AdvancedPaste.Services.CustomActions;
+using AdvancedPaste.Services.PythonScripts;
+using ManagedCommon;
 using Microsoft.PowerToys.Telemetry;
 using Windows.ApplicationModel.DataTransfer;
 
 namespace AdvancedPaste.Services;
 
-public sealed class PasteFormatExecutor(IKernelService kernelService, ICustomActionTransformService customActionTransformService) : IPasteFormatExecutor
+public sealed class PasteFormatExecutor(
+    IKernelService kernelService,
+    ICustomActionTransformService customActionTransformService,
+    IPythonScriptService pythonScriptService,
+    IPythonScriptTrustService pythonScriptTrustService) : IPasteFormatExecutor
 {
     private readonly IKernelService _kernelService = kernelService;
     private readonly ICustomActionTransformService _customActionTransformService = customActionTransformService;
+    private readonly IPythonScriptService _pythonScriptService = pythonScriptService;
+    private readonly IPythonScriptTrustService _pythonScriptTrustService = pythonScriptTrustService;
 
     public async Task<DataPackage> ExecutePasteFormatAsync(PasteFormat pasteFormat, PasteActionSource source, CancellationToken cancellationToken, IProgress<double> progress)
     {
@@ -32,6 +40,15 @@ public sealed class PasteFormatExecutor(IKernelService kernelService, ICustomAct
 
         var clipboardData = Clipboard.GetContent();
 
+        // PythonScript must NOT run inside Task.Run: the trust confirmation (ContentDialog)
+        // requires the UI (XAML) thread and will throw if called from a thread-pool thread.
+        // Python script execution is fully async (process.WaitForExitAsync), so it is safe
+        // to await it directly without wrapping in Task.Run.
+        if (format == PasteFormats.PythonScript)
+        {
+            return await ExecutePythonScriptAsync(pasteFormat.Prompt, clipboardData, cancellationToken, progress);
+        }
+
         // Run on thread-pool; although we use Async routines consistently, some actions still occasionally take a long time without yielding.
         return await Task.Run(async () =>
             pasteFormat.Format switch
@@ -42,6 +59,92 @@ public sealed class PasteFormatExecutor(IKernelService kernelService, ICustomAct
             });
     }
 
+    private async Task<DataPackage> ExecutePythonScriptAsync(
+        string scriptPath,
+        DataPackageView clipboardData,
+        CancellationToken cancellationToken,
+        IProgress<double> progress)
+    {
+        // Security: ensure the script is trusted before executing.
+        if (!_pythonScriptTrustService.IsTrusted(scriptPath))
+        {
+            var hash = _pythonScriptTrustService.ComputeHash(scriptPath);
+            var approved = await _pythonScriptTrustService.RequestTrustAsync(scriptPath, hash);
+
+            if (!approved)
+            {
+                throw new OperationCanceledException("User declined to trust the Python script.");
+            }
+
+            _pythonScriptTrustService.StoreTrust(scriptPath, hash);
+        }
+
+        var metadata = _pythonScriptService.ReadMetadata(scriptPath);
+
+        // Pre-flight: check for missing packages and offer to install them.
+        var missingPackages = await _pythonScriptService.GetMissingRequirementsAsync(metadata, cancellationToken);
+        if (missingPackages.Count > 0)
+        {
+            var approved = await _pythonScriptTrustService.RequestInstallAsync(metadata.Name, missingPackages);
+            if (!approved)
+            {
+                throw new OperationCanceledException("User declined to install missing Python packages.");
+            }
+
+            await _pythonScriptService.InstallRequirementsAsync(missingPackages, metadata.Platform, cancellationToken);
+        }
+
+        var detectedFormat = await clipboardData.GetAvailableFormatsAsync();
+
+        // V2 interface: script defines advanced_paste_from_*_to_*() — use unified runner.
+        if (metadata.IsV2)
+        {
+            return await _pythonScriptService.ExecuteScriptAsync(scriptPath, metadata.Platform, clipboardData, detectedFormat, cancellationToken, progress);
+        }
+
+        // Legacy paths for backward compatibility.
+        if (string.Equals(metadata.Platform, "linux", StringComparison.OrdinalIgnoreCase))
+        {
+            return await _pythonScriptService.ExecuteWslScriptAsync(scriptPath, clipboardData, detectedFormat, cancellationToken, progress);
+        }
+        else
+        {
+            // Windows mode: script modifies the clipboard in-process; we return the updated clipboard.
+            await _pythonScriptService.ExecuteWindowsScriptAsync(scriptPath, detectedFormat, cancellationToken, progress);
+
+            // Re-read clipboard after script has run.
+            return Clipboard.GetContent() is { } updatedView
+                ? await DataPackageFromViewAsync(updatedView)
+                : new DataPackage();
+        }
+    }
+
+    private static async Task<DataPackage> DataPackageFromViewAsync(DataPackageView view)
+    {
+        var pkg = new DataPackage();
+
+        if (view.Contains(StandardDataFormats.Text))
+        {
+            pkg.SetText(await view.GetTextAsync());
+        }
+        else if (view.Contains(StandardDataFormats.Html))
+        {
+            pkg.SetHtmlFormat(await view.GetHtmlFormatAsync());
+        }
+        else if (view.Contains(StandardDataFormats.StorageItems))
+        {
+            var items = await view.GetStorageItemsAsync();
+            pkg.SetStorageItems(items);
+        }
+        else if (view.Contains(StandardDataFormats.Bitmap))
+        {
+            var bitmap = await view.GetBitmapAsync();
+            pkg.SetBitmap(bitmap);
+        }
+
+        return pkg;
+    }
+
     private static void WriteTelemetry(PasteFormats format, PasteActionSource source)
     {
         switch (source)

src/modules/AdvancedPaste/AdvancedPaste/Services/PythonScripts/IPythonScriptService.cs

@@ -0,0 +1,71 @@
+// 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.Threading;
+using System.Threading.Tasks;
+
+using AdvancedPaste.Models;
+using Windows.ApplicationModel.DataTransfer;
+
+namespace AdvancedPaste.Services.PythonScripts;
+
+public interface IPythonScriptService
+{
+    /// <summary>
+    /// V2 unified execution: C# reads the clipboard, pipes data as JSON to the runner,
+    /// and receives a DataPackage from JSON stdout. Works on both Windows and WSL
+    /// depending on the specified platform.
+    /// </summary>
+    Task<DataPackage> ExecuteScriptAsync(string scriptPath, string platform, DataPackageView clipboardData, ClipboardFormat detectedFormat, CancellationToken cancellationToken, IProgress<double> progress);
+
+    /// <summary>
+    /// Legacy Windows mode: the script directly manipulates the clipboard. C# waits for the process to exit.
+    /// Kept for backward compatibility with scripts that use win32clipboard directly.
+    /// </summary>
+    Task ExecuteWindowsScriptAsync(string scriptPath, ClipboardFormat detectedFormat, CancellationToken cancellationToken, IProgress<double> progress);
+
+    /// <summary>
+    /// Legacy WSL mode: C# passes data via JSON stdin, receives a DataPackage from JSON stdout.
+    /// Kept for backward compatibility with scripts that use json.load(sys.stdin) directly.
+    /// </summary>
+    Task<DataPackage> ExecuteWslScriptAsync(string scriptPath, DataPackageView clipboardData, ClipboardFormat detectedFormat, CancellationToken cancellationToken, IProgress<double> progress);
+
+    /// <summary>
+    /// Parses the @advancedpaste: header comments from a Python script file.
+    /// </summary>
+    PythonScriptMetadata ReadMetadata(string scriptPath);
+
+    /// <summary>
+    /// Discovers all .py scripts in <paramref name="folderPath"/> and returns their metadata.
+    /// </summary>
+    IReadOnlyList<PythonScriptMetadata> DiscoverScripts(string folderPath);
+
+    /// <summary>
+    /// Finds the Python executable to use. Returns null if none is found.
+    /// </summary>
+    string TryFindPythonExecutable(string overridePath = null);
+
+    /// <summary>
+    /// Returns true if wsl.exe is available on this machine.
+    /// </summary>
+    bool IsWslAvailable();
+
+    /// <summary>
+    /// Checks which of the declared requirements are not yet importable.
+    /// Returns an empty list if all packages are installed.
+    /// </summary>
+    Task<IReadOnlyList<PythonRequirement>> GetMissingRequirementsAsync(
+        PythonScriptMetadata metadata,
+        CancellationToken cancellationToken);
+
+    /// <summary>
+    /// Installs the given packages via pip / pip3.
+    /// </summary>
+    Task InstallRequirementsAsync(
+        IReadOnlyList<PythonRequirement> requirements,
+        string platform,
+        CancellationToken cancellationToken);
+}

src/modules/AdvancedPaste/AdvancedPaste/Services/PythonScripts/IPythonScriptTrustService.cs

@@ -0,0 +1,37 @@
+// 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;
+
+namespace AdvancedPaste.Services.PythonScripts;
+
+public interface IPythonScriptTrustService
+{
+    /// <summary>
+    /// Returns true if the script at <paramref name="scriptPath"/> is currently trusted (hash matches stored value).
+    /// </summary>
+    bool IsTrusted(string scriptPath);
+
+    /// <summary>
+    /// Shows a UI confirmation dialog for the script. Returns true if the user approved execution.
+    /// </summary>
+    Task<bool> RequestTrustAsync(string scriptPath, string hash);
+
+    /// <summary>
+    /// Persists the trust entry for <paramref name="scriptPath"/> with the given <paramref name="hash"/>.
+    /// </summary>
+    void StoreTrust(string scriptPath, string hash);
+
+    /// <summary>
+    /// Computes the SHA-256 hash of the script file and returns the hex string.
+    /// </summary>
+    string ComputeHash(string scriptPath);
+
+    /// <summary>
+    /// Shows a confirmation dialog listing the missing packages and asking the user
+    /// whether to install them. Returns true if the user approved installation.
+    /// </summary>
+    Task<bool> RequestInstallAsync(string scriptName, IReadOnlyList<PythonRequirement> missingPackages);
+}

src/modules/AdvancedPaste/AdvancedPaste/Services/PythonScripts/PythonRequirement.cs

@@ -0,0 +1,13 @@
+// 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 AdvancedPaste.Services.PythonScripts;
+
+/// <summary>
+/// Represents a single Python package requirement declared via
+/// <c># @advancedpaste:requires import_name=pip_package</c>.
+/// </summary>
+/// <param name="ImportName">The Python import name used in the script (e.g. "cv2").</param>
+/// <param name="PipPackage">The pip install name (e.g. "opencv-python-headless"). Equals <see cref="ImportName"/> when not explicitly specified.</param>
+public sealed record PythonRequirement(string ImportName, string PipPackage);

src/modules/AdvancedPaste/AdvancedPaste/Services/PythonScripts/PythonScriptMetadata.cs

@@ -0,0 +1,21 @@
+// 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 AdvancedPaste.Models;
+
+namespace AdvancedPaste.Services.PythonScripts;
+
+public sealed record PythonScriptMetadata(
+    string ScriptPath,
+    string Name,
+    string Description,
+    ClipboardFormat SupportedFormats,
+    string Platform,
+    string Version,
+    bool IsEnabled,
+    IReadOnlyList<PythonRequirement> Requirements,
+    bool IsV2 = false,
+    string OutputTypeHint = null);

src/modules/AdvancedPaste/AdvancedPaste/Services/PythonScripts/PythonScriptTrustService.cs

@@ -0,0 +1,126 @@
+// 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.IO;
+using System.Linq;
+using System.Security.Cryptography;
+using System.Threading.Tasks;
+
+using AdvancedPaste.Helpers;
+using AdvancedPaste.Settings;
+using ManagedCommon;
+using Microsoft.UI.Xaml.Controls;
+
+namespace AdvancedPaste.Services.PythonScripts;
+
+public sealed class PythonScriptTrustService(IUserSettings userSettings) : IPythonScriptTrustService
+{
+    private readonly IUserSettings _userSettings = userSettings;
+
+    public bool IsTrusted(string scriptPath)
+    {
+        var hashes = _userSettings.TrustedScriptHashes;
+        if (hashes is null || !hashes.TryGetValue(scriptPath, out var storedHash))
+        {
+            return false;
+        }
+
+        try
+        {
+            var currentHash = ComputeHash(scriptPath);
+            return string.Equals(currentHash, storedHash, StringComparison.OrdinalIgnoreCase);
+        }
+        catch (Exception ex)
+        {
+            Logger.LogError($"Failed to compute hash for {scriptPath}", ex);
+            return false;
+        }
+    }
+
+    public async Task<bool> RequestTrustAsync(string scriptPath, string hash)
+    {
+        try
+        {
+            var resourceLoader = ResourceLoaderInstance.ResourceLoader;
+
+            var dialog = new ContentDialog
+            {
+                Title = resourceLoader.GetString("PythonScriptTrustTitle"),
+                Content = string.Format(
+                    System.Globalization.CultureInfo.CurrentCulture,
+                    resourceLoader.GetString("PythonScriptTrustContent"),
+                    scriptPath),
+                PrimaryButtonText = resourceLoader.GetString("PythonScriptTrustConfirm"),
+                CloseButtonText = resourceLoader.GetString("PythonScriptTrustCancel"),
+            };
+
+            // XamlRoot must be set for ContentDialog to function.
+            var mainWindow = (Microsoft.UI.Xaml.Application.Current as AdvancedPaste.App)?.GetMainWindow();
+            if (mainWindow?.Content?.XamlRoot is { } xamlRoot)
+            {
+                dialog.XamlRoot = xamlRoot;
+            }
+
+            var result = await dialog.ShowAsync();
+            return result == ContentDialogResult.Primary;
+        }
+        catch (Exception ex)
+        {
+            Logger.LogError("Failed to show trust dialog", ex);
+            return false;
+        }
+    }
+
+    public void StoreTrust(string scriptPath, string hash)
+    {
+        _userSettings.StoreTrustedScriptHash(scriptPath, hash);
+    }
+
+    public string ComputeHash(string scriptPath)
+    {
+        using var stream = File.OpenRead(scriptPath);
+        var hashBytes = SHA256.HashData(stream);
+        return Convert.ToHexStringLower(hashBytes);
+    }
+
+    public async Task<bool> RequestInstallAsync(string scriptName, IReadOnlyList<PythonRequirement> missingPackages)
+    {
+        try
+        {
+            var resourceLoader = ResourceLoaderInstance.ResourceLoader;
+            var packageList = string.Join("\n", missingPackages.Select(r =>
+                string.Equals(r.ImportName, r.PipPackage, StringComparison.Ordinal)
+                    ? $"  • {r.PipPackage}"
+                    : $"  • {r.PipPackage}  (import: {r.ImportName})"));
+
+            var dialog = new ContentDialog
+            {
+                Title = resourceLoader.GetString("PythonPackageInstallTitle"),
+                Content = string.Format(
+                    System.Globalization.CultureInfo.CurrentCulture,
+                    resourceLoader.GetString("PythonPackageInstallContent"),
+                    scriptName,
+                    packageList),
+                PrimaryButtonText = resourceLoader.GetString("PythonPackageInstallConfirm"),
+                CloseButtonText = resourceLoader.GetString("PythonPackageInstallCancel"),
+            };
+
+            var mainWindow = (Microsoft.UI.Xaml.Application.Current as AdvancedPaste.App)?.GetMainWindow();
+            if (mainWindow?.Content?.XamlRoot is { } xamlRoot)
+            {
+                dialog.XamlRoot = xamlRoot;
+            }
+
+            var result = await dialog.ShowAsync();
+            return result == ContentDialogResult.Primary;
+        }
+        catch (Exception ex)
+        {
+            Logger.LogError("Failed to show package install dialog", ex);
+            return false;
+        }
+    }
+}

src/modules/AdvancedPaste/AdvancedPaste/Services/PythonScripts/_runner.py

@@ -0,0 +1,247 @@
+# 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.
+
+"""
+Advanced Paste – Script Runner (V3 Named Function Interface)
+
+This runner is shipped with PowerToys and is NOT user-editable.
+It loads a user script, discovers the single advanced_paste_from_<input>_to_<output>
+function by name convention, calls it with the current clipboard data, and formats
+the return value into JSON on stdout.
+
+Each script must define exactly one function matching the pattern:
+  def advanced_paste_from_<input>_to_<output>(<param>)
+
+Supported input types:
+  - text, html, image, files
+
+Required output types (declared via _to_ suffix):
+  - text, html, image, file, files
+
+Examples:
+  - advanced_paste_from_text_to_text(text: str)    → output is text
+  - advanced_paste_from_text_to_image(text: str)   → output is image
+  - advanced_paste_from_image_to_text(image_path)  → output is text
+  - advanced_paste_from_files_to_text(file_paths)  → output is text
+
+Protocol:
+  - Input:  JSON on stdin (clipboard data from C#)
+  - Output: JSON on stdout (result for C# to set on clipboard)
+  - Errors: stderr (displayed to user on failure)
+"""
+
+import importlib.util
+import json
+import os
+import re
+import sys
+from pathlib import Path
+
+
+def _apply_output_hint(result, hint: str) -> dict:
+    """
+    Force the output to the type specified by the _to_ suffix in the function name.
+    Converts the return value to match the hinted type.
+    """
+    if result is None:
+        if hint == "text":
+            return {"result_type": "text", "text": ""}
+        elif hint == "html":
+            return {"result_type": "html", "html": ""}
+        elif hint == "image":
+            return {"result_type": "image", "image_path": ""}
+        elif hint == "audio":
+            return {"result_type": "audio", "audio_path": ""}
+        elif hint == "video":
+            return {"result_type": "video", "video_path": ""}
+        elif hint in ("file", "files"):
+            return {"result_type": hint, "file_paths": []}
+
+    if hint == "text":
+        return {"result_type": "text", "text": str(result) if not isinstance(result, str) else result}
+    elif hint == "html":
+        return {"result_type": "html", "html": str(result) if not isinstance(result, str) else result}
+    elif hint == "image":
+        path = str(result)
+        return {"result_type": "image", "image_path": path}
+    elif hint == "audio":
+        path = str(result)
+        return {"result_type": "audio", "audio_path": path}
+    elif hint == "video":
+        path = str(result)
+        return {"result_type": "video", "video_path": path}
+    elif hint == "file":
+        if isinstance(result, (list, tuple)):
+            paths = [str(p) for p in result]
+        else:
+            paths = [str(result)]
+        return {"result_type": "file", "file_paths": paths}
+    elif hint == "files":
+        if isinstance(result, (list, tuple)):
+            paths = [str(p) for p in result]
+        else:
+            paths = [str(result)]
+        return {"result_type": "files", "file_paths": paths}
+
+    # Fallback (shouldn't happen with valid hints)
+    return {"result_type": "text", "text": str(result)}
+
+# Pattern matching advanced_paste_from_<input>_to_<output> function names.
+_AP_FUNCTION_PATTERN = re.compile(
+    r"^advanced_paste_from_(text|html|image|audio|video|files)_to_(text|html|image|audio|video|file|files)$"
+)
+
+
+def _load_user_module(script_path: str):
+    """Dynamically load the user script as a Python module."""
+    spec = importlib.util.spec_from_file_location("_user_script", script_path)
+    if spec is None or spec.loader is None:
+        raise ImportError(f"Cannot load script: {script_path}")
+    module = importlib.util.module_from_spec(spec)
+    # Add the script's directory to sys.path so relative imports/helpers work.
+    script_dir = os.path.dirname(os.path.abspath(script_path))
+    if script_dir not in sys.path:
+        sys.path.insert(0, script_dir)
+    spec.loader.exec_module(module)
+    return module
+
+
+def _discover_ap_function(module) -> tuple:
+    """
+    Discover the single advanced_paste_from_<input>_to_<output> function in the module.
+    Returns a tuple (input_type, output_type, function) or None if not found.
+    Exits with error if multiple functions are defined.
+    """
+    matches = []
+    for name in dir(module):
+        match = _AP_FUNCTION_PATTERN.match(name)
+        if match:
+            fn = getattr(module, name)
+            if callable(fn):
+                input_type = match.group(1)
+                output_type = match.group(2)
+                matches.append((input_type, output_type, fn))
+
+    if len(matches) == 0:
+        return None
+    if len(matches) > 1:
+        names = [f"advanced_paste_from_{m[0]}_to_{m[1]}" for m in matches]
+        print(
+            f"Error: script defines multiple advanced_paste_from_*_to_* functions "
+            f"({', '.join(names)}). Only one is allowed per script.",
+            file=sys.stderr,
+        )
+        sys.exit(1)
+    return matches[0]
+
+
+def _format_output(result, output_type: str) -> dict:
+    """
+    Format the return value according to the declared output type from the function name.
+    The output_type comes from the _to_ suffix and is always provided.
+    """
+    if result is None:
+        if output_type in ("file", "files"):
+            return {"result_type": output_type, "file_paths": []}
+        elif output_type == "image":
+            return {"result_type": "image", "image_path": ""}
+        elif output_type == "audio":
+            return {"result_type": "audio", "audio_path": ""}
+        elif output_type == "video":
+            return {"result_type": "video", "video_path": ""}
+        elif output_type == "html":
+            return {"result_type": "html", "html": ""}
+        return {"result_type": "text", "text": ""}
+
+    return _apply_output_hint(result, output_type)
+
+
+# ---------------------------------------------------------------------------
+# Main entry point
+# ---------------------------------------------------------------------------
+
+def main():
+    if len(sys.argv) < 2:
+        print("Usage: _runner.py <script_path>", file=sys.stderr)
+        sys.exit(1)
+
+    script_path = sys.argv[1]
+
+    if not os.path.isfile(script_path):
+        print(f"Error: script not found: {script_path}", file=sys.stderr)
+        sys.exit(1)
+
+    # Read input payload from stdin.
+    try:
+        data = json.load(sys.stdin)
+    except json.JSONDecodeError as e:
+        print(f"Error: invalid JSON input: {e}", file=sys.stderr)
+        sys.exit(1)
+
+    # Load the user script.
+    module = _load_user_module(script_path)
+
+    # Discover the single advanced_paste_from_* function.
+    ap_result = _discover_ap_function(module)
+
+    if ap_result is None:
+        print(
+            f"Error: script '{os.path.basename(script_path)}' does not define an "
+            f"advanced_paste_from_<input>_to_<output> function.\n"
+            f"Example: def advanced_paste_from_text_to_text(text): return text.upper()",
+            file=sys.stderr,
+        )
+        sys.exit(1)
+
+    input_type, output_type, fn = ap_result
+
+    # Determine the input data key for this function's input type.
+    input_map = {
+        "text": "text",
+        "html": "html",
+        "image": "image_path",
+        "audio": "audio_path",
+        "video": "video_path",
+        "files": "file_paths",
+    }
+
+    key = input_map.get(input_type, input_type)
+    input_value = data.get(key)
+
+    # Expose work_dir as environment variable so scripts can write output files
+    # to a location accessible from both WSL and Windows (under /mnt/c/...).
+    work_dir = data.get("work_dir", "")
+    if work_dir:
+        os.environ["ADVANCED_PASTE_WORK_DIR"] = work_dir
+
+    # Check if the clipboard has matching data for this script's input type.
+    formats = data.get("format", ["text"])
+    if isinstance(formats, str):
+        formats = [formats]
+
+    if input_type not in formats:
+        print(
+            f"Error: script expects '{input_type}' input but clipboard has [{', '.join(formats)}].",
+            file=sys.stderr,
+        )
+        sys.exit(1)
+
+    if not input_value:
+        print(
+            f"Error: no data available for format '{input_type}' "
+            f"(expected '{key}' in input payload).",
+            file=sys.stderr,
+        )
+        sys.exit(1)
+
+    # Call the function.
+    result = fn(input_value)
+    output = _format_output(result, output_type)
+
+    # Output JSON result.
+    json.dump(output, sys.stdout, ensure_ascii=False)
+
+
+if __name__ == "__main__":
+    main()

src/modules/AdvancedPaste/AdvancedPaste/Strings/en-us/Resources.resw

@@ -212,10 +212,10 @@
     <value>Delete</value>
   </data>
   <data name="CustomFormatTextBox.PlaceholderText" xml:space="preserve">
-    <value>Describe what format you want..</value>
+    <value>Search or describe what format you want..</value>
   </data>
   <data name="InputTxtBoxTooltip.Text" xml:space="preserve">
-    <value>Describe what format you want..</value>
+    <value>Search or describe what format you want..</value>
   </data>
   <data name="LearnMoreLink.Text" xml:space="preserve">
     <value>Privacy</value>
@@ -372,4 +372,73 @@
     <value>Unable to load Foundry Local model: {0}</value>
     <comment>{0} is the model identifier. Do not translate {0}.</comment>
   </data>
+  <data name="PythonNotFound" xml:space="preserve">
+    <value>Python was not found. Please install Python or configure the path in Settings.</value>
+  </data>
+  <data name="WslNotAvailable" xml:space="preserve">
+    <value>WSL is not installed or not available. Cannot run Linux scripts.</value>
+  </data>
+  <data name="PythonScriptFailed" xml:space="preserve">
+    <value>The Python script failed to execute.</value>
+  </data>
+  <data name="PythonScriptTimeout" xml:space="preserve">
+    <value>Script execution timed out ({0} seconds).</value>
+    <comment>{0} is the configured timeout in seconds. Do not translate {0}.</comment>
+  </data>
+  <data name="PythonScriptNotFound" xml:space="preserve">
+    <value>Script file not found: {0}</value>
+    <comment>{0} is the script file path. Do not translate {0}.</comment>
+  </data>
+  <data name="PythonScriptInvalidJson" xml:space="preserve">
+    <value>The script output is not valid JSON.</value>
+  </data>
+  <data name="PythonScriptTrustTitle" xml:space="preserve">
+    <value>Run Python Script?</value>
+  </data>
+  <data name="PythonScriptTrustContent" xml:space="preserve">
+    <value>This script has not been verified. Running untrusted scripts can be a security risk. Do you want to run the following script?
+
+{0}</value>
+    <comment>{0} is the script file path. Do not translate {0}.</comment>
+  </data>
+  <data name="PythonScriptTrustConfirm" xml:space="preserve">
+    <value>Run</value>
+  </data>
+  <data name="PythonScriptTrustCancel" xml:space="preserve">
+    <value>Cancel</value>
+  </data>
+  <data name="PythonPackageInstallTitle" xml:space="preserve">
+    <value>Install Missing Packages?</value>
+  </data>
+  <data name="PythonPackageInstallContent" xml:space="preserve">
+    <value>The script "{0}" requires the following Python packages that are not installed:
+
+{1}
+
+Install them now?</value>
+    <comment>{0} = script display name, {1} = bullet list of package names. Do not translate package names.</comment>
+  </data>
+  <data name="PythonPackageInstallConfirm" xml:space="preserve">
+    <value>Install</value>
+  </data>
+  <data name="PythonPackageInstallCancel" xml:space="preserve">
+    <value>Skip</value>
+  </data>
+  <data name="PythonPackageInstallFailed" xml:space="preserve">
+    <value>Failed to install package(s) "{0}": {1}</value>
+    <comment>{0} = pip package names, {1} = error detail. Do not translate package names.</comment>
+  </data>
+  <data name="PythonPackageInstallTimeout" xml:space="preserve">
+    <value>Package installation for "{0}" timed out ({1} seconds).</value>
+    <comment>{0} = pip package names, {1} = timeout in seconds. Do not translate {0} or {1}.</comment>
+  </data>
+  <data name="ShowErrorDetailsBtn.Content" xml:space="preserve">
+    <value>Show details</value>
+  </data>
+  <data name="ErrorDetailsDialogTitle" xml:space="preserve">
+    <value>Error Details</value>
+  </data>
+  <data name="ErrorDetailsDialogClose" xml:space="preserve">
+    <value>Close</value>
+  </data>
 </root>

src/modules/AdvancedPaste/AdvancedPaste/ViewModels/OptionsViewModel.cs

@@ -16,6 +16,7 @@ using System.Threading.Tasks;
 using AdvancedPaste.Helpers;
 using AdvancedPaste.Models;
 using AdvancedPaste.Services;
+using AdvancedPaste.Services.PythonScripts;
 using AdvancedPaste.Settings;
 using Common.UI;
 using CommunityToolkit.Mvvm.ComponentModel;
@@ -41,6 +42,7 @@ namespace AdvancedPaste.ViewModels
         private readonly IUserSettings _userSettings;
         private readonly IPasteFormatExecutor _pasteFormatExecutor;
         private readonly IAICredentialsProvider _credentialsProvider;
+        private readonly IPythonScriptService _pythonScriptService;
 
         private CancellationTokenSource _pasteActionCancellationTokenSource;
 
@@ -100,6 +102,8 @@ namespace AdvancedPaste.ViewModels
 
         public ObservableCollection<PasteFormat> CustomActionPasteFormats { get; } = [];
 
+        public ObservableCollection<PasteFormat> PythonScriptPasteFormats { get; } = [];
+
         public bool IsCustomAIServiceEnabled
         {
             get
@@ -258,11 +262,12 @@ namespace AdvancedPaste.ViewModels
 
         public event EventHandler PreviewRequested;
 
-        public OptionsViewModel(IFileSystem fileSystem, IAICredentialsProvider credentialsProvider, IUserSettings userSettings, IPasteFormatExecutor pasteFormatExecutor)
+        public OptionsViewModel(IFileSystem fileSystem, IAICredentialsProvider credentialsProvider, IUserSettings userSettings, IPasteFormatExecutor pasteFormatExecutor, IPythonScriptService pythonScriptService)
         {
             _credentialsProvider = credentialsProvider;
             _userSettings = userSettings;
             _pasteFormatExecutor = pasteFormatExecutor;
+            _pythonScriptService = pythonScriptService;
 
             GeneratedResponses = [];
             GeneratedResponses.CollectionChanged += (s, e) =>
@@ -413,12 +418,51 @@ namespace AdvancedPaste.ViewModels
             }
 
             UpdateFormats(StandardPasteFormats, Enum.GetValues<PasteFormats>()
-                                                    .Where(format => PasteFormat.MetadataDict[format].IsCoreAction || _userSettings.AdditionalActions.Contains(format))
+                                                    .Where(format => format != PasteFormats.PythonScript &&
+                                                                     (PasteFormat.MetadataDict[format].IsCoreAction || _userSettings.AdditionalActions.Contains(format)))
                                                     .Select(CreateStandardPasteFormat));
 
             UpdateFormats(
                 CustomActionPasteFormats,
                 IsCustomAIServiceEnabled ? _userSettings.CustomActions.Select(customAction => CreateCustomAIPasteFormat(customAction.Name, customAction.Prompt, isSavedQuery: true)) : []);
+
+            UpdateFormats(
+                PythonScriptPasteFormats,
+                BuildPythonScriptFormats());
+        }
+
+        private IEnumerable<PasteFormat> BuildPythonScriptFormats()
+        {
+            if (!_userSettings.IsPythonScriptsEnabled)
+            {
+                yield break;
+            }
+
+            var folder = _userSettings.PythonScriptsFolder;
+            if (string.IsNullOrWhiteSpace(folder))
+            {
+                yield break;
+            }
+
+            var discoveredScripts = _pythonScriptService.DiscoverScripts(folder);
+            var scriptActions = _userSettings.PythonScriptActions;
+
+            // Use metadata from discovered scripts, but apply IsShown from saved settings.
+            var hiddenPaths = new System.Collections.Generic.HashSet<string>(
+                scriptActions.Where(a => !a.IsShown).Select(a => a.ScriptPath),
+                StringComparer.OrdinalIgnoreCase);
+
+            foreach (var meta in discoveredScripts)
+            {
+                if (hiddenPaths.Contains(meta.ScriptPath) || !meta.IsEnabled)
+                {
+                    continue;
+                }
+
+                // Filter by intersection: only pass clipboard formats the script supports.
+                var filteredFormats = AvailableClipboardFormats & meta.SupportedFormats;
+                yield return PasteFormat.CreatePythonScriptFormat(meta.Name, meta.ScriptPath, filteredFormats);
+            }
         }
 
         public void Dispose()
@@ -692,7 +736,10 @@ namespace AdvancedPaste.ViewModels
             _pasteActionCancellationTokenSource = new();
             TransformProgress = double.NaN;
             PasteActionError = PasteActionError.None;
-            Query = pasteFormat.Query;
+
+            // For Python scripts the Prompt field holds the file path, not a user-visible query.
+            // Setting Query to the path would show it in the AI prompt box, which is misleading.
+            Query = pasteFormat.Format == PasteFormats.PythonScript ? string.Empty : pasteFormat.Query;
 
             try
             {
@@ -732,7 +779,7 @@ namespace AdvancedPaste.ViewModels
 
         internal async Task ExecutePasteFormatAsync(VirtualKey key)
         {
-            var pasteFormat = StandardPasteFormats.Concat(CustomActionPasteFormats)
+            var pasteFormat = StandardPasteFormats.Concat(CustomActionPasteFormats).Concat(PythonScriptPasteFormats)
                                                   .Where(pasteFormat => pasteFormat.IsEnabled)
                                                   .ElementAtOrDefault(key - VirtualKey.Number1);
 

src/modules/cmdpal/.wt.json

@@ -26,6 +26,11 @@
             "input": "pushd .\\ExtensionTemplate\\ ; git archive -o ..\\Microsoft.CmdPal.UI.ViewModels\\Assets\\template.zip HEAD -- .\\TemplateCmdPalExtension\\ ; popd",
             "name": "Update template project",
             "description": "zips up the ExtensionTemplate into our assets. Run this in the cmdpal/ directory."
+        },
+        {
+            "input": " .\\extensionsdk\\nuget\\BuildSDKHelper.ps1 -VersionOfSDK 0.0.1",
+            "name": "Build SDK",
+            "description": "Builds the SDK nuget package with the specified version."
         }
     ]
 }

src/modules/cmdpal/Microsoft.CmdPal.Common/CoreLogger.cs

@@ -2,8 +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;
-
 namespace Microsoft.CmdPal.Common;
 
 public static class CoreLogger
@@ -15,6 +13,8 @@ public static class CoreLogger
 
     private static ILogger? _logger;
 
+    public static ILogger? Instance => _logger;
+
     public static void LogError(string message, Exception ex, [System.Runtime.CompilerServices.CallerMemberName] string memberName = "", [System.Runtime.CompilerServices.CallerFilePath] string sourceFilePath = "", [System.Runtime.CompilerServices.CallerLineNumber] int sourceLineNumber = 0)
     {
         _logger?.LogError(message, ex, memberName, sourceFilePath, sourceLineNumber);

src/modules/cmdpal/Microsoft.CmdPal.Common/Helpers/PinnedDockItem.cs

@@ -0,0 +1,24 @@
+// 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 Microsoft.CommandPalette.Extensions;
+using Microsoft.CommandPalette.Extensions.Toolkit;
+
+namespace Microsoft.CmdPal.Common.Helpers;
+
+public partial class PinnedDockItem : WrappedDockItem
+{
+    public override string Title => $"{base.Title} ({Properties.Resources.PinnedItemSuffix})";
+
+    public PinnedDockItem(ICommand command)
+        : base(command, command.Name)
+    {
+    }
+
+    public PinnedDockItem(IListItem item, string id)
+        : base([item], id, item.Title)
+    {
+        Icon = item.Icon;
+    }
+}

src/modules/cmdpal/Microsoft.CmdPal.Common/Properties/Resources.Designer.cs

@@ -72,5 +72,14 @@ namespace Microsoft.CmdPal.Common.Properties {
                 return ResourceManager.GetString("ErrorReport_Global_Preamble", resourceCulture);
             }
         }
+        
+        /// <summary>
+        ///   Looks up a localized string similar to Pinned.
+        /// </summary>
+        internal static string PinnedItemSuffix {
+            get {
+                return ResourceManager.GetString("PinnedItemSuffix", resourceCulture);
+            }
+        }
     }
 }

src/modules/cmdpal/Microsoft.CmdPal.Common/Properties/Resources.resx

@@ -1,4 +1,4 @@
-<?xml version="1.0" encoding="utf-8"?>
+<?xml version="1.0" encoding="utf-8"?>
 <root>
   <!-- 
     Microsoft ResX Schema 
@@ -117,6 +117,10 @@
   <resheader name="writer">
     <value>System.Resources.ResXResourceWriter, System.Windows.Forms, Version=4.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089</value>
   </resheader>
+  <data name="PinnedItemSuffix" xml:space="preserve">
+    <value>Pinned</value>
+    <comment>Suffix shown for pinned items in the dock</comment>
+  </data>
   <data name="ErrorReport_Global_Preamble" xml:space="preserve">
     <value>This is an error report generated by Windows Command Palette.
 If you are seeing this, it means something went a little sideways in the app.
@@ -124,4 +128,4 @@ You can help us fix it by filing a report at https://aka.ms/powerToysReportBug.
 
 (While you’re at it, give the details below a quick skim — just to make sure there’s nothing personal you’d prefer not to share. It’s rare, but sometimes little surprises sneak in.)</value>
   </data>
-</root>
+</root>

src/modules/cmdpal/Microsoft.CmdPal.UI.ViewModels/AppearanceSettingsViewModel.cs

@@ -18,9 +18,9 @@ namespace Microsoft.CmdPal.UI.ViewModels;
 
 public sealed partial class AppearanceSettingsViewModel : ObservableObject, IDisposable
 {
-    private static readonly Color DefaultTintColor = Color.FromArgb(255, 0, 120, 212);
+    internal static readonly Color DefaultTintColor = Color.FromArgb(255, 0, 120, 212);
 
-    private static readonly ObservableCollection<Color> WindowsColorSwatches = [
+    internal static readonly ObservableCollection<Color> WindowsColorSwatches = [
 
         // row 0
         Color.FromArgb(255, 255, 185, 0), // #ffb900

src/modules/cmdpal/Microsoft.CmdPal.UI.ViewModels/CommandBarViewModel.cs

@@ -96,9 +96,10 @@ public partial class CommandBarViewModel : ObservableObject,
 
         SecondaryCommand = SelectedItem.SecondaryCommand;
 
-        ShouldShowContextMenu = SelectedItem.MoreCommands
-            .OfType<CommandContextItemViewModel>()
-            .Count() > 1;
+        var hasMoreThanOneContextItem = SelectedItem.MoreCommands.Count() > 1;
+        var hasMoreThanOneCommand = SelectedItem.MoreCommands.OfType<CommandContextItemViewModel>().Any();
+
+        ShouldShowContextMenu = hasMoreThanOneContextItem && hasMoreThanOneCommand;
 
         OnPropertyChanged(nameof(HasSecondaryCommand));
         OnPropertyChanged(nameof(SecondaryCommand));

src/modules/cmdpal/Microsoft.CmdPal.UI.ViewModels/CommandItemViewModel.cs

@@ -51,9 +51,11 @@ public partial class CommandItemViewModel : ExtensionObjectViewModel, ICommandBa
 
     private string _itemTitle = string.Empty;
 
-    public string Title => string.IsNullOrEmpty(_itemTitle) ? Name : _itemTitle;
+    protected string ItemTitle => _itemTitle;
 
-    public string Subtitle { get; private set; } = string.Empty;
+    public virtual string Title => string.IsNullOrEmpty(_itemTitle) ? Name : _itemTitle;
+
+    public virtual string Subtitle { get; private set; } = string.Empty;
 
     private IconInfoViewModel _icon = new(null);
 
@@ -73,10 +75,30 @@ public partial class CommandItemViewModel : ExtensionObjectViewModel, ICommandBa
 
     public CommandItemViewModel? PrimaryCommand => this;
 
-    public CommandItemViewModel? SecondaryCommand => HasMoreCommands ? ActualCommands[0] : null;
+    public CommandItemViewModel? SecondaryCommand
+    {
+        get
+        {
+            if (HasMoreCommands)
+            {
+                if (MoreCommands[0] is CommandContextItemViewModel command)
+                {
+                    return command;
+                }
+            }
+
+            return null;
+        }
+    }
 
     public bool ShouldBeVisible => !string.IsNullOrEmpty(Name);
 
+    public bool HasTitle => !string.IsNullOrEmpty(Title);
+
+    public bool HasSubtitle => !string.IsNullOrEmpty(Subtitle);
+
+    public virtual bool HasText => HasTitle || HasSubtitle;
+
     public DataPackageView? DataPackage { get; private set; }
 
     public List<IContextItemViewModel> AllCommands
@@ -331,11 +353,13 @@ public partial class CommandItemViewModel : ExtensionObjectViewModel, ICommandBa
                 UpdateProperty(nameof(Name));
                 UpdateProperty(nameof(Title));
                 UpdateProperty(nameof(Icon));
+                UpdateProperty(nameof(HasText));
                 break;
 
             case nameof(Title):
                 _itemTitle = model.Title;
                 _titleCache.Invalidate();
+                UpdateProperty(nameof(HasText));
                 break;
 
             case nameof(Subtitle):
@@ -343,6 +367,7 @@ public partial class CommandItemViewModel : ExtensionObjectViewModel, ICommandBa
                 this.Subtitle = modelSubtitle;
                 _defaultCommandContextItemViewModel?.Subtitle = modelSubtitle;
                 _subtitleCache.Invalidate();
+                UpdateProperty(nameof(HasText));
                 break;
 
             case nameof(Icon):
@@ -401,11 +426,10 @@ public partial class CommandItemViewModel : ExtensionObjectViewModel, ICommandBa
         }
     }
 
-    private void UpdateDefaultContextItemIcon()
-    {
+    private void UpdateDefaultContextItemIcon() =>
+
         // Command icon takes precedence over our icon on the primary command
         _defaultCommandContextItemViewModel?.UpdateIcon(Command.Icon.IsSet ? Command.Icon : _icon);
-    }
 
     private void UpdateTitle(string? title)
     {

src/modules/cmdpal/Microsoft.CmdPal.UI.ViewModels/CommandPalettePageViewModelFactory.cs

@@ -22,7 +22,7 @@ public class CommandPalettePageViewModelFactory
     {
         return page switch
         {
-            IListPage listPage => new ListViewModel(listPage, _scheduler, host, providerContext, _contextMenuFactory) { IsNested = nested },
+            IListPage listPage => new ListViewModel(listPage, _scheduler, host, providerContext, _contextMenuFactory) { IsRootPage = !nested },
             IContentPage contentPage => new CommandPaletteContentPageViewModel(contentPage, _scheduler, host, providerContext),
             _ => null,
         };

src/modules/cmdpal/Microsoft.CmdPal.UI.ViewModels/CommandProviderWrapper.cs

@@ -6,6 +6,7 @@ using ManagedCommon;
 using Microsoft.CmdPal.Common.Services;
 using Microsoft.CmdPal.UI.ViewModels.Models;
 using Microsoft.CmdPal.UI.ViewModels.Services;
+using Microsoft.CmdPal.UI.ViewModels.Settings;
 using Microsoft.CommandPalette.Extensions;
 using Microsoft.CommandPalette.Extensions.Toolkit;
 using Microsoft.Extensions.DependencyInjection;
@@ -29,6 +30,8 @@ public sealed class CommandProviderWrapper : ICommandProviderContext
 
     public TopLevelViewModel[] FallbackItems { get; private set; } = [];
 
+    public TopLevelViewModel[] DockBandItems { get; private set; } = [];
+
     public string DisplayName { get; private set; } = string.Empty;
 
     public IExtensionWrapper? Extension { get; }
@@ -57,7 +60,7 @@ public sealed class CommandProviderWrapper : ICommandProviderContext
         // calls are pretty dang safe actually.
         _commandProvider = new(provider);
         _taskScheduler = mainThread;
-        TopLevelPageContext = new TopLevelItemPageContext(this, _taskScheduler);
+        TopLevelPageContext = new(this, _taskScheduler);
 
         // Hook the extension back into us
         ExtensionHost = new CommandPaletteHost(provider);
@@ -82,7 +85,7 @@ public sealed class CommandProviderWrapper : ICommandProviderContext
     {
         _taskScheduler = mainThread;
         _commandProviderCache = commandProviderCache;
-        TopLevelPageContext = new TopLevelItemPageContext(this, _taskScheduler);
+        TopLevelPageContext = new(this, _taskScheduler);
 
         Extension = extension;
         ExtensionHost = new CommandPaletteHost(extension);
@@ -146,26 +149,42 @@ public sealed class CommandProviderWrapper : ICommandProviderContext
             return;
         }
 
+        ICommandItem[]? commands = null;
+        IFallbackCommandItem[]? fallbacks = null;
+        ICommandItem[] dockBands = []; // do not initialize me to null
         var displayInfoInitialized = false;
+
         try
         {
             var model = _commandProvider.Unsafe!;
 
             Task<ICommandItem[]> loadTopLevelCommandsTask = new(model.TopLevelCommands);
             loadTopLevelCommandsTask.Start();
-            var commands = await loadTopLevelCommandsTask.ConfigureAwait(false);
+            commands = await loadTopLevelCommandsTask.ConfigureAwait(false);
 
             // On a BG thread here
-            var fallbacks = model.FallbackCommands();
+            fallbacks = model.FallbackCommands();
 
             if (model is ICommandProvider2 two)
             {
                 UnsafePreCacheApiAdditions(two);
             }
 
-            ICommandItem[] pinnedCommands = [];
-            if (model is ICommandProvider4 four)
+            if (model is ICommandProvider3 supportsDockBands)
             {
+                var bands = supportsDockBands.GetDockBands();
+                if (bands is not null)
+                {
+                    Logger.LogDebug($"Found {bands.Length} bands on {DisplayName} ({ProviderId}) ");
+                    dockBands = bands;
+                }
+            }
+
+            ICommandItem[] pinnedCommands = [];
+            ICommandProvider4? four = null;
+            if (model is ICommandProvider4 definitelyFour)
+            {
+                four = definitelyFour; // stash this away so we don't need to QI again
                 SupportsPinning = true;
 
                 // Load pinned commands from saved settings
@@ -189,7 +208,8 @@ public sealed class CommandProviderWrapper : ICommandProviderContext
             Settings = new(model.Settings, this, _taskScheduler);
 
             // We do need to explicitly initialize commands though
-            InitializeCommands(commands, fallbacks, pinnedCommands, serviceProvider);
+            var objects = new TopLevelObjects(commands, fallbacks, pinnedCommands, dockBands);
+            InitializeCommands(objects, serviceProvider, four);
 
             Logger.LogDebug($"Loaded commands from {DisplayName} ({ProviderId})");
         }
@@ -220,21 +240,27 @@ public sealed class CommandProviderWrapper : ICommandProviderContext
         }
     }
 
+    private record TopLevelObjects(
+        ICommandItem[]? Commands,
+        IFallbackCommandItem[]? Fallbacks,
+        ICommandItem[]? PinnedCommands,
+        ICommandItem[]? DockBands);
+
     private void InitializeCommands(
-        ICommandItem[] commands,
-        IFallbackCommandItem[] fallbacks,
-        ICommandItem[] pinnedCommands,
-        IServiceProvider serviceProvider)
+        TopLevelObjects objects,
+        IServiceProvider serviceProvider,
+        ICommandProvider4? four)
     {
         var settings = serviceProvider.GetService<SettingsModel>()!;
         var contextMenuFactory = serviceProvider.GetService<IContextMenuFactory>()!;
+        var state = serviceProvider.GetService<AppStateModel>()!;
         var providerSettings = GetProviderSettings(settings);
         var ourContext = GetProviderContext();
-        var pageContext = new WeakReference<IPageContext>(TopLevelPageContext);
-        var makeAndAdd = (ICommandItem? i, bool fallback) =>
+        WeakReference<IPageContext> pageContext = new(this.TopLevelPageContext);
+        var make = (ICommandItem? i, TopLevelType t) =>
         {
             CommandItemViewModel commandItemViewModel = new(new(i), pageContext, contextMenuFactory: contextMenuFactory);
-            TopLevelViewModel topLevelViewModel = new(commandItemViewModel, fallback, ExtensionHost, ourContext, settings, providerSettings, serviceProvider, i);
+            TopLevelViewModel topLevelViewModel = new(commandItemViewModel, t, ExtensionHost, ourContext, settings, providerSettings, serviceProvider, i, contextMenuFactory: contextMenuFactory);
             topLevelViewModel.InitializeProperties();
 
             return topLevelViewModel;
@@ -242,24 +268,103 @@ public sealed class CommandProviderWrapper : ICommandProviderContext
 
         var topLevelList = new List<TopLevelViewModel>();
 
-        if (commands is not null)
+        if (objects.Commands is not null)
         {
-            topLevelList.AddRange(commands.Select(c => makeAndAdd(c, false)));
+            topLevelList.AddRange(objects.Commands.Select(c => make(c, TopLevelType.Normal)));
         }
 
-        if (pinnedCommands is not null)
+        if (objects.PinnedCommands is not null)
         {
-            topLevelList.AddRange(pinnedCommands.Select(c => makeAndAdd(c, false)));
+            topLevelList.AddRange(objects.PinnedCommands.Select(c => make(c, TopLevelType.Normal)));
         }
 
         TopLevelItems = topLevelList.ToArray();
 
-        if (fallbacks is not null)
+        if (objects.Fallbacks is not null)
         {
-            FallbackItems = fallbacks
-                .Select(c => makeAndAdd(c, true))
+            FallbackItems = objects.Fallbacks
+                .Select(c => make(c, TopLevelType.Fallback))
                 .ToArray();
         }
+
+        List<TopLevelViewModel> bands = new();
+        if (objects.DockBands is not null)
+        {
+            // Start by adding TopLevelViewModels for all the dock bands which
+            // are explicitly provided by the provider through the GetDockBands
+            // API.
+            foreach (var b in objects.DockBands)
+            {
+                var bandVm = make(b, TopLevelType.DockBand);
+                bands.Add(bandVm);
+            }
+        }
+
+        var dockSettings = settings.DockSettings;
+        var allPinnedCommands = dockSettings.AllPinnedCommands;
+        var pinnedBandsForThisProvider = allPinnedCommands.Where(c => c.ProviderId == ProviderId);
+        foreach (var (providerId, commandId) in pinnedBandsForThisProvider)
+        {
+            Logger.LogDebug($"Looking for pinned dock band command {commandId} for provider {providerId}");
+
+            // First, try to lookup the command as one of this provider's
+            // top-level commands. If it's there, then we can skip a lot of
+            // work and just clone it as a band.
+            if (LookupTopLevelCommand(commandId) is TopLevelViewModel topLevelCommand)
+            {
+                Logger.LogDebug($"Found pinned dock band command {commandId} for provider {providerId} as a top-level command");
+                var bandModel = topLevelCommand.ToPinnedDockBandItem();
+                var bandVm = make(bandModel, TopLevelType.DockBand);
+                bands.Add(bandVm);
+                continue;
+            }
+
+            // If we didn't find it as a top-level command, then we need to
+            // try to get it directly from the provider and hope it supports
+            // being a dock band. This is the fallback for providers that
+            // don't explicitly support dock bands through GetDockBands, but
+            // do support pinning commands (ICommandProvider4)
+            if (four is not null)
+            {
+                try
+                {
+                    var commandItem = four.GetCommandItem(commandId);
+                    if (commandItem is not null)
+                    {
+                        Logger.LogDebug($"Found pinned dock band command {commandId} for provider {providerId} through ICommandProvider4 API");
+                        var bandVm = make(commandItem, TopLevelType.DockBand);
+                        bands.Add(bandVm);
+                    }
+                    else
+                    {
+                        Logger.LogWarning($"Couldn't find pinned dock band command {commandId} for provider {providerId} through ICommandProvider4 API. This command won't be shown as a dock band.");
+                    }
+                }
+                catch (Exception e)
+                {
+                    Logger.LogError($"Failed to load pinned dock band command {commandId} for provider {providerId}: {e.Message}");
+                }
+            }
+            else
+            {
+                Logger.LogWarning($"Couldn't find pinned dock band command {commandId} for provider {providerId} as a top-level command, and provider doesn't support ICommandProvider4 API to get it directly. This command won't be shown as a dock band.");
+            }
+        }
+
+        DockBandItems = bands.ToArray();
+    }
+
+    private TopLevelViewModel? LookupTopLevelCommand(string commandId)
+    {
+        foreach (var c in TopLevelItems)
+        {
+            if (c.Id == commandId)
+            {
+                return c;
+            }
+        }
+
+        return null;
     }
 
     private ICommandItem[] LoadPinnedCommands(ICommandProvider4 model, ProviderSettings providerSettings)
@@ -295,6 +400,10 @@ public sealed class CommandProviderWrapper : ICommandProviderContext
             {
                 Logger.LogDebug($"{ProviderId}: Found an IExtendedAttributesProvider");
             }
+            else if (a is ICommandItem[] commands)
+            {
+                Logger.LogDebug($"{ProviderId}: Found an ICommandItem[]");
+            }
         }
     }
 
@@ -306,10 +415,10 @@ public sealed class CommandProviderWrapper : ICommandProviderContext
         if (!providerSettings.PinnedCommandIds.Contains(commandId))
         {
             providerSettings.PinnedCommandIds.Add(commandId);
-            SettingsModel.SaveSettings(settings);
 
             // Raise CommandsChanged so the TopLevelCommandManager reloads our commands
             this.CommandsChanged?.Invoke(this, new ItemsChangedEventArgs(-1));
+            SettingsModel.SaveSettings(settings, false);
         }
     }
 
@@ -320,13 +429,41 @@ public sealed class CommandProviderWrapper : ICommandProviderContext
 
         if (providerSettings.PinnedCommandIds.Remove(commandId))
         {
-            SettingsModel.SaveSettings(settings);
-
             // Raise CommandsChanged so the TopLevelCommandManager reloads our commands
             this.CommandsChanged?.Invoke(this, new ItemsChangedEventArgs(-1));
+
+            SettingsModel.SaveSettings(settings, false);
         }
     }
 
+    public void PinDockBand(string commandId, IServiceProvider serviceProvider)
+    {
+        var settings = serviceProvider.GetService<SettingsModel>()!;
+        var bandSettings = new DockBandSettings
+        {
+            CommandId = commandId,
+            ProviderId = this.ProviderId,
+        };
+        settings.DockSettings.StartBands.Add(bandSettings);
+
+        // Raise CommandsChanged so the TopLevelCommandManager reloads our commands
+        this.CommandsChanged?.Invoke(this, new ItemsChangedEventArgs(-1));
+
+        SettingsModel.SaveSettings(settings, false);
+    }
+
+    public void UnpinDockBand(string commandId, IServiceProvider serviceProvider)
+    {
+        var settings = serviceProvider.GetService<SettingsModel>()!;
+        settings.DockSettings.StartBands.RemoveAll(b => b.CommandId == commandId && b.ProviderId == ProviderId);
+        settings.DockSettings.CenterBands.RemoveAll(b => b.CommandId == commandId && b.ProviderId == ProviderId);
+        settings.DockSettings.EndBands.RemoveAll(b => b.CommandId == commandId && b.ProviderId == ProviderId);
+
+        // Raise CommandsChanged so the TopLevelCommandManager reloads our commands
+        this.CommandsChanged?.Invoke(this, new ItemsChangedEventArgs(-1));
+        SettingsModel.SaveSettings(settings, false);
+    }
+
     public ICommandProviderContext GetProviderContext() => this;
 
     public override bool Equals(object? obj) => obj is CommandProviderWrapper wrapper && isValid == wrapper.isValid;
@@ -342,4 +479,14 @@ public sealed class CommandProviderWrapper : ICommandProviderContext
         // In handling this, a call will be made to `LoadTopLevelCommands` to
         // retrieve the new items.
         this.CommandsChanged?.Invoke(this, args);
+
+    internal void PinDockBand(TopLevelViewModel bandVm)
+    {
+        Logger.LogDebug($"CommandProviderWrapper.PinDockBand: {ProviderId} - {bandVm.Id}");
+
+        var bands = this.DockBandItems.ToList();
+        bands.Add(bandVm);
+        this.DockBandItems = bands.ToArray();
+        this.CommandsChanged?.Invoke(this, new ItemsChangedEventArgs());
+    }
 }

src/modules/cmdpal/Microsoft.CmdPal.UI.ViewModels/Commands/BuiltInsCommandProvider.cs

@@ -1,4 +1,4 @@
-// Copyright (c) Microsoft Corporation
+// 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.
 
@@ -18,6 +18,8 @@ public sealed partial class BuiltInsCommandProvider : CommandProvider
     private readonly FallbackLogItem _fallbackLogItem = new();
     private readonly NewExtensionPage _newExtension = new();
 
+    private readonly IRootPageService _rootPageService;
+
     public override ICommandItem[] TopLevelCommands() =>
         [
             new CommandItem(openSettings) { },
@@ -37,11 +39,22 @@ public sealed partial class BuiltInsCommandProvider : CommandProvider
             _fallbackLogItem,
         ];
 
-    public BuiltInsCommandProvider()
+    public BuiltInsCommandProvider(IRootPageService rootPageService)
     {
         Id = "com.microsoft.cmdpal.builtin.core";
         DisplayName = Properties.Resources.builtin_display_name;
-        Icon = IconHelpers.FromRelativePath("Assets\\StoreLogo.scale-200.png");
+        Icon = IconHelpers.FromRelativePath("Assets\\Square44x44Logo.altform-unplated_targetsize-256.png");
+
+        _rootPageService = rootPageService;
+    }
+
+    public override ICommandItem[]? GetDockBands()
+    {
+        var rootPage = _rootPageService.GetRootPage();
+        List<ICommandItem> bandItems = new();
+        bandItems.Add(new WrappedDockItem(rootPage, Properties.Resources.builtin_command_palette_title));
+
+        return bandItems.ToArray();
     }
 
     public override void InitializeWithHost(IExtensionHost host) => BuiltinsExtensionHost.Instance.Initialize(host);

src/modules/cmdpal/Microsoft.CmdPal.UI.ViewModels/Commands/MainListPage.cs

@@ -65,6 +65,7 @@ public sealed partial class MainListPage : DynamicListPage,
         AppStateModel appStateModel,
         IFuzzyMatcherProvider fuzzyMatcherProvider)
     {
+        Id = "com.microsoft.cmdpal.home";
         Title = Resources.builtin_home_name;
         Icon = IconHelpers.FromRelativePath("Assets\\StoreLogo.scale-200.png");
         PlaceholderText = Properties.Resources.builtin_main_list_page_searchbar_placeholder;

src/modules/cmdpal/Microsoft.CmdPal.UI.ViewModels/Commands/OpenSettingsCommand.cs

@@ -1,4 +1,4 @@
-// Copyright (c) Microsoft Corporation
+// 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.
 

src/modules/cmdpal/Microsoft.CmdPal.UI.ViewModels/ContentFormViewModel.cs

@@ -1,4 +1,4 @@
-// Copyright (c) Microsoft Corporation
+// 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.
 
@@ -70,6 +70,15 @@ public partial class ContentFormViewModel(IFormContent _form, WeakReference<IPag
         StateJson = model.StateJson;
         DataJson = model.DataJson;
 
+        RenderCard();
+
+        UpdateProperty(nameof(Card));
+
+        model.PropChanged += Model_PropChanged;
+    }
+
+    private void RenderCard()
+    {
         if (TryBuildCard(TemplateJson, DataJson, out var builtCard, out var renderingError))
         {
             Card = builtCard;
@@ -93,8 +102,41 @@ public partial class ContentFormViewModel(IFormContent _form, WeakReference<IPag
             UpdateProperty(nameof(Card));
             return;
         }
+    }
 
-        UpdateProperty(nameof(Card));
+    private void Model_PropChanged(object sender, IPropChangedEventArgs args)
+    {
+        try
+        {
+            FetchProperty(args.PropertyName);
+        }
+        catch (Exception ex)
+        {
+            ShowException(ex);
+        }
+    }
+
+    protected virtual void FetchProperty(string propertyName)
+    {
+        var model = this._formModel.Unsafe;
+        if (model is null)
+        {
+            return; // throw?
+        }
+
+        switch (propertyName)
+        {
+            case nameof(DataJson):
+                DataJson = model.DataJson;
+                RenderCard();
+                break;
+            case nameof(TemplateJson):
+                TemplateJson = model.TemplateJson;
+                RenderCard();
+                break;
+        }
+
+        UpdateProperty(propertyName);
     }
 
     [DynamicDependency(DynamicallyAccessedMemberTypes.All, typeof(AdaptiveOpenUrlAction))]

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

@@ -59,11 +59,8 @@ public partial class ContextMenuViewModel : ObservableObject,
     {
         if (SelectedItem is not null)
         {
-            if (SelectedItem.PrimaryCommand is not null || SelectedItem.HasMoreCommands)
-            {
-                ContextMenuStack.Clear();
-                PushContextStack(SelectedItem.AllCommands);
-            }
+            ContextMenuStack.Clear();
+            PushContextStack(SelectedItem.AllCommands);
         }
     }
 

src/modules/cmdpal/Microsoft.CmdPal.UI.ViewModels/DefaultContextMenuFactory.cs

@@ -40,4 +40,12 @@ public partial class DefaultContextMenuFactory : IContextMenuFactory
 
         return results;
     }
+
+    public void AddMoreCommandsToTopLevel(
+        TopLevelViewModel topLevelItem,
+        ICommandProviderContext providerContext,
+        List<IContextItem?> contextItems)
+    {
+        // do nothing
+    }
 }

src/modules/cmdpal/Microsoft.CmdPal.UI.ViewModels/Dock/DockBandSettingsViewModel.cs

@@ -0,0 +1,251 @@
+// 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.Globalization;
+using System.Text;
+using CommunityToolkit.Mvvm.ComponentModel;
+using Microsoft.CmdPal.UI.ViewModels.Settings;
+
+namespace Microsoft.CmdPal.UI.ViewModels.Dock;
+
+public partial class DockBandSettingsViewModel : ObservableObject
+{
+    private static readonly CompositeFormat PluralItemsFormatString = CompositeFormat.Parse(Properties.Resources.dock_item_count_plural);
+    private readonly SettingsModel _settingsModel;
+    private readonly DockBandSettings _dockSettingsModel;
+    private readonly TopLevelViewModel _adapter;
+    private readonly DockBandViewModel? _bandViewModel;
+
+    public string Title => _adapter.Title;
+
+    public string Description
+    {
+        get
+        {
+            List<string> parts = [_adapter.ExtensionName];
+
+            // Add the number of items in the band
+            var itemCount = NumItemsInBand();
+            if (itemCount > 0)
+            {
+                var itemsString = itemCount == 1 ?
+                    Properties.Resources.dock_item_count_singular :
+                    string.Format(CultureInfo.CurrentCulture, PluralItemsFormatString, itemCount);
+                parts.Add(itemsString);
+            }
+
+            return string.Join(" - ", parts);
+        }
+    }
+
+    public string ProviderId => _adapter.CommandProviderId;
+
+    public IconInfoViewModel Icon => _adapter.IconViewModel;
+
+    private ShowLabelsOption _showLabels;
+
+    public ShowLabelsOption ShowLabels
+    {
+        get => _showLabels;
+        set
+        {
+            if (value != _showLabels)
+            {
+                _showLabels = value;
+                _dockSettingsModel.ShowLabels = value switch
+                {
+                    ShowLabelsOption.Default => null,
+                    ShowLabelsOption.ShowLabels => true,
+                    ShowLabelsOption.HideLabels => false,
+                    _ => null,
+                };
+                Save();
+            }
+        }
+    }
+
+    private ShowLabelsOption FetchShowLabels()
+    {
+        if (_dockSettingsModel.ShowLabels == null)
+        {
+            return ShowLabelsOption.Default;
+        }
+
+        return _dockSettingsModel.ShowLabels.Value ? ShowLabelsOption.ShowLabels : ShowLabelsOption.HideLabels;
+    }
+
+    // used to map to ComboBox selection
+    public int ShowLabelsIndex
+    {
+        get => (int)ShowLabels;
+        set => ShowLabels = (ShowLabelsOption)value;
+    }
+
+    private DockPinSide PinSide
+    {
+        get => _pinSide;
+        set
+        {
+            if (value != _pinSide)
+            {
+                UpdatePinSide(value);
+            }
+        }
+    }
+
+    private DockPinSide _pinSide;
+
+    public int PinSideIndex
+    {
+        get => (int)PinSide;
+        set => PinSide = (DockPinSide)value;
+    }
+
+    /// <summary>
+    /// Gets or sets a value indicating whether the band is pinned to the dock.
+    /// When enabled, pins to Center. When disabled, removes from all sides.
+    /// </summary>
+    public bool IsPinned
+    {
+        get => PinSide != DockPinSide.None;
+        set
+        {
+            if (value && PinSide == DockPinSide.None)
+            {
+                // Pin to Center by default when enabling
+                PinSide = DockPinSide.Center;
+            }
+            else if (!value && PinSide != DockPinSide.None)
+            {
+                // Remove from dock when disabling
+                PinSide = DockPinSide.None;
+            }
+        }
+    }
+
+    public DockBandSettingsViewModel(
+        DockBandSettings dockSettingsModel,
+        TopLevelViewModel topLevelAdapter,
+        DockBandViewModel? bandViewModel,
+        SettingsModel settingsModel)
+    {
+        _dockSettingsModel = dockSettingsModel;
+        _adapter = topLevelAdapter;
+        _bandViewModel = bandViewModel;
+        _settingsModel = settingsModel;
+        _pinSide = FetchPinSide();
+        _showLabels = FetchShowLabels();
+    }
+
+    private DockPinSide FetchPinSide()
+    {
+        var dockSettings = _settingsModel.DockSettings;
+        var inStart = dockSettings.StartBands.Any(b => b.CommandId == _dockSettingsModel.CommandId);
+        if (inStart)
+        {
+            return DockPinSide.Start;
+        }
+
+        var inCenter = dockSettings.CenterBands.Any(b => b.CommandId == _dockSettingsModel.CommandId);
+        if (inCenter)
+        {
+            return DockPinSide.Center;
+        }
+
+        var inEnd = dockSettings.EndBands.Any(b => b.CommandId == _dockSettingsModel.CommandId);
+        if (inEnd)
+        {
+            return DockPinSide.End;
+        }
+
+        return DockPinSide.None;
+    }
+
+    private int NumItemsInBand()
+    {
+        var bandVm = _bandViewModel;
+        if (bandVm is null)
+        {
+            return 0;
+        }
+
+        return bandVm.Items.Count;
+    }
+
+    private void Save()
+    {
+        SettingsModel.SaveSettings(_settingsModel);
+    }
+
+    private void UpdatePinSide(DockPinSide value)
+    {
+        OnPinSideChanged(value);
+        OnPropertyChanged(nameof(PinSideIndex));
+        OnPropertyChanged(nameof(PinSide));
+        OnPropertyChanged(nameof(IsPinned));
+    }
+
+    public void SetBandPosition(DockPinSide side, int? index)
+    {
+        var dockSettings = _settingsModel.DockSettings;
+
+        // Remove from all sides first
+        dockSettings.StartBands.RemoveAll(b => b.CommandId == _dockSettingsModel.CommandId);
+        dockSettings.CenterBands.RemoveAll(b => b.CommandId == _dockSettingsModel.CommandId);
+        dockSettings.EndBands.RemoveAll(b => b.CommandId == _dockSettingsModel.CommandId);
+
+        // Add to the selected side
+        switch (side)
+        {
+            case DockPinSide.Start:
+                {
+                    var insertIndex = index ?? dockSettings.StartBands.Count;
+                    dockSettings.StartBands.Insert(insertIndex, _dockSettingsModel);
+                    break;
+                }
+
+            case DockPinSide.Center:
+                {
+                    var insertIndex = index ?? dockSettings.CenterBands.Count;
+                    dockSettings.CenterBands.Insert(insertIndex, _dockSettingsModel);
+                    break;
+                }
+
+            case DockPinSide.End:
+                {
+                    var insertIndex = index ?? dockSettings.EndBands.Count;
+                    dockSettings.EndBands.Insert(insertIndex, _dockSettingsModel);
+                    break;
+                }
+
+            case DockPinSide.None:
+            default:
+                // Do nothing
+                break;
+        }
+
+        Save();
+    }
+
+    private void OnPinSideChanged(DockPinSide value)
+    {
+        SetBandPosition(value, null);
+        _pinSide = value;
+    }
+}
+
+public enum DockPinSide
+{
+    None,
+    Start,
+    Center,
+    End,
+}
+
+public enum ShowLabelsOption
+{
+    Default,
+    ShowLabels,
+    HideLabels,
+}

src/modules/cmdpal/Microsoft.CmdPal.UI.ViewModels/Dock/DockBandViewModel.cs

@@ -0,0 +1,300 @@
+// 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.ObjectModel;
+using Microsoft.CmdPal.UI.ViewModels.Models;
+using Microsoft.CmdPal.UI.ViewModels.Settings;
+using Microsoft.CommandPalette.Extensions;
+using Microsoft.CommandPalette.Extensions.Toolkit;
+
+namespace Microsoft.CmdPal.UI.ViewModels.Dock;
+
+#pragma warning disable SA1402 // File may only contain a single type
+
+public sealed partial class DockBandViewModel : ExtensionObjectViewModel
+{
+    private readonly CommandItemViewModel _rootItem;
+    private readonly DockBandSettings _bandSettings;
+    private readonly DockSettings _dockSettings;
+    private readonly Action _saveSettings;
+    private readonly IContextMenuFactory _contextMenuFactory;
+
+    public ObservableCollection<DockItemViewModel> Items { get; } = new();
+
+    private bool _showTitles = true;
+    private bool _showSubtitles = true;
+    private bool? _showTitlesSnapshot;
+    private bool? _showSubtitlesSnapshot;
+
+    public string Id => _rootItem.Command.Id;
+
+    /// <summary>
+    /// Gets or sets a value indicating whether titles are shown for items in this band.
+    /// This is a preview value - call <see cref="SaveLabelSettings"/> to persist or
+    /// <see cref="RestoreLabelSettings"/> to discard changes.
+    /// </summary>
+    public bool ShowTitles
+    {
+        get => _showTitles;
+        set
+        {
+            if (_showTitles != value)
+            {
+                _showTitles = value;
+                foreach (var item in Items)
+                {
+                    item.ShowTitle = value;
+                }
+
+                UpdateProperty(nameof(ShowTitles));
+            }
+        }
+    }
+
+    /// <summary>
+    /// Gets or sets a value indicating whether subtitles are shown for items in this band.
+    /// This is a preview value - call <see cref="SaveLabelSettings"/> to persist or
+    /// <see cref="RestoreLabelSettings"/> to discard changes.
+    /// </summary>
+    public bool ShowSubtitles
+    {
+        get => _showSubtitles;
+        set
+        {
+            if (_showSubtitles != value)
+            {
+                _showSubtitles = value;
+                foreach (var item in Items)
+                {
+                    item.ShowSubtitle = value;
+                }
+
+                UpdateProperty(nameof(ShowSubtitles));
+            }
+        }
+    }
+
+    /// <summary>
+    /// Gets or sets a value indicating whether labels (both titles and subtitles) are shown.
+    /// Provided for backward compatibility - setting this sets both ShowTitles and ShowSubtitles.
+    /// </summary>
+    public bool ShowLabels
+    {
+        get => _showTitles && _showSubtitles;
+        set
+        {
+            ShowTitles = value;
+            ShowSubtitles = value;
+        }
+    }
+
+    /// <summary>
+    /// Takes a snapshot of the current label settings before editing.
+    /// </summary>
+    internal void SnapshotShowLabels()
+    {
+        _showTitlesSnapshot = _showTitles;
+        _showSubtitlesSnapshot = _showSubtitles;
+    }
+
+    /// <summary>
+    /// Saves the current label settings to settings.
+    /// </summary>
+    internal void SaveShowLabels()
+    {
+        _bandSettings.ShowTitles = _showTitles;
+        _bandSettings.ShowSubtitles = _showSubtitles;
+        _showTitlesSnapshot = null;
+        _showSubtitlesSnapshot = null;
+    }
+
+    /// <summary>
+    /// Restores the label settings from the snapshot.
+    /// </summary>
+    internal void RestoreShowLabels()
+    {
+        if (_showTitlesSnapshot.HasValue)
+        {
+            ShowTitles = _showTitlesSnapshot.Value;
+            _showTitlesSnapshot = null;
+        }
+
+        if (_showSubtitlesSnapshot.HasValue)
+        {
+            ShowSubtitles = _showSubtitlesSnapshot.Value;
+            _showSubtitlesSnapshot = null;
+        }
+    }
+
+    internal DockBandViewModel(
+        CommandItemViewModel commandItemViewModel,
+        WeakReference<IPageContext> errorContext,
+        DockBandSettings settings,
+        DockSettings dockSettings,
+        Action saveSettings,
+        IContextMenuFactory contextMenuFactory)
+        : base(errorContext)
+    {
+        _rootItem = commandItemViewModel;
+        _bandSettings = settings;
+        _dockSettings = dockSettings;
+        _saveSettings = saveSettings;
+        _contextMenuFactory = contextMenuFactory;
+
+        _showTitles = settings.ResolveShowTitles(dockSettings.ShowLabels);
+        _showSubtitles = settings.ResolveShowSubtitles(dockSettings.ShowLabels);
+    }
+
+    private void InitializeFromList(IListPage list)
+    {
+        var items = list.GetItems();
+        var newViewModels = new List<DockItemViewModel>();
+        foreach (var item in items)
+        {
+            var newItemVm = new DockItemViewModel(new(item), this.PageContext, _showTitles, _showSubtitles, _contextMenuFactory);
+            newItemVm.SlowInitializeProperties();
+            newViewModels.Add(newItemVm);
+        }
+
+        List<DockItemViewModel> removed = new();
+        DoOnUiThread(() =>
+        {
+            ListHelpers.InPlaceUpdateList(Items, newViewModels, out removed);
+        });
+
+        foreach (var removedItem in removed)
+        {
+            removedItem.SafeCleanup();
+        }
+    }
+
+    public override void InitializeProperties()
+    {
+        var command = _rootItem.Command;
+        var list = command.Model.Unsafe as IListPage;
+        if (list is not null)
+        {
+            InitializeFromList(list);
+            list.ItemsChanged += HandleItemsChanged;
+        }
+        else
+        {
+            var dockItem = new DockItemViewModel(_rootItem, _showTitles, _showSubtitles, _contextMenuFactory);
+            dockItem.SlowInitializeProperties();
+            DoOnUiThread(() =>
+            {
+                Items.Add(dockItem);
+            });
+        }
+    }
+
+    private void HandleItemsChanged(object sender, IItemsChangedEventArgs args)
+    {
+        if (_rootItem.Command.Model.Unsafe is IListPage p)
+        {
+            InitializeFromList(p);
+        }
+    }
+
+    protected override void UnsafeCleanup()
+    {
+        base.UnsafeCleanup();
+
+        var command = _rootItem.Command;
+        if (command.Model.Unsafe is IListPage list)
+        {
+            list.ItemsChanged -= HandleItemsChanged;
+        }
+
+        foreach (var item in Items)
+        {
+            item.SafeCleanup();
+        }
+    }
+}
+
+public partial class DockItemViewModel : CommandItemViewModel
+{
+    private bool _showTitle = true;
+    private bool _showSubtitle = true;
+
+    public bool ShowTitle
+    {
+        get => _showTitle;
+        internal set
+        {
+            if (_showTitle != value)
+            {
+                _showTitle = value;
+                UpdateProperty(nameof(ShowTitle));
+                UpdateProperty(nameof(ShowLabel));
+                UpdateProperty(nameof(HasText));
+                UpdateProperty(nameof(Title));
+            }
+        }
+    }
+
+    public bool ShowSubtitle
+    {
+        get => _showSubtitle;
+        internal set
+        {
+            if (_showSubtitle != value)
+            {
+                _showSubtitle = value;
+                UpdateProperty(nameof(ShowSubtitle));
+                UpdateProperty(nameof(ShowLabel));
+                UpdateProperty(nameof(Subtitle));
+            }
+        }
+    }
+
+    /// <summary>
+    /// Gets a value indicating whether labels are shown (either titles or subtitles).
+    /// Setting this sets both ShowTitle and ShowSubtitle.
+    /// </summary>
+    public bool ShowLabel
+    {
+        get => _showTitle || _showSubtitle;
+        internal set
+        {
+            ShowTitle = value;
+            ShowSubtitle = value;
+        }
+    }
+
+    public override string Title => _showTitle ? ItemTitle : string.Empty;
+
+    public override string Subtitle => _showSubtitle ? base.Subtitle : string.Empty;
+
+    public override bool HasText => (_showTitle && !string.IsNullOrEmpty(ItemTitle)) || (_showSubtitle && !string.IsNullOrEmpty(base.Subtitle));
+
+    /// <summary>
+    /// Gets the tooltip for the dock item, which includes the title and
+    /// subtitle. If it doesn't have one part, it just returns the other.
+    /// </summary>
+    /// <remarks>
+    /// Trickery: in the case one is empty, we can just concatenate, and it will
+    /// always only be the one that's non-empty
+    /// </remarks>
+    public string Tooltip =>
+        !string.IsNullOrEmpty(ItemTitle) && !string.IsNullOrEmpty(base.Subtitle) ?
+            $"{ItemTitle}\n{base.Subtitle}" :
+            ItemTitle + base.Subtitle;
+
+    public DockItemViewModel(CommandItemViewModel root, bool showTitle, bool showSubtitle, IContextMenuFactory contextMenuFactory)
+        : this(root.Model, root.PageContext, showTitle, showSubtitle, contextMenuFactory)
+    {
+    }
+
+    public DockItemViewModel(ExtensionObject<ICommandItem> item, WeakReference<IPageContext> errorContext, bool showTitle, bool showSubtitle, IContextMenuFactory contextMenuFactory)
+        : base(item, errorContext, contextMenuFactory)
+    {
+        _showTitle = showTitle;
+        _showSubtitle = showSubtitle;
+    }
+}
+
+
+#pragma warning restore SA1402 // File may only contain a single type

src/modules/cmdpal/Microsoft.CmdPal.UI.ViewModels/Dock/DockViewModel.cs

@@ -0,0 +1,651 @@
+// 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.ObjectModel;
+using CommunityToolkit.Mvvm.Messaging;
+using ManagedCommon;
+using Microsoft.CmdPal.UI.Messages;
+using Microsoft.CmdPal.UI.ViewModels.Messages;
+using Microsoft.CmdPal.UI.ViewModels.Settings;
+using Microsoft.CommandPalette.Extensions.Toolkit;
+
+namespace Microsoft.CmdPal.UI.ViewModels.Dock;
+
+public sealed partial class DockViewModel
+{
+    private readonly TopLevelCommandManager _topLevelCommandManager;
+    private readonly SettingsModel _settingsModel;
+    private readonly DockPageContext _pageContext; // only to be used for our own context menu - not for dock bands themselves
+    private readonly IContextMenuFactory _contextMenuFactory;
+
+    private DockSettings _settings;
+
+    public TaskScheduler Scheduler { get; }
+
+    public ObservableCollection<DockBandViewModel> StartItems { get; } = new();
+
+    public ObservableCollection<DockBandViewModel> CenterItems { get; } = new();
+
+    public ObservableCollection<DockBandViewModel> EndItems { get; } = new();
+
+    public ObservableCollection<TopLevelViewModel> AllItems => _topLevelCommandManager.DockBands;
+
+    public DockViewModel(
+        TopLevelCommandManager tlcManager,
+        IContextMenuFactory contextMenuFactory,
+        SettingsModel settings,
+        TaskScheduler scheduler)
+    {
+        _topLevelCommandManager = tlcManager;
+        _contextMenuFactory = contextMenuFactory;
+        _settingsModel = settings;
+        _settings = settings.DockSettings;
+        Scheduler = scheduler;
+        _pageContext = new(this);
+
+        _topLevelCommandManager.DockBands.CollectionChanged += DockBands_CollectionChanged;
+
+        EmitDockConfiguration();
+    }
+
+    private void DockBands_CollectionChanged(object? sender, System.Collections.Specialized.NotifyCollectionChangedEventArgs e)
+    {
+        Logger.LogDebug("Starting DockBands_CollectionChanged");
+        SetupBands();
+        Logger.LogDebug("Ended DockBands_CollectionChanged");
+    }
+
+    public void UpdateSettings(DockSettings settings)
+    {
+        Logger.LogDebug($"DockViewModel.UpdateSettings");
+        _settings = settings;
+        SetupBands();
+    }
+
+    private void SetupBands()
+    {
+        Logger.LogDebug($"Setting up dock bands");
+        SetupBands(_settings.StartBands, StartItems);
+        SetupBands(_settings.CenterBands, CenterItems);
+        SetupBands(_settings.EndBands, EndItems);
+    }
+
+    private void SetupBands(
+        List<DockBandSettings> bands,
+        ObservableCollection<DockBandViewModel> target)
+    {
+        List<DockBandViewModel> newBands = new();
+        foreach (var band in bands)
+        {
+            var commandId = band.CommandId;
+            var topLevelCommand = _topLevelCommandManager.LookupDockBand(commandId);
+
+            if (topLevelCommand is null)
+            {
+                Logger.LogWarning($"Failed to find band {commandId}");
+            }
+
+            if (topLevelCommand is not null)
+            {
+                // note: CreateBandItem doesn't actually initialize the band, it
+                // just creates the VM. Callers need to make sure to call
+                // InitializeProperties() on a BG thread elsewhere
+                var bandVm = CreateBandItem(band, topLevelCommand.ItemViewModel);
+                newBands.Add(bandVm);
+            }
+        }
+
+        var beforeCount = target.Count;
+        var afterCount = newBands.Count;
+
+        DoOnUiThread(() =>
+        {
+            List<DockBandViewModel> removed = new();
+            ListHelpers.InPlaceUpdateList(target, newBands, out removed);
+            var isStartBand = target == StartItems;
+            var label = isStartBand ? "Start bands:" : "End bands:";
+            Logger.LogDebug($"{label} ({beforeCount}) -> ({afterCount}), Removed {removed?.Count ?? 0} items");
+
+            // then, back to a BG thread:
+            Task.Run(() =>
+            {
+                if (removed is not null)
+                {
+                    foreach (var removedItem in removed)
+                    {
+                        removedItem.SafeCleanup();
+                    }
+                }
+            });
+        });
+
+        // Initialize properties on BG thread
+        Task.Run(() =>
+        {
+            foreach (var band in newBands)
+            {
+                band.SafeInitializePropertiesSynchronous();
+            }
+        });
+    }
+
+    /// <summary>
+    /// Instantiate a new band view model for this CommandItem, given the
+    /// settings. The DockBandViewModel will _not_ be initialized - callers
+    /// will need to make sure to initialize it somewhere else (off the UI
+    /// thread)
+    /// </summary>
+    private DockBandViewModel CreateBandItem(
+        DockBandSettings bandSettings,
+        CommandItemViewModel commandItem)
+    {
+        DockBandViewModel band = new(commandItem, commandItem.PageContext, bandSettings, _settings, SaveSettings, _contextMenuFactory);
+
+        // the band is NOT initialized here!
+        return band;
+    }
+
+    private void SaveSettings()
+    {
+        SettingsModel.SaveSettings(_settingsModel);
+    }
+
+    public DockBandViewModel? FindBandByTopLevel(TopLevelViewModel tlc)
+    {
+        var id = tlc.Id;
+        return FindBandById(id);
+    }
+
+    public DockBandViewModel? FindBandById(string id)
+    {
+        foreach (var band in StartItems)
+        {
+            if (band.Id == id)
+            {
+                return band;
+            }
+        }
+
+        foreach (var band in CenterItems)
+        {
+            if (band.Id == id)
+            {
+                return band;
+            }
+        }
+
+        foreach (var band in EndItems)
+        {
+            if (band.Id == id)
+            {
+                return band;
+            }
+        }
+
+        return null;
+    }
+
+    /// <summary>
+    /// Syncs the band position in settings after a same-list reorder.
+    /// Does not save to disk - call SaveBandOrder() when done editing.
+    /// </summary>
+    public void SyncBandPosition(DockBandViewModel band, DockPinSide targetSide, int targetIndex)
+    {
+        var bandId = band.Id;
+        var dockSettings = _settingsModel.DockSettings;
+
+        var bandSettings = dockSettings.StartBands.FirstOrDefault(b => b.CommandId == bandId)
+                        ?? dockSettings.CenterBands.FirstOrDefault(b => b.CommandId == bandId)
+                        ?? dockSettings.EndBands.FirstOrDefault(b => b.CommandId == bandId);
+
+        if (bandSettings == null)
+        {
+            return;
+        }
+
+        // Remove from all settings lists
+        dockSettings.StartBands.RemoveAll(b => b.CommandId == bandId);
+        dockSettings.CenterBands.RemoveAll(b => b.CommandId == bandId);
+        dockSettings.EndBands.RemoveAll(b => b.CommandId == bandId);
+
+        // Add to target settings list at the correct index
+        var targetSettings = targetSide switch
+        {
+            DockPinSide.Start => dockSettings.StartBands,
+            DockPinSide.Center => dockSettings.CenterBands,
+            DockPinSide.End => dockSettings.EndBands,
+            _ => dockSettings.StartBands,
+        };
+        var insertIndex = Math.Min(targetIndex, targetSettings.Count);
+        targetSettings.Insert(insertIndex, bandSettings);
+    }
+
+    /// <summary>
+    /// Moves a dock band to a new position (cross-list drop).
+    /// Does not save to disk - call SaveBandOrder() when done editing.
+    /// </summary>
+    public void MoveBandWithoutSaving(DockBandViewModel band, DockPinSide targetSide, int targetIndex)
+    {
+        var bandId = band.Id;
+        var dockSettings = _settingsModel.DockSettings;
+
+        var bandSettings = dockSettings.StartBands.FirstOrDefault(b => b.CommandId == bandId)
+                        ?? dockSettings.CenterBands.FirstOrDefault(b => b.CommandId == bandId)
+                        ?? dockSettings.EndBands.FirstOrDefault(b => b.CommandId == bandId);
+
+        if (bandSettings == null)
+        {
+            Logger.LogWarning($"Could not find band settings for band {bandId}");
+            return;
+        }
+
+        // Remove from all sides (settings and UI)
+        dockSettings.StartBands.RemoveAll(b => b.CommandId == bandId);
+        dockSettings.CenterBands.RemoveAll(b => b.CommandId == bandId);
+        dockSettings.EndBands.RemoveAll(b => b.CommandId == bandId);
+        StartItems.Remove(band);
+        CenterItems.Remove(band);
+        EndItems.Remove(band);
+
+        // Add to the target side at the specified index
+        switch (targetSide)
+        {
+            case DockPinSide.Start:
+                {
+                    var settingsIndex = Math.Min(targetIndex, dockSettings.StartBands.Count);
+                    dockSettings.StartBands.Insert(settingsIndex, bandSettings);
+
+                    var uiIndex = Math.Min(targetIndex, StartItems.Count);
+                    StartItems.Insert(uiIndex, band);
+                    break;
+                }
+
+            case DockPinSide.Center:
+                {
+                    var settingsIndex = Math.Min(targetIndex, dockSettings.CenterBands.Count);
+                    dockSettings.CenterBands.Insert(settingsIndex, bandSettings);
+
+                    var uiIndex = Math.Min(targetIndex, CenterItems.Count);
+                    CenterItems.Insert(uiIndex, band);
+                    break;
+                }
+
+            case DockPinSide.End:
+                {
+                    var settingsIndex = Math.Min(targetIndex, dockSettings.EndBands.Count);
+                    dockSettings.EndBands.Insert(settingsIndex, bandSettings);
+
+                    var uiIndex = Math.Min(targetIndex, EndItems.Count);
+                    EndItems.Insert(uiIndex, band);
+                    break;
+                }
+        }
+
+        Logger.LogDebug($"Moved band {bandId} to {targetSide} at index {targetIndex} (not saved yet)");
+    }
+
+    /// <summary>
+    /// Saves the current band order and label settings to settings.
+    /// Call this when exiting edit mode.
+    /// </summary>
+    public void SaveBandOrder()
+    {
+        // Save ShowLabels for all bands
+        foreach (var band in StartItems.Concat(CenterItems).Concat(EndItems))
+        {
+            band.SaveShowLabels();
+        }
+
+        _snapshotStartBands = null;
+        _snapshotCenterBands = null;
+        _snapshotEndBands = null;
+        _snapshotBandViewModels = null;
+        SettingsModel.SaveSettings(_settingsModel);
+        Logger.LogDebug("Saved band order to settings");
+    }
+
+    private List<DockBandSettings>? _snapshotStartBands;
+    private List<DockBandSettings>? _snapshotCenterBands;
+    private List<DockBandSettings>? _snapshotEndBands;
+    private Dictionary<string, DockBandViewModel>? _snapshotBandViewModels;
+
+    /// <summary>
+    /// Takes a snapshot of the current band order and label settings before editing.
+    /// Call this when entering edit mode.
+    /// </summary>
+    public void SnapshotBandOrder()
+    {
+        var dockSettings = _settingsModel.DockSettings;
+        _snapshotStartBands = dockSettings.StartBands.Select(b => b.Clone()).ToList();
+        _snapshotCenterBands = dockSettings.CenterBands.Select(b => b.Clone()).ToList();
+        _snapshotEndBands = dockSettings.EndBands.Select(b => b.Clone()).ToList();
+
+        // Snapshot band ViewModels so we can restore unpinned bands
+        // Use a dictionary but handle potential duplicates gracefully
+        _snapshotBandViewModels = new Dictionary<string, DockBandViewModel>();
+        foreach (var band in StartItems.Concat(CenterItems).Concat(EndItems))
+        {
+            _snapshotBandViewModels.TryAdd(band.Id, band);
+        }
+
+        // Snapshot ShowLabels for all bands
+        foreach (var band in _snapshotBandViewModels.Values)
+        {
+            band.SnapshotShowLabels();
+        }
+
+        Logger.LogDebug($"Snapshot taken: {_snapshotStartBands.Count} start bands, {_snapshotCenterBands.Count} center bands, {_snapshotEndBands.Count} end bands");
+    }
+
+    /// <summary>
+    /// Restores the band order and label settings from the snapshot taken when entering edit mode.
+    /// Call this when discarding edit mode changes.
+    /// </summary>
+    public void RestoreBandOrder()
+    {
+        if (_snapshotStartBands == null ||
+            _snapshotCenterBands == null ||
+            _snapshotEndBands == null || _snapshotBandViewModels == null)
+        {
+            Logger.LogWarning("No snapshot to restore from");
+            return;
+        }
+
+        // Restore ShowLabels for all snapshotted bands
+        foreach (var band in _snapshotBandViewModels.Values)
+        {
+            band.RestoreShowLabels();
+        }
+
+        var dockSettings = _settingsModel.DockSettings;
+
+        // Restore settings from snapshot
+        dockSettings.StartBands.Clear();
+        dockSettings.CenterBands.Clear();
+        dockSettings.EndBands.Clear();
+
+        foreach (var bandSnapshot in _snapshotStartBands)
+        {
+            var bandSettings = bandSnapshot.Clone();
+            dockSettings.StartBands.Add(bandSettings);
+        }
+
+        foreach (var bandSnapshot in _snapshotCenterBands)
+        {
+            var bandSettings = bandSnapshot.Clone();
+            dockSettings.CenterBands.Add(bandSettings);
+        }
+
+        foreach (var bandSnapshot in _snapshotEndBands)
+        {
+            var bandSettings = bandSnapshot.Clone();
+            dockSettings.EndBands.Add(bandSettings);
+        }
+
+        // Rebuild UI collections from restored settings using the snapshotted ViewModels
+        RebuildUICollectionsFromSnapshot();
+
+        _snapshotStartBands = null;
+        _snapshotCenterBands = null;
+        _snapshotEndBands = null;
+        _snapshotBandViewModels = null;
+        Logger.LogDebug("Restored band order from snapshot");
+    }
+
+    private void RebuildUICollectionsFromSnapshot()
+    {
+        if (_snapshotBandViewModels == null)
+        {
+            return;
+        }
+
+        var dockSettings = _settingsModel.DockSettings;
+
+        StartItems.Clear();
+        CenterItems.Clear();
+        EndItems.Clear();
+
+        foreach (var bandSettings in dockSettings.StartBands)
+        {
+            if (_snapshotBandViewModels.TryGetValue(bandSettings.CommandId, out var bandVM))
+            {
+                StartItems.Add(bandVM);
+            }
+        }
+
+        foreach (var bandSettings in dockSettings.CenterBands)
+        {
+            if (_snapshotBandViewModels.TryGetValue(bandSettings.CommandId, out var bandVM))
+            {
+                CenterItems.Add(bandVM);
+            }
+        }
+
+        foreach (var bandSettings in dockSettings.EndBands)
+        {
+            if (_snapshotBandViewModels.TryGetValue(bandSettings.CommandId, out var bandVM))
+            {
+                EndItems.Add(bandVM);
+            }
+        }
+    }
+
+    private void RebuildUICollections()
+    {
+        var dockSettings = _settingsModel.DockSettings;
+
+        // Create a lookup of all current band ViewModels
+        var allBands = StartItems.Concat(CenterItems).Concat(EndItems).ToDictionary(b => b.Id);
+
+        StartItems.Clear();
+        CenterItems.Clear();
+        EndItems.Clear();
+
+        foreach (var bandSettings in dockSettings.StartBands)
+        {
+            if (allBands.TryGetValue(bandSettings.CommandId, out var bandVM))
+            {
+                StartItems.Add(bandVM);
+            }
+        }
+
+        foreach (var bandSettings in dockSettings.CenterBands)
+        {
+            if (allBands.TryGetValue(bandSettings.CommandId, out var bandVM))
+            {
+                CenterItems.Add(bandVM);
+            }
+        }
+
+        foreach (var bandSettings in dockSettings.EndBands)
+        {
+            if (allBands.TryGetValue(bandSettings.CommandId, out var bandVM))
+            {
+                EndItems.Add(bandVM);
+            }
+        }
+    }
+
+    /// <summary>
+    /// Gets the list of dock bands that are not currently pinned to any section.
+    /// </summary>
+    public IEnumerable<TopLevelViewModel> GetAvailableBandsToAdd()
+    {
+        // Get IDs of all bands currently in the dock
+        var pinnedBandIds = new HashSet<string>();
+        foreach (var band in StartItems)
+        {
+            pinnedBandIds.Add(band.Id);
+        }
+
+        foreach (var band in CenterItems)
+        {
+            pinnedBandIds.Add(band.Id);
+        }
+
+        foreach (var band in EndItems)
+        {
+            pinnedBandIds.Add(band.Id);
+        }
+
+        // Return all dock bands that are not already pinned
+        return AllItems.Where(tlc => !pinnedBandIds.Contains(tlc.Id));
+    }
+
+    /// <summary>
+    /// Adds a band to the specified dock section.
+    /// Does not save to disk - call SaveBandOrder() when done editing.
+    /// </summary>
+    public void AddBandToSection(TopLevelViewModel topLevel, DockPinSide targetSide)
+    {
+        var bandId = topLevel.Id;
+
+        // Check if already in the dock
+        if (FindBandById(bandId) != null)
+        {
+            Logger.LogWarning($"Band {bandId} is already in the dock");
+            return;
+        }
+
+        // Create settings for the new band
+        var bandSettings = new DockBandSettings { ProviderId = topLevel.CommandProviderId, CommandId = bandId, ShowLabels = null };
+        var dockSettings = _settingsModel.DockSettings;
+
+        // Create the band view model
+        var bandVm = CreateBandItem(bandSettings, topLevel.ItemViewModel);
+
+        // Add to the appropriate section
+        switch (targetSide)
+        {
+            case DockPinSide.Start:
+                dockSettings.StartBands.Add(bandSettings);
+                StartItems.Add(bandVm);
+                break;
+            case DockPinSide.Center:
+                dockSettings.CenterBands.Add(bandSettings);
+                CenterItems.Add(bandVm);
+                break;
+            case DockPinSide.End:
+                dockSettings.EndBands.Add(bandSettings);
+                EndItems.Add(bandVm);
+                break;
+        }
+
+        // Snapshot the new band so it can be removed on discard
+        bandVm.SnapshotShowLabels();
+
+        Task.Run(() =>
+        {
+            bandVm.SafeInitializePropertiesSynchronous();
+        });
+
+        Logger.LogDebug($"Added band {bandId} to {targetSide} (not saved yet)");
+    }
+
+    /// <summary>
+    /// Unpins a band from the dock, removing it from whichever section it's in.
+    /// Does not save to disk - call SaveBandOrder() when done editing.
+    /// </summary>
+    public void UnpinBand(DockBandViewModel band)
+    {
+        var bandId = band.Id;
+        var dockSettings = _settingsModel.DockSettings;
+
+        // Remove from settings
+        dockSettings.StartBands.RemoveAll(b => b.CommandId == bandId);
+        dockSettings.CenterBands.RemoveAll(b => b.CommandId == bandId);
+        dockSettings.EndBands.RemoveAll(b => b.CommandId == bandId);
+
+        // Remove from UI collections
+        StartItems.Remove(band);
+        CenterItems.Remove(band);
+        EndItems.Remove(band);
+
+        Logger.LogDebug($"Unpinned band {bandId} (not saved yet)");
+    }
+
+    private void DoOnUiThread(Action action)
+    {
+        Task.Factory.StartNew(
+            action,
+            CancellationToken.None,
+            TaskCreationOptions.None,
+            Scheduler);
+    }
+
+    public CommandItemViewModel GetContextMenuForDock()
+    {
+        var model = new DockContextMenuItem();
+        var vm = new CommandItemViewModel(new(model), new(_pageContext), contextMenuFactory: null);
+        vm.SlowInitializeProperties();
+        return vm;
+    }
+
+    private sealed partial class DockContextMenuItem : CommandItem
+    {
+        public DockContextMenuItem()
+        {
+            var editDockCommand = new AnonymousCommand(
+                action: () =>
+                {
+                    WeakReferenceMessenger.Default.Send(new EnterDockEditModeMessage());
+                })
+            {
+                Name = Properties.Resources.dock_edit_dock_name,
+                Icon = Icons.EditIcon,
+            };
+
+            var openSettingsCommand = new AnonymousCommand(
+                action: () =>
+                {
+                    WeakReferenceMessenger.Default.Send(new OpenSettingsMessage("Dock"));
+                })
+            {
+                Name = Properties.Resources.dock_settings_name,
+                Icon = Icons.SettingsIcon,
+            };
+
+            MoreCommands = new CommandContextItem[]
+            {
+                new CommandContextItem(editDockCommand),
+                new CommandContextItem(openSettingsCommand),
+            };
+        }
+    }
+
+    private void EmitDockConfiguration()
+    {
+        var isDockEnabled = _settingsModel.EnableDock;
+        var dockSide = isDockEnabled ? _settings.Side.ToString().ToLowerInvariant() : "none";
+
+        static string FormatBands(List<DockBandSettings> bands) =>
+            string.Join("\n", bands.Select(b => $"{b.ProviderId}/{b.CommandId}"));
+
+        var startBands = isDockEnabled ? FormatBands(_settings.StartBands) : string.Empty;
+        var centerBands = isDockEnabled ? FormatBands(_settings.CenterBands) : string.Empty;
+        var endBands = isDockEnabled ? FormatBands(_settings.EndBands) : string.Empty;
+
+        WeakReferenceMessenger.Default.Send(new TelemetryDockConfigurationMessage(
+            isDockEnabled, dockSide, startBands, centerBands, endBands));
+    }
+
+    /// <summary>
+    /// Provides an empty page context, for the dock's own context menu. We're
+    /// building the context menu for the dock using literally our own cmdpal
+    /// types, but that means we need a page context for the VM we will
+    /// generate.
+    /// </summary>
+    private sealed partial class DockPageContext(DockViewModel dockViewModel) : IPageContext
+    {
+        public TaskScheduler Scheduler => dockViewModel.Scheduler;
+
+        public ICommandProviderContext ProviderContext => CommandProviderContext.Empty;
+
+        public void ShowException(Exception ex, string? extensionHint)
+        {
+            var extensionText = extensionHint ?? "<unknown>";
+            Logger.LogError($"Error in dock context {extensionText}", ex);
+        }
+    }
+}

src/modules/cmdpal/Microsoft.CmdPal.UI.ViewModels/Dock/DockWindowViewModel.cs

@@ -0,0 +1,90 @@
+// 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 CommunityToolkit.Mvvm.ComponentModel;
+using Microsoft.CmdPal.UI.ViewModels.Services;
+using Microsoft.CmdPal.UI.ViewModels.Settings;
+using Microsoft.UI.Dispatching;
+using Microsoft.UI.Xaml.Media;
+using Windows.UI;
+
+namespace Microsoft.CmdPal.UI.ViewModels.Dock;
+
+public partial class DockWindowViewModel : ObservableObject, IDisposable
+{
+    private readonly IThemeService _themeService;
+    private readonly DispatcherQueue _uiDispatcherQueue = DispatcherQueue.GetForCurrentThread()!;
+
+    [ObservableProperty]
+    public partial ImageSource? BackgroundImageSource { get; private set; }
+
+    [ObservableProperty]
+    public partial Stretch BackgroundImageStretch { get; private set; } = Stretch.Fill;
+
+    [ObservableProperty]
+    public partial double BackgroundImageOpacity { get; private set; }
+
+    [ObservableProperty]
+    public partial Color BackgroundImageTint { get; private set; }
+
+    [ObservableProperty]
+    public partial double BackgroundImageTintIntensity { get; private set; }
+
+    [ObservableProperty]
+    public partial int BackgroundImageBlurAmount { get; private set; }
+
+    [ObservableProperty]
+    public partial double BackgroundImageBrightness { get; private set; }
+
+    [ObservableProperty]
+    public partial bool ShowBackgroundImage { get; private set; }
+
+    [ObservableProperty]
+    public partial bool ShowColorizationOverlay { get; private set; }
+
+    [ObservableProperty]
+    public partial Color ColorizationColor { get; private set; }
+
+    [ObservableProperty]
+    public partial double ColorizationOpacity { get; private set; }
+
+    public DockWindowViewModel(IThemeService themeService)
+    {
+        _themeService = themeService;
+        _themeService.ThemeChanged += ThemeService_ThemeChanged;
+        UpdateFromThemeSnapshot();
+    }
+
+    private void ThemeService_ThemeChanged(object? sender, ThemeChangedEventArgs e)
+    {
+        _uiDispatcherQueue.TryEnqueue(UpdateFromThemeSnapshot);
+    }
+
+    private void UpdateFromThemeSnapshot()
+    {
+        var snapshot = _themeService.CurrentDockTheme;
+
+        BackgroundImageSource = snapshot.BackgroundImageSource;
+        BackgroundImageStretch = snapshot.BackgroundImageStretch;
+        BackgroundImageOpacity = snapshot.BackgroundImageOpacity;
+
+        BackgroundImageBrightness = snapshot.BackgroundBrightness;
+        BackgroundImageTint = snapshot.Tint;
+        BackgroundImageTintIntensity = snapshot.TintIntensity;
+        BackgroundImageBlurAmount = snapshot.BlurAmount;
+
+        ShowBackgroundImage = BackgroundImageSource != null;
+
+        // Colorization overlay for transparent backdrop
+        ShowColorizationOverlay = snapshot.Backdrop == DockBackdrop.Transparent && snapshot.TintIntensity > 0;
+        ColorizationColor = snapshot.Tint;
+        ColorizationOpacity = snapshot.TintIntensity;
+    }
+
+    public void Dispose()
+    {
+        _themeService.ThemeChanged -= ThemeService_ThemeChanged;
+        GC.SuppressFinalize(this);
+    }
+}

src/modules/cmdpal/Microsoft.CmdPal.UI.ViewModels/DockAppearanceSettingsViewModel.cs

@@ -0,0 +1,341 @@
+// 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.ObjectModel;
+using CommunityToolkit.Mvvm.ComponentModel;
+using CommunityToolkit.Mvvm.Input;
+using CommunityToolkit.WinUI;
+using Microsoft.CmdPal.UI.ViewModels.Services;
+using Microsoft.CmdPal.UI.ViewModels.Settings;
+using Microsoft.UI;
+using Microsoft.UI.Dispatching;
+using Microsoft.UI.Xaml;
+using Microsoft.UI.Xaml.Media;
+using Windows.UI;
+using Windows.UI.ViewManagement;
+
+namespace Microsoft.CmdPal.UI.ViewModels;
+
+/// <summary>
+/// View model for dock appearance settings, controlling theme, backdrop, colorization,
+/// and background image settings for the dock.
+/// </summary>
+public sealed partial class DockAppearanceSettingsViewModel : ObservableObject, IDisposable
+{
+    private readonly SettingsModel _settings;
+    private readonly DockSettings _dockSettings;
+    private readonly UISettings _uiSettings;
+    private readonly IThemeService _themeService;
+    private readonly DispatcherQueueTimer _saveTimer = DispatcherQueue.GetForCurrentThread().CreateTimer();
+    private readonly DispatcherQueue _uiDispatcher = DispatcherQueue.GetForCurrentThread();
+
+    private ElementTheme? _elementThemeOverride;
+    private Color _currentSystemAccentColor;
+
+    public ObservableCollection<Color> Swatches => AppearanceSettingsViewModel.WindowsColorSwatches;
+
+    public int ThemeIndex
+    {
+        get => (int)_dockSettings.Theme;
+        set => Theme = (UserTheme)value;
+    }
+
+    public UserTheme Theme
+    {
+        get => _dockSettings.Theme;
+        set
+        {
+            if (_dockSettings.Theme != value)
+            {
+                _dockSettings.Theme = value;
+                OnPropertyChanged();
+                OnPropertyChanged(nameof(ThemeIndex));
+                Save();
+            }
+        }
+    }
+
+    public int BackdropIndex
+    {
+        get => (int)_dockSettings.Backdrop;
+        set => Backdrop = (DockBackdrop)value;
+    }
+
+    public DockBackdrop Backdrop
+    {
+        get => _dockSettings.Backdrop;
+        set
+        {
+            if (_dockSettings.Backdrop != value)
+            {
+                _dockSettings.Backdrop = value;
+                OnPropertyChanged();
+                OnPropertyChanged(nameof(BackdropIndex));
+                Save();
+            }
+        }
+    }
+
+    public ColorizationMode ColorizationMode
+    {
+        get => _dockSettings.ColorizationMode;
+        set
+        {
+            if (_dockSettings.ColorizationMode != value)
+            {
+                _dockSettings.ColorizationMode = value;
+                OnPropertyChanged();
+                OnPropertyChanged(nameof(ColorizationModeIndex));
+                OnPropertyChanged(nameof(IsCustomTintVisible));
+                OnPropertyChanged(nameof(IsCustomTintIntensityVisible));
+                OnPropertyChanged(nameof(IsBackgroundControlsVisible));
+                OnPropertyChanged(nameof(IsNoBackgroundVisible));
+                OnPropertyChanged(nameof(IsAccentColorControlsVisible));
+
+                if (value == ColorizationMode.WindowsAccentColor)
+                {
+                    ThemeColor = _currentSystemAccentColor;
+                }
+
+                IsColorizationDetailsExpanded = value != ColorizationMode.None;
+
+                Save();
+            }
+        }
+    }
+
+    public int ColorizationModeIndex
+    {
+        get => (int)_dockSettings.ColorizationMode;
+        set => ColorizationMode = (ColorizationMode)value;
+    }
+
+    public Color ThemeColor
+    {
+        get => _dockSettings.CustomThemeColor;
+        set
+        {
+            if (_dockSettings.CustomThemeColor != value)
+            {
+                _dockSettings.CustomThemeColor = value;
+
+                OnPropertyChanged();
+
+                if (ColorIntensity == 0)
+                {
+                    ColorIntensity = 100;
+                }
+
+                Save();
+            }
+        }
+    }
+
+    public int ColorIntensity
+    {
+        get => _dockSettings.CustomThemeColorIntensity;
+        set
+        {
+            _dockSettings.CustomThemeColorIntensity = value;
+            OnPropertyChanged();
+            Save();
+        }
+    }
+
+    public string BackgroundImagePath
+    {
+        get => _dockSettings.BackgroundImagePath ?? string.Empty;
+        set
+        {
+            if (_dockSettings.BackgroundImagePath != value)
+            {
+                _dockSettings.BackgroundImagePath = value;
+                OnPropertyChanged();
+
+                if (BackgroundImageOpacity == 0)
+                {
+                    BackgroundImageOpacity = 100;
+                }
+
+                Save();
+            }
+        }
+    }
+
+    public int BackgroundImageOpacity
+    {
+        get => _dockSettings.BackgroundImageOpacity;
+        set
+        {
+            if (_dockSettings.BackgroundImageOpacity != value)
+            {
+                _dockSettings.BackgroundImageOpacity = value;
+                OnPropertyChanged();
+                Save();
+            }
+        }
+    }
+
+    public int BackgroundImageBrightness
+    {
+        get => _dockSettings.BackgroundImageBrightness;
+        set
+        {
+            if (_dockSettings.BackgroundImageBrightness != value)
+            {
+                _dockSettings.BackgroundImageBrightness = value;
+                OnPropertyChanged();
+                Save();
+            }
+        }
+    }
+
+    public int BackgroundImageBlurAmount
+    {
+        get => _dockSettings.BackgroundImageBlurAmount;
+        set
+        {
+            if (_dockSettings.BackgroundImageBlurAmount != value)
+            {
+                _dockSettings.BackgroundImageBlurAmount = value;
+                OnPropertyChanged();
+                Save();
+            }
+        }
+    }
+
+    public BackgroundImageFit BackgroundImageFit
+    {
+        get => _dockSettings.BackgroundImageFit;
+        set
+        {
+            if (_dockSettings.BackgroundImageFit != value)
+            {
+                _dockSettings.BackgroundImageFit = value;
+                OnPropertyChanged();
+                OnPropertyChanged(nameof(BackgroundImageFitIndex));
+                Save();
+            }
+        }
+    }
+
+    public int BackgroundImageFitIndex
+    {
+        get => BackgroundImageFit switch
+        {
+            BackgroundImageFit.Fill => 1,
+            _ => 0,
+        };
+        set => BackgroundImageFit = value switch
+        {
+            1 => BackgroundImageFit.Fill,
+            _ => BackgroundImageFit.UniformToFill,
+        };
+    }
+
+    [ObservableProperty]
+    public partial bool IsColorizationDetailsExpanded { get; set; }
+
+    public bool IsCustomTintVisible => _dockSettings.ColorizationMode is ColorizationMode.CustomColor or ColorizationMode.Image;
+
+    public bool IsCustomTintIntensityVisible => _dockSettings.ColorizationMode is ColorizationMode.CustomColor or ColorizationMode.WindowsAccentColor or ColorizationMode.Image;
+
+    public bool IsBackgroundControlsVisible => _dockSettings.ColorizationMode is ColorizationMode.Image;
+
+    public bool IsNoBackgroundVisible => _dockSettings.ColorizationMode is ColorizationMode.None;
+
+    public bool IsAccentColorControlsVisible => _dockSettings.ColorizationMode is ColorizationMode.WindowsAccentColor;
+
+    public ElementTheme EffectiveTheme => _elementThemeOverride ?? _themeService.Current.Theme;
+
+    public Color EffectiveThemeColor => ColorizationMode switch
+    {
+        ColorizationMode.WindowsAccentColor => _currentSystemAccentColor,
+        ColorizationMode.CustomColor or ColorizationMode.Image => ThemeColor,
+        _ => Colors.Transparent,
+    };
+
+    // Since the blur amount is absolute, we need to scale it down for the preview (which is smaller than full screen).
+    public int EffectiveBackgroundImageBlurAmount => (int)Math.Round(BackgroundImageBlurAmount / 4f);
+
+    public double EffectiveBackgroundImageBrightness => BackgroundImageBrightness / 100.0;
+
+    public ImageSource? EffectiveBackgroundImageSource =>
+        ColorizationMode is ColorizationMode.Image
+        && !string.IsNullOrWhiteSpace(BackgroundImagePath)
+        && Uri.TryCreate(BackgroundImagePath, UriKind.RelativeOrAbsolute, out var uri)
+            ? new Microsoft.UI.Xaml.Media.Imaging.BitmapImage(uri)
+            : null;
+
+    public DockAppearanceSettingsViewModel(IThemeService themeService, SettingsModel settings)
+    {
+        _themeService = themeService;
+        _themeService.ThemeChanged += ThemeServiceOnThemeChanged;
+        _settings = settings;
+        _dockSettings = settings.DockSettings;
+
+        _uiSettings = new UISettings();
+        _uiSettings.ColorValuesChanged += UiSettingsOnColorValuesChanged;
+        UpdateAccentColor(_uiSettings);
+
+        Reapply();
+
+        IsColorizationDetailsExpanded = _dockSettings.ColorizationMode != ColorizationMode.None;
+    }
+
+    private void UiSettingsOnColorValuesChanged(UISettings sender, object args) => _uiDispatcher.TryEnqueue(() => UpdateAccentColor(sender));
+
+    private void UpdateAccentColor(UISettings sender)
+    {
+        _currentSystemAccentColor = sender.GetColorValue(UIColorType.Accent);
+        if (ColorizationMode == ColorizationMode.WindowsAccentColor)
+        {
+            ThemeColor = _currentSystemAccentColor;
+        }
+    }
+
+    private void ThemeServiceOnThemeChanged(object? sender, ThemeChangedEventArgs e)
+    {
+        _saveTimer.Debounce(Reapply, TimeSpan.FromMilliseconds(200));
+    }
+
+    private void Save()
+    {
+        SettingsModel.SaveSettings(_settings);
+        _saveTimer.Debounce(Reapply, TimeSpan.FromMilliseconds(200));
+    }
+
+    private void Reapply()
+    {
+        OnPropertyChanged(nameof(EffectiveBackgroundImageBrightness));
+        OnPropertyChanged(nameof(EffectiveBackgroundImageSource));
+        OnPropertyChanged(nameof(EffectiveThemeColor));
+        OnPropertyChanged(nameof(EffectiveBackgroundImageBlurAmount));
+
+        // LOAD BEARING:
+        // We need to cycle through the EffectiveTheme property to force reload of resources.
+        _elementThemeOverride = ElementTheme.Light;
+        OnPropertyChanged(nameof(EffectiveTheme));
+        _elementThemeOverride = ElementTheme.Dark;
+        OnPropertyChanged(nameof(EffectiveTheme));
+        _elementThemeOverride = null;
+        OnPropertyChanged(nameof(EffectiveTheme));
+    }
+
+    [RelayCommand]
+    private void ResetBackgroundImageProperties()
+    {
+        BackgroundImageBrightness = 0;
+        BackgroundImageBlurAmount = 0;
+        BackgroundImageFit = BackgroundImageFit.UniformToFill;
+        BackgroundImageOpacity = 100;
+        ColorIntensity = 0;
+    }
+
+    public void Dispose()
+    {
+        _uiSettings.ColorValuesChanged -= UiSettingsOnColorValuesChanged;
+        _themeService.ThemeChanged -= ThemeServiceOnThemeChanged;
+    }
+}

src/modules/cmdpal/Microsoft.CmdPal.UI.ViewModels/ExtensionObjectViewModel.cs

@@ -59,7 +59,7 @@ public abstract partial class ExtensionObjectViewModel : ObservableObject, IBatc
         LogIfDefaultScheduler();
     }
 
-    private protected ExtensionObjectViewModel(WeakReference<IPageContext> contextRef)
+    protected ExtensionObjectViewModel(WeakReference<IPageContext> contextRef)
     {
         ArgumentNullException.ThrowIfNull(contextRef);
 

src/modules/cmdpal/Microsoft.CmdPal.UI.ViewModels/IContextMenuFactory.cs

@@ -9,4 +9,9 @@ namespace Microsoft.CmdPal.UI.ViewModels;
 public interface IContextMenuFactory
 {
     List<IContextItemViewModel> UnsafeBuildAndInitMoreCommands(IContextItem[] items, CommandItemViewModel commandItem);
+
+    void AddMoreCommandsToTopLevel(
+        TopLevelViewModel topLevelItem,
+        ICommandProviderContext providerContext,
+        List<IContextItem?> contextItems);
 }

src/modules/cmdpal/Microsoft.CmdPal.UI.ViewModels/ItemsUpdatedEventArgs.cs

@@ -2,7 +2,7 @@
 // The Microsoft Corporation licenses this file to you under the MIT license.
 // See the LICENSE file in the project root for more information.
 
-namespace Microsoft.CmdPal.Core.ViewModels;
+namespace Microsoft.CmdPal.UI.ViewModels;
 
 public sealed partial class ItemsUpdatedEventArgs : EventArgs
 {

src/modules/cmdpal/Microsoft.CmdPal.UI.ViewModels/ListViewModel.cs

@@ -8,7 +8,6 @@ using CommunityToolkit.Mvvm.Input;
 using CommunityToolkit.Mvvm.Messaging;
 using Microsoft.CmdPal.Common;
 using Microsoft.CmdPal.Common.Helpers;
-using Microsoft.CmdPal.Core.ViewModels;
 using Microsoft.CmdPal.UI.ViewModels.Messages;
 using Microsoft.CmdPal.UI.ViewModels.Models;
 using Microsoft.CommandPalette.Extensions;
@@ -228,32 +227,44 @@ public partial class ListViewModel : PageViewModel, IDisposable
             var reused = 0;
             foreach (var item in newItems)
             {
-                // Check for cancellation during item processing
-                if (cancellationToken.IsCancellationRequested)
+                try
                 {
-                    return;
+                    if (item is null)
+                    {
+                        continue;
+                    }
+
+                    // Check for cancellation during item processing
+                    if (cancellationToken.IsCancellationRequested)
+                    {
+                        return;
+                    }
+
+                    if (_vmCache.TryGetValue(item, out var existing))
+                    {
+                        existing.LayoutShowsTitle = showsTitle;
+                        existing.LayoutShowsSubtitle = showsSubtitle;
+                        newViewModels.Add(existing);
+                        reused++;
+                        continue;
+                    }
+
+                    var viewModel = new ListItemViewModel(item, new(this), _contextMenuFactory);
+
+                    // If an item fails to load, silently ignore it.
+                    if (viewModel.SafeFastInit())
+                    {
+                        viewModel.LayoutShowsTitle = showsTitle;
+                        viewModel.LayoutShowsSubtitle = showsSubtitle;
+
+                        _vmCache[item] = viewModel;
+                        newViewModels.Add(viewModel);
+                        created++;
+                    }
                 }
-
-                if (_vmCache.TryGetValue(item, out var existing))
+                catch (Exception ex)
                 {
-                    existing.LayoutShowsTitle = showsTitle;
-                    existing.LayoutShowsSubtitle = showsSubtitle;
-                    newViewModels.Add(existing);
-                    reused++;
-                    continue;
-                }
-
-                var viewModel = new ListItemViewModel(item, new(this), _contextMenuFactory);
-
-                // If an item fails to load, silently ignore it.
-                if (viewModel.SafeFastInit())
-                {
-                    viewModel.LayoutShowsTitle = showsTitle;
-                    viewModel.LayoutShowsSubtitle = showsSubtitle;
-
-                    _vmCache[item] = viewModel;
-                    newViewModels.Add(viewModel);
-                    created++;
+                    CoreLogger.LogError("Failed to load item:\n", ex + ToString());
                 }
             }
 
@@ -371,7 +382,7 @@ public partial class ListViewModel : PageViewModel, IDisposable
                     UpdateEmptyContent();
                 }
 
-                ItemsUpdated?.Invoke(this, new ItemsUpdatedEventArgs(!IsNested));
+                ItemsUpdated?.Invoke(this, new ItemsUpdatedEventArgs(IsRootPage));
                 _isLoading.Clear();
             });
     }

src/modules/cmdpal/Microsoft.CmdPal.UI.ViewModels/LoadingPageViewModel.cs

@@ -12,6 +12,7 @@ public partial class LoadingPageViewModel : PageViewModel
         : base(model, scheduler, host, CommandProviderContext.Empty)
     {
         ModelIsLoading = true;
+        HasBackButton = false;
         IsInitialized = false;
     }
 }

src/modules/cmdpal/Microsoft.CmdPal.UI.ViewModels/Messages/EnterDockEditModeMessage.cs

@@ -0,0 +1,7 @@
+// 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 Microsoft.CmdPal.UI.ViewModels.Messages;
+
+public record EnterDockEditModeMessage();

src/modules/cmdpal/Microsoft.CmdPal.UI.ViewModels/Messages/NavigateToPageMessage.cs

@@ -4,4 +4,4 @@
 
 namespace Microsoft.CmdPal.UI.ViewModels.Messages;
 
-public record NavigateToPageMessage(PageViewModel Page, bool WithAnimation, CancellationToken CancellationToken);
+public record NavigateToPageMessage(PageViewModel Page, bool WithAnimation, CancellationToken CancellationToken, bool TransientPage = false);

src/modules/cmdpal/Microsoft.CmdPal.UI.ViewModels/Messages/PerformCommandMessage.cs

@@ -18,6 +18,8 @@ public record PerformCommandMessage
 
     public bool WithAnimation { get; set; } = true;
 
+    public bool TransientPage { get; set; }
+
     public PerformCommandMessage(ExtensionObject<ICommand> command)
     {
         Command = command;

src/modules/cmdpal/Microsoft.CmdPal.UI.ViewModels/Messages/PinToDockMessage.cs

@@ -0,0 +1,7 @@
+// 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 Microsoft.CmdPal.UI.ViewModels.Messages;
+
+public record PinToDockMessage(string ProviderId, string CommandId, bool Pin);

src/modules/cmdpal/Microsoft.CmdPal.UI.ViewModels/Messages/ShowHideDockMessage.cs

@@ -0,0 +1,7 @@
+// 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 Microsoft.CmdPal.UI.ViewModels.Messages;
+
+public record ShowHideDockMessage(bool ShowDock);

src/modules/cmdpal/Microsoft.CmdPal.UI.ViewModels/Messages/TelemetryDockConfigurationMessage.cs

@@ -0,0 +1,11 @@
+// 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 Microsoft.CmdPal.UI.ViewModels.Messages;
+
+/// <summary>
+/// Telemetry message sent when the dock is initialized.
+/// Captures the dock configuration for telemetry tracking.
+/// </summary>
+public record TelemetryDockConfigurationMessage(bool IsDockEnabled, string DockSide, string StartBands, string CenterBands, string EndBands);

src/modules/cmdpal/Microsoft.CmdPal.UI.ViewModels/Messages/UnpinCommandItemMessage.cs

@@ -4,6 +4,4 @@
 
 namespace Microsoft.CmdPal.UI.ViewModels.Messages;
 
-public record UnpinCommandItemMessage(string ProviderId, string CommandId)
-{
-}
+public record UnpinCommandItemMessage(string ProviderId, string CommandId);

src/modules/cmdpal/Microsoft.CmdPal.UI.ViewModels/Messages/WindowHiddenMessage.cs

@@ -0,0 +1,7 @@
+// 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 Microsoft.CmdPal.ViewModels.Messages;
+
+public sealed record WindowHiddenMessage();

src/modules/cmdpal/Microsoft.CmdPal.UI.ViewModels/NullPageViewModel.cs

@@ -4,5 +4,11 @@
 
 namespace Microsoft.CmdPal.UI.ViewModels;
 
-internal sealed partial class NullPageViewModel(TaskScheduler scheduler, AppExtensionHost extensionHost)
-    : PageViewModel(null, scheduler, extensionHost, CommandProviderContext.Empty);
+internal sealed partial class NullPageViewModel : PageViewModel
+{
+    internal NullPageViewModel(TaskScheduler scheduler, AppExtensionHost extensionHost)
+        : base(null, scheduler, extensionHost, CommandProviderContext.Empty)
+    {
+        HasBackButton = false;
+    }
+}

src/modules/cmdpal/Microsoft.CmdPal.UI.ViewModels/PageViewModel.cs

@@ -26,8 +26,25 @@ public partial class PageViewModel : ExtensionObjectViewModel, IPageContext
     [ObservableProperty]
     public partial string ErrorMessage { get; protected set; } = string.Empty;
 
+    /// <summary>
+    /// Explicitly: is this page, the VM for the root page. This is used
+    /// slightly differently than being "nested". When we open CmdPal as a
+    /// transient window, we want that page to not have a back button, but that
+    /// page is _not_ the root page.
+    ///
+    /// Later in ListViewModel, we will have logic that checks if it is the root
+    /// page, and modify how selection is handled when the list changes.
+    /// </summary>
     [ObservableProperty]
-    public partial bool IsNested { get; set; } = true;
+    public partial bool IsRootPage { get; set; } = true;
+
+    /// <summary>
+    /// This is used to determine whether to show the back button on this page.
+    /// When a nested page is opened for the transient "dock flyout" window,
+    /// then we don't want to show the back button.
+    /// </summary>
+    [ObservableProperty]
+    public partial bool HasBackButton { get; set; } = true;
 
     // This is set from the SearchBar
     [ObservableProperty]

src/modules/cmdpal/Microsoft.CmdPal.UI.ViewModels/Properties/Resources.Designer.cs

@@ -60,6 +60,15 @@ namespace Microsoft.CmdPal.UI.ViewModels.Properties {
             }
         }
         
+        /// <summary>
+        ///   Looks up a localized string similar to Open Command Palette.
+        /// </summary>
+        public static string builtin_command_palette_title {
+            get {
+                return ResourceManager.GetString("builtin_command_palette_title", resourceCulture);
+            }
+        }
+        
         /// <summary>
         ///   Looks up a localized string similar to Create another.
         /// </summary>
@@ -294,6 +303,15 @@ namespace Microsoft.CmdPal.UI.ViewModels.Properties {
             }
         }
         
+        /// <summary>
+        ///   Looks up a localized string similar to Built-in.
+        /// </summary>
+        public static string builtin_extension_name_fallback {
+            get {
+                return ResourceManager.GetString("builtin_extension_name_fallback", resourceCulture);
+            }
+        }
+        
         /// <summary>
         ///   Looks up a localized string similar to {0}, {1} commands.
         /// </summary>
@@ -465,6 +483,42 @@ namespace Microsoft.CmdPal.UI.ViewModels.Properties {
             }
         }
         
+        /// <summary>
+        ///   Looks up a localized string similar to Edit dock.
+        /// </summary>
+        public static string dock_edit_dock_name {
+            get {
+                return ResourceManager.GetString("dock_edit_dock_name", resourceCulture);
+            }
+        }
+        
+        /// <summary>
+        ///   Looks up a localized string similar to {0} items.
+        /// </summary>
+        public static string dock_item_count_plural {
+            get {
+                return ResourceManager.GetString("dock_item_count_plural", resourceCulture);
+            }
+        }
+        
+        /// <summary>
+        ///   Looks up a localized string similar to 1 item.
+        /// </summary>
+        public static string dock_item_count_singular {
+            get {
+                return ResourceManager.GetString("dock_item_count_singular", resourceCulture);
+            }
+        }
+        
+        /// <summary>
+        ///   Looks up a localized string similar to Dock settings.
+        /// </summary>
+        public static string dock_settings_name {
+            get {
+                return ResourceManager.GetString("dock_settings_name", resourceCulture);
+            }
+        }
+        
         /// <summary>
         ///   Looks up a localized string similar to Fallbacks.
         /// </summary>
@@ -475,6 +529,14 @@ namespace Microsoft.CmdPal.UI.ViewModels.Properties {
         }
         
         /// <summary>
+        ///   Looks up a localized string similar to Pinned.
+        /// </summary>
+        public static string PinnedItemSuffix {
+            get {
+                return ResourceManager.GetString("PinnedItemSuffix", resourceCulture);
+            }
+        }
+
         ///   Looks up a localized string similar to Results.
         /// </summary>
         public static string results {

src/modules/cmdpal/Microsoft.CmdPal.UI.ViewModels/Properties/Resources.resx

@@ -254,16 +254,44 @@
   <data name="builtin_settings_extension_n_extensions_installed" xml:space="preserve">
     <value>{0} extensions installed</value>
   </data>
+  <data name="builtin_extension_name_fallback" xml:space="preserve">
+    <value>Built-in</value>
+    <comment>Fallback name for built-in extensions</comment>
+  </data>
+  <data name="dock_item_count_singular" xml:space="preserve">
+    <value>1 item</value>
+    <comment>Singular form for item count in dock band</comment>
+  </data>
+  <data name="dock_item_count_plural" xml:space="preserve">
+    <value>{0} items</value>
+    <comment>Plural form for item count in dock band</comment>
+  </data>
+  <data name="builtin_command_palette_title" xml:space="preserve">
+    <value>Open Command Palette</value>
+    <comment>Title for the command to open the command palette</comment>
+  </data>
   <data name="builtin_settings_appearance_pick_background_image_title" xml:space="preserve">
     <value>Pick background image</value>
   </data>
   <data name="fallbacks" xml:space="preserve">
     <value>Fallbacks</value>
   </data>
+  <data name="dock_edit_dock_name" xml:space="preserve">
+    <value>Edit dock</value>
+    <comment>Command name for editing the dock</comment>
+  </data>
+  <data name="dock_settings_name" xml:space="preserve">
+    <value>Dock settings</value>
+    <comment>Command name for opening dock settings</comment>
+  </data> 
   <data name="ShowDetailsCommand" xml:space="preserve">
     <value>Show details</value>
     <comment>Name for the command that shows details of an item</comment>
   </data>
+  <data name="PinnedItemSuffix" xml:space="preserve">
+    <value>Pinned</value>
+    <comment>Suffix shown for pinned items in the dock</comment>
+  </data>
   <data name="results" xml:space="preserve">
     <value>Results</value>
     <comment>Section title for list of all search results that doesn't fall into any other category</comment>

src/modules/cmdpal/Microsoft.CmdPal.UI.ViewModels/Services/DockThemeSnapshot.cs

@@ -0,0 +1,73 @@
+// 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 Microsoft.CmdPal.UI.ViewModels.Settings;
+using Microsoft.UI.Xaml;
+using Microsoft.UI.Xaml.Media;
+using Windows.UI;
+
+namespace Microsoft.CmdPal.UI.ViewModels.Services;
+
+/// <summary>
+/// Represents a snapshot of dock theme-related visual settings, including accent color, theme preference,
+/// backdrop, and background image configuration, for use in rendering the Dock UI.
+/// </summary>
+public sealed class DockThemeSnapshot
+{
+    /// <summary>
+    /// Gets the accent tint color used by the Dock visuals.
+    /// </summary>
+    public required Color Tint { get; init; }
+
+    /// <summary>
+    /// Gets the intensity of the accent tint color (0-1 range).
+    /// </summary>
+    public required float TintIntensity { get; init; }
+
+    /// <summary>
+    /// Gets the configured application theme preference for the Dock.
+    /// </summary>
+    public required ElementTheme Theme { get; init; }
+
+    /// <summary>
+    /// Gets the backdrop type for the Dock.
+    /// </summary>
+    public required DockBackdrop Backdrop { get; init; }
+
+    /// <summary>
+    /// Gets the image source to render as the background, if any.
+    /// </summary>
+    /// <remarks>
+    /// Returns <see langword="null"/> when no background image is configured.
+    /// </remarks>
+    public required ImageSource? BackgroundImageSource { get; init; }
+
+    /// <summary>
+    /// Gets the stretch mode used to lay out the background image.
+    /// </summary>
+    public required Stretch BackgroundImageStretch { get; init; }
+
+    /// <summary>
+    /// Gets the opacity applied to the background image.
+    /// </summary>
+    /// <value>
+    /// A value in the range [0, 1], where 0 is fully transparent and 1 is fully opaque.
+    /// </value>
+    public required double BackgroundImageOpacity { get; init; }
+
+    /// <summary>
+    /// Gets the effective acrylic backdrop parameters based on current settings and theme.
+    /// </summary>
+    public required BackdropParameters BackdropParameters { get; init; }
+
+    /// <summary>
+    /// Gets the blur amount for the background image.
+    /// </summary>
+    public required int BlurAmount { get; init; }
+
+    /// <summary>
+    /// Gets the brightness adjustment for the background (0-1 range).
+    /// </summary>
+    public required float BackgroundBrightness { get; init; }
+}

src/modules/cmdpal/Microsoft.CmdPal.UI.ViewModels/Services/IThemeService.cs

@@ -2,6 +2,8 @@
 // The Microsoft Corporation licenses this file to you under the MIT license.
 // See the LICENSE file in the project root for more information.
 
+using Microsoft.CmdPal.UI.ViewModels.Settings;
+
 namespace Microsoft.CmdPal.UI.ViewModels.Services;
 
 /// <summary>
@@ -36,4 +38,9 @@ public interface IThemeService
     /// Gets the current theme settings.
     /// </summary>
     ThemeSnapshot Current { get; }
+
+    /// <summary>
+    /// Gets the current dock theme settings.
+    /// </summary>
+    DockThemeSnapshot CurrentDockTheme { get; }
 }

src/modules/cmdpal/Microsoft.CmdPal.UI.ViewModels/Settings/DockSettings.cs

@@ -0,0 +1,172 @@
+// 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.Text.Json.Serialization;
+using Microsoft.UI;
+using Windows.UI;
+
+namespace Microsoft.CmdPal.UI.ViewModels.Settings;
+
+#pragma warning disable SA1402 // File may only contain a single type
+
+/// <summary>
+/// Settings for the Dock. These are settings for _the whole dock_. Band-specific
+/// settings are in <see cref="DockBandSettings"/>.
+/// </summary>
+public class DockSettings
+{
+    public DockSide Side { get; set; } = DockSide.Top;
+
+    public DockSize DockSize { get; set; } = DockSize.Small;
+
+    public DockSize DockIconsSize { get; set; } = DockSize.Small;
+
+    // <Theme settings>
+    public DockBackdrop Backdrop { get; set; } = DockBackdrop.Acrylic;
+
+    public UserTheme Theme { get; set; } = UserTheme.Default;
+
+    public ColorizationMode ColorizationMode { get; set; }
+
+    public Color CustomThemeColor { get; set; } = Colors.Transparent;
+
+    public int CustomThemeColorIntensity { get; set; } = 100;
+
+    public int BackgroundImageOpacity { get; set; } = 20;
+
+    public int BackgroundImageBlurAmount { get; set; }
+
+    public int BackgroundImageBrightness { get; set; }
+
+    public BackgroundImageFit BackgroundImageFit { get; set; }
+
+    public string? BackgroundImagePath { get; set; }
+
+    // </Theme settings>
+    // public List<string> PinnedCommands { get; set; } = [];
+    public List<DockBandSettings> StartBands { get; set; } = [];
+
+    public List<DockBandSettings> CenterBands { get; set; } = [];
+
+    public List<DockBandSettings> EndBands { get; set; } = [];
+
+    public bool ShowLabels { get; set; } = true;
+
+    [JsonIgnore]
+    public IEnumerable<(string ProviderId, string CommandId)> AllPinnedCommands =>
+        StartBands.Select(b => (b.ProviderId, b.CommandId))
+        .Concat(CenterBands.Select(b => (b.ProviderId, b.CommandId)))
+        .Concat(EndBands.Select(b => (b.ProviderId, b.CommandId)));
+
+    public DockSettings()
+    {
+        // Initialize with default values
+        // PinnedCommands = [
+        //     "com.microsoft.cmdpal.winget"
+        // ];
+        StartBands.Add(new DockBandSettings
+        {
+            ProviderId = "com.microsoft.cmdpal.builtin.core",
+            CommandId = "com.microsoft.cmdpal.home",
+        });
+        StartBands.Add(new DockBandSettings
+        {
+            ProviderId = "WinGet",
+            CommandId = "com.microsoft.cmdpal.winget",
+            ShowLabels = false,
+        });
+
+        EndBands.Add(new DockBandSettings
+        {
+            ProviderId = "PerformanceMonitor",
+            CommandId = "com.microsoft.cmdpal.performanceWidget",
+        });
+        EndBands.Add(new DockBandSettings
+        {
+            ProviderId = "com.microsoft.cmdpal.builtin.datetime",
+            CommandId = "com.microsoft.cmdpal.timedate.dockBand",
+        });
+    }
+}
+
+/// <summary>
+/// Settings for a specific dock band. These are per-band settings stored
+/// within the overall <see cref="DockSettings"/>.
+/// </summary>
+public class DockBandSettings
+{
+    public required string ProviderId { get; set; }
+
+    public required string CommandId { get; set; }
+
+    /// <summary>
+    /// Gets or sets whether titles are shown for items in this band.
+    /// If null, falls back to dock-wide ShowLabels setting.
+    /// </summary>
+    public bool? ShowTitles { get; set; }
+
+    /// <summary>
+    /// Gets or sets whether subtitles are shown for items in this band.
+    /// If null, falls back to dock-wide ShowLabels setting.
+    /// </summary>
+    public bool? ShowSubtitles { get; set; }
+
+    /// <summary>
+    /// Gets or sets a value for backward compatibility. Maps to ShowTitles.
+    /// </summary>
+    [System.Text.Json.Serialization.JsonIgnore]
+    public bool? ShowLabels
+    {
+        get => ShowTitles;
+        set => ShowTitles = value;
+    }
+
+    /// <summary>
+    /// Resolves the effective value of <see cref="ShowTitles"/> for this band.
+    /// If this band doesn't have a specific value set, we'll fall back to the
+    /// dock-wide setting (passed as <paramref name="defaultValue"/>).
+    /// </summary>
+    public bool ResolveShowTitles(bool defaultValue) => ShowTitles ?? defaultValue;
+
+    /// <summary>
+    /// Resolves the effective value of <see cref="ShowSubtitles"/> for this band.
+    /// If this band doesn't have a specific value set, we'll fall back to the
+    /// dock-wide setting (passed as <paramref name="defaultValue"/>).
+    /// </summary>
+    public bool ResolveShowSubtitles(bool defaultValue) => ShowSubtitles ?? defaultValue;
+
+    public DockBandSettings Clone()
+    {
+        return new()
+        {
+            ProviderId = this.ProviderId,
+            CommandId = this.CommandId,
+            ShowTitles = this.ShowTitles,
+            ShowSubtitles = this.ShowSubtitles,
+        };
+    }
+}
+
+public enum DockSide
+{
+    Left = 0,
+    Top = 1,
+    Right = 2,
+    Bottom = 3,
+}
+
+public enum DockSize
+{
+    Small,
+    Medium,
+    Large,
+}
+
+public enum DockBackdrop
+{
+    Transparent,
+    Acrylic,
+}
+
+#pragma warning restore SA1402 // File may only contain a single type

src/modules/cmdpal/Microsoft.CmdPal.UI.ViewModels/SettingsModel.cs

@@ -1,4 +1,4 @@
-// Copyright (c) Microsoft Corporation
+// 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.
 
@@ -68,6 +68,11 @@ public partial class SettingsModel : ObservableObject
 
     public EscapeKeyBehavior EscapeKeyBehaviorSetting { get; set; } = EscapeKeyBehavior.ClearSearchFirstThenGoBack;
 
+    public bool EnableDock { get; set; }
+
+    public DockSettings DockSettings { get; set; } = new();
+
+    // Theme settings
     public UserTheme Theme { get; set; } = UserTheme.Default;
 
     public ColorizationMode ColorizationMode { get; set; }
@@ -92,6 +97,8 @@ public partial class SettingsModel : ObservableObject
 
     public int BackdropOpacity { get; set; } = 100;
 
+    // </Theme settings>
+
     // END SETTINGS
     ///////////////////////////////////////////////////////////////////////////
 
@@ -230,7 +237,7 @@ public partial class SettingsModel : ObservableObject
         return false;
     }
 
-    public static void SaveSettings(SettingsModel model)
+    public static void SaveSettings(SettingsModel model, bool hotReload = true)
     {
         if (string.IsNullOrEmpty(FilePath))
         {
@@ -265,7 +272,10 @@ public partial class SettingsModel : ObservableObject
                     // TODO: Instead of just raising the event here, we should
                     // have a file change watcher on the settings file, and
                     // reload the settings then
-                    model.SettingsChanged?.Invoke(model, null);
+                    if (hotReload)
+                    {
+                        model.SettingsChanged?.Invoke(model, null);
+                    }
                 }
                 else
                 {
@@ -311,6 +321,7 @@ public partial class SettingsModel : ObservableObject
 [JsonSerializable(typeof(int))]
 [JsonSerializable(typeof(string))]
 [JsonSerializable(typeof(bool))]
+[JsonSerializable(typeof(Color))]
 [JsonSerializable(typeof(HistoryItem))]
 [JsonSerializable(typeof(SettingsModel))]
 [JsonSerializable(typeof(WindowPosition))]

src/modules/cmdpal/Microsoft.CmdPal.UI.ViewModels/SettingsViewModel.cs

@@ -4,6 +4,8 @@
 
 using System.Collections.ObjectModel;
 using System.ComponentModel;
+using CommunityToolkit.Mvvm.Messaging;
+using Microsoft.CmdPal.UI.ViewModels.Messages;
 using Microsoft.CmdPal.UI.ViewModels.Services;
 using Microsoft.CmdPal.UI.ViewModels.Settings;
 using Microsoft.CommandPalette.Extensions.Toolkit;
@@ -32,6 +34,8 @@ public partial class SettingsViewModel : INotifyPropertyChanged
 
     public AppearanceSettingsViewModel Appearance { get; }
 
+    public DockAppearanceSettingsViewModel DockAppearance { get; }
+
     public HotkeySettings? Hotkey
     {
         get => _settings.Hotkey;
@@ -183,6 +187,58 @@ public partial class SettingsViewModel : INotifyPropertyChanged
         }
     }
 
+    public DockSide Dock_Side
+    {
+        get => _settings.DockSettings.Side;
+        set
+        {
+            _settings.DockSettings.Side = value;
+            Save();
+        }
+    }
+
+    public DockSize Dock_DockSize
+    {
+        get => _settings.DockSettings.DockSize;
+        set
+        {
+            _settings.DockSettings.DockSize = value;
+            Save();
+        }
+    }
+
+    public DockBackdrop Dock_Backdrop
+    {
+        get => _settings.DockSettings.Backdrop;
+        set
+        {
+            _settings.DockSettings.Backdrop = value;
+            Save();
+        }
+    }
+
+    public bool Dock_ShowLabels
+    {
+        get => _settings.DockSettings.ShowLabels;
+        set
+        {
+            _settings.DockSettings.ShowLabels = value;
+            Save();
+        }
+    }
+
+    public bool EnableDock
+    {
+        get => _settings.EnableDock;
+        set
+        {
+            _settings.EnableDock = value;
+            Save();
+            WeakReferenceMessenger.Default.Send(new ShowHideDockMessage(value));
+            WeakReferenceMessenger.Default.Send(new ReloadCommandsMessage()); // TODO! we need to update the MoreCommands of all top level items, but we don't _really_ want to reload
+        }
+    }
+
     public ObservableCollection<ProviderSettingsViewModel> CommandProviders { get; } = new();
 
     public ObservableCollection<FallbackSettingsViewModel> FallbackRankings { get; set; } = new();
@@ -195,6 +251,7 @@ public partial class SettingsViewModel : INotifyPropertyChanged
         _topLevelCommandManager = topLevelCommandManager;
 
         Appearance = new AppearanceSettingsViewModel(themeService, _settings);
+        DockAppearance = new DockAppearanceSettingsViewModel(themeService, _settings);
 
         var activeProviders = GetCommandProviders();
         var allProviderSettings = _settings.ProviderSettings;

src/modules/cmdpal/Microsoft.CmdPal.UI.ViewModels/ShellViewModel.cs

@@ -9,6 +9,7 @@ using CommunityToolkit.Mvvm.Messaging;
 using Microsoft.CmdPal.Common;
 using Microsoft.CmdPal.UI.ViewModels.Messages;
 using Microsoft.CmdPal.UI.ViewModels.Models;
+using Microsoft.CmdPal.ViewModels.Messages;
 using Microsoft.CommandPalette.Extensions;
 
 namespace Microsoft.CmdPal.UI.ViewModels;
@@ -16,7 +17,8 @@ namespace Microsoft.CmdPal.UI.ViewModels;
 public partial class ShellViewModel : ObservableObject,
     IDisposable,
     IRecipient<PerformCommandMessage>,
-    IRecipient<HandleCommandResultMessage>
+    IRecipient<HandleCommandResultMessage>,
+    IRecipient<WindowHiddenMessage>
 {
     private readonly IRootPageService _rootPageService;
     private readonly IAppHostService _appHostService;
@@ -79,8 +81,9 @@ public partial class ShellViewModel : ObservableObject,
     private IPage? _rootPage;
 
     private bool _isNested;
+    private bool _currentlyTransient;
 
-    public bool IsNested => _isNested;
+    public bool IsNested => _isNested && !_currentlyTransient;
 
     public PageViewModel NullPage { get; private set; }
 
@@ -101,6 +104,7 @@ public partial class ShellViewModel : ObservableObject,
         // Register to receive messages
         WeakReferenceMessenger.Default.Register<PerformCommandMessage>(this);
         WeakReferenceMessenger.Default.Register<HandleCommandResultMessage>(this);
+        WeakReferenceMessenger.Default.Register<WindowHiddenMessage>(this);
     }
 
     [RelayCommand]
@@ -260,7 +264,7 @@ public partial class ShellViewModel : ObservableObject,
         var host = _appHostService.GetHostForCommand(message.Context, CurrentPage.ExtensionHost);
         var providerContext = _appHostService.GetProviderContextForCommand(message.Context, CurrentPage.ProviderContext);
 
-        _rootPageService.OnPerformCommand(message.Context, !CurrentPage.IsNested, host);
+        _rootPageService.OnPerformCommand(message.Context, CurrentPage.IsRootPage, host);
 
         try
         {
@@ -270,6 +274,7 @@ public partial class ShellViewModel : ObservableObject,
 
                 var isMainPage = command == _rootPage;
                 _isNested = !isMainPage;
+                _currentlyTransient = message.TransientPage;
 
                 // Telemetry: Track extension page navigation for session metrics
                 if (host is not null)
@@ -289,6 +294,9 @@ public partial class ShellViewModel : ObservableObject,
                     throw new NotSupportedException();
                 }
 
+                pageViewModel.IsRootPage = isMainPage;
+                pageViewModel.HasBackButton = IsNested;
+
                 // Clear command bar, ViewModel initialization can already set new commands if it wants to
                 OnUIThread(() => WeakReferenceMessenger.Default.Send<UpdateCommandBarMessage>(new(null)));
 
@@ -308,7 +316,8 @@ public partial class ShellViewModel : ObservableObject,
                         _scheduler);
 
                 // While we're loading in the background, immediately move to the next page.
-                WeakReferenceMessenger.Default.Send<NavigateToPageMessage>(new(pageViewModel, message.WithAnimation, navigationToken));
+                NavigateToPageMessage msg = new(pageViewModel, message.WithAnimation, navigationToken, message.TransientPage);
+                WeakReferenceMessenger.Default.Send(msg);
 
                 // Note: Originally we set our page back in the ViewModel here, but that now happens in response to the Frame navigating triggered from the above
                 // See RootFrame_Navigated event handler.
@@ -479,6 +488,19 @@ public partial class ShellViewModel : ObservableObject,
         UnsafeHandleCommandResult(message.Result.Unsafe);
     }
 
+    public void Receive(WindowHiddenMessage message)
+    {
+        // If the window was hidden while we had a transient page, we need to reset that state.
+        if (_currentlyTransient)
+        {
+            _currentlyTransient = false;
+
+            // navigate back to the main page without animation
+            GoHome(withAnimation: false, focusSearch: false);
+            WeakReferenceMessenger.Default.Send<PerformCommandMessage>(new(new ExtensionObject<ICommand>(_rootPage)));
+        }
+    }
+
     private void OnUIThread(Action action)
     {
         _ = Task.Factory.StartNew(

src/modules/cmdpal/Microsoft.CmdPal.UI.ViewModels/TopLevelCommandManager.cs

@@ -23,6 +23,7 @@ public partial class TopLevelCommandManager : ObservableObject,
     IRecipient<ReloadCommandsMessage>,
     IRecipient<PinCommandItemMessage>,
     IRecipient<UnpinCommandItemMessage>,
+    IRecipient<PinToDockMessage>,
     IDisposable
 {
     private readonly IServiceProvider _serviceProvider;
@@ -32,6 +33,11 @@ public partial class TopLevelCommandManager : ObservableObject,
     private readonly List<CommandProviderWrapper> _builtInCommands = [];
     private readonly List<CommandProviderWrapper> _extensionCommandProviders = [];
     private readonly Lock _commandProvidersLock = new();
+
+    // watch out: if you add code that locks CommandProviders, be sure to always
+    // lock CommandProviders before locking DockBands, or you will cause a
+    // deadlock.
+    private readonly Lock _dockBandsLock = new();
     private readonly SupersedingAsyncGate _reloadCommandsGate;
 
     public TopLevelCommandManager(IServiceProvider serviceProvider, ICommandProviderCache commandProviderCache)
@@ -42,11 +48,14 @@ public partial class TopLevelCommandManager : ObservableObject,
         WeakReferenceMessenger.Default.Register<ReloadCommandsMessage>(this);
         WeakReferenceMessenger.Default.Register<PinCommandItemMessage>(this);
         WeakReferenceMessenger.Default.Register<UnpinCommandItemMessage>(this);
+        WeakReferenceMessenger.Default.Register<PinToDockMessage>(this);
         _reloadCommandsGate = new(ReloadAllCommandsAsyncCore);
     }
 
     public ObservableCollection<TopLevelViewModel> TopLevelCommands { get; set; } = [];
 
+    public ObservableCollection<TopLevelViewModel> DockBands { get; set; } = [];
+
     [ObservableProperty]
     public partial bool IsLoading { get; private set; } = true;
 
@@ -82,12 +91,26 @@ public partial class TopLevelCommandManager : ObservableObject,
                 _builtInCommands.Add(wrapper);
             }
 
-            var commands = await LoadTopLevelCommandsFromProvider(wrapper);
+            var objects = await LoadTopLevelCommandsFromProvider(wrapper);
             lock (TopLevelCommands)
             {
-                foreach (var c in commands)
+                if (objects.Commands is IEnumerable<TopLevelViewModel> commands)
                 {
-                    TopLevelCommands.Add(c);
+                    foreach (var c in commands)
+                    {
+                        TopLevelCommands.Add(c);
+                    }
+                }
+            }
+
+            lock (_dockBandsLock)
+            {
+                if (objects.DockBands is IEnumerable<TopLevelViewModel> bands)
+                {
+                    foreach (var c in bands)
+                    {
+                        DockBands.Add(c);
+                    }
                 }
             }
         }
@@ -100,7 +123,7 @@ public partial class TopLevelCommandManager : ObservableObject,
     }
 
     // May be called from a background thread
-    private async Task<IEnumerable<TopLevelViewModel>> LoadTopLevelCommandsFromProvider(CommandProviderWrapper commandProvider)
+    private async Task<TopLevelObjectSets> LoadTopLevelCommandsFromProvider(CommandProviderWrapper commandProvider)
     {
         await commandProvider.LoadTopLevelCommands(_serviceProvider);
 
@@ -108,6 +131,7 @@ public partial class TopLevelCommandManager : ObservableObject,
             () =>
             {
                 List<TopLevelViewModel> commands = [];
+                List<TopLevelViewModel> bands = [];
                 foreach (var item in commandProvider.TopLevelItems)
                 {
                     commands.Add(item);
@@ -121,7 +145,15 @@ public partial class TopLevelCommandManager : ObservableObject,
                     }
                 }
 
-                return commands;
+                foreach (var item in commandProvider.DockBandItems)
+                {
+                    bands.Add(item);
+                }
+
+                var commandsCount = commands.Count;
+                var bandsCount = bands.Count;
+                Logger.LogDebug($"{commandProvider.ProviderId}: Loaded {commandsCount} commands, {bandsCount} bands");
+                return new TopLevelObjectSets(commands, bands);
             },
             CancellationToken.None,
             TaskCreationOptions.None,
@@ -160,6 +192,8 @@ public partial class TopLevelCommandManager : ObservableObject,
             }
         }
 
+        List<TopLevelViewModel> newBands = [.. sender.DockBandItems];
+
         // modify the TopLevelCommands under shared lock; event if we clone it, we don't want
         // TopLevelCommands to get modified while we're working on it. Otherwise, we might
         // out clone would be stale at the end of this method.
@@ -178,6 +212,16 @@ public partial class TopLevelCommandManager : ObservableObject,
             ListHelpers.InPlaceUpdateList(TopLevelCommands, clone);
         }
 
+        lock (_dockBandsLock)
+        {
+            // same idea for DockBands
+            List<TopLevelViewModel> dockClone = [.. DockBands];
+            var dockStartIndex = FindIndexForFirstProviderItem(dockClone, sender.ProviderId);
+            dockClone.RemoveAll(item => item.CommandProviderId == sender.ProviderId);
+            dockClone.InsertRange(dockStartIndex, newBands);
+            ListHelpers.InPlaceUpdateList(DockBands, dockClone);
+        }
+
         return;
 
         static int FindIndexForFirstProviderItem(List<TopLevelViewModel> topLevelItems, string providerId)
@@ -224,6 +268,11 @@ public partial class TopLevelCommandManager : ObservableObject,
             TopLevelCommands.Clear();
         }
 
+        lock (_dockBandsLock)
+        {
+            DockBands.Clear();
+        }
+
         await LoadBuiltinsAsync();
         _ = Task.Run(LoadExtensionsAsync);
     }
@@ -298,13 +347,31 @@ public partial class TopLevelCommandManager : ObservableObject,
 
         var commandSets = (await Task.WhenAll(loadTasks)).Where(results => results is not null).Select(r => r!).ToList();
 
-        lock (TopLevelCommands)
+        foreach (var providerObjects in commandSets)
         {
-            foreach (var commands in commandSets)
+            var commandsCount = providerObjects.Commands?.Count() ?? 0;
+            var bandsCount = providerObjects.DockBands?.Count() ?? 0;
+            Logger.LogDebug($"(some provider) Loaded {commandsCount} commands and {bandsCount} bands");
+
+            lock (TopLevelCommands)
             {
-                foreach (var c in commands)
+                if (providerObjects.Commands is IEnumerable<TopLevelViewModel> commands)
                 {
-                    TopLevelCommands.Add(c);
+                    foreach (var c in commands)
+                    {
+                        TopLevelCommands.Add(c);
+                    }
+                }
+            }
+
+            lock (_dockBandsLock)
+            {
+                if (providerObjects.DockBands is IEnumerable<TopLevelViewModel> bands)
+                {
+                    foreach (var c in bands)
+                    {
+                        DockBands.Add(c);
+                    }
                 }
             }
         }
@@ -328,7 +395,9 @@ public partial class TopLevelCommandManager : ObservableObject,
         }
     }
 
-    private async Task<IEnumerable<TopLevelViewModel>?> LoadCommandsWithTimeoutAsync(CommandProviderWrapper wrapper)
+    private record TopLevelObjectSets(IEnumerable<TopLevelViewModel>? Commands, IEnumerable<TopLevelViewModel>? DockBands);
+
+    private async Task<TopLevelObjectSets?> LoadCommandsWithTimeoutAsync(CommandProviderWrapper wrapper)
     {
         try
         {
@@ -354,6 +423,7 @@ public partial class TopLevelCommandManager : ObservableObject,
             {
                 // Then find all the top-level commands that belonged to that extension
                 List<TopLevelViewModel> commandsToRemove = [];
+                List<TopLevelViewModel> bandsToRemove = [];
                 lock (TopLevelCommands)
                 {
                     foreach (var extension in extensions)
@@ -366,6 +436,15 @@ public partial class TopLevelCommandManager : ObservableObject,
                                 commandsToRemove.Add(command);
                             }
                         }
+
+                        foreach (var band in DockBands)
+                        {
+                            var host = band.ExtensionHost;
+                            if (host?.Extension == extension)
+                            {
+                                bandsToRemove.Add(band);
+                            }
+                        }
                     }
                 }
 
@@ -385,6 +464,17 @@ public partial class TopLevelCommandManager : ObservableObject,
                             }
                         }
                     }
+
+                    lock (_dockBandsLock)
+                    {
+                        if (bandsToRemove.Count != 0)
+                        {
+                            foreach (var deleted in bandsToRemove)
+                            {
+                                DockBands.Remove(deleted);
+                            }
+                        }
+                    }
                 },
                 CancellationToken.None,
                 TaskCreationOptions.None,
@@ -408,6 +498,22 @@ public partial class TopLevelCommandManager : ObservableObject,
         return null;
     }
 
+    public TopLevelViewModel? LookupDockBand(string id)
+    {
+        lock (_dockBandsLock)
+        {
+            foreach (var command in DockBands)
+            {
+                if (command.Id == id)
+                {
+                    return command;
+                }
+            }
+        }
+
+        return null;
+    }
+
     public void Receive(ReloadCommandsMessage message) =>
         ReloadAllCommandsAsync().ConfigureAwait(false);
 
@@ -423,6 +529,21 @@ public partial class TopLevelCommandManager : ObservableObject,
         wrapper?.UnpinCommand(message.CommandId, _serviceProvider);
     }
 
+    public void Receive(PinToDockMessage message)
+    {
+        if (LookupProvider(message.ProviderId) is CommandProviderWrapper wrapper)
+        {
+            if (message.Pin)
+            {
+                wrapper?.PinDockBand(message.CommandId, _serviceProvider);
+            }
+            else
+            {
+                wrapper?.UnpinDockBand(message.CommandId, _serviceProvider);
+            }
+        }
+    }
+
     public CommandProviderWrapper? LookupProvider(string providerId)
     {
         lock (_commandProvidersLock)
@@ -441,6 +562,53 @@ public partial class TopLevelCommandManager : ObservableObject,
         }
     }
 
+    internal void PinDockBand(TopLevelViewModel bandVm)
+    {
+        lock (_dockBandsLock)
+        {
+            foreach (var existing in DockBands)
+            {
+                if (existing.Id == bandVm.Id)
+                {
+                    // already pinned
+                    Logger.LogDebug($"Dock band '{bandVm.Id}' is already pinned.");
+                    return;
+                }
+            }
+
+            Logger.LogDebug($"Attempting to pin dock band '{bandVm.Id}' from provider '{bandVm.CommandProviderId}'.");
+            var providerId = bandVm.CommandProviderId;
+            var foundProvider = false;
+
+            // WATCH OUT: This locks CommandProviders. If you add code that
+            // locks CommandProviders first, before locking DockBands, you will
+            // cause a deadlock.
+            foreach (var provider in CommandProviders)
+            {
+                if (provider.Id == providerId)
+                {
+                    Logger.LogDebug($"Found provider '{providerId}' to pin dock band '{bandVm.Id}'.");
+                    provider.PinDockBand(bandVm);
+                    foundProvider = true;
+                    break;
+                }
+            }
+
+            if (!foundProvider)
+            {
+                Logger.LogWarning($"Could not find provider '{providerId}' to pin dock band '{bandVm.Id}'.");
+            }
+            else
+            {
+                // Add the band to DockBands if not already present
+                if (!DockBands.Any(b => b.Id == bandVm.Id))
+                {
+                    DockBands.Add(bandVm);
+                }
+            }
+        }
+    }
+
     public void Dispose()
     {
         _reloadCommandsGate.Dispose();

src/modules/cmdpal/Microsoft.CmdPal.UI.ViewModels/TopLevelViewModel.cs

@@ -25,6 +25,7 @@ public sealed partial class TopLevelViewModel : ObservableObject, IListItem, IEx
     private readonly ProviderSettings _providerSettings;
     private readonly IServiceProvider _serviceProvider;
     private readonly CommandItemViewModel _commandItemViewModel;
+    private readonly IContextMenuFactory _contextMenuFactory;
 
     public ICommandProviderContext ProviderContext { get; private set; }
 
@@ -52,39 +53,28 @@ public sealed partial class TopLevelViewModel : ObservableObject, IListItem, IEx
 
     public CommandPaletteHost ExtensionHost { get; private set; }
 
+    public string ExtensionName => ExtensionHost.GetExtensionDisplayName() ?? string.Empty;
+
     public CommandViewModel CommandViewModel => _commandItemViewModel.Command;
 
     public CommandItemViewModel ItemViewModel => _commandItemViewModel;
 
     public string CommandProviderId => ProviderContext.ProviderId;
 
+    public IconInfoViewModel IconViewModel => _commandItemViewModel.Icon;
+
     ////// ICommandItem
     public string Title => _commandItemViewModel.Title;
 
     public string Subtitle => _commandItemViewModel.Subtitle;
 
-    public IIconInfo Icon => _commandItemViewModel.Icon;
+    public IIconInfo Icon => (IIconInfo)IconViewModel;
 
     public IIconInfo InitialIcon => _initialIcon ?? _commandItemViewModel.Icon;
 
     ICommand? ICommandItem.Command => _commandItemViewModel.Command.Model.Unsafe;
 
-    IContextItem?[] ICommandItem.MoreCommands => _commandItemViewModel.MoreCommands
-                                                    .Select(item =>
-                                                    {
-                                                        if (item is ISeparatorContextItem)
-                                                        {
-                                                            return item as IContextItem;
-                                                        }
-                                                        else if (item is CommandContextItemViewModel commandItem)
-                                                        {
-                                                            return commandItem.Model.Unsafe;
-                                                        }
-                                                        else
-                                                        {
-                                                            return null;
-                                                        }
-                                                    }).ToArray();
+    IContextItem?[] ICommandItem.MoreCommands => BuildContextMenu();
 
     ////// IListItem
     ITag[] IListItem.Tags => Tags.ToArray();
@@ -183,17 +173,46 @@ public sealed partial class TopLevelViewModel : ObservableObject, IListItem, IEx
         }
     }
 
-    public string ExtensionName => ExtensionHost.GetExtensionDisplayName() ?? string.Empty;
+    // Dock properties
+    public bool IsDockBand { get; private set; }
+
+    public DockBandSettings? DockBandSettings
+    {
+        get
+        {
+            if (!IsDockBand)
+            {
+                return null;
+            }
+
+            var bandSettings = _settings.DockSettings.StartBands
+                .Concat(_settings.DockSettings.CenterBands)
+                .Concat(_settings.DockSettings.EndBands)
+                .FirstOrDefault(band => band.CommandId == this.Id);
+            if (bandSettings is null)
+            {
+                return new DockBandSettings()
+                {
+                    ProviderId = this.CommandProviderId,
+                    CommandId = this.Id,
+                    ShowLabels = true,
+                };
+            }
+
+            return bandSettings;
+        }
+    }
 
     public TopLevelViewModel(
         CommandItemViewModel item,
-        bool isFallback,
+        TopLevelType topLevelType,
         CommandPaletteHost extensionHost,
         ICommandProviderContext commandProviderContext,
         SettingsModel settings,
         ProviderSettings providerSettings,
         IServiceProvider serviceProvider,
-        ICommandItem? commandItem)
+        ICommandItem? commandItem,
+        IContextMenuFactory? contextMenuFactory)
     {
         _serviceProvider = serviceProvider;
         _settings = settings;
@@ -201,22 +220,26 @@ public sealed partial class TopLevelViewModel : ObservableObject, IListItem, IEx
         ProviderContext = commandProviderContext;
         _commandItemViewModel = item;
 
-        IsFallback = isFallback;
+        _contextMenuFactory = contextMenuFactory ?? DefaultContextMenuFactory.Instance;
+
+        IsFallback = topLevelType == TopLevelType.Fallback;
+        IsDockBand = topLevelType == TopLevelType.DockBand;
         ExtensionHost = extensionHost;
-        if (isFallback && commandItem is FallbackCommandItem fallback)
+        if (IsFallback && commandItem is FallbackCommandItem fallback)
         {
             _fallbackId = fallback.Id;
         }
 
         item.PropertyChangedBackground += Item_PropertyChanged;
-
-        // UpdateAlias();
-        // UpdateHotkey();
-        // UpdateTags();
     }
 
     internal void InitializeProperties()
     {
+        // Init first, so that we get the ID & titles,
+        // then generate the ID,
+        // then slow init for the context menu
+        ItemViewModel.InitializeProperties();
+        GenerateId();
         ItemViewModel.SlowInitializeProperties();
 
         if (IsFallback)
@@ -278,7 +301,7 @@ public sealed partial class TopLevelViewModel : ObservableObject, IListItem, IEx
             return;
         }
 
-        _initialIcon = _commandItemViewModel.Icon;
+        _initialIcon = (IIconInfo?)_commandItemViewModel.Icon;
 
         if (raiseNotification)
         {
@@ -452,4 +475,43 @@ public sealed partial class TopLevelViewModel : ObservableObject, IListItem, IEx
     {
         return ToString();
     }
+
+    /// <summary>
+    /// Helper to convert our context menu viewmodels back into the API
+    /// interfaces that ICommandItem expects.
+    /// </summary>
+    private IContextItem?[] BuildContextMenu()
+    {
+        List<IContextItem?> contextItems = new();
+
+        foreach (var item in _commandItemViewModel.MoreCommands)
+        {
+            if (item is ISeparatorContextItem)
+            {
+                contextItems.Add(item as IContextItem);
+            }
+            else if (item is CommandContextItemViewModel commandItem)
+            {
+                contextItems.Add(commandItem.Model.Unsafe);
+            }
+        }
+
+        _contextMenuFactory.AddMoreCommandsToTopLevel(this, this.ProviderContext, contextItems);
+
+        return contextItems.ToArray();
+    }
+
+    internal ICommandItem ToPinnedDockBandItem()
+    {
+        var item = new PinnedDockItem(item: this, id: Id);
+
+        return item;
+    }
+}
+
+public enum TopLevelType
+{
+    Normal,
+    Fallback,
+    DockBand,
 }

src/modules/cmdpal/Microsoft.CmdPal.UI/App.xaml

@@ -4,6 +4,7 @@
     xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
     xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
     xmlns:controls="using:Microsoft.CmdPal.UI.Controls"
+    xmlns:converters="using:CommunityToolkit.WinUI.Converters"
     xmlns:local="using:Microsoft.CmdPal.UI"
     xmlns:ptcontrols="using:Microsoft.PowerToys.Common.UI.Controls"
     xmlns:services="using:Microsoft.CmdPal.UI.Services">
@@ -12,7 +13,7 @@
             <ResourceDictionary.MergedDictionaries>
                 <XamlControlsResources xmlns="using:Microsoft.UI.Xaml.Controls" />
                 <!--  Other merged dictionaries here  -->
-                <ResourceDictionary Source="ms-appx:///Styles/Colors.xaml" />
+                <ResourceDictionary Source="ms-appx:///Styles/TeachingTip.xaml" />
                 <ResourceDictionary Source="ms-appx:///Styles/TextBlock.xaml" />
                 <ResourceDictionary Source="ms-appx:///Styles/TextBox.xaml" />
                 <ResourceDictionary Source="ms-appx:///Styles/Settings.xaml" />
@@ -21,6 +22,7 @@
                 <ResourceDictionary Source="ms-appx:///PowerToys.Common.UI.Controls/Controls/KeyVisual/KeyCharPresenter.xaml" />
                 <ResourceDictionary Source="ms-appx:///PowerToys.Common.UI.Controls/Controls/ShortcutWithTextLabelControl/ShortcutWithTextLabelControl.xaml" />
                 <ResourceDictionary Source="ms-appx:///PowerToys.Common.UI.Controls/Controls/IsEnabledTextBlock/IsEnabledTextBlock.xaml" />
+                <ResourceDictionary Source="ms-appx:///Dock/DockItemControl.xaml" />
                 <!--  Default theme dictionary  -->
                 <ResourceDictionary Source="ms-appx:///Styles/Theme.Normal.xaml" />
                 <services:MutableOverridesDictionary />
@@ -29,6 +31,12 @@
 
             <x:Double x:Key="SettingActionControlMinWidth">240</x:Double>
             <Style BasedOn="{StaticResource DefaultCheckBoxStyle}" TargetType="ptcontrols:CheckBoxWithDescriptionControl" />
+
+            <converters:StringVisibilityConverter
+                x:Key="StringNotEmptyToVisibilityConverter"
+                EmptyValue="Collapsed"
+                NotEmptyValue="Visible" />
+
         </ResourceDictionary>
     </Application.Resources>
 </Application>

src/modules/cmdpal/Microsoft.CmdPal.UI/App.xaml.cs

@@ -28,6 +28,7 @@ using Microsoft.CmdPal.UI.Helpers;
 using Microsoft.CmdPal.UI.Services;
 using Microsoft.CmdPal.UI.ViewModels;
 using Microsoft.CmdPal.UI.ViewModels.BuiltinCommands;
+using Microsoft.CmdPal.UI.ViewModels.Dock;
 using Microsoft.CmdPal.UI.ViewModels.Models;
 using Microsoft.CmdPal.UI.ViewModels.Services;
 using Microsoft.CommandPalette.Extensions;
@@ -220,6 +221,7 @@ public partial class App : Application, IDisposable
 
         // ViewModels
         services.AddSingleton<ShellViewModel>();
+        services.AddSingleton<DockViewModel>();
         services.AddSingleton<IContextMenuFactory, CommandPaletteContextMenuFactory>();
         services.AddSingleton<IPageViewModelFactoryService, CommandPalettePageViewModelFactory>();
     }

src/modules/cmdpal/Microsoft.CmdPal.UI/CommandPaletteContextMenuFactory.cs

@@ -6,6 +6,7 @@ using CommunityToolkit.Mvvm.Messaging;
 using ManagedCommon;
 using Microsoft.CmdPal.UI.ViewModels;
 using Microsoft.CmdPal.UI.ViewModels.Messages;
+using Microsoft.CmdPal.UI.ViewModels.Settings;
 using Microsoft.CommandPalette.Extensions;
 using Microsoft.CommandPalette.Extensions.Toolkit;
 using RS_ = Microsoft.CmdPal.UI.Helpers.ResourceLoaderInstance;
@@ -23,22 +24,45 @@ internal sealed partial class CommandPaletteContextMenuFactory : IContextMenuFac
         _topLevelCommandManager = topLevelCommandManager;
     }
 
+    /// <summary>
+    /// Constructs the view models for the MoreCommands of a
+    /// CommandItemViewModel. In our case, we can use our settings to add a
+    /// contextually-relevant pin/unpin command to this item.
+    ///
+    /// This is called on all CommandItemViewModels. There are however some
+    /// weird edge cases we need to handle, concerning
+    /// </summary>
     public List<IContextItemViewModel> UnsafeBuildAndInitMoreCommands(
         IContextItem[] items,
         CommandItemViewModel commandItem)
     {
         var results = DefaultContextMenuFactory.Instance.UnsafeBuildAndInitMoreCommands(items, commandItem);
 
+        IPageContext? page = null;
+        var succeeded = commandItem.PageContext.TryGetTarget(out page);
+        if (!succeeded || page is null)
+        {
+            return results;
+        }
+
+        var isTopLevelItem = page is TopLevelItemPageContext;
+        if (isTopLevelItem)
+        {
+            // Bail early. We'll handle it below.
+            return results;
+        }
+
         List<IContextItem> moreCommands = [];
         var itemId = commandItem.Command.Id;
+        var providerContext = page.ProviderContext;
+        var supportsPinning = providerContext.SupportsPinning;
 
-        if (commandItem.PageContext.TryGetTarget(out var page) &&
-            page.ProviderContext.SupportsPinning &&
+        if (supportsPinning &&
             !string.IsNullOrEmpty(itemId))
         {
             // Add pin/unpin commands for pinning items to the top-level or to
             // the dock.
-            var providerId = page.ProviderContext.ProviderId;
+            var providerId = providerContext.ProviderId;
             if (_topLevelCommandManager.LookupProvider(providerId) is CommandProviderWrapper provider)
             {
                 var providerSettings = _settingsModel.GetProviderSettings(provider);
@@ -51,8 +75,6 @@ internal sealed partial class CommandPaletteContextMenuFactory : IContextMenuFac
                 // We can't look up if this command item is in the top level
                 // items in the manager, because we are being called _before_ we
                 // get added to the manager's list of commands.
-                var isTopLevelItem = page is TopLevelItemPageContext;
-
                 if (!isTopLevelItem || alreadyPinnedToTopLevel)
                 {
                     var pinToTopLevelCommand = new PinToCommand(
@@ -66,6 +88,8 @@ internal sealed partial class CommandPaletteContextMenuFactory : IContextMenuFac
                     var contextItem = new PinToContextItem(pinToTopLevelCommand, commandItem);
                     moreCommands.Add(contextItem);
                 }
+
+                TryAddPinToDockCommand(providerSettings, itemId, providerId, moreCommands, commandItem);
             }
         }
 
@@ -79,6 +103,99 @@ internal sealed partial class CommandPaletteContextMenuFactory : IContextMenuFac
         return results;
     }
 
+    /// <summary>
+    /// Called to create the context menu on TopLevelViewModels.
+    ///
+    /// These are handled differently from everyone else. With
+    /// TopLevelViewModels, the ID isn't on the Command, it is on the
+    /// TopLevelViewModel itself. Basically, we can't figure out how to add
+    /// pin/unpin commands directly attached to the ICommandItems that we get
+    /// from the API.
+    ///
+    /// Instead, this method is used to extend the set of IContextItems that are
+    /// added to the TopLevelViewModel itself. This lets us pin/unpin the
+    /// generated ID of the TopLevelViewModel, even if the command didn't have
+    /// one.
+    /// </summary>
+    public void AddMoreCommandsToTopLevel(
+        TopLevelViewModel topLevelItem,
+        ICommandProviderContext providerContext,
+        List<IContextItem?> contextItems)
+    {
+        var itemId = topLevelItem.Id;
+        var supportsPinning = providerContext.SupportsPinning;
+        List<IContextItem> moreCommands = [];
+        var commandItem = topLevelItem.ItemViewModel;
+
+        // Add pin/unpin commands for pinning items to the top-level or to
+        // the dock.
+        var providerId = providerContext.ProviderId;
+        if (_topLevelCommandManager.LookupProvider(providerId) is CommandProviderWrapper provider)
+        {
+            var providerSettings = _settingsModel.GetProviderSettings(provider);
+
+            var isPinnedSubCommand = providerSettings.PinnedCommandIds.Contains(itemId);
+            if (isPinnedSubCommand)
+            {
+                var pinToTopLevelCommand = new PinToCommand(
+                       commandId: itemId,
+                       providerId: providerId,
+                       pin: !isPinnedSubCommand,
+                       PinLocation.TopLevel,
+                       _settingsModel,
+                       _topLevelCommandManager);
+
+                var contextItem = new PinToContextItem(pinToTopLevelCommand, commandItem);
+                moreCommands.Add(contextItem);
+            }
+
+            TryAddPinToDockCommand(providerSettings, itemId, providerId, moreCommands, commandItem);
+        }
+
+        if (moreCommands.Count > 0)
+        {
+            moreCommands.Insert(0, new Separator());
+
+            // var moreResults = DefaultContextMenuFactory.Instance.UnsafeBuildAndInitMoreCommands(moreCommands.ToArray(), commandItem);
+            contextItems.AddRange(moreCommands);
+        }
+    }
+
+    private void TryAddPinToDockCommand(
+        ProviderSettings providerSettings,
+        string itemId,
+        string providerId,
+        List<IContextItem> moreCommands,
+        CommandItemViewModel commandItem)
+    {
+        if (!_settingsModel.EnableDock)
+        {
+            return;
+        }
+
+        var inStartBands = _settingsModel.DockSettings.StartBands.Any(band => MatchesBand(band, itemId, providerId));
+        var inCenterBands = _settingsModel.DockSettings.CenterBands.Any(band => MatchesBand(band, itemId, providerId));
+        var inEndBands = _settingsModel.DockSettings.EndBands.Any(band => MatchesBand(band, itemId, providerId));
+        var alreadyPinned = inStartBands || inCenterBands || inEndBands; /** &&
+                            _settingsModel.DockSettings.PinnedCommands.Contains(this.Id)**/
+        var pinToTopLevelCommand = new PinToCommand(
+            commandId: itemId,
+            providerId: providerId,
+            pin: !alreadyPinned,
+            PinLocation.Dock,
+            _settingsModel,
+            _topLevelCommandManager);
+
+        var contextItem = new PinToContextItem(pinToTopLevelCommand, commandItem);
+        moreCommands.Add(contextItem);
+    }
+
+    internal static bool MatchesBand(DockBandSettings bandSettings, string commandId, string providerId)
+    {
+        return bandSettings.CommandId == commandId &&
+               bandSettings.ProviderId == providerId;
+    }
+
     internal enum PinLocation
     {
         TopLevel,
@@ -119,9 +236,13 @@ internal sealed partial class CommandPaletteContextMenuFactory : IContextMenuFac
         private readonly bool _pin;
         private readonly PinLocation _pinLocation;
 
+        private bool IsPinToDock => _pinLocation == PinLocation.Dock;
+
         public override IconInfo Icon => _pin ? Icons.PinIcon : Icons.UnpinIcon;
 
-        public override string Name => _pin ? RS_.GetString("top_level_pin_command_name") : RS_.GetString("top_level_unpin_command_name");
+        public override string Name => _pin ?
+            (IsPinToDock ? RS_.GetString("dock_pin_command_name") : RS_.GetString("top_level_pin_command_name")) :
+            (IsPinToDock ? RS_.GetString("dock_unpin_command_name") : RS_.GetString("top_level_unpin_command_name"));
 
         internal event EventHandler? PinStateChanged;
 
@@ -152,10 +273,9 @@ internal sealed partial class CommandPaletteContextMenuFactory : IContextMenuFac
                         PinToTopLevel();
                         break;
 
-                        // TODO: After dock is added:
-                        // case PinLocation.Dock:
-                        //     PinToDock();
-                        //     break;
+                    case PinLocation.Dock:
+                        PinToDock();
+                        break;
                 }
             }
             else
@@ -166,9 +286,9 @@ internal sealed partial class CommandPaletteContextMenuFactory : IContextMenuFac
                         UnpinFromTopLevel();
                         break;
 
-                        // case PinLocation.Dock:
-                        //     UnpinFromDock();
-                        //     break;
+                    case PinLocation.Dock:
+                        UnpinFromDock();
+                        break;
                 }
             }
 
@@ -188,5 +308,17 @@ internal sealed partial class CommandPaletteContextMenuFactory : IContextMenuFac
             UnpinCommandItemMessage message = new(_providerId, _commandId);
             WeakReferenceMessenger.Default.Send(message);
         }
+
+        private void PinToDock()
+        {
+            PinToDockMessage message = new(_providerId, _commandId, true);
+            WeakReferenceMessenger.Default.Send(message);
+        }
+
+        private void UnpinFromDock()
+        {
+            PinToDockMessage message = new(_providerId, _commandId, false);
+            WeakReferenceMessenger.Default.Send(message);
+        }
     }
 }

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

@@ -97,7 +97,7 @@
         <Grid
             x:Name="IconRoot"
             Margin="3,0,-5,0"
-            Visibility="{x:Bind CurrentPageViewModel.IsNested, Mode=OneWay}">
+            Visibility="{x:Bind CurrentPageViewModel.IsRootPage, Mode=OneWay, Converter={StaticResource BoolToInvertedVisibilityConverter}}">
             <Button
                 x:Name="StatusMessagesButton"
                 x:Uid="StatusMessagesButton"
@@ -134,7 +134,7 @@
             x:Uid="SettingsButton"
             Click="SettingsIcon_Clicked"
             Style="{StaticResource SubtleButtonStyle}"
-            Visibility="{x:Bind CurrentPageViewModel.IsNested, Mode=OneWay, Converter={StaticResource BoolToInvertedVisibilityConverter}}">
+            Visibility="{x:Bind CurrentPageViewModel.IsRootPage, Mode=OneWay}">
             <StackPanel Orientation="Horizontal" Spacing="8">
                 <FontIcon
                     VerticalAlignment="Center"
@@ -153,7 +153,7 @@
             Text="{x:Bind CurrentPageViewModel.Title, Mode=OneWay}"
             TextTrimming="CharacterEllipsis"
             TextWrapping="NoWrap"
-            Visibility="{x:Bind CurrentPageViewModel.IsNested, Mode=OneWay}" />
+            Visibility="{x:Bind CurrentPageViewModel.IsRootPage, Mode=OneWay, Converter={StaticResource BoolToInvertedVisibilityConverter}}" />
         <StackPanel
             Grid.Column="2"
             Padding="0,0,4,0"

src/modules/cmdpal/Microsoft.CmdPal.UI/Controls/ScrollContainer.xaml

@@ -0,0 +1,302 @@
+<?xml version="1.0" encoding="utf-8" ?>
+<UserControl
+    x:Class="Microsoft.CmdPal.UI.Controls.ScrollContainer"
+    xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
+    xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
+    xmlns:d="http://schemas.microsoft.com/expression/blend/2008"
+    xmlns:local="using:Microsoft.CmdPal.UI.Controls"
+    xmlns:mc="http://schemas.openxmlformats.org/markup-compatibility/2006"
+    mc:Ignorable="d">
+    <UserControl.Resources>
+        <ResourceDictionary>
+            <Style x:Key="ScrollButtonStyle" TargetType="Button">
+                <Setter Property="Background" Value="{ThemeResource FlipViewNextPreviousButtonBackground}" />
+                <Setter Property="BackgroundSizing" Value="InnerBorderEdge" />
+                <Setter Property="Foreground" Value="{ThemeResource ButtonForeground}" />
+                <Setter Property="BorderBrush" Value="{ThemeResource FlipViewNextPreviousButtonBorderBrush}" />
+                <Setter Property="BorderThickness" Value="1" />
+                <Setter Property="Padding" Value="0" />
+                <Setter Property="HorizontalAlignment" Value="Left" />
+                <Setter Property="VerticalAlignment" Value="Center" />
+                <Setter Property="FontFamily" Value="{ThemeResource ContentControlThemeFontFamily}" />
+                <Setter Property="FontWeight" Value="Normal" />
+                <Setter Property="FontSize" Value="{ThemeResource ControlContentThemeFontSize}" />
+                <Setter Property="UseSystemFocusVisuals" Value="{StaticResource UseSystemFocusVisuals}" />
+                <Setter Property="FocusVisualMargin" Value="-3" />
+                <Setter Property="CornerRadius" Value="{ThemeResource ControlCornerRadius}" />
+                <Setter Property="Template">
+                    <Setter.Value>
+                        <ControlTemplate TargetType="Button">
+                            <ContentPresenter
+                                x:Name="ContentPresenter"
+                                Padding="{TemplateBinding Padding}"
+                                HorizontalContentAlignment="{TemplateBinding HorizontalContentAlignment}"
+                                VerticalContentAlignment="{TemplateBinding VerticalContentAlignment}"
+                                AnimatedIcon.State="Normal"
+                                AutomationProperties.AccessibilityView="Raw"
+                                Background="{TemplateBinding Background}"
+                                BackgroundSizing="{TemplateBinding BackgroundSizing}"
+                                BorderBrush="{TemplateBinding BorderBrush}"
+                                BorderThickness="{TemplateBinding BorderThickness}"
+                                Content="{TemplateBinding Content}"
+                                ContentTemplate="{TemplateBinding ContentTemplate}"
+                                ContentTransitions="{TemplateBinding ContentTransitions}"
+                                CornerRadius="{TemplateBinding CornerRadius}">
+                                <ContentPresenter.BackgroundTransition>
+                                    <BrushTransition Duration="0:0:0.083" />
+                                </ContentPresenter.BackgroundTransition>
+                                <VisualStateManager.VisualStateGroups>
+                                    <VisualStateGroup x:Name="CommonStates">
+                                        <VisualState x:Name="Normal" />
+                                        <VisualState x:Name="PointerOver">
+                                            <Storyboard>
+                                                <ObjectAnimationUsingKeyFrames Storyboard.TargetName="ContentPresenter" Storyboard.TargetProperty="Background">
+                                                    <DiscreteObjectKeyFrame KeyTime="0" Value="{ThemeResource FlipViewNextPreviousButtonBackgroundPointerOver}" />
+                                                </ObjectAnimationUsingKeyFrames>
+                                                <ObjectAnimationUsingKeyFrames Storyboard.TargetName="ContentPresenter" Storyboard.TargetProperty="BorderBrush">
+                                                    <DiscreteObjectKeyFrame KeyTime="0" Value="{ThemeResource FlipViewNextPreviousButtonBorderBrushPointerOver}" />
+                                                </ObjectAnimationUsingKeyFrames>
+                                                <ObjectAnimationUsingKeyFrames Storyboard.TargetName="ContentPresenter" Storyboard.TargetProperty="Foreground">
+                                                    <DiscreteObjectKeyFrame KeyTime="0" Value="{ThemeResource FlipViewNextPreviousArrowForegroundPointerOver}" />
+                                                </ObjectAnimationUsingKeyFrames>
+                                            </Storyboard>
+                                            <VisualState.Setters>
+                                                <Setter Target="ContentPresenter.(AnimatedIcon.State)" Value="PointerOver" />
+                                            </VisualState.Setters>
+                                        </VisualState>
+                                        <VisualState x:Name="Pressed">
+                                            <Storyboard>
+                                                <ObjectAnimationUsingKeyFrames Storyboard.TargetName="ContentPresenter" Storyboard.TargetProperty="Background">
+                                                    <DiscreteObjectKeyFrame KeyTime="0" Value="{ThemeResource FlipViewNextPreviousButtonBackgroundPressed}" />
+                                                </ObjectAnimationUsingKeyFrames>
+                                                <ObjectAnimationUsingKeyFrames Storyboard.TargetName="ContentPresenter" Storyboard.TargetProperty="BorderBrush">
+                                                    <DiscreteObjectKeyFrame KeyTime="0" Value="{ThemeResource FlipViewNextPreviousButtonBorderBrushPressed}" />
+                                                </ObjectAnimationUsingKeyFrames>
+                                                <ObjectAnimationUsingKeyFrames Storyboard.TargetName="ContentPresenter" Storyboard.TargetProperty="Foreground">
+                                                    <DiscreteObjectKeyFrame KeyTime="0" Value="{ThemeResource FlipViewNextPreviousArrowForegroundPressed}" />
+                                                </ObjectAnimationUsingKeyFrames>
+                                            </Storyboard>
+                                            <VisualState.Setters>
+                                                <Setter Target="ContentPresenter.(AnimatedIcon.State)" Value="Pressed" />
+                                            </VisualState.Setters>
+                                        </VisualState>
+                                        <VisualState x:Name="Disabled">
+                                            <Storyboard>
+                                                <ObjectAnimationUsingKeyFrames Storyboard.TargetName="ContentPresenter" Storyboard.TargetProperty="Background">
+                                                    <DiscreteObjectKeyFrame KeyTime="0" Value="{ThemeResource ButtonBackgroundDisabled}" />
+                                                </ObjectAnimationUsingKeyFrames>
+                                                <ObjectAnimationUsingKeyFrames Storyboard.TargetName="ContentPresenter" Storyboard.TargetProperty="BorderBrush">
+                                                    <DiscreteObjectKeyFrame KeyTime="0" Value="{ThemeResource ButtonBorderBrushDisabled}" />
+                                                </ObjectAnimationUsingKeyFrames>
+                                                <ObjectAnimationUsingKeyFrames Storyboard.TargetName="ContentPresenter" Storyboard.TargetProperty="Foreground">
+                                                    <DiscreteObjectKeyFrame KeyTime="0" Value="{ThemeResource ButtonForegroundDisabled}" />
+                                                </ObjectAnimationUsingKeyFrames>
+                                            </Storyboard>
+                                            <VisualState.Setters>
+                                                <!--  DisabledVisual Should be handled by the control, not the animated icon.  -->
+                                                <Setter Target="ContentPresenter.(AnimatedIcon.State)" Value="Normal" />
+                                            </VisualState.Setters>
+                                        </VisualState>
+                                    </VisualStateGroup>
+                                </VisualStateManager.VisualStateGroups>
+                            </ContentPresenter>
+                        </ControlTemplate>
+                    </Setter.Value>
+                </Setter>
+            </Style>
+        </ResourceDictionary>
+    </UserControl.Resources>
+    <Grid
+        x:Name="RootGrid"
+        Background="{x:Bind Background, Mode=OneWay}"
+        BorderBrush="{x:Bind BorderBrush, Mode=OneWay}"
+        BorderThickness="{x:Bind BorderThickness, Mode=OneWay}"
+        CornerRadius="{x:Bind CornerRadius, Mode=OneWay}">
+        <Grid.ColumnDefinitions>
+            <ColumnDefinition Width="Auto" />
+            <ColumnDefinition Width="*" />
+            <ColumnDefinition Width="Auto" />
+        </Grid.ColumnDefinitions>
+        <Grid.RowDefinitions>
+            <RowDefinition Height="Auto" />
+            <RowDefinition Height="*" />
+            <RowDefinition x:Name="Row2" Height="Auto" />
+        </Grid.RowDefinitions>
+
+        <!--  Action button - position controlled by visual states  -->
+        <ContentPresenter
+            x:Name="ActionButtonPresenter"
+            Grid.Row="0"
+            Grid.RowSpan="3"
+            Grid.Column="2"
+            Margin="4,0,0,0"
+            VerticalAlignment="Center"
+            Content="{x:Bind ActionButton, Mode=OneWay}"
+            Visibility="{x:Bind ActionButtonVisibility, Mode=OneWay}" />
+
+        <Grid
+            x:Name="ScrollerContainer"
+            Grid.Row="0"
+            Grid.RowSpan="3"
+            Grid.Column="1">
+            <ScrollViewer
+                x:Name="scroller"
+                HorizontalScrollBarVisibility="Hidden"
+                HorizontalScrollMode="Enabled"
+                SizeChanged="Scroller_SizeChanged"
+                VerticalScrollBarVisibility="Hidden"
+                VerticalScrollMode="Disabled"
+                ViewChanging="Scroller_ViewChanging">
+                <Grid x:Name="ContentGrid">
+                    <ContentPresenter Content="{x:Bind Source, Mode=OneWay}" />
+                </Grid>
+            </ScrollViewer>
+            <Button
+                x:Name="ScrollBackBtn"
+                Margin="8,0,0,0"
+                Padding="2,8,2,8"
+                HorizontalAlignment="Left"
+                VerticalAlignment="Center"
+                AutomationProperties.Name="Scroll left"
+                Click="ScrollBackBtn_Click"
+                Style="{StaticResource ScrollButtonStyle}"
+                ToolTipService.ToolTip="Scroll left"
+                Visibility="Collapsed">
+                <FontIcon
+                    x:Name="ScrollBackIcon"
+                    FontSize="{ThemeResource FlipViewButtonFontSize}"
+                    Glyph="&#xEDD9;" />
+            </Button>
+            <Button
+                x:Name="ScrollForwardBtn"
+                Margin="0,0,8,0"
+                Padding="2,8,2,8"
+                HorizontalAlignment="Right"
+                VerticalAlignment="Center"
+                AutomationProperties.Name="Scroll right"
+                Click="ScrollForwardBtn_Click"
+                Style="{StaticResource ScrollButtonStyle}"
+                ToolTipService.ToolTip="Scroll right">
+                <FontIcon
+                    x:Name="ScrollForwardIcon"
+                    FontSize="{ThemeResource FlipViewButtonFontSize}"
+                    Glyph="&#xEDDA;" />
+            </Button>
+        </Grid>
+
+        <VisualStateManager.VisualStateGroups>
+            <VisualStateGroup x:Name="OrientationStates">
+                <VisualState x:Name="HorizontalState">
+                    <VisualState.Setters>
+                        <Setter Target="scroller.HorizontalScrollBarVisibility" Value="Hidden" />
+                        <Setter Target="scroller.HorizontalScrollMode" Value="Enabled" />
+                        <Setter Target="scroller.VerticalScrollBarVisibility" Value="Hidden" />
+                        <Setter Target="scroller.VerticalScrollMode" Value="Disabled" />
+                        <Setter Target="ScrollBackBtn.Padding" Value="4,12,4,12" />
+                        <Setter Target="ScrollBackBtn.Margin" Value="8,0,0,0" />
+                        <Setter Target="ScrollBackBtn.HorizontalAlignment" Value="Left" />
+                        <Setter Target="ScrollBackBtn.VerticalAlignment" Value="Center" />
+                        <Setter Target="ScrollBackBtn.(AutomationProperties.Name)" Value="Scroll left" />
+                        <Setter Target="ScrollBackBtn.(ToolTipService.ToolTip)" Value="Scroll left" />
+                        <Setter Target="ScrollBackIcon.Glyph" Value="&#xEDD9;" />
+                        <Setter Target="ScrollForwardBtn.Padding" Value="4,12,4,12" />
+                        <Setter Target="ScrollForwardBtn.Margin" Value="0,0,8,0" />
+                        <Setter Target="ScrollForwardBtn.HorizontalAlignment" Value="Right" />
+                        <Setter Target="ScrollForwardBtn.VerticalAlignment" Value="Center" />
+                        <Setter Target="ScrollForwardBtn.(AutomationProperties.Name)" Value="Scroll right" />
+                        <Setter Target="ScrollForwardBtn.(ToolTipService.ToolTip)" Value="Scroll right" />
+                        <Setter Target="ScrollForwardIcon.Glyph" Value="&#xEDDA;" />
+                    </VisualState.Setters>
+                </VisualState>
+                <VisualState x:Name="VerticalState">
+                    <VisualState.Setters>
+                        <Setter Target="scroller.HorizontalScrollBarVisibility" Value="Hidden" />
+                        <Setter Target="scroller.HorizontalScrollMode" Value="Disabled" />
+                        <Setter Target="scroller.VerticalScrollBarVisibility" Value="Hidden" />
+                        <Setter Target="scroller.VerticalScrollMode" Value="Enabled" />
+                        <Setter Target="ScrollBackBtn.Padding" Value="12,4,12,4" />
+                        <Setter Target="ScrollBackBtn.Margin" Value="0,8,0,0" />
+                        <Setter Target="ScrollBackBtn.HorizontalAlignment" Value="Center" />
+                        <Setter Target="ScrollBackBtn.VerticalAlignment" Value="Top" />
+                        <Setter Target="ScrollBackBtn.(AutomationProperties.Name)" Value="Scroll up" />
+                        <Setter Target="ScrollBackBtn.(ToolTipService.ToolTip)" Value="Scroll up" />
+                        <Setter Target="ScrollBackIcon.Glyph" Value="&#xEDDB;" />
+                        <Setter Target="ScrollForwardBtn.Padding" Value="12,4,12,4" />
+                        <Setter Target="ScrollForwardBtn.Margin" Value="0,0,0,8" />
+                        <Setter Target="ScrollForwardBtn.HorizontalAlignment" Value="Center" />
+                        <Setter Target="ScrollForwardBtn.VerticalAlignment" Value="Bottom" />
+                        <Setter Target="ScrollForwardBtn.(AutomationProperties.Name)" Value="Scroll down" />
+                        <Setter Target="ScrollForwardBtn.(ToolTipService.ToolTip)" Value="Scroll down" />
+                        <Setter Target="ScrollForwardIcon.Glyph" Value="&#xEDDC;" />
+                    </VisualState.Setters>
+                </VisualState>
+            </VisualStateGroup>
+            <VisualStateGroup x:Name="LayoutStates">
+                <!--  Horizontal + Start: button on right  -->
+                <VisualState x:Name="HorizontalStartState">
+                    <VisualState.Setters>
+                        <Setter Target="ScrollerContainer.(Grid.Row)" Value="0" />
+                        <Setter Target="ScrollerContainer.(Grid.RowSpan)" Value="3" />
+                        <Setter Target="ScrollerContainer.(Grid.Column)" Value="1" />
+                        <Setter Target="ScrollerContainer.(Grid.ColumnSpan)" Value="1" />
+                        <Setter Target="ActionButtonPresenter.(Grid.Row)" Value="0" />
+                        <Setter Target="ActionButtonPresenter.(Grid.RowSpan)" Value="3" />
+                        <Setter Target="ActionButtonPresenter.(Grid.Column)" Value="2" />
+                        <Setter Target="ActionButtonPresenter.(Grid.ColumnSpan)" Value="1" />
+                        <Setter Target="ActionButtonPresenter.Margin" Value="4,0,0,0" />
+                        <Setter Target="ActionButtonPresenter.HorizontalAlignment" Value="Stretch" />
+                        <Setter Target="ActionButtonPresenter.VerticalAlignment" Value="Center" />
+                    </VisualState.Setters>
+                </VisualState>
+                <!--  Horizontal + End: button on left  -->
+                <VisualState x:Name="HorizontalEndState">
+                    <VisualState.Setters>
+                        <Setter Target="ScrollerContainer.(Grid.Row)" Value="0" />
+                        <Setter Target="ScrollerContainer.(Grid.RowSpan)" Value="3" />
+                        <Setter Target="ScrollerContainer.(Grid.Column)" Value="1" />
+                        <Setter Target="ScrollerContainer.(Grid.ColumnSpan)" Value="1" />
+                        <Setter Target="ActionButtonPresenter.(Grid.Row)" Value="0" />
+                        <Setter Target="ActionButtonPresenter.(Grid.RowSpan)" Value="3" />
+                        <Setter Target="ActionButtonPresenter.(Grid.Column)" Value="0" />
+                        <Setter Target="ActionButtonPresenter.(Grid.ColumnSpan)" Value="1" />
+                        <Setter Target="ActionButtonPresenter.Margin" Value="0,0,4,0" />
+                        <Setter Target="ActionButtonPresenter.HorizontalAlignment" Value="Stretch" />
+                        <Setter Target="ActionButtonPresenter.VerticalAlignment" Value="Center" />
+                    </VisualState.Setters>
+                </VisualState>
+                <!--  Vertical + Start: button on bottom  -->
+                <VisualState x:Name="VerticalStartState">
+                    <VisualState.Setters>
+                        <Setter Target="ScrollerContainer.(Grid.Row)" Value="1" />
+                        <Setter Target="ScrollerContainer.(Grid.RowSpan)" Value="1" />
+                        <Setter Target="ScrollerContainer.(Grid.Column)" Value="0" />
+                        <Setter Target="ScrollerContainer.(Grid.ColumnSpan)" Value="3" />
+                        <Setter Target="ActionButtonPresenter.(Grid.Row)" Value="2" />
+                        <Setter Target="ActionButtonPresenter.(Grid.RowSpan)" Value="1" />
+                        <Setter Target="ActionButtonPresenter.(Grid.Column)" Value="0" />
+                        <Setter Target="ActionButtonPresenter.(Grid.ColumnSpan)" Value="3" />
+                        <Setter Target="ActionButtonPresenter.Margin" Value="0,4,0,0" />
+                        <Setter Target="ActionButtonPresenter.HorizontalAlignment" Value="Center" />
+                        <Setter Target="ActionButtonPresenter.VerticalAlignment" Value="Stretch" />
+                    </VisualState.Setters>
+                </VisualState>
+                <!--  Vertical + End: button on top  -->
+                <VisualState x:Name="VerticalEndState">
+                    <VisualState.Setters>
+                        <Setter Target="ScrollerContainer.(Grid.Row)" Value="1" />
+                        <Setter Target="ScrollerContainer.(Grid.RowSpan)" Value="1" />
+                        <Setter Target="ScrollerContainer.(Grid.Column)" Value="0" />
+                        <Setter Target="ScrollerContainer.(Grid.ColumnSpan)" Value="3" />
+                        <Setter Target="ActionButtonPresenter.(Grid.Row)" Value="0" />
+                        <Setter Target="ActionButtonPresenter.(Grid.RowSpan)" Value="1" />
+                        <Setter Target="ActionButtonPresenter.(Grid.Column)" Value="0" />
+                        <Setter Target="ActionButtonPresenter.(Grid.ColumnSpan)" Value="3" />
+                        <Setter Target="ActionButtonPresenter.Margin" Value="0,0,0,4" />
+                        <Setter Target="ActionButtonPresenter.HorizontalAlignment" Value="Center" />
+                        <Setter Target="ActionButtonPresenter.VerticalAlignment" Value="Stretch" />
+                    </VisualState.Setters>
+                </VisualState>
+            </VisualStateGroup>
+        </VisualStateManager.VisualStateGroups>
+    </Grid>
+</UserControl>

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

@@ -0,0 +1,222 @@
+// 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.IO;
+using System.Linq;
+using System.Runtime.InteropServices.WindowsRuntime;
+using Microsoft.UI.Xaml;
+using Microsoft.UI.Xaml.Controls;
+using Microsoft.UI.Xaml.Controls.Primitives;
+using Microsoft.UI.Xaml.Data;
+using Microsoft.UI.Xaml.Input;
+using Microsoft.UI.Xaml.Media;
+using Microsoft.UI.Xaml.Navigation;
+using Windows.Foundation;
+using Windows.Foundation.Collections;
+
+namespace Microsoft.CmdPal.UI.Controls;
+
+public sealed partial class ScrollContainer : UserControl
+{
+    public enum ScrollContentAlignment
+    {
+        Start,
+        End,
+    }
+
+    public ScrollContainer()
+    {
+        InitializeComponent();
+        Loaded += ScrollContainer_Loaded;
+    }
+
+    private void ScrollContainer_Loaded(object sender, RoutedEventArgs e)
+    {
+        UpdateOrientationState();
+        UpdateLayoutState();
+    }
+
+    public object Source
+    {
+        get => (object)GetValue(SourceProperty);
+        set => SetValue(SourceProperty, value);
+    }
+
+    public static readonly DependencyProperty SourceProperty =
+        DependencyProperty.Register(nameof(Source), typeof(object), typeof(ScrollContainer), new PropertyMetadata(null));
+
+    public Orientation Orientation
+    {
+        get => (Orientation)GetValue(OrientationProperty);
+        set => SetValue(OrientationProperty, value);
+    }
+
+    public static readonly DependencyProperty OrientationProperty =
+        DependencyProperty.Register(nameof(Orientation), typeof(Orientation), typeof(ScrollContainer), new PropertyMetadata(Orientation.Horizontal, OnOrientationChanged));
+
+    public ScrollContentAlignment ContentAlignment
+    {
+        get => (ScrollContentAlignment)GetValue(ContentAlignmentProperty);
+        set => SetValue(ContentAlignmentProperty, value);
+    }
+
+    public static readonly DependencyProperty ContentAlignmentProperty =
+        DependencyProperty.Register(nameof(ContentAlignment), typeof(ScrollContentAlignment), typeof(ScrollContainer), new PropertyMetadata(ScrollContentAlignment.Start, OnContentAlignmentChanged));
+
+    public object ActionButton
+    {
+        get => (object)GetValue(ActionButtonProperty);
+        set => SetValue(ActionButtonProperty, value);
+    }
+
+    public static readonly DependencyProperty ActionButtonProperty =
+        DependencyProperty.Register(nameof(ActionButton), typeof(object), typeof(ScrollContainer), new PropertyMetadata(null));
+
+    public Visibility ActionButtonVisibility
+    {
+        get => (Visibility)GetValue(ActionButtonVisibilityProperty);
+        set => SetValue(ActionButtonVisibilityProperty, value);
+    }
+
+    public static readonly DependencyProperty ActionButtonVisibilityProperty =
+        DependencyProperty.Register(nameof(ActionButtonVisibility), typeof(Visibility), typeof(ScrollContainer), new PropertyMetadata(Visibility.Collapsed));
+
+    private static void OnContentAlignmentChanged(DependencyObject d, DependencyPropertyChangedEventArgs e)
+    {
+        if (d is ScrollContainer control)
+        {
+            control.UpdateLayoutState();
+            control.ScrollToAlignment();
+        }
+    }
+
+    private void ScrollToAlignment()
+    {
+        // Reset button visibility
+        ScrollBackBtn.Visibility = Visibility.Collapsed;
+        ScrollForwardBtn.Visibility = Visibility.Collapsed;
+
+        if (ContentAlignment == ScrollContentAlignment.End)
+        {
+            // Scroll to the end
+            if (Orientation == Orientation.Horizontal)
+            {
+                scroller.ChangeView(scroller.ScrollableWidth, null, null, true);
+            }
+            else
+            {
+                scroller.ChangeView(null, scroller.ScrollableHeight, null, true);
+            }
+        }
+        else
+        {
+            // Scroll to the beginning
+            scroller.ChangeView(0, 0, null, true);
+        }
+
+        // Defer visibility update until after layout
+        void OnLayoutUpdated(object? sender, object args)
+        {
+            scroller.LayoutUpdated -= OnLayoutUpdated;
+            UpdateScrollButtonsVisibility();
+        }
+
+        scroller.LayoutUpdated += OnLayoutUpdated;
+    }
+
+    private static void OnOrientationChanged(DependencyObject d, DependencyPropertyChangedEventArgs e)
+    {
+        if (d is ScrollContainer control)
+        {
+            control.UpdateOrientationState();
+            control.UpdateLayoutState();
+            control.ScrollToAlignment();
+        }
+    }
+
+    private void UpdateOrientationState()
+    {
+        var stateName = Orientation == Orientation.Horizontal ? "HorizontalState" : "VerticalState";
+        VisualStateManager.GoToState(this, stateName, true);
+    }
+
+    private void UpdateLayoutState()
+    {
+        var isHorizontal = Orientation == Orientation.Horizontal;
+        var isStart = ContentAlignment == ScrollContentAlignment.Start;
+
+        var stateName = (isHorizontal, isStart) switch
+        {
+            (true, true) => "HorizontalStartState",
+            (true, false) => "HorizontalEndState",
+            (false, true) => "VerticalStartState",
+            (false, false) => "VerticalEndState",
+        };
+
+        VisualStateManager.GoToState(this, stateName, true);
+    }
+
+    private void Scroller_ViewChanging(object sender, ScrollViewerViewChangingEventArgs e)
+    {
+        UpdateScrollButtonsVisibility(e.FinalView.HorizontalOffset, e.FinalView.VerticalOffset);
+    }
+
+    private void ScrollBackBtn_Click(object sender, RoutedEventArgs e)
+    {
+        if (Orientation == Orientation.Horizontal)
+        {
+            scroller.ChangeView(scroller.HorizontalOffset - scroller.ViewportWidth, null, null);
+        }
+        else
+        {
+            scroller.ChangeView(null, scroller.VerticalOffset - scroller.ViewportHeight, null);
+        }
+
+        // Manually focus to ScrollForwardBtn since this button disappears after scrolling to the end.
+        ScrollForwardBtn.Focus(FocusState.Programmatic);
+    }
+
+    private void ScrollForwardBtn_Click(object sender, RoutedEventArgs e)
+    {
+        if (Orientation == Orientation.Horizontal)
+        {
+            scroller.ChangeView(scroller.HorizontalOffset + scroller.ViewportWidth, null, null);
+        }
+        else
+        {
+            scroller.ChangeView(null, scroller.VerticalOffset + scroller.ViewportHeight, null);
+        }
+
+        // Manually focus to ScrollBackBtn since this button disappears after scrolling to the end.
+        ScrollBackBtn.Focus(FocusState.Programmatic);
+    }
+
+    private void Scroller_SizeChanged(object sender, SizeChangedEventArgs e)
+    {
+        UpdateScrollButtonsVisibility();
+    }
+
+    private void UpdateScrollButtonsVisibility(double? horizontalOffset = null, double? verticalOffset = null)
+    {
+        var hOffset = horizontalOffset ?? scroller.HorizontalOffset;
+        var vOffset = verticalOffset ?? scroller.VerticalOffset;
+
+        if (Orientation == Orientation.Horizontal)
+        {
+            ScrollBackBtn.Visibility = hOffset > 1 ? Visibility.Visible : Visibility.Collapsed;
+            ScrollForwardBtn.Visibility = scroller.ScrollableWidth > 0 && hOffset < scroller.ScrollableWidth - 1
+                ? Visibility.Visible
+                : Visibility.Collapsed;
+        }
+        else
+        {
+            ScrollBackBtn.Visibility = vOffset > 1 ? Visibility.Visible : Visibility.Collapsed;
+            ScrollForwardBtn.Visibility = scroller.ScrollableHeight > 0 && vOffset < scroller.ScrollableHeight - 1
+                ? Visibility.Visible
+                : Visibility.Collapsed;
+        }
+    }
+}

src/modules/cmdpal/Microsoft.CmdPal.UI/Dock/DockControl.xaml

@@ -0,0 +1,449 @@
+<?xml version="1.0" encoding="utf-8" ?>
+<UserControl
+    x:Class="Microsoft.CmdPal.UI.Dock.DockControl"
+    xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
+    xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
+    xmlns:converters="using:CommunityToolkit.WinUI.Converters"
+    xmlns:coreVm="using:Microsoft.CmdPal.Core.ViewModels"
+    xmlns:cpcontrols="using:Microsoft.CmdPal.UI.Controls"
+    xmlns:d="http://schemas.microsoft.com/expression/blend/2008"
+    xmlns:dockVm="using:Microsoft.CmdPal.UI.ViewModels.Dock"
+    xmlns:help="using:Microsoft.CmdPal.UI.Helpers"
+    xmlns:local="using:Microsoft.CmdPal.UI.Dock"
+    xmlns:mc="http://schemas.openxmlformats.org/markup-compatibility/2006"
+    xmlns:ui="using:CommunityToolkit.WinUI"
+    xmlns:vm="using:Microsoft.CmdPal.UI.ViewModels"
+    mc:Ignorable="d">
+
+    <UserControl.Resources>
+        <ResourceDictionary>
+            <StackLayout
+                x:Key="ItemsOrientationLayout"
+                Orientation="{x:Bind ItemsOrientation, Mode=OneWay}"
+                Spacing="4" />
+            <ItemsPanelTemplate x:Key="HorizontalItemsPanel">
+                <StackPanel Orientation="Horizontal" Spacing="4" />
+            </ItemsPanelTemplate>
+            <ItemsPanelTemplate x:Key="VerticalItemsPanel">
+                <StackPanel Orientation="Vertical" Spacing="4" />
+            </ItemsPanelTemplate>
+
+            <DataTemplate x:Key="DockBandTemplate" x:DataType="dockVm:DockBandViewModel">
+                <ItemsRepeater ItemsSource="{x:Bind Items, Mode=OneWay}" Layout="{StaticResource ItemsOrientationLayout}">
+                    <ItemsRepeater.Transitions>
+                        <TransitionCollection />
+                    </ItemsRepeater.Transitions>
+                    <ItemsRepeater.ItemTemplate>
+                        <DataTemplate x:DataType="dockVm:DockItemViewModel">
+                            <local:DockItemControl
+                                Title="{x:Bind Title, Mode=OneWay}"
+                                RightTapped="BandItem_RightTapped"
+                                Subtitle="{x:Bind Subtitle, Mode=OneWay}"
+                                Tag="{x:Bind}"
+                                Tapped="BandItem_Tapped"
+                                ToolTip="{x:Bind Tooltip, Mode=OneWay}">
+                                <local:DockItemControl.Icon>
+                                    <cpcontrols:IconBox
+                                        x:Name="IconBorder"
+                                        Width="16"
+                                        VerticalAlignment="Center"
+                                        AutomationProperties.AccessibilityView="Raw"
+                                        Foreground="{ThemeResource TextFillColorSecondaryBrush}"
+                                        SourceKey="{x:Bind Icon, Mode=OneWay}"
+                                        SourceRequested="{x:Bind help:IconCacheProvider.SourceRequested16}" />
+                                </local:DockItemControl.Icon>
+                            </local:DockItemControl>
+                        </DataTemplate>
+                    </ItemsRepeater.ItemTemplate>
+                </ItemsRepeater>
+            </DataTemplate>
+
+            <Style x:Key="DockBandListViewStyle" TargetType="ListView">
+                <Setter Property="Background" Value="Transparent" />
+                <Setter Property="Padding" Value="0" />
+                <Setter Property="IsItemClickEnabled" Value="False" />
+                <Setter Property="SelectionMode" Value="None" />
+                <!--  Drag properties controlled by code-behind based on IsEditMode  -->
+                <Setter Property="CanDragItems" Value="False" />
+                <Setter Property="CanReorderItems" Value="False" />
+                <Setter Property="AllowDrop" Value="False" />
+            </Style>
+
+            <Style x:Key="DockBandListViewItemStyle" TargetType="ListViewItem">
+                <Setter Property="Padding" Value="0" />
+                <Setter Property="Margin" Value="0,0,4,0" />
+                <Setter Property="MinHeight" Value="0" />
+                <Setter Property="MinWidth" Value="0" />
+                <Setter Property="HorizontalContentAlignment" Value="Stretch" />
+                <Setter Property="VerticalContentAlignment" Value="Stretch" />
+            </Style>
+
+            <Style
+                x:Name="ContextMenuFlyoutStyle"
+                BasedOn="{StaticResource DefaultFlyoutPresenterStyle}"
+                TargetType="FlyoutPresenter">
+                <Style.Setters>
+                    <Setter Property="Margin" Value="0" />
+                    <Setter Property="Padding" Value="0" />
+                    <Setter Property="Background" Value="{ThemeResource DesktopAcrylicTransparentBrush}" />
+                    <Setter Property="BorderBrush" Value="{ThemeResource DividerStrokeColorDefaultBrush}" />
+                </Style.Setters>
+            </Style>
+
+            <!--  Backdrop requires ShouldConstrainToRootBounds="False"  -->
+            <Flyout
+                x:Name="ContextMenuFlyout"
+                FlyoutPresenterStyle="{StaticResource ContextMenuFlyoutStyle}"
+                Opened="ContextMenuFlyout_Opened"
+                ShouldConstrainToRootBounds="False"
+                SystemBackdrop="{ThemeResource AcrylicBackgroundFillColorDefaultBackdrop}">
+                <cpcontrols:ContextMenu x:Name="ContextControl" />
+            </Flyout>
+
+            <!--  Edit mode context menu for dock bands  -->
+            <MenuFlyout x:Name="EditModeContextMenu" ShouldConstrainToRootBounds="False">
+                <MenuFlyoutSubItem x:Name="LabelsSubMenu" Text="Labels">
+                    <MenuFlyoutSubItem.Icon>
+                        <FontIcon Glyph="&#xE8EC;" />
+                    </MenuFlyoutSubItem.Icon>
+                    <ToggleMenuFlyoutItem
+                        x:Name="ShowTitlesMenuItem"
+                        Click="ShowTitlesMenuItem_Click"
+                        Text="Show titles" />
+                    <ToggleMenuFlyoutItem
+                        x:Name="ShowSubtitlesMenuItem"
+                        Click="ShowSubtitlesMenuItem_Click"
+                        Text="Show subtitles" />
+                </MenuFlyoutSubItem>
+                <MenuFlyoutSeparator />
+                <MenuFlyoutItem
+                    x:Name="UnpinBandMenuItem"
+                    Click="UnpinBandMenuItem_Click"
+                    Text="Unpin">
+                    <MenuFlyoutItem.Icon>
+                        <FontIcon Glyph="&#xE77A;" />
+                    </MenuFlyoutItem.Icon>
+                </MenuFlyoutItem>
+            </MenuFlyout>
+
+            <!--  Add band flyout - used in edit mode to add bands to dock sections  -->
+            <Flyout
+                x:Name="AddBandFlyout"
+                Placement="Bottom"
+                ShouldConstrainToRootBounds="False">
+                <StackPanel Width="320">
+                    <TextBlock
+                        x:Name="NoAvailableBandsText"
+                        Padding="12"
+                        Foreground="{ThemeResource TextFillColorSecondaryBrush}"
+                        Text="No commands available to pin"
+                        TextAlignment="Center"
+                        Visibility="Collapsed" />
+                    <ListView
+                        x:Name="AddBandListView"
+                        MaxHeight="300"
+                        HorizontalAlignment="Stretch"
+                        IsItemClickEnabled="True"
+                        ItemClick="AddBandListView_ItemClick"
+                        SelectionMode="None">
+                        <ListView.ItemTemplate>
+                            <DataTemplate x:DataType="vm:TopLevelViewModel">
+                                <Grid Padding="4" ColumnSpacing="8">
+                                    <Grid.ColumnDefinitions>
+                                        <ColumnDefinition Width="Auto" />
+                                        <ColumnDefinition Width="*" />
+                                    </Grid.ColumnDefinitions>
+                                    <cpcontrols:IconBox
+                                        Width="20"
+                                        Height="20"
+                                        VerticalAlignment="Center"
+                                        Foreground="{ThemeResource TextFillColorSecondaryBrush}"
+                                        SourceKey="{x:Bind IconViewModel, Mode=OneWay}"
+                                        SourceRequested="{x:Bind help:IconCacheProvider.SourceRequested20}" />
+                                    <TextBlock
+                                        Grid.Column="1"
+                                        VerticalAlignment="Center"
+                                        Text="{x:Bind Title, Mode=OneWay}"
+                                        TextTrimming="CharacterEllipsis" />
+                                </Grid>
+                            </DataTemplate>
+                        </ListView.ItemTemplate>
+                    </ListView>
+                </StackPanel>
+            </Flyout>
+        </ResourceDictionary>
+    </UserControl.Resources>
+
+    <Grid
+        x:Name="RootGrid"
+        BorderThickness="0,0,0,1"
+        RightTapped="RootGrid_RightTapped">
+        <!--  Edit Mode Overlay - shown when in edit mode  -->
+        <Grid
+            x:Name="ContentGrid"
+            Margin="4"
+            Padding="4,0,4,0"
+            Background="Transparent"
+            RightTapped="RootGrid_RightTapped">
+            <Grid.ColumnDefinitions>
+                <ColumnDefinition Width="*" />
+                <ColumnDefinition Width="Auto" />
+                <ColumnDefinition Width="*" />
+            </Grid.ColumnDefinitions>
+            <Grid.RowDefinitions>
+                <RowDefinition Height="*" />
+                <RowDefinition Height="Auto" />
+                <RowDefinition Height="*" />
+            </Grid.RowDefinitions>
+
+            <cpcontrols:ScrollContainer
+                x:Name="StartScroller"
+                Grid.Row="0"
+                Grid.RowSpan="3"
+                HorizontalAlignment="Left"
+                VerticalAlignment="Stretch">
+                <cpcontrols:ScrollContainer.ActionButton>
+                    <Button
+                        x:Name="StartAddButton"
+                        Click="AddBandButton_Click"
+                        Style="{StaticResource SubtleButtonStyle}"
+                        Tag="Start"
+                        ToolTipService.ToolTip="Add band to Start">
+                        <FontIcon FontSize="12" Glyph="&#xE710;" />
+                    </Button>
+                </cpcontrols:ScrollContainer.ActionButton>
+                <cpcontrols:ScrollContainer.Source>
+                    <ListView
+                        x:Name="StartListView"
+                        HorizontalAlignment="Stretch"
+                        DragItemsCompleted="BandListView_DragItemsCompleted"
+                        DragItemsStarting="BandListView_DragItemsStarting"
+                        DragOver="BandListView_DragOver"
+                        Drop="StartListView_Drop"
+                        ItemContainerStyle="{StaticResource DockBandListViewItemStyle}"
+                        ItemTemplate="{StaticResource DockBandTemplate}"
+                        ItemsPanel="{StaticResource HorizontalItemsPanel}"
+                        ItemsSource="{x:Bind ViewModel.StartItems, Mode=OneWay}"
+                        SelectionMode="None"
+                        Style="{StaticResource DockBandListViewStyle}" />
+                </cpcontrols:ScrollContainer.Source>
+            </cpcontrols:ScrollContainer>
+
+            <cpcontrols:ScrollContainer
+                x:Name="CenterScroller"
+                Grid.Row="0"
+                Grid.RowSpan="3"
+                Grid.Column="1"
+                MinWidth="48"
+                HorizontalAlignment="Center"
+                VerticalAlignment="Stretch">
+                <cpcontrols:ScrollContainer.ActionButton>
+                    <Button
+                        x:Name="CenterAddButton"
+                        Click="AddBandButton_Click"
+                        Style="{StaticResource SubtleButtonStyle}"
+                        Tag="Center"
+                        ToolTipService.ToolTip="Add band to Center">
+                        <FontIcon FontSize="12" Glyph="&#xE710;" />
+                    </Button>
+                </cpcontrols:ScrollContainer.ActionButton>
+                <cpcontrols:ScrollContainer.Source>
+                    <ListView
+                        x:Name="CenterListView"
+                        HorizontalAlignment="Stretch"
+                        DragItemsCompleted="BandListView_DragItemsCompleted"
+                        DragItemsStarting="BandListView_DragItemsStarting"
+                        DragOver="BandListView_DragOver"
+                        Drop="CenterListView_Drop"
+                        ItemContainerStyle="{StaticResource DockBandListViewItemStyle}"
+                        ItemTemplate="{StaticResource DockBandTemplate}"
+                        ItemsPanel="{StaticResource HorizontalItemsPanel}"
+                        ItemsSource="{x:Bind ViewModel.CenterItems, Mode=OneWay}"
+                        SelectionMode="None"
+                        Style="{StaticResource DockBandListViewStyle}" />
+                </cpcontrols:ScrollContainer.Source>
+            </cpcontrols:ScrollContainer>
+
+            <cpcontrols:ScrollContainer
+                x:Name="EndScroller"
+                Grid.Row="0"
+                Grid.RowSpan="3"
+                Grid.Column="2"
+                HorizontalAlignment="Right"
+                VerticalAlignment="Stretch"
+                ContentAlignment="End">
+                <cpcontrols:ScrollContainer.ActionButton>
+                    <Button
+                        x:Name="EndAddButton"
+                        Click="AddBandButton_Click"
+                        Style="{StaticResource SubtleButtonStyle}"
+                        Tag="End"
+                        ToolTipService.ToolTip="Add band to End">
+                        <FontIcon FontSize="12" Glyph="&#xE710;" />
+                    </Button>
+                </cpcontrols:ScrollContainer.ActionButton>
+                <cpcontrols:ScrollContainer.Source>
+                    <ListView
+                        x:Name="EndListView"
+                        DragItemsCompleted="BandListView_DragItemsCompleted"
+                        DragItemsStarting="BandListView_DragItemsStarting"
+                        DragOver="BandListView_DragOver"
+                        Drop="EndListView_Drop"
+                        ItemContainerStyle="{StaticResource DockBandListViewItemStyle}"
+                        ItemTemplate="{StaticResource DockBandTemplate}"
+                        ItemsPanel="{StaticResource HorizontalItemsPanel}"
+                        ItemsSource="{x:Bind ViewModel.EndItems, Mode=OneWay}"
+                        SelectionMode="None"
+                        Style="{StaticResource DockBandListViewStyle}">
+                        <ListView.ItemContainerTransitions>
+                            <TransitionCollection />
+                        </ListView.ItemContainerTransitions>
+                    </ListView>
+                </cpcontrols:ScrollContainer.Source>
+            </cpcontrols:ScrollContainer>
+            <TeachingTip
+                x:Name="EditButtonsTeachingTip"
+                MinWidth="0"
+                PreferredPlacement="Bottom"
+                ShouldConstrainToRootBounds="False"
+                Style="{StaticResource TeachingTipWithoutCloseButtonStyle}"
+                Target="{x:Bind ContentGrid}">
+
+                <TeachingTip.Content>
+                    <StackPanel
+                        x:Name="EditButtonsPanel"
+                        HorizontalAlignment="Stretch"
+                        Orientation="Vertical"
+                        Spacing="4">
+                        <Button
+                            HorizontalAlignment="Stretch"
+                            Click="DoneEditingButton_Click"
+                            Content="Save"
+                            Style="{StaticResource AccentButtonStyle}" />
+                        <Button
+                            HorizontalAlignment="Stretch"
+                            Click="DiscardEditingButton_Click"
+                            Content="Discard" />
+                    </StackPanel>
+                </TeachingTip.Content>
+            </TeachingTip>
+        </Grid>
+        <VisualStateManager.VisualStateGroups>
+            <VisualStateGroup x:Name="DockOrientation">
+                <VisualState x:Name="DockOnTop">
+                    <VisualState.StateTriggers>
+                        <ui:IsEqualStateTrigger Value="{x:Bind DockSide, Mode=OneWay}" To="Top" />
+                    </VisualState.StateTriggers>
+                </VisualState>
+                <VisualState x:Name="DockOnBottom">
+                    <VisualState.StateTriggers>
+                        <ui:IsEqualStateTrigger Value="{x:Bind DockSide, Mode=OneWay}" To="Bottom" />
+                    </VisualState.StateTriggers>
+                    <VisualState.Setters>
+                        <Setter Target="RootGrid.BorderThickness" Value="0,1,0,0" />
+                    </VisualState.Setters>
+                </VisualState>
+                <VisualState x:Name="DockOnLeft">
+                    <VisualState.StateTriggers>
+                        <ui:IsEqualStateTrigger Value="{x:Bind DockSide, Mode=OneWay}" To="Left" />
+                    </VisualState.StateTriggers>
+                    <VisualState.Setters>
+                        <Setter Target="StartScroller.(Grid.Row)" Value="0" />
+                        <Setter Target="StartScroller.(Grid.RowSpan)" Value="1" />
+                        <Setter Target="StartScroller.(Grid.Column)" Value="0" />
+                        <Setter Target="StartScroller.(Grid.ColumnSpan)" Value="3" />
+                        <Setter Target="StartScroller.Orientation" Value="Vertical" />
+                        <Setter Target="StartScroller.HorizontalAlignment" Value="Stretch" />
+                        <Setter Target="StartScroller.VerticalAlignment" Value="Top" />
+                        <Setter Target="StartScroller.Orientation" Value="Vertical" />
+
+                        <Setter Target="CenterScroller.(Grid.Row)" Value="1" />
+                        <Setter Target="CenterScroller.(Grid.RowSpan)" Value="1" />
+                        <Setter Target="CenterScroller.(Grid.Column)" Value="0" />
+                        <Setter Target="CenterScroller.(Grid.ColumnSpan)" Value="3" />
+                        <Setter Target="CenterScroller.Orientation" Value="Vertical" />
+                        <Setter Target="CenterScroller.HorizontalAlignment" Value="Stretch" />
+                        <Setter Target="CenterScroller.VerticalAlignment" Value="Center" />
+                        <Setter Target="CenterScroller.Orientation" Value="Vertical" />
+
+                        <Setter Target="EndScroller.Orientation" Value="Vertical" />
+                        <Setter Target="EndScroller.(Grid.Row)" Value="2" />
+                        <Setter Target="EndScroller.(Grid.RowSpan)" Value="1" />
+                        <Setter Target="EndScroller.(Grid.Column)" Value="0" />
+                        <Setter Target="EndScroller.(Grid.ColumnSpan)" Value="3" />
+                        <Setter Target="EndScroller.HorizontalAlignment" Value="Stretch" />
+                        <Setter Target="EndScroller.VerticalAlignment" Value="Bottom" />
+                        <Setter Target="ContentGrid.Padding" Value="4,8,4,8" />
+                        <Setter Target="RootGrid.BorderThickness" Value="0,0,1,0" />
+
+                        <Setter Target="StartListView.ItemsPanel" Value="{StaticResource VerticalItemsPanel}" />
+                        <Setter Target="CenterListView.ItemsPanel" Value="{StaticResource VerticalItemsPanel}" />
+                        <Setter Target="EndListView.ItemsPanel" Value="{StaticResource VerticalItemsPanel}" />
+                    </VisualState.Setters>
+                </VisualState>
+                <VisualState x:Name="DockOnRight">
+                    <VisualState.StateTriggers>
+                        <ui:IsEqualStateTrigger Value="{x:Bind DockSide, Mode=OneWay}" To="Right" />
+                    </VisualState.StateTriggers>
+                    <VisualState.Setters>
+                        <Setter Target="StartScroller.(Grid.Row)" Value="0" />
+                        <Setter Target="StartScroller.(Grid.RowSpan)" Value="1" />
+                        <Setter Target="StartScroller.(Grid.Column)" Value="0" />
+                        <Setter Target="StartScroller.(Grid.ColumnSpan)" Value="3" />
+                        <Setter Target="StartScroller.Orientation" Value="Vertical" />
+                        <Setter Target="StartScroller.HorizontalAlignment" Value="Stretch" />
+                        <Setter Target="StartScroller.VerticalAlignment" Value="Top" />
+                        <Setter Target="StartScroller.Orientation" Value="Vertical" />
+
+                        <Setter Target="CenterScroller.(Grid.Row)" Value="1" />
+                        <Setter Target="CenterScroller.(Grid.RowSpan)" Value="1" />
+                        <Setter Target="CenterScroller.(Grid.Column)" Value="0" />
+                        <Setter Target="CenterScroller.(Grid.ColumnSpan)" Value="3" />
+                        <Setter Target="CenterScroller.Orientation" Value="Vertical" />
+                        <Setter Target="CenterScroller.HorizontalAlignment" Value="Stretch" />
+                        <Setter Target="CenterScroller.VerticalAlignment" Value="Center" />
+                        <Setter Target="CenterScroller.Orientation" Value="Vertical" />
+
+                        <Setter Target="EndScroller.Orientation" Value="Vertical" />
+                        <Setter Target="EndScroller.(Grid.Row)" Value="2" />
+                        <Setter Target="EndScroller.(Grid.RowSpan)" Value="1" />
+                        <Setter Target="EndScroller.(Grid.Column)" Value="0" />
+                        <Setter Target="EndScroller.(Grid.ColumnSpan)" Value="3" />
+                        <Setter Target="EndScroller.HorizontalAlignment" Value="Stretch" />
+                        <Setter Target="EndScroller.VerticalAlignment" Value="Bottom" />
+                        <Setter Target="ContentGrid.Padding" Value="4,8,4,8" />
+                        <Setter Target="RootGrid.BorderThickness" Value="1,0,0,0" />
+
+                        <Setter Target="StartListView.ItemsPanel" Value="{StaticResource VerticalItemsPanel}" />
+                        <Setter Target="CenterListView.ItemsPanel" Value="{StaticResource VerticalItemsPanel}" />
+                        <Setter Target="EndListView.ItemsPanel" Value="{StaticResource VerticalItemsPanel}" />
+                    </VisualState.Setters>
+                </VisualState>
+            </VisualStateGroup>
+
+            <!--  Edit Mode Visual States  -->
+            <VisualStateGroup x:Name="EditModeStates">
+                <VisualState x:Name="EditModeOff" />
+                <VisualState x:Name="EditModeOn">
+                    <VisualState.Setters>
+                        <Setter Target="StartScroller.BorderBrush" Value="{ThemeResource CardStrokeColorDefaultBrush}" />
+                        <Setter Target="StartScroller.Background" Value="{ThemeResource CardBackgroundFillColorDefaultBrush}" />
+                        <Setter Target="StartScroller.BorderThickness" Value="1" />
+                        <Setter Target="StartScroller.CornerRadius" Value="{StaticResource OverlayCornerRadius}" />
+                        <Setter Target="CenterScroller.BorderBrush" Value="{ThemeResource CardStrokeColorDefaultBrush}" />
+                        <Setter Target="CenterScroller.Background" Value="{ThemeResource CardBackgroundFillColorDefaultBrush}" />
+                        <Setter Target="CenterScroller.BorderThickness" Value="1" />
+                        <Setter Target="CenterScroller.CornerRadius" Value="{StaticResource OverlayCornerRadius}" />
+                        <Setter Target="EndScroller.BorderBrush" Value="{ThemeResource CardStrokeColorDefaultBrush}" />
+                        <Setter Target="EndScroller.Background" Value="{ThemeResource CardBackgroundFillColorDefaultBrush}" />
+                        <Setter Target="EndScroller.BorderThickness" Value="1" />
+                        <Setter Target="EndScroller.CornerRadius" Value="{StaticResource OverlayCornerRadius}" />
+                        <Setter Target="StartScroller.ActionButtonVisibility" Value="Visible" />
+                        <Setter Target="CenterScroller.ActionButtonVisibility" Value="Visible" />
+                        <Setter Target="EndScroller.ActionButtonVisibility" Value="Visible" />
+                    </VisualState.Setters>
+                </VisualState>
+            </VisualStateGroup>
+        </VisualStateManager.VisualStateGroups>
+    </Grid>
+</UserControl>

src/modules/cmdpal/Microsoft.CmdPal.UI/Dock/DockControl.xaml.cs

@@ -0,0 +1,510 @@
+// 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.ObjectModel;
+using System.Runtime.InteropServices;
+using CommunityToolkit.Mvvm.Messaging;
+using ManagedCommon;
+using Microsoft.CmdPal.UI.ViewModels;
+using Microsoft.CmdPal.UI.ViewModels.Dock;
+using Microsoft.CmdPal.UI.ViewModels.Messages;
+using Microsoft.CmdPal.UI.ViewModels.Settings;
+using Microsoft.CommandPalette.Extensions;
+using Microsoft.UI;
+using Microsoft.UI.Xaml;
+using Microsoft.UI.Xaml.Controls;
+using Microsoft.UI.Xaml.Controls.Primitives;
+using Microsoft.UI.Xaml.Media;
+using Windows.ApplicationModel.DataTransfer;
+using Windows.Foundation;
+
+namespace Microsoft.CmdPal.UI.Dock;
+
+public sealed partial class DockControl : UserControl, IRecipient<CloseContextMenuMessage>, IRecipient<EnterDockEditModeMessage>
+{
+    private DockViewModel _viewModel;
+
+    internal DockViewModel ViewModel => _viewModel;
+
+    public static readonly DependencyProperty ItemsOrientationProperty =
+        DependencyProperty.Register(nameof(ItemsOrientation), typeof(Orientation), typeof(DockControl), new PropertyMetadata(Orientation.Horizontal));
+
+    public Orientation ItemsOrientation
+    {
+        get => (Orientation)GetValue(ItemsOrientationProperty);
+        set => SetValue(ItemsOrientationProperty, value);
+    }
+
+    public static readonly DependencyProperty DockSideProperty =
+        DependencyProperty.Register(nameof(DockSide), typeof(DockSide), typeof(DockControl), new PropertyMetadata(DockSide.Top));
+
+    public DockSide DockSide
+    {
+        get => (DockSide)GetValue(DockSideProperty);
+        set => SetValue(DockSideProperty, value);
+    }
+
+    public static readonly DependencyProperty IsEditModeProperty =
+        DependencyProperty.Register(nameof(IsEditMode), typeof(bool), typeof(DockControl), new PropertyMetadata(false, OnIsEditModeChanged));
+
+    public bool IsEditMode
+    {
+        get => (bool)GetValue(IsEditModeProperty);
+        set => SetValue(IsEditModeProperty, value);
+    }
+
+    private static void OnIsEditModeChanged(DependencyObject d, DependencyPropertyChangedEventArgs e)
+    {
+        if (d is DockControl control && e.NewValue is bool isEditMode)
+        {
+            control.UpdateEditMode(isEditMode);
+        }
+    }
+
+    internal DockControl(DockViewModel viewModel)
+    {
+        _viewModel = viewModel;
+        InitializeComponent();
+        WeakReferenceMessenger.Default.Register<CloseContextMenuMessage>(this);
+        WeakReferenceMessenger.Default.Register<EnterDockEditModeMessage>(this);
+
+        // Start with edit mode disabled - normal click behavior
+        UpdateEditMode(false);
+    }
+
+    public void Receive(EnterDockEditModeMessage message)
+    {
+        // Message may arrive from a background thread, dispatch to UI thread
+        DispatcherQueue.TryEnqueue(() =>
+        {
+            EnterEditMode();
+        });
+    }
+
+    private void UpdateEditMode(bool isEditMode)
+    {
+        // Enable/disable drag-and-drop based on edit mode
+        StartListView.CanDragItems = isEditMode;
+        StartListView.CanReorderItems = isEditMode;
+        StartListView.AllowDrop = isEditMode;
+
+        CenterListView.CanDragItems = isEditMode;
+        CenterListView.CanReorderItems = isEditMode;
+        CenterListView.AllowDrop = isEditMode;
+
+        EndListView.CanDragItems = isEditMode;
+        EndListView.CanReorderItems = isEditMode;
+        EndListView.AllowDrop = isEditMode;
+
+        if (isEditMode)
+        {
+            EditButtonsTeachingTip.PreferredPlacement = DockSide switch
+            {
+                DockSide.Left => TeachingTipPlacementMode.Right,
+                DockSide.Right => TeachingTipPlacementMode.Left,
+                DockSide.Top => TeachingTipPlacementMode.Bottom,
+                DockSide.Bottom => TeachingTipPlacementMode.Top,
+                _ => TeachingTipPlacementMode.Auto,
+            };
+        }
+
+        EditButtonsTeachingTip.IsOpen = isEditMode;
+
+        // Update visual state
+        VisualStateManager.GoToState(this, isEditMode ? "EditModeOn" : "EditModeOff", true);
+    }
+
+    internal void EnterEditMode()
+    {
+        // Snapshot current state so we can restore on discard
+        ViewModel.SnapshotBandOrder();
+        IsEditMode = true;
+    }
+
+    internal void ExitEditMode()
+    {
+        IsEditMode = false;
+
+        // Save all changes when exiting edit mode
+        ViewModel.SaveBandOrder();
+    }
+
+    internal void DiscardEditMode()
+    {
+        IsEditMode = false;
+
+        // Restore the original band order from snapshot
+        ViewModel.RestoreBandOrder();
+    }
+
+    private void DoneEditingButton_Click(object sender, RoutedEventArgs e)
+    {
+        ExitEditMode();
+    }
+
+    private void DiscardEditingButton_Click(object sender, RoutedEventArgs e)
+    {
+        DiscardEditMode();
+    }
+
+    internal void UpdateSettings(DockSettings settings)
+    {
+        DockSide = settings.Side;
+
+        var isHorizontal = settings.Side == DockSide.Top || settings.Side == DockSide.Bottom;
+
+        ItemsOrientation = isHorizontal ? Orientation.Horizontal : Orientation.Vertical;
+
+        if (settings.Backdrop == DockBackdrop.Transparent)
+        {
+            RootGrid.BorderBrush = new SolidColorBrush(Colors.Transparent);
+        }
+    }
+
+    private void BandItem_Tapped(object sender, Microsoft.UI.Xaml.Input.TappedRoutedEventArgs e)
+    {
+        // Ignore clicks when in edit mode - allow drag behavior instead
+        if (IsEditMode)
+        {
+            return;
+        }
+
+        if (sender is DockItemControl dockItem && dockItem.DataContext is DockBandViewModel band && dockItem.Tag is DockItemViewModel item)
+        {
+            // Use the center of the border as the point to open at
+            var borderPos = dockItem.TransformToVisual(null).TransformPoint(new Point(0, 0));
+            var borderCenter = new Point(
+                borderPos.X + (dockItem.ActualWidth / 2),
+                borderPos.Y + (dockItem.ActualHeight / 2));
+
+            InvokeItem(item, borderCenter);
+            e.Handled = true;
+        }
+    }
+
+    // Stores the band that was right-clicked for edit mode context menu
+    private DockBandViewModel? _editModeContextBand;
+
+    private void BandItem_RightTapped(object sender, Microsoft.UI.Xaml.Input.RightTappedRoutedEventArgs e)
+    {
+        if (sender is DockItemControl dockItem && dockItem.DataContext is DockBandViewModel band && dockItem.Tag is DockItemViewModel item)
+        {
+            // In edit mode, show the edit mode context menu (show/hide labels)
+            if (IsEditMode)
+            {
+                // Find the parent DockBandViewModel for this item
+                _editModeContextBand = band;
+                if (_editModeContextBand != null)
+                {
+                    // Update toggle menu item checked state based on current settings
+                    ShowTitlesMenuItem.IsChecked = _editModeContextBand.ShowTitles;
+                    ShowSubtitlesMenuItem.IsChecked = _editModeContextBand.ShowSubtitles;
+
+                    EditModeContextMenu.ShowAt(
+                        dockItem,
+                        new FlyoutShowOptions()
+                        {
+                            ShowMode = FlyoutShowMode.Standard,
+                            Placement = FlyoutPlacementMode.TopEdgeAlignedRight,
+                        });
+                    e.Handled = true;
+                }
+
+                return;
+            }
+
+            // Normal mode - show the command context menu
+            if (item.HasMoreCommands)
+            {
+                ContextControl.ViewModel.SelectedItem = item;
+                ContextMenuFlyout.ShowAt(
+                    dockItem,
+                    new FlyoutShowOptions()
+                    {
+                        ShowMode = FlyoutShowMode.Standard,
+                        Placement = FlyoutPlacementMode.TopEdgeAlignedRight,
+                    });
+                e.Handled = true;
+            }
+        }
+    }
+
+    private void ShowTitlesMenuItem_Click(object sender, RoutedEventArgs e)
+    {
+        if (_editModeContextBand != null)
+        {
+            _editModeContextBand.ShowTitles = ShowTitlesMenuItem.IsChecked;
+        }
+    }
+
+    private void ShowSubtitlesMenuItem_Click(object sender, RoutedEventArgs e)
+    {
+        if (_editModeContextBand != null)
+        {
+            _editModeContextBand.ShowSubtitles = ShowSubtitlesMenuItem.IsChecked;
+        }
+    }
+
+    private void UnpinBandMenuItem_Click(object sender, RoutedEventArgs e)
+    {
+        if (_editModeContextBand != null)
+        {
+            ViewModel.UnpinBand(_editModeContextBand);
+            _editModeContextBand = null;
+        }
+    }
+
+    private void InvokeItem(DockItemViewModel item, Point pos)
+    {
+        var command = item.Command;
+        try
+        {
+            PerformCommandMessage m = new(command.Model);
+            m.WithAnimation = false;
+            m.TransientPage = true;
+            WeakReferenceMessenger.Default.Send(m);
+
+            var isPage = command.Model.Unsafe is not IInvokableCommand invokable;
+            if (isPage)
+            {
+                WeakReferenceMessenger.Default.Send<RequestShowPaletteAtMessage>(new(pos));
+            }
+        }
+        catch (COMException e)
+        {
+            Logger.LogError("Error invoking dock command", e);
+        }
+    }
+
+    private void ContextMenuFlyout_Opened(object sender, object e)
+    {
+        // We need to wait until our flyout is opened to try and toss focus
+        // at its search box. The control isn't in the UI tree before that
+        ContextControl.FocusSearchBox();
+    }
+
+    public void Receive(CloseContextMenuMessage message)
+    {
+        if (ContextMenuFlyout.IsOpen)
+        {
+            ContextMenuFlyout.Hide();
+        }
+    }
+
+    private void RootGrid_RightTapped(object sender, Microsoft.UI.Xaml.Input.RightTappedRoutedEventArgs e)
+    {
+        var pos = e.GetPosition(null);
+        var item = this.ViewModel.GetContextMenuForDock();
+        if (item.HasMoreCommands)
+        {
+            ContextControl.ViewModel.SelectedItem = item;
+            ContextMenuFlyout.ShowAt(
+            this.RootGrid,
+            new FlyoutShowOptions()
+            {
+                ShowMode = FlyoutShowMode.Standard,
+                Placement = FlyoutPlacementMode.TopEdgeAlignedRight,
+                Position = pos,
+            });
+            e.Handled = true;
+        }
+    }
+
+    private DockBandViewModel? _draggedBand;
+
+    private void BandListView_DragItemsStarting(object sender, DragItemsStartingEventArgs e)
+    {
+        if (e.Items.Count > 0 && e.Items[0] is DockBandViewModel band)
+        {
+            _draggedBand = band;
+            e.Data.RequestedOperation = DataPackageOperation.Move;
+        }
+    }
+
+    private void BandListView_DragOver(object sender, DragEventArgs e)
+    {
+        if (_draggedBand != null)
+        {
+            e.AcceptedOperation = DataPackageOperation.Move;
+        }
+    }
+
+    private void BandListView_DragItemsCompleted(ListViewBase sender, DragItemsCompletedEventArgs args)
+    {
+        // Reordering within the same list is handled automatically by ListView
+        // We just need to sync the ViewModel order without saving
+        if (args.DropResult == DataPackageOperation.Move && _draggedBand != null)
+        {
+            DockPinSide targetSide;
+            ObservableCollection<DockBandViewModel> targetCollection;
+
+            if (sender == StartListView)
+            {
+                targetSide = DockPinSide.Start;
+                targetCollection = ViewModel.StartItems;
+            }
+            else if (sender == CenterListView)
+            {
+                targetSide = DockPinSide.Center;
+                targetCollection = ViewModel.CenterItems;
+            }
+            else
+            {
+                targetSide = DockPinSide.End;
+                targetCollection = ViewModel.EndItems;
+            }
+
+            // Find the new index and sync ViewModel (without saving)
+            var newIndex = targetCollection.IndexOf(_draggedBand);
+            if (newIndex >= 0)
+            {
+                ViewModel.SyncBandPosition(_draggedBand, targetSide, newIndex);
+            }
+        }
+
+        _draggedBand = null;
+    }
+
+    private void StartListView_Drop(object sender, DragEventArgs e)
+    {
+        HandleCrossListDrop(DockPinSide.Start, e);
+    }
+
+    private void CenterListView_Drop(object sender, DragEventArgs e)
+    {
+        HandleCrossListDrop(DockPinSide.Center, e);
+    }
+
+    private void EndListView_Drop(object sender, DragEventArgs e)
+    {
+        HandleCrossListDrop(DockPinSide.End, e);
+    }
+
+    private void HandleCrossListDrop(DockPinSide targetSide, DragEventArgs e)
+    {
+        if (_draggedBand == null)
+        {
+            return;
+        }
+
+        // Check which list the band is currently in
+        var isInStart = ViewModel.StartItems.Contains(_draggedBand);
+        var isInCenter = ViewModel.CenterItems.Contains(_draggedBand);
+        var isInEnd = ViewModel.EndItems.Contains(_draggedBand);
+
+        DockPinSide sourceSide;
+        if (isInStart)
+        {
+            sourceSide = DockPinSide.Start;
+        }
+        else if (isInCenter)
+        {
+            sourceSide = DockPinSide.Center;
+        }
+        else
+        {
+            sourceSide = DockPinSide.End;
+        }
+
+        // Only handle cross-list drops here; same-list reorders are handled in DragItemsCompleted
+        if (sourceSide != targetSide)
+        {
+            // Calculate drop index based on drop position
+            var targetListView = targetSide switch
+            {
+                DockPinSide.Start => StartListView,
+                DockPinSide.Center => CenterListView,
+                _ => EndListView,
+            };
+            var targetCollection = targetSide switch
+            {
+                DockPinSide.Start => ViewModel.StartItems,
+                DockPinSide.Center => ViewModel.CenterItems,
+                _ => ViewModel.EndItems,
+            };
+
+            var dropIndex = GetDropIndex(targetListView, e, targetCollection.Count);
+
+            // Move the band to the new side (without saving - save happens on Done)
+            ViewModel.MoveBandWithoutSaving(_draggedBand, targetSide, dropIndex);
+            e.Handled = true;
+        }
+    }
+
+    private int GetDropIndex(ListView listView, DragEventArgs e, int itemCount)
+    {
+        var position = e.GetPosition(listView);
+
+        // Find the item at the drop position
+        for (var i = 0; i < itemCount; i++)
+        {
+            if (listView.ContainerFromIndex(i) is ListViewItem container)
+            {
+                var itemBounds = container.TransformToVisual(listView).TransformBounds(
+                    new Rect(0, 0, container.ActualWidth, container.ActualHeight));
+
+                if (ItemsOrientation == Orientation.Horizontal)
+                {
+                    // For horizontal layout, check X position
+                    if (position.X < itemBounds.X + (itemBounds.Width / 2))
+                    {
+                        return i;
+                    }
+                }
+                else
+                {
+                    // For vertical layout, check Y position
+                    if (position.Y < itemBounds.Y + (itemBounds.Height / 2))
+                    {
+                        return i;
+                    }
+                }
+            }
+        }
+
+        // If we're past all items, insert at the end
+        return itemCount;
+    }
+
+    // Tracks which section (Start/Center/End) the add button was clicked for
+    private DockPinSide _addBandTargetSide;
+
+    private void AddBandButton_Click(object sender, RoutedEventArgs e)
+    {
+        if (sender is Button button && button.Tag is string sideTag)
+        {
+            _addBandTargetSide = sideTag switch
+            {
+                "Start" => DockPinSide.Start,
+                "Center" => DockPinSide.Center,
+                "End" => DockPinSide.End,
+                _ => DockPinSide.Center,
+            };
+
+            // Populate the list with available bands (not already in the dock)
+            var availableBands = ViewModel.GetAvailableBandsToAdd().ToList();
+            AddBandListView.ItemsSource = availableBands;
+
+            // Show/hide empty state text based on whether there are bands to add
+            var hasAvailableBands = availableBands.Count > 0;
+            NoAvailableBandsText.Visibility = hasAvailableBands ? Visibility.Collapsed : Visibility.Visible;
+            AddBandListView.Visibility = hasAvailableBands ? Visibility.Visible : Visibility.Collapsed;
+
+            // Show the flyout
+            AddBandFlyout.ShowAt(button);
+        }
+    }
+
+    private void AddBandListView_ItemClick(object sender, ItemClickEventArgs e)
+    {
+        if (e.ClickedItem is TopLevelViewModel topLevel)
+        {
+            // Add the band to the target section
+            ViewModel.AddBandToSection(topLevel, _addBandTargetSide);
+
+            // Close the flyout
+            AddBandFlyout.Hide();
+        }
+    }
+}

src/modules/cmdpal/Microsoft.CmdPal.UI/Dock/DockItemControl.xaml

@@ -0,0 +1,178 @@
+<?xml version="1.0" encoding="utf-8" ?>
+<ResourceDictionary
+    xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
+    xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
+    xmlns:local="using:Microsoft.CmdPal.UI.Dock">
+
+    <ResourceDictionary.ThemeDictionaries>
+        <ResourceDictionary x:Key="Default">
+            <SolidColorBrush x:Key="DockItemBackground" Color="Transparent" />
+            <SolidColorBrush x:Key="DockItemBorderBrush" Color="Transparent" />
+            <SolidColorBrush x:Key="DockItemBackgroundPointerOver" Color="#0FFFFFFF" />
+            <SolidColorBrush x:Key="DockItemBackgroundPressed" Color="#0BFFFFFF" />
+            <LinearGradientBrush x:Key="DockItemBorderBrushPointerOver" MappingMode="Absolute" StartPoint="0,0" EndPoint="0,3">
+                <LinearGradientBrush.GradientStops>
+                    <GradientStop Offset="0.33" Color="#0FFFFFFF" />
+                    <GradientStop Offset="1.0" Color="#19FFFFFF" />
+                </LinearGradientBrush.GradientStops>
+            </LinearGradientBrush>
+            <SolidColorBrush x:Key="DockItemBorderBrushPressed" Color="#0BFFFFFF" />
+        </ResourceDictionary>
+        <ResourceDictionary x:Key="Light">
+            <SolidColorBrush x:Key="DockItemBackground" Color="Transparent" />
+            <SolidColorBrush x:Key="DockItemBorderBrush" Color="Transparent" />
+            <SolidColorBrush x:Key="DockItemBackgroundPointerOver" Color="#80FFFFFF" />
+            <SolidColorBrush x:Key="DockItemBackgroundPressed" Color="#4DFFFFFF" />
+            <LinearGradientBrush x:Key="DockItemBorderBrushPointerOver" MappingMode="Absolute" StartPoint="0,0" EndPoint="0,3">
+                <LinearGradientBrush.GradientStops>
+                    <GradientStop Offset="0.33" Color="#08000000" />
+                    <GradientStop Offset="1.0" Color="#17000000" />
+                </LinearGradientBrush.GradientStops>
+            </LinearGradientBrush>
+            <SolidColorBrush x:Key="DockItemBorderBrushPressed" Color="#05000000" />
+        </ResourceDictionary>
+        <ResourceDictionary x:Key="HighContrast">
+            <SolidColorBrush x:Key="DockItemBackground" Color="Transparent" />
+            <SolidColorBrush x:Key="DockItemBorderBrush" Color="Transparent" />
+            <SolidColorBrush x:Key="DockItemBackgroundPointerOver" Color="{StaticResource SystemColorHighlightTextColor}" />
+            <SolidColorBrush x:Key="DockItemBackgroundPressed" Color="{StaticResource SystemColorHighlightTextColor}" />
+            <SolidColorBrush x:Key="DockItemBorderBrushPointerOver" Color="{StaticResource SystemColorHighlightColor}" />
+            <SolidColorBrush x:Key="DockItemBorderBrushPressed" Color="{StaticResource SystemColorHighlightTextColor}" />
+        </ResourceDictionary>
+    </ResourceDictionary.ThemeDictionaries>
+
+    <CornerRadius x:Key="DockItemCornerRadius">4</CornerRadius>
+    <Thickness x:Key="DockItemPadding">4,0,4,0</Thickness>
+
+    <Style BasedOn="{StaticResource DefaultDockItemControlStyle}" TargetType="local:DockItemControl" />
+
+    <Style x:Key="DefaultDockItemControlStyle" TargetType="local:DockItemControl">
+        <Style.Setters>
+            <Setter Property="Background" Value="{ThemeResource DockItemBackground}" />
+            <Setter Property="BorderBrush" Value="{ThemeResource DockItemBorderBrush}" />
+            <Setter Property="Padding" Value="{StaticResource DockItemPadding}" />
+            <Setter Property="BorderThickness" Value="{ThemeResource ButtonBorderThemeThickness}" />
+            <Setter Property="CornerRadius" Value="{StaticResource DockItemCornerRadius}" />
+            <Setter Property="TextVisibility" Value="Visible" />
+            <Setter Property="Template">
+                <Setter.Value>
+                    <ControlTemplate TargetType="local:DockItemControl">
+                        <Grid
+                            x:Name="PART_RootGrid"
+                            Padding="{TemplateBinding Padding}"
+                            VerticalAlignment="Stretch"
+                            Background="{TemplateBinding Background}"
+                            BorderBrush="{TemplateBinding BorderBrush}"
+                            BorderThickness="{TemplateBinding BorderThickness}"
+                            CornerRadius="{TemplateBinding CornerRadius}"
+                            ToolTipService.ToolTip="{TemplateBinding ToolTip}">
+                            <Grid
+                                x:Name="ContentGrid"
+                                AutomationProperties.Name="{TemplateBinding Title}"
+                                Background="Transparent"
+                                ColumnSpacing="8">
+                                <Grid.ColumnDefinitions>
+                                    <ColumnDefinition Width="Auto" />
+                                    <ColumnDefinition Width="Auto" />
+                                </Grid.ColumnDefinitions>
+
+                                <!--  Icon  -->
+                                <ContentPresenter
+                                    x:Name="IconPresenter"
+                                    VerticalAlignment="Center"
+                                    Content="{TemplateBinding Icon}" />
+
+                                <!--  Text (Title + Subtitle)  -->
+                                <StackPanel
+                                    x:Name="TextPanel"
+                                    Grid.Column="1"
+                                    VerticalAlignment="Center"
+                                    Visibility="{TemplateBinding TextVisibility}">
+                                    <TextBlock
+                                        x:Name="TitleText"
+                                        MinWidth="24"
+                                        MaxWidth="100"
+                                        HorizontalAlignment="Left"
+                                        VerticalAlignment="Center"
+                                        FontFamily="Segoe UI"
+                                        FontSize="12"
+                                        Text="{TemplateBinding Title}"
+                                        TextAlignment="Left"
+                                        TextTrimming="CharacterEllipsis"
+                                        TextWrapping="NoWrap" />
+                                    <TextBlock
+                                        x:Name="SubtitleText"
+                                        MaxWidth="100"
+                                        Margin="0,-4,0,0"
+                                        HorizontalAlignment="Left"
+                                        VerticalAlignment="Center"
+                                        FontFamily="Segoe UI"
+                                        FontSize="10"
+                                        Foreground="{ThemeResource TextFillColorTertiary}"
+                                        Text="{TemplateBinding Subtitle}"
+                                        TextAlignment="Center"
+                                        TextTrimming="CharacterEllipsis"
+                                        TextWrapping="NoWrap" />
+                                </StackPanel>
+                            </Grid>
+                            <VisualStateManager.VisualStateGroups>
+                                <VisualStateGroup x:Name="CommonStates">
+                                    <VisualState x:Name="Normal" />
+                                    <VisualState x:Name="PointerOver">
+                                        <VisualState.Setters>
+                                            <Setter Target="PART_RootGrid.Background" Value="{ThemeResource DockItemBackgroundPointerOver}" />
+                                            <Setter Target="PART_RootGrid.BorderBrush" Value="{ThemeResource DockItemBorderBrushPointerOver}" />
+                                        </VisualState.Setters>
+                                    </VisualState>
+                                    <VisualState x:Name="Pressed">
+                                        <VisualState.Setters>
+                                            <Setter Target="PART_RootGrid.Background" Value="{ThemeResource DockItemBackgroundPointerOver}" />
+                                            <Setter Target="PART_RootGrid.BorderBrush" Value="{ThemeResource DockItemBorderBrushPressed}" />
+                                        </VisualState.Setters>
+                                    </VisualState>
+                                    <VisualState x:Name="Disabled">
+                                        <VisualState.Setters>
+                                            <Setter Target="PART_RootGrid.Background" Value="{ThemeResource DockItemBackground}" />
+                                            <Setter Target="PART_RootGrid.BorderBrush" Value="{ThemeResource DockItemBackground}" />
+                                            <Setter Target="IconPresenter.Foreground" Value="{ThemeResource ButtonForegroundDisabled}" />
+                                            <Setter Target="TitleText.Foreground" Value="{ThemeResource ButtonForegroundDisabled}" />
+                                            <Setter Target="SubtitleText.Foreground" Value="{ThemeResource ButtonForegroundDisabled}" />
+                                        </VisualState.Setters>
+                                    </VisualState>
+                                </VisualStateGroup>
+                                <VisualStateGroup x:Name="TextVisibilityStates">
+                                    <VisualState x:Name="TextVisible" />
+                                    <VisualState x:Name="TitleOnly">
+                                        <VisualState.Setters>
+                                            <Setter Target="SubtitleText.Visibility" Value="Collapsed" />
+                                        </VisualState.Setters>
+                                    </VisualState>
+                                    <VisualState x:Name="SubtitleOnly">
+                                        <VisualState.Setters>
+                                            <Setter Target="TitleText.Visibility" Value="Collapsed" />
+                                            <Setter Target="SubtitleText.Margin" Value="0" />
+                                        </VisualState.Setters>
+                                    </VisualState>
+                                    <VisualState x:Name="TextHidden">
+                                        <VisualState.Setters>
+                                            <Setter Target="ContentGrid.ColumnSpacing" Value="0" />
+                                            <Setter Target="TextPanel.Visibility" Value="Collapsed" />
+                                        </VisualState.Setters>
+                                    </VisualState>
+                                </VisualStateGroup>
+                                <VisualStateGroup x:Name="IconVisibilityStates">
+                                    <VisualState x:Name="IconVisible" />
+                                    <VisualState x:Name="IconHidden">
+                                        <VisualState.Setters>
+                                            <Setter Target="ContentGrid.ColumnSpacing" Value="0" />
+                                        </VisualState.Setters>
+                                    </VisualState>
+                                </VisualStateGroup>
+                            </VisualStateManager.VisualStateGroups>
+                        </Grid>
+                    </ControlTemplate>
+                </Setter.Value>
+            </Setter>
+        </Style.Setters>
+    </Style>
+</ResourceDictionary>

src/modules/cmdpal/Microsoft.CmdPal.UI/Dock/DockItemControl.xaml.cs

@@ -0,0 +1,213 @@
+// 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 Microsoft.CmdPal.UI.Controls;
+using Microsoft.CmdPal.UI.ViewModels;
+using Microsoft.CmdPal.UI.ViewModels.Dock;
+using Microsoft.UI.Xaml;
+using Microsoft.UI.Xaml.Controls;
+using Microsoft.UI.Xaml.Input;
+using Microsoft.UI.Xaml.Markup;
+
+namespace Microsoft.CmdPal.UI.Dock;
+
+[ContentProperty(Name = nameof(Icon))]
+public sealed partial class DockItemControl : Control
+{
+    public DockItemControl()
+    {
+        DefaultStyleKey = typeof(DockItemControl);
+    }
+
+    public static readonly DependencyProperty ToolTipProperty =
+        DependencyProperty.Register(nameof(ToolTip), typeof(string), typeof(DockItemControl), new PropertyMetadata(null));
+
+    public string ToolTip
+    {
+        get => (string)GetValue(ToolTipProperty);
+        set => SetValue(ToolTipProperty, value);
+    }
+
+    public static readonly DependencyProperty TitleProperty =
+        DependencyProperty.Register(nameof(Title), typeof(string), typeof(DockItemControl), new PropertyMetadata(null, OnTextPropertyChanged));
+
+    public string Title
+    {
+        get => (string)GetValue(TitleProperty);
+        set => SetValue(TitleProperty, value);
+    }
+
+    public static readonly DependencyProperty SubtitleProperty =
+        DependencyProperty.Register(nameof(Subtitle), typeof(string), typeof(DockItemControl), new PropertyMetadata(null, OnTextPropertyChanged));
+
+    public string Subtitle
+    {
+        get => (string)GetValue(SubtitleProperty);
+        set => SetValue(SubtitleProperty, value);
+    }
+
+    public static readonly DependencyProperty IconProperty =
+        DependencyProperty.Register(nameof(Icon), typeof(object), typeof(DockItemControl), new PropertyMetadata(null, OnIconPropertyChanged));
+
+    public object Icon
+    {
+        get => GetValue(IconProperty);
+        set => SetValue(IconProperty, value);
+    }
+
+    public static readonly DependencyProperty TextVisibilityProperty =
+        DependencyProperty.Register(nameof(TextVisibility), typeof(Visibility), typeof(DockItemControl), new PropertyMetadata(null, OnTextPropertyChanged));
+
+    public Visibility TextVisibility
+    {
+        get => (Visibility)GetValue(TextVisibilityProperty);
+        set => SetValue(TextVisibilityProperty, value);
+    }
+
+    private const string IconPresenterName = "IconPresenter";
+
+    private FrameworkElement? _iconPresenter;
+
+    private static void OnTextPropertyChanged(DependencyObject d, DependencyPropertyChangedEventArgs e)
+    {
+        if (d is DockItemControl control)
+        {
+            control.UpdateTextVisibility();
+            control.UpdateAlignment();
+        }
+    }
+
+    private static void OnIconPropertyChanged(DependencyObject d, DependencyPropertyChangedEventArgs e)
+    {
+        if (d is DockItemControl control)
+        {
+            control.UpdateIconVisibility();
+            control.UpdateAlignment();
+        }
+    }
+
+    internal bool HasTitle => !string.IsNullOrEmpty(Title);
+
+    internal bool HasSubtitle => !string.IsNullOrEmpty(Subtitle);
+
+    internal bool HasText => HasTitle || HasSubtitle;
+
+    private void UpdateTextVisibility()
+    {
+        UpdateTextVisibilityState();
+    }
+
+    private void UpdateTextVisibilityState()
+    {
+        // Determine which visual state to use based on title/subtitle presence
+        var stateName = (HasTitle, HasSubtitle) switch
+        {
+            (true, true) => "TextVisible",
+            (true, false) => "TitleOnly",
+            (false, true) => "SubtitleOnly",
+            (false, false) => "TextHidden",
+        };
+
+        VisualStateManager.GoToState(this, stateName, true);
+    }
+
+    private void UpdateIconVisibility()
+    {
+        if (Icon is IconBox icon)
+        {
+            var dt = icon.DataContext;
+            var src = icon.Source;
+
+            if (_iconPresenter is not null)
+            {
+                // n.b. this might be wrong - I think we always have an Icon (an IconBox),
+                // we need to check if the box has an icon
+                _iconPresenter.Visibility = Icon is null ? Visibility.Collapsed : Visibility.Visible;
+            }
+
+            UpdateIconVisibilityState();
+        }
+    }
+
+    private void UpdateIconVisibilityState()
+    {
+        var hasIcon = Icon is not null;
+        VisualStateManager.GoToState(this, hasIcon ? "IconVisible" : "IconHidden", true);
+    }
+
+    private void UpdateAlignment()
+    {
+        // If this item has both an icon and a label, left align so that the
+        // icons don't wobble if the text changes.
+        //
+        // Otherwise, center align.
+        var requestedTheme = ActualTheme;
+        var isLight = requestedTheme == ElementTheme.Light;
+        var showText = HasText;
+        if (Icon is IconBox icoBox &&
+            icoBox.DataContext is DockItemViewModel item &&
+            item.Icon is IconInfoViewModel icon)
+        {
+            var showIcon = icon is not null && icon.HasIcon(isLight);
+            if (showText && showIcon)
+            {
+                HorizontalAlignment = HorizontalAlignment.Left;
+                return;
+            }
+        }
+
+        HorizontalAlignment = HorizontalAlignment.Center;
+    }
+
+    private void UpdateAllVisibility()
+    {
+        UpdateTextVisibility();
+        UpdateIconVisibility();
+        UpdateAlignment();
+    }
+
+    protected override void OnApplyTemplate()
+    {
+        base.OnApplyTemplate();
+        IsEnabledChanged -= OnIsEnabledChanged;
+
+        PointerEntered -= Control_PointerEntered;
+        PointerExited -= Control_PointerExited;
+
+        PointerEntered += Control_PointerEntered;
+        PointerExited += Control_PointerExited;
+
+        IsEnabledChanged += OnIsEnabledChanged;
+
+        // Get template children for visibility updates
+        _iconPresenter = GetTemplateChild(IconPresenterName) as FrameworkElement;
+
+        // Set initial visibility
+        UpdateAllVisibility();
+    }
+
+    private void Control_PointerEntered(object sender, PointerRoutedEventArgs e)
+    {
+        VisualStateManager.GoToState(this, "PointerOver", true);
+    }
+
+    private void Control_PointerExited(object sender, PointerRoutedEventArgs e)
+    {
+        VisualStateManager.GoToState(this, "Normal", true);
+    }
+
+    protected override void OnPointerPressed(PointerRoutedEventArgs e)
+    {
+        if (IsEnabled)
+        {
+            base.OnPointerPressed(e);
+            VisualStateManager.GoToState(this, "Pressed", true);
+        }
+    }
+
+    private void OnIsEnabledChanged(object sender, DependencyPropertyChangedEventArgs e)
+    {
+        VisualStateManager.GoToState(this, IsEnabled ? "Normal" : "Disabled", true);
+    }
+}

src/modules/cmdpal/Microsoft.CmdPal.UI/Dock/DockSettingsToViews.cs

@@ -0,0 +1,67 @@
+// 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 Microsoft.CmdPal.UI.ViewModels.Settings;
+using Windows.Win32;
+using WinUIEx;
+
+namespace Microsoft.CmdPal.UI.Dock;
+
+internal static class DockSettingsToViews
+{
+    public static double WidthForSize(DockSize size)
+    {
+        return size switch
+        {
+            DockSize.Small => 128,
+            DockSize.Medium => 192,
+            DockSize.Large => 256,
+            _ => throw new NotImplementedException(),
+        };
+    }
+
+    public static double HeightForSize(DockSize size)
+    {
+        return size switch
+        {
+            DockSize.Small => 32,
+            DockSize.Medium => 54,
+            DockSize.Large => 76,
+            _ => throw new NotImplementedException(),
+        };
+    }
+
+    public static double IconSizeForSize(DockSize size)
+    {
+        return size switch
+        {
+            DockSize.Small => 32 / 2,
+            DockSize.Medium => 54 / 2,
+            DockSize.Large => 76 / 2,
+            _ => throw new NotImplementedException(),
+        };
+    }
+
+    public static Microsoft.UI.Xaml.Media.SystemBackdrop? GetSystemBackdrop(DockBackdrop backdrop)
+    {
+        return backdrop switch
+        {
+            DockBackdrop.Transparent => new TransparentTintBackdrop(),
+            DockBackdrop.Acrylic => null,
+            _ => throw new NotImplementedException(),
+        };
+    }
+
+    public static uint GetAppBarEdge(DockSide side)
+    {
+        return side switch
+        {
+            DockSide.Left => PInvoke.ABE_LEFT,
+            DockSide.Top => PInvoke.ABE_TOP,
+            DockSide.Right => PInvoke.ABE_RIGHT,
+            DockSide.Bottom => PInvoke.ABE_BOTTOM,
+            _ => throw new NotImplementedException(),
+        };
+    }
+}

src/modules/cmdpal/Microsoft.CmdPal.UI/Dock/DockWindow.xaml

@@ -0,0 +1,49 @@
+<?xml version="1.0" encoding="utf-8" ?>
+<winuiex:WindowEx
+    x:Class="Microsoft.CmdPal.UI.Dock.DockWindow"
+    xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
+    xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
+    xmlns:cpcontrols="using:Microsoft.CmdPal.UI.Controls"
+    xmlns:d="http://schemas.microsoft.com/expression/blend/2008"
+    xmlns:help="using:Microsoft.CmdPal.UI.Helpers"
+    xmlns:local="using:Microsoft.CmdPal.UI.Dock"
+    xmlns:mc="http://schemas.openxmlformats.org/markup-compatibility/2006"
+    xmlns:vm="using:Microsoft.CmdPal.UI.ViewModels"
+    xmlns:winuiex="using:WinUIEx"
+    Title="PowerDock"
+    Closed="DockWindow_Closed"
+    mc:Ignorable="d">
+
+    <Grid
+        x:Name="Root"
+        HorizontalAlignment="Stretch"
+        VerticalAlignment="Stretch">
+
+        <!--  Colorization overlay for transparent backdrop  -->
+        <Border
+            x:Name="ColorizationOverlay"
+            HorizontalAlignment="Stretch"
+            VerticalAlignment="Stretch"
+            IsHitTestVisible="False"
+            Opacity="{x:Bind WindowViewModel.ColorizationOpacity, Mode=OneWay}"
+            Visibility="{x:Bind WindowViewModel.ShowColorizationOverlay, Mode=OneWay}">
+            <Border.Background>
+                <SolidColorBrush Color="{x:Bind WindowViewModel.ColorizationColor, Mode=OneWay}" />
+            </Border.Background>
+        </Border>
+
+        <cpcontrols:BlurImageControl
+            HorizontalAlignment="Stretch"
+            VerticalAlignment="Stretch"
+            BlurAmount="{x:Bind WindowViewModel.BackgroundImageBlurAmount, Mode=OneWay}"
+            ImageBrightness="{x:Bind WindowViewModel.BackgroundImageBrightness, Mode=OneWay}"
+            ImageOpacity="{x:Bind WindowViewModel.BackgroundImageOpacity, Mode=OneWay}"
+            ImageSource="{x:Bind WindowViewModel.BackgroundImageSource, Mode=OneWay}"
+            ImageStretch="{x:Bind WindowViewModel.BackgroundImageStretch, Mode=OneWay}"
+            IsHitTestVisible="False"
+            IsHoldingEnabled="False"
+            TintColor="{x:Bind WindowViewModel.BackgroundImageTint, Mode=OneWay}"
+            TintIntensity="{x:Bind WindowViewModel.BackgroundImageTintIntensity, Mode=OneWay}"
+            Visibility="{x:Bind WindowViewModel.ShowBackgroundImage, Mode=OneWay}" />
+    </Grid>
+</winuiex:WindowEx>

src/modules/cmdpal/Microsoft.CmdPal.UI/Dock/DockWindow.xaml.cs

@@ -0,0 +1,725 @@
+// 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.Runtime.InteropServices;
+using CommunityToolkit.Mvvm.Messaging;
+using ManagedCommon;
+using Microsoft.CmdPal.UI.Helpers;
+using Microsoft.CmdPal.UI.ViewModels;
+using Microsoft.CmdPal.UI.ViewModels.Dock;
+using Microsoft.CmdPal.UI.ViewModels.Messages;
+using Microsoft.CmdPal.UI.ViewModels.Services;
+using Microsoft.CmdPal.UI.ViewModels.Settings;
+using Microsoft.Extensions.DependencyInjection;
+using Microsoft.UI.Composition;
+using Microsoft.UI.Composition.SystemBackdrops;
+using Microsoft.UI.Dispatching;
+using Microsoft.UI.Windowing;
+using Microsoft.UI.Xaml;
+using Windows.Foundation;
+using Windows.Win32;
+using Windows.Win32.Foundation;
+using Windows.Win32.Graphics.Dwm;
+using Windows.Win32.UI.Accessibility;
+using Windows.Win32.UI.Shell;
+using Windows.Win32.UI.WindowsAndMessaging;
+using WinRT;
+using WinRT.Interop;
+using WinUIEx;
+using WindowExtensions = Microsoft.CmdPal.UI.Helpers.WindowExtensions;
+
+namespace Microsoft.CmdPal.UI.Dock;
+
+#pragma warning disable SA1402 // File may only contain a single type
+
+public sealed partial class DockWindow : WindowEx,
+                                                 IRecipient<BringToTopMessage>,
+                                                 IRecipient<RequestShowPaletteAtMessage>,
+    IRecipient<QuitMessage>,
+    IDisposable
+{
+#pragma warning disable SA1306 // Field names should begin with lower-case letter
+#pragma warning disable SA1310 // Field names should not contain underscore
+    private readonly uint WM_TASKBAR_RESTART;
+#pragma warning restore SA1310 // Field names should not contain underscore
+#pragma warning restore SA1306 // Field names should begin with lower-case letter
+
+    private readonly IThemeService _themeService;
+    private readonly DockWindowViewModel _windowViewModel;
+    private readonly HiddenOwnerWindowBehavior _hiddenOwnerWindowBehavior = new();
+
+    private HWND _hwnd = HWND.Null;
+    private APPBARDATA _appBarData;
+    private uint _callbackMessageId;
+
+    private DockSettings _settings;
+    private DockViewModel viewModel;
+    private DockControl _dock;
+    private DesktopAcrylicController? _acrylicController;
+    private SystemBackdropConfiguration? _configurationSource;
+    private DockSize _lastSize;
+
+    // Store the original WndProc
+    private WNDPROC? _originalWndProc;
+    private WNDPROC? _customWndProc;
+
+    // internal Settings CurrentSettings => _settings;
+    public DockWindow()
+    {
+        var serviceProvider = App.Current.Services;
+        var mainSettings = serviceProvider.GetService<SettingsModel>()!;
+        mainSettings.SettingsChanged += SettingsChangedHandler;
+        _settings = mainSettings.DockSettings;
+        _lastSize = _settings.DockSize;
+
+        viewModel = serviceProvider.GetService<DockViewModel>()!;
+        _themeService = serviceProvider.GetRequiredService<IThemeService>();
+        _themeService.ThemeChanged += ThemeService_ThemeChanged;
+        _windowViewModel = new DockWindowViewModel(_themeService);
+        _dock = new DockControl(viewModel);
+
+        InitializeComponent();
+        Root.Children.Add(_dock);
+        ExtendsContentIntoTitleBar = true;
+        AppWindow.TitleBar.PreferredHeightOption = TitleBarHeightOption.Collapsed;
+        _hiddenOwnerWindowBehavior.ShowInTaskbar(this, false);
+        if (AppWindow.Presenter is OverlappedPresenter overlappedPresenter)
+        {
+            overlappedPresenter.SetBorderAndTitleBar(false, false);
+            overlappedPresenter.IsResizable = false;
+        }
+
+        this.Activated += DockWindow_Activated;
+
+        WeakReferenceMessenger.Default.Register<BringToTopMessage>(this);
+        WeakReferenceMessenger.Default.Register<RequestShowPaletteAtMessage>(this);
+        WeakReferenceMessenger.Default.Register<QuitMessage>(this);
+
+        _hwnd = GetWindowHandle(this);
+
+        // Subclass the window to intercept messages
+        //
+        // Set up custom window procedure to listen for display changes
+        // LOAD BEARING: If you don't stick the pointer to HotKeyPrc into a
+        // member (and instead like, use a local), then the pointer we marshal
+        // into the WindowLongPtr will be useless after we leave this function,
+        // and our **WindProc will explode**.
+        _customWndProc = CustomWndProc;
+
+        _callbackMessageId = PInvoke.RegisterWindowMessage($"CmdPal_ABM_{_hwnd}");
+
+        // TaskbarCreated is the message that's broadcast when explorer.exe
+        // restarts. We need to know when that happens to be able to bring our
+        // app bar back
+        // And this apparently happens on lock screens / hibernates, too
+        WM_TASKBAR_RESTART = PInvoke.RegisterWindowMessage("TaskbarCreated");
+
+        var hotKeyPrcPointer = Marshal.GetFunctionPointerForDelegate(_customWndProc);
+        _originalWndProc = Marshal.GetDelegateForFunctionPointer<WNDPROC>(PInvoke.SetWindowLongPtr(_hwnd, WINDOW_LONG_PTR_INDEX.GWL_WNDPROC, hotKeyPrcPointer));
+
+        // Disable minimize and maximize box
+        var style = (WINDOW_STYLE)PInvoke.GetWindowLong(_hwnd, WINDOW_LONG_PTR_INDEX.GWL_STYLE);
+        style &= ~WINDOW_STYLE.WS_MINIMIZEBOX; // Remove WS_MINIMIZEBOX
+        style &= ~WINDOW_STYLE.WS_MAXIMIZEBOX; // Remove WS_MAXIMIZEBOX
+        _ = PInvoke.SetWindowLong(_hwnd, WINDOW_LONG_PTR_INDEX.GWL_STYLE, (int)style);
+
+        ShowDesktop.AddHook(this);
+        UpdateSettingsOnUiThread();
+    }
+
+    private void SettingsChangedHandler(SettingsModel sender, object? args)
+    {
+        _settings = sender.DockSettings;
+        DispatcherQueue.TryEnqueue(UpdateSettingsOnUiThread);
+    }
+
+    private void DockWindow_Activated(object sender, WindowActivatedEventArgs args)
+    {
+        // These are used for removing the very subtle shadow/border that we get from Windows 11
+        HwndExtensions.ToggleWindowStyle(_hwnd, false, WindowStyle.TiledWindow);
+        unsafe
+        {
+            BOOL value = false;
+            PInvoke.DwmSetWindowAttribute(_hwnd, DWMWINDOWATTRIBUTE.DWMWA_WINDOW_CORNER_PREFERENCE, &value, (uint)sizeof(BOOL));
+        }
+    }
+
+    private HWND GetWindowHandle(Window window)
+    {
+        var hwnd = WindowNative.GetWindowHandle(window);
+        return new HWND(hwnd);
+    }
+
+    private void UpdateSettingsOnUiThread()
+    {
+        this.viewModel.UpdateSettings(_settings);
+
+        SystemBackdrop = DockSettingsToViews.GetSystemBackdrop(_settings.Backdrop);
+
+        // If the backdrop is acrylic, things are more complicated
+        if (_settings.Backdrop == DockBackdrop.Acrylic)
+        {
+            SetAcrylic();
+        }
+
+        _dock.UpdateSettings(_settings);
+        var side = DockSettingsToViews.GetAppBarEdge(_settings.Side);
+
+        if (_appBarData.hWnd != IntPtr.Zero)
+        {
+            var sameEdge = _appBarData.uEdge == side;
+            var sameSize = _lastSize == _settings.DockSize;
+            if (sameEdge && sameSize)
+            {
+                return;
+            }
+
+            DestroyAppBar(_hwnd);
+        }
+
+        CreateAppBar(_hwnd);
+    }
+
+    // We want to use DesktopAcrylicKind.Thin and custom colors as this is the default material
+    // other Shell surfaces are using, this cannot be set in XAML however.
+    private void SetAcrylic()
+    {
+        if (DesktopAcrylicController.IsSupported())
+        {
+            // Hooking up the policy object.
+            _configurationSource = new SystemBackdropConfiguration
+            {
+                // Initial configuration state.
+                IsInputActive = true,
+            };
+            UpdateAcrylic();
+        }
+    }
+
+    private void UpdateAcrylic()
+    {
+        if (_acrylicController != null)
+        {
+            _acrylicController.RemoveAllSystemBackdropTargets();
+            _acrylicController.Dispose();
+        }
+
+        var backdrop = _themeService.CurrentDockTheme.BackdropParameters;
+        _acrylicController = new DesktopAcrylicController
+        {
+            Kind = DesktopAcrylicKind.Thin,
+            TintColor = backdrop.TintColor,
+            TintOpacity = backdrop.EffectiveOpacity,
+            FallbackColor = backdrop.FallbackColor,
+            LuminosityOpacity = backdrop.EffectiveLuminosityOpacity,
+        };
+
+        // Enable the system backdrop.
+        // Note: Be sure to have "using WinRT;" to support the Window.As<...>() call.
+        _acrylicController.AddSystemBackdropTarget(this.As<ICompositionSupportsSystemBackdrop>());
+        _acrylicController.SetSystemBackdropConfiguration(_configurationSource);
+    }
+
+    private void DisposeAcrylic()
+    {
+        if (_acrylicController is not null)
+        {
+            _acrylicController.Dispose();
+            _acrylicController = null!;
+            _configurationSource = null!;
+        }
+    }
+
+    private void ThemeService_ThemeChanged(object? sender, ThemeChangedEventArgs e)
+    {
+        DispatcherQueue.TryEnqueue(() =>
+        {
+            // We only need to handle acrylic here.
+            // Transparent background is handled directly in XAML by binding to
+            // the DockWindowViewModel's ColorizationColor properties.
+            if (_settings.Backdrop == DockBackdrop.Acrylic)
+            {
+                UpdateAcrylic();
+            }
+
+            // ActualTheme / RequestedTheme sync,
+            // as pilfered from WindowThemeSynchronizer
+            // LOAD BEARING: Changing the RequestedTheme to Dark then Light then target forces
+            // a refresh of the theme.
+            Root.RequestedTheme = ElementTheme.Dark;
+            Root.RequestedTheme = ElementTheme.Light;
+            Root.RequestedTheme = _themeService.CurrentDockTheme.Theme;
+        });
+    }
+
+    private void CreateAppBar(HWND hwnd)
+    {
+        _appBarData = new APPBARDATA
+        {
+            cbSize = (uint)Marshal.SizeOf<APPBARDATA>(),
+            hWnd = hwnd,
+            uCallbackMessage = _callbackMessageId,
+        };
+
+        // Register this window as an app bar
+        PInvoke.SHAppBarMessage(PInvoke.ABM_NEW, ref _appBarData);
+
+        // Stash the last size we created the bar at, so we know when to hot-
+        // reload it
+        _lastSize = _settings.DockSize;
+
+        UpdateWindowPosition();
+    }
+
+    private void DestroyAppBar(HWND hwnd)
+    {
+        PInvoke.SHAppBarMessage(PInvoke.ABM_REMOVE, ref _appBarData);
+        _appBarData = default;
+    }
+
+    private void UpdateWindowPosition()
+    {
+        Logger.LogDebug("UpdateWindowPosition");
+
+        var dpi = PInvoke.GetDpiForWindow(_hwnd);
+
+        var screenWidth = PInvoke.GetSystemMetrics(SYSTEM_METRICS_INDEX.SM_CXSCREEN);
+
+        // Get system border metrics
+        var borderWidth = PInvoke.GetSystemMetrics(SYSTEM_METRICS_INDEX.SM_CXBORDER);
+        var edgeWidth = PInvoke.GetSystemMetrics(SYSTEM_METRICS_INDEX.SM_CXEDGE);
+        var frameWidth = PInvoke.GetSystemMetrics(SYSTEM_METRICS_INDEX.SM_CXFRAME);
+
+        var scaleFactor = dpi / 96.0;
+        UpdateAppBarDataForEdge(_settings.Side, _settings.DockSize, scaleFactor);
+
+        // Query and set position
+        PInvoke.SHAppBarMessage(PInvoke.ABM_QUERYPOS, ref _appBarData);
+
+        // ABM_QUERYPOS adjusts our rect so we don't overlap other app bars,
+        // but it may have shifted our anchored edge without updating the
+        // opposite edge. We need to re-apply our desired thickness so the
+        // bar keeps its correct size. Without this, a second bar docked to
+        // the same side would get a zero-height/width rect and fail to
+        // reserve work-area space.
+        switch (_settings.Side)
+        {
+            case DockSide.Top:
+                _appBarData.rc.bottom = _appBarData.rc.top + (int)(DockSettingsToViews.HeightForSize(_settings.DockSize) * scaleFactor);
+                break;
+            case DockSide.Bottom:
+                _appBarData.rc.top = _appBarData.rc.bottom - (int)(DockSettingsToViews.HeightForSize(_settings.DockSize) * scaleFactor);
+                break;
+            case DockSide.Left:
+                _appBarData.rc.right = _appBarData.rc.left + (int)(DockSettingsToViews.WidthForSize(_settings.DockSize) * scaleFactor);
+                break;
+            case DockSide.Right:
+                _appBarData.rc.left = _appBarData.rc.right - (int)(DockSettingsToViews.WidthForSize(_settings.DockSize) * scaleFactor);
+                break;
+        }
+
+        PInvoke.SHAppBarMessage(PInvoke.ABM_SETPOS, ref _appBarData);
+
+        // TODO: investigate ABS_AUTOHIDE and auto hide bars.
+        // I think it's something like this, but I don't totally know
+        //   _appBarData.lParam = ABS_ALWAYSONTOP;
+        //   _appBarData.lParam = (LPARAM)(int)PInvoke.ABS_AUTOHIDE;
+        //   PInvoke.SHAppBarMessage(ABM_SETSTATE, ref _appBarData);
+        //   PInvoke.SHAppBarMessage(PInvoke.ABM_SETAUTOHIDEBAR, ref _appBarData);
+
+        // Account for system borders when moving the window
+        // Adjust position to account for window frame/border
+        var adjustedLeft = _appBarData.rc.left - frameWidth;
+        var adjustedTop = _appBarData.rc.top - frameWidth;
+        var adjustedWidth = (_appBarData.rc.right - _appBarData.rc.left) + (2 * frameWidth);
+        var adjustedHeight = (_appBarData.rc.bottom - _appBarData.rc.top) + (2 * frameWidth);
+
+        // Move the actual window
+        PInvoke.MoveWindow(
+            _hwnd,
+            adjustedLeft,
+            adjustedTop,
+            adjustedWidth,
+            adjustedHeight,
+            true);
+    }
+
+    private void UpdateAppBarDataForEdge(DockSide side, DockSize size, double scaleFactor)
+    {
+        Logger.LogDebug("UpdateAppBarDataForEdge");
+        var horizontalHeightDips = DockSettingsToViews.HeightForSize(size);
+        var verticalWidthDips = DockSettingsToViews.WidthForSize(size);
+        var screenHeight = PInvoke.GetSystemMetrics(SYSTEM_METRICS_INDEX.SM_CYSCREEN);
+        var screenWidth = PInvoke.GetSystemMetrics(SYSTEM_METRICS_INDEX.SM_CXSCREEN);
+
+        if (side == DockSide.Top)
+        {
+            _appBarData.uEdge = PInvoke.ABE_TOP;
+            _appBarData.rc.left = 0;
+            _appBarData.rc.top = 0;
+            _appBarData.rc.right = screenWidth;
+            _appBarData.rc.bottom = (int)(horizontalHeightDips * scaleFactor);
+        }
+        else if (side == DockSide.Bottom)
+        {
+            var heightPixels = (int)(horizontalHeightDips * scaleFactor);
+
+            _appBarData.uEdge = PInvoke.ABE_BOTTOM;
+            _appBarData.rc.left = 0;
+            _appBarData.rc.top = screenHeight - heightPixels;
+            _appBarData.rc.right = screenWidth;
+            _appBarData.rc.bottom = screenHeight;
+        }
+        else if (side == DockSide.Left)
+        {
+            var widthPixels = (int)(verticalWidthDips * scaleFactor);
+
+            _appBarData.uEdge = PInvoke.ABE_LEFT;
+            _appBarData.rc.left = 0;
+            _appBarData.rc.top = 0;
+            _appBarData.rc.right = widthPixels;
+            _appBarData.rc.bottom = screenHeight;
+        }
+        else if (side == DockSide.Right)
+        {
+            var widthPixels = (int)(verticalWidthDips * scaleFactor);
+
+            _appBarData.uEdge = PInvoke.ABE_RIGHT;
+            _appBarData.rc.left = screenWidth - widthPixels;
+            _appBarData.rc.top = 0;
+            _appBarData.rc.right = screenWidth;
+            _appBarData.rc.bottom = screenHeight;
+        }
+        else
+        {
+            return;
+        }
+    }
+
+    private LRESULT CustomWndProc(HWND hwnd, uint msg, WPARAM wParam, LPARAM lParam)
+    {
+        // check settings changed
+        if (msg == PInvoke.WM_SETTINGCHANGE)
+        {
+            if (wParam == (uint)SYSTEM_PARAMETERS_INFO_ACTION.SPI_SETWORKAREA)
+            {
+                Logger.LogDebug($"WM_SETTINGCHANGE(SPI_SETWORKAREA)");
+
+                // Use debounced call to throttle rapid successive calls
+                DispatcherQueue.TryEnqueue(() => UpdateWindowPosition());
+            }
+        }
+        else if (msg == PInvoke.WM_DISPLAYCHANGE)
+        {
+            Logger.LogDebug("WM_DISPLAYCHANGE");
+
+            // Use dispatcher to ensure we're on the UI thread
+            DispatcherQueue.TryEnqueue(() => UpdateWindowPosition());
+        }
+
+        // Intercept WM_SYSCOMMAND to prevent minimize and maximize
+        else if (msg == PInvoke.WM_SYSCOMMAND)
+        {
+            var command = (int)(wParam.Value & 0xFFF0);
+            if (command == PInvoke.SC_MINIMIZE || command == PInvoke.SC_MAXIMIZE)
+            {
+                // Block minimize and maximize commands
+                return new LRESULT(0);
+            }
+        }
+
+        // Stop min/max on WM_WINDOWPOSCHANGING too
+        else if (msg == PInvoke.WM_WINDOWPOSCHANGING)
+        {
+            unsafe
+            {
+                var pWindowPos = (WINDOWPOS*)lParam.Value;
+
+                // Check if the window is being hidden (minimized) or if flags suggest minimize/maximize
+                if ((pWindowPos->flags & SET_WINDOW_POS_FLAGS.SWP_HIDEWINDOW) != 0)
+                {
+                    // Prevent hiding the window (minimize)
+                    pWindowPos->flags &= ~SET_WINDOW_POS_FLAGS.SWP_HIDEWINDOW;
+                    pWindowPos->flags |= SET_WINDOW_POS_FLAGS.SWP_SHOWWINDOW;
+                }
+
+                // Additional check: if the window position suggests it's being minimized or maximized
+                // by checking for dramatic size changes
+                if (pWindowPos->cx <= 0 || pWindowPos->cy <= 0)
+                {
+                    // Prevent zero or negative size changes (minimize)
+                    pWindowPos->flags |= SET_WINDOW_POS_FLAGS.SWP_NOSIZE;
+                }
+            }
+        }
+
+        // Handle WM_SIZE to prevent minimize/maximize state changes
+        else if (msg == PInvoke.WM_SIZE)
+        {
+            var sizeType = (int)wParam.Value;
+            if (sizeType == PInvoke.SIZE_MINIMIZED || sizeType == PInvoke.SIZE_MAXIMIZED)
+            {
+                // Block the size change by not calling the original window procedure
+                return new LRESULT(0);
+            }
+        }
+
+        // Handle WM_SHOWWINDOW to prevent hiding (minimize)
+        else if (msg == PInvoke.WM_SHOWWINDOW)
+        {
+            var isBeingShown = wParam.Value != 0;
+            if (!isBeingShown)
+            {
+                // Prevent hiding the window
+                return new LRESULT(0);
+            }
+        }
+
+        // Handle double-click on title bar (non-client area)
+        else if (msg == PInvoke.WM_NCLBUTTONDBLCLK)
+        {
+            var hitTest = (int)wParam.Value;
+            if (hitTest == PInvoke.HTCAPTION)
+            {
+                // Block double-click on title bar to prevent maximize
+                return new LRESULT(0);
+            }
+        }
+
+        // Handle WM_GETMINMAXINFO to control window size limits
+        else if (msg == PInvoke.WM_GETMINMAXINFO)
+        {
+            // We can modify the min/max tracking info here if needed
+            // For now, let it pass through but we could restrict max size
+        }
+
+        // Handle the AppBarMessage message
+        // This is needed to update the position when the work area changes.
+        // (notably, when the user toggles auto-hide taskbars)
+        else if (msg == _callbackMessageId)
+        {
+            if (wParam.Value == PInvoke.ABN_POSCHANGED)
+            {
+                UpdateWindowPosition();
+            }
+        }
+        else if (msg == WM_TASKBAR_RESTART)
+        {
+            Logger.LogDebug("WM_TASKBAR_RESTART");
+
+            DispatcherQueue.TryEnqueue(() => CreateAppBar(_hwnd));
+
+            WeakReferenceMessenger.Default.Send<BringToTopMessage>(new(false));
+        }
+
+        // Call the original window procedure for all other messages
+        return PInvoke.CallWindowProc(_originalWndProc, hwnd, msg, wParam, lParam);
+    }
+
+    void IRecipient<BringToTopMessage>.Receive(BringToTopMessage message)
+    {
+        DispatcherQueue.TryEnqueue(() =>
+        {
+            var onTop = message.OnTop ? HWND.HWND_TOPMOST : HWND.HWND_NOTOPMOST;
+            PInvoke.SetWindowPos(_hwnd, onTop, 0, 0, 0, 0, SET_WINDOW_POS_FLAGS.SWP_NOMOVE | SET_WINDOW_POS_FLAGS.SWP_NOSIZE);
+            PInvoke.SetWindowPos(_hwnd, HWND.HWND_NOTOPMOST, 0, 0, 0, 0, SET_WINDOW_POS_FLAGS.SWP_NOMOVE | SET_WINDOW_POS_FLAGS.SWP_NOSIZE);
+        });
+    }
+
+    public void Receive(QuitMessage message)
+    {
+        DispatcherQueue.TryEnqueue(() =>
+        {
+            DestroyAppBar(_hwnd);
+
+            this.Close();
+        });
+    }
+
+    void IRecipient<RequestShowPaletteAtMessage>.Receive(RequestShowPaletteAtMessage message)
+    {
+        DispatcherQueue.TryEnqueue(DispatcherQueuePriority.Low, () => RequestShowPaletteOnUiThread(message.PosDips));
+    }
+
+    private void RequestShowPaletteOnUiThread(Point posDips)
+    {
+        // pos is relative to our root. We need to convert to screen coords.
+        var rootPosDips = Root.TransformToVisual(null).TransformPoint(new Point(0, 0));
+        var screenPosDips = new Point(rootPosDips.X + posDips.X, rootPosDips.Y + posDips.Y);
+
+        var dpi = PInvoke.GetDpiForWindow(_hwnd);
+        var scaleFactor = dpi / 96.0;
+        var screenPosPixels = new Point(screenPosDips.X * scaleFactor, screenPosDips.Y * scaleFactor);
+
+        var screenWidth = PInvoke.GetSystemMetrics(SYSTEM_METRICS_INDEX.SM_CXSCREEN);
+        var screenHeight = PInvoke.GetSystemMetrics(SYSTEM_METRICS_INDEX.SM_CYSCREEN);
+
+        // Now we're going to find the best position for the palette.
+
+        // We want to anchor the palette on the dock side.
+        // on the top:
+        //   - anchor to the top, left if we're on the left half of the screen
+        //   - anchor to the top, right if we're on the right half of the screen
+        // On the left:
+        //   - anchor to the top, left if we're on the top half of the screen
+        //   - anchor to the bottom, left if we're on the bottom half of the screen
+        // On the right:
+        //   - anchor to the top, right if we're on the top half of the screen
+        //   - anchor to the bottom, right if we're on the bottom half of the screen
+        // On the bottom:
+        //   - anchor to the bottom, left if we're on the left half of the screen
+        //   - anchor to the bottom, right if we're on the right half of the screen
+        var onTopHalf = screenPosPixels.Y < screenHeight / 2;
+        var onLeftHalf = screenPosPixels.X < screenWidth / 2;
+        var onRightHalf = !onLeftHalf;
+        var onBottomHalf = !onTopHalf;
+
+        var anchorPoint = _settings.Side switch
+        {
+            DockSide.Top => onLeftHalf ? AnchorPoint.TopLeft : AnchorPoint.TopRight,
+            DockSide.Bottom => onLeftHalf ? AnchorPoint.BottomLeft : AnchorPoint.BottomRight,
+            DockSide.Left => onTopHalf ? AnchorPoint.TopLeft : AnchorPoint.BottomLeft,
+            DockSide.Right => onTopHalf ? AnchorPoint.TopRight : AnchorPoint.BottomRight,
+            _ => AnchorPoint.TopLeft,
+        };
+
+        // we also need to slide the anchor point a bit away from the dock
+        var paddingDips = 8;
+        var paddingPixels = paddingDips * scaleFactor;
+        PInvoke.GetWindowRect(_hwnd, out var ourRect);
+
+        // Depending on the side we're on, we need to offset differently
+        switch (_settings.Side)
+        {
+            case DockSide.Top:
+                screenPosPixels.Y = ourRect.bottom + paddingPixels;
+                break;
+            case DockSide.Bottom:
+                screenPosPixels.Y = ourRect.top - paddingPixels;
+                break;
+            case DockSide.Left:
+                screenPosPixels.X = ourRect.right + paddingPixels;
+                break;
+            case DockSide.Right:
+                screenPosPixels.X = ourRect.left - paddingPixels;
+                break;
+        }
+
+        // Now that we know the anchor corner, and where to attempt to place it, we can
+        // ask the palette to show itself there.
+        WeakReferenceMessenger.Default.Send<ShowPaletteAtMessage>(new(screenPosPixels, anchorPoint));
+    }
+
+    public DockWindowViewModel WindowViewModel => _windowViewModel;
+
+    public void Dispose()
+    {
+        DisposeAcrylic();
+        _windowViewModel.Dispose();
+    }
+
+    private void DockWindow_Closed(object sender, WindowEventArgs args)
+    {
+        var serviceProvider = App.Current.Services;
+        var settings = serviceProvider.GetService<SettingsModel>();
+        settings?.SettingsChanged -= SettingsChangedHandler;
+        _themeService.ThemeChanged -= ThemeService_ThemeChanged;
+        DisposeAcrylic();
+
+        // Remove our app bar registration
+        DestroyAppBar(_hwnd);
+
+        // Unhook the window procedure
+        ShowDesktop.RemoveHook();
+    }
+}
+
+// Thank you to https://stackoverflow.com/a/35422795/1481137
+internal static class ShowDesktop
+{
+    private const string WORKERW = "WorkerW";
+    private const string PROGMAN = "Progman";
+
+    private static WINEVENTPROC? _hookProc;
+    private static IntPtr _hookHandle = IntPtr.Zero;
+
+    public static void AddHook(Window window)
+    {
+        if (IsHooked)
+        {
+            return;
+        }
+
+        IsHooked = true;
+
+        _hookProc = (WINEVENTPROC)WinEventCallback;
+        _hookHandle = PInvoke.SetWinEventHook(PInvoke.EVENT_SYSTEM_FOREGROUND, PInvoke.EVENT_SYSTEM_FOREGROUND, HMODULE.Null, _hookProc, 0, 0, PInvoke.WINEVENT_OUTOFCONTEXT);
+    }
+
+    public static void RemoveHook()
+    {
+        if (!IsHooked)
+        {
+            return;
+        }
+
+        IsHooked = false;
+
+        PInvoke.UnhookWinEvent((HWINEVENTHOOK)_hookHandle);
+        _hookProc = null;
+        _hookHandle = IntPtr.Zero;
+    }
+
+    private static string GetWindowClass(HWND hwnd)
+    {
+        unsafe
+        {
+            fixed (char* c = new char[32])
+            {
+                _ = PInvoke.GetClassName(hwnd, (PWSTR)c, 32);
+                return new string(c);
+            }
+        }
+    }
+
+    internal delegate void WinEventDelegate(IntPtr hWinEventHook, uint eventType, IntPtr hwnd, int idObject, int idChild, uint dwEventThread, uint dwmsEventTime);
+
+    private static void WinEventCallback(
+        HWINEVENTHOOK hWinEventHook,
+        uint eventType,
+        HWND hwnd,
+        int idObject,
+        int idChild,
+        uint dwEventThread,
+        uint dwmsEventTime)
+    {
+        if (eventType == PInvoke.EVENT_SYSTEM_FOREGROUND)
+        {
+            var @class = GetWindowClass(hwnd);
+            if (string.Equals(@class, WORKERW, StringComparison.Ordinal) || string.Equals(@class, PROGMAN, StringComparison.Ordinal))
+            {
+                Logger.LogDebug("ShowDesktop invoked. Bring us back");
+                WeakReferenceMessenger.Default.Send<BringToTopMessage>(new(true));
+            }
+        }
+    }
+
+    public static bool IsHooked { get; private set; }
+}
+
+internal sealed record BringToTopMessage(bool OnTop);
+
+internal sealed record RequestShowPaletteAtMessage(Point PosDips);
+
+internal sealed record ShowPaletteAtMessage(Point PosPixels, AnchorPoint Anchor);
+
+internal enum AnchorPoint
+{
+    TopLeft,
+    TopRight,
+    BottomLeft,
+    BottomRight,
+}
+
+#pragma warning restore SA1402 // File may only contain a single type

src/modules/cmdpal/Microsoft.CmdPal.UI/Events/CmdPalDockConfiguration.cs

@@ -0,0 +1,60 @@
+// 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;
+using System.Diagnostics.Tracing;
+using Microsoft.PowerToys.Telemetry;
+using Microsoft.PowerToys.Telemetry.Events;
+
+namespace Microsoft.CmdPal.UI.Events;
+
+/// <summary>
+/// Tracks the dock configuration at startup.
+/// Purpose: Understand how users configure their dock - which side, which bands, and whether it's enabled.
+/// </summary>
+[EventData]
+[DynamicallyAccessedMembers(DynamicallyAccessedMemberTypes.PublicProperties)]
+public class CmdPalDockConfiguration : EventBase, IEvent
+{
+    /// <summary>
+    /// Gets or sets whether the dock is enabled.
+    /// </summary>
+    public bool IsDockEnabled { get; set; }
+
+    /// <summary>
+    /// Gets or sets the dock side (top, bottom, left, right, none).
+    /// "none" when the dock is disabled.
+    /// </summary>
+    public string DockSide { get; set; }
+
+    /// <summary>
+    /// Gets or sets the start bands as a newline-delimited list of "{ProviderId}/{CommandId}".
+    /// Empty if the dock is disabled.
+    /// </summary>
+    public string StartBands { get; set; }
+
+    /// <summary>
+    /// Gets or sets the center bands as a newline-delimited list of "{ProviderId}/{CommandId}".
+    /// Empty if the dock is disabled.
+    /// </summary>
+    public string CenterBands { get; set; }
+
+    /// <summary>
+    /// Gets or sets the end bands as a newline-delimited list of "{ProviderId}/{CommandId}".
+    /// Empty if the dock is disabled.
+    /// </summary>
+    public string EndBands { get; set; }
+
+    public CmdPalDockConfiguration(bool isDockEnabled, string dockSide, string startBands, string centerBands, string endBands)
+    {
+        EventName = "CmdPal_DockConfiguration";
+        IsDockEnabled = isDockEnabled;
+        DockSide = dockSide;
+        StartBands = startBands;
+        CenterBands = centerBands;
+        EndBands = endBands;
+    }
+
+    public PartA_PrivTags PartA_PrivTags => PartA_PrivTags.ProductAndServiceUsage;
+}

src/modules/cmdpal/Microsoft.CmdPal.UI/ExtViews/ListPage.xaml.cs

@@ -2,10 +2,8 @@
 // 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;
 using CommunityToolkit.Mvvm.Messaging;
 using ManagedCommon;
-using Microsoft.CmdPal.Core.ViewModels;
 using Microsoft.CmdPal.UI.Helpers;
 using Microsoft.CmdPal.UI.Messages;
 using Microsoft.CmdPal.UI.ViewModels;

src/modules/cmdpal/Microsoft.CmdPal.UI/Helpers/Icons/IconCacheProvider.cs

@@ -24,6 +24,7 @@ public static partial class IconCacheProvider
       | 256×256   | 256.0 KB |    64 |  16.0 MB |            1 MB |      64.0 MB |          2.3 MB |       144 MB |
     */
 
+    private static IIconSourceProvider _provider16 = null!;
     private static IIconSourceProvider _provider20 = null!;
     private static IIconSourceProvider _provider32 = null!;
     private static IIconSourceProvider _provider64 = null!;
@@ -31,6 +32,7 @@ public static partial class IconCacheProvider
 
     public static void Initialize(IServiceProvider serviceProvider)
     {
+        _provider16 = serviceProvider.GetRequiredKeyedService<IIconSourceProvider>(WellKnownIconSize.Size16);
         _provider20 = serviceProvider.GetRequiredKeyedService<IIconSourceProvider>(WellKnownIconSize.Size20);
         _provider32 = serviceProvider.GetRequiredKeyedService<IIconSourceProvider>(WellKnownIconSize.Size32);
         _provider64 = serviceProvider.GetRequiredKeyedService<IIconSourceProvider>(WellKnownIconSize.Size64);
@@ -64,6 +66,9 @@ public static partial class IconCacheProvider
     }
 
 #pragma warning disable IDE0060 // Remove unused parameter
+    public static void SourceRequested16(IconBox sender, SourceRequestedEventArgs args)
+        => SourceRequestedCore(_provider16, args);
+
     public static void SourceRequested20(IconBox sender, SourceRequestedEventArgs args)
         => SourceRequestedCore(_provider20, args);
 

src/modules/cmdpal/Microsoft.CmdPal.UI/Helpers/Icons/IconServiceRegistration.cs

@@ -16,6 +16,10 @@ internal static class IconServiceRegistration
         services.AddSingleton<IIconLoaderService>(loader);
 
         // Keyed providers by size
+        services.AddKeyedSingleton<IIconSourceProvider>(
+            WellKnownIconSize.Size16,
+            (_, _) => new IconSourceProvider(loader, 16));
+
         services.AddKeyedSingleton<IIconSourceProvider>(
             WellKnownIconSize.Size20,
             (_, _) => new CachedIconSourceProvider(loader, 20, 1024));

src/modules/cmdpal/Microsoft.CmdPal.UI/Helpers/Icons/WellKnownIconSize.cs

@@ -6,6 +6,7 @@ namespace Microsoft.CmdPal.UI.Helpers;
 
 internal enum WellKnownIconSize
 {
+    Size16 = 16,
     Size20 = 20,
     Size32 = 32,
     Size64 = 64,

src/modules/cmdpal/Microsoft.CmdPal.UI/Helpers/TelemetryForwarder.cs

@@ -20,13 +20,15 @@ internal sealed class TelemetryForwarder :
     ITelemetryService,
     IRecipient<TelemetryBeginInvokeMessage>,
     IRecipient<TelemetryInvokeResultMessage>,
-    IRecipient<TelemetryExtensionInvokedMessage>
+    IRecipient<TelemetryExtensionInvokedMessage>,
+    IRecipient<TelemetryDockConfigurationMessage>
 {
     public TelemetryForwarder()
     {
         WeakReferenceMessenger.Default.Register<TelemetryBeginInvokeMessage>(this);
         WeakReferenceMessenger.Default.Register<TelemetryInvokeResultMessage>(this);
         WeakReferenceMessenger.Default.Register<TelemetryExtensionInvokedMessage>(this);
+        WeakReferenceMessenger.Default.Register<TelemetryDockConfigurationMessage>(this);
     }
 
     // Message handlers for telemetry events from core layer
@@ -56,6 +58,16 @@ internal sealed class TelemetryForwarder :
         }
     }
 
+    public void Receive(TelemetryDockConfigurationMessage message)
+    {
+        PowerToysTelemetry.Log.WriteEvent(new CmdPalDockConfiguration(
+            message.IsDockEnabled,
+            message.DockSide,
+            message.StartBands,
+            message.CenterBands,
+            message.EndBands));
+    }
+
     // Static method for logging session duration from UI layer
     public static void LogSessionDuration(
         ulong durationMs,

src/modules/cmdpal/Microsoft.CmdPal.UI/Helpers/TrayIconService.cs

@@ -1,4 +1,4 @@
-// Copyright (c) Microsoft Corporation
+// 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.
 

src/modules/cmdpal/Microsoft.CmdPal.UI/LocalSuppressions.cs

@@ -8,3 +8,4 @@ using System.Diagnostics.CodeAnalysis;
 [assembly: SuppressMessage("Interoperability", "CsWinRT1028: Class should be marked partial", Justification = "CsWin32 generated code; not used across WinRT boundary", Scope = "type", Target = "~T:Windows.Win32.FreeLibrarySafeHandle")]
 [assembly: SuppressMessage("Interoperability", "CsWinRT1028: Class should be marked partial", Justification = "CsWin32 generated code; not used across WinRT boundary", Scope = "type", Target = "~T:Windows.Win32.UnhookWindowsHookExSafeHandle")]
 [assembly: SuppressMessage("Interoperability", "CsWinRT1028: Class should be marked partial", Justification = "CsWin32 generated code; not used across WinRT boundary", Scope = "type", Target = "~T:Windows.Win32.DeleteObjectSafeHandle")]
+[assembly: SuppressMessage("Interoperability", "CsWinRT1028: Class should be marked partial", Justification = "CsWin32 generated code; not used across WinRT boundary", Scope = "type", Target = "~T:Windows.Win32.UnhookWinEventSafeHandle")]

src/modules/cmdpal/Microsoft.CmdPal.UI/MainWindow.xaml.cs

@@ -11,6 +11,7 @@ using Microsoft.CmdPal.Common.Helpers;
 using Microsoft.CmdPal.Common.Services;
 using Microsoft.CmdPal.Ext.ClipboardHistory.Messages;
 using Microsoft.CmdPal.UI.Controls;
+using Microsoft.CmdPal.UI.Dock;
 using Microsoft.CmdPal.UI.Events;
 using Microsoft.CmdPal.UI.Helpers;
 using Microsoft.CmdPal.UI.Messages;
@@ -18,6 +19,7 @@ using Microsoft.CmdPal.UI.Services;
 using Microsoft.CmdPal.UI.ViewModels;
 using Microsoft.CmdPal.UI.ViewModels.Messages;
 using Microsoft.CmdPal.UI.ViewModels.Services;
+using Microsoft.CmdPal.ViewModels.Messages;
 using Microsoft.Extensions.DependencyInjection;
 using Microsoft.PowerToys.Telemetry;
 using Microsoft.UI.Composition;
@@ -45,6 +47,7 @@ namespace Microsoft.CmdPal.UI;
 public sealed partial class MainWindow : WindowEx,
     IRecipient<DismissMessage>,
     IRecipient<ShowWindowMessage>,
+    IRecipient<ShowPaletteAtMessage>,
     IRecipient<HideWindowMessage>,
     IRecipient<QuitMessage>,
     IRecipient<NavigateToPageMessage>,
@@ -145,6 +148,7 @@ public sealed partial class MainWindow : WindowEx,
         WeakReferenceMessenger.Default.Register<DismissMessage>(this);
         WeakReferenceMessenger.Default.Register<QuitMessage>(this);
         WeakReferenceMessenger.Default.Register<ShowWindowMessage>(this);
+        WeakReferenceMessenger.Default.Register<ShowPaletteAtMessage>(this);
         WeakReferenceMessenger.Default.Register<HideWindowMessage>(this);
         WeakReferenceMessenger.Default.Register<NavigateToPageMessage>(this);
         WeakReferenceMessenger.Default.Register<NavigationDepthMessage>(this);
@@ -206,7 +210,10 @@ public sealed partial class MainWindow : WindowEx,
         }
     }
 
-    private void SettingsChangedHandler(SettingsModel sender, object? args) => HotReloadSettings();
+    private void SettingsChangedHandler(SettingsModel sender, object? args)
+    {
+        DispatcherQueue.TryEnqueue(HotReloadSettings);
+    }
 
     private void RootElementLoaded(object sender, RoutedEventArgs e)
     {
@@ -496,6 +503,78 @@ public sealed partial class MainWindow : WindowEx,
     }
 
     private void ShowHwnd(IntPtr hwndValue, MonitorBehavior target)
+    {
+        var positionWindowForTargetMonitor = (HWND hwnd) =>
+        {
+            if (target == MonitorBehavior.ToLast)
+            {
+                var originalScreen = new SizeInt32(_currentWindowPosition.ScreenWidth, _currentWindowPosition.ScreenHeight);
+                var newRect = WindowPositionHelper.AdjustRectForVisibility(_currentWindowPosition.ToPhysicalWindowRectangle(), originalScreen, _currentWindowPosition.Dpi);
+                MoveAndResizeDpiAware(newRect);
+            }
+            else
+            {
+                var display = GetScreen(hwnd, target);
+                PositionCentered(display);
+            }
+        };
+        ShowHwnd(hwndValue, positionWindowForTargetMonitor);
+    }
+
+    private void ShowHwnd(IntPtr hwndValue, Point anchorInPixels, AnchorPoint anchorCorner)
+    {
+        var positionWindowForAnchor = (HWND hwnd) =>
+        {
+            PInvoke.GetWindowRect(hwnd, out var bounds);
+            var swpFlags = SET_WINDOW_POS_FLAGS.SWP_NOSIZE | SET_WINDOW_POS_FLAGS.SWP_NOACTIVATE | SET_WINDOW_POS_FLAGS.SWP_NOZORDER;
+            switch (anchorCorner)
+            {
+                case AnchorPoint.TopLeft:
+                    PInvoke.SetWindowPos(
+                        hwnd,
+                        HWND.HWND_TOP,
+                        (int)anchorInPixels.X,
+                        (int)anchorInPixels.Y,
+                        0,
+                        0,
+                        swpFlags);
+                    break;
+                case AnchorPoint.TopRight:
+                    PInvoke.SetWindowPos(
+                        hwnd,
+                        HWND.HWND_TOP,
+                        (int)(anchorInPixels.X - bounds.Width),
+                        (int)anchorInPixels.Y,
+                        0,
+                        0,
+                        swpFlags);
+                    break;
+                case AnchorPoint.BottomLeft:
+                    PInvoke.SetWindowPos(
+                        hwnd,
+                        HWND.HWND_TOP,
+                        (int)anchorInPixels.X,
+                        (int)(anchorInPixels.Y - bounds.Height),
+                        0,
+                        0,
+                        swpFlags);
+                    break;
+                case AnchorPoint.BottomRight:
+                    PInvoke.SetWindowPos(
+                        hwnd,
+                        HWND.HWND_TOP,
+                        (int)(anchorInPixels.X - bounds.Width),
+                        (int)(anchorInPixels.Y - bounds.Height),
+                        0,
+                        0,
+                        swpFlags);
+                    break;
+            }
+        };
+        ShowHwnd(hwndValue, positionWindowForAnchor);
+    }
+
+    private void ShowHwnd(IntPtr hwndValue, Action<HWND>? positionWindow)
     {
         StopAutoGoHome();
 
@@ -514,16 +593,9 @@ public sealed partial class MainWindow : WindowEx,
             PInvoke.ShowWindow(hwnd, SHOW_WINDOW_CMD.SW_RESTORE);
         }
 
-        if (target == MonitorBehavior.ToLast)
+        if (positionWindow is not null)
         {
-            var originalScreen = new SizeInt32(_currentWindowPosition.ScreenWidth, _currentWindowPosition.ScreenHeight);
-            var newRect = WindowPositionHelper.AdjustRectForVisibility(_currentWindowPosition.ToPhysicalWindowRectangle(), originalScreen, _currentWindowPosition.Dpi);
-            MoveAndResizeDpiAware(newRect);
-        }
-        else
-        {
-            var display = GetScreen(hwnd, target);
-            PositionCentered(display);
+            positionWindow(hwnd);
         }
 
         // Check if the debugger is attached. If it is, we don't want to apply the tool window style,
@@ -605,6 +677,11 @@ public sealed partial class MainWindow : WindowEx,
         ShowHwnd(message.Hwnd, settings.SummonOn);
     }
 
+    internal void Receive(ShowPaletteAtMessage message)
+    {
+        ShowHwnd(HWND.Null, message.PosPixels, message.Anchor);
+    }
+
     public void Receive(HideWindowMessage message)
     {
         // This might come in off the UI thread. Make sure to hop back.
@@ -715,6 +792,8 @@ public sealed partial class MainWindow : WindowEx,
             // Sure, it's not ideal, but at least it's not visible.
         }
 
+        WeakReferenceMessenger.Default.Send(new WindowHiddenMessage());
+
         // Start auto-go-home timer
         RestartAutoGoHome();
     }
@@ -1121,6 +1200,7 @@ public sealed partial class MainWindow : WindowEx,
                 // but that's the price to pay for having the HWND not light-dismiss while we're debugging.
                 Cloak();
                 this.Hide();
+                WeakReferenceMessenger.Default.Send(new WindowHiddenMessage());
 
                 return;
             }
@@ -1178,6 +1258,8 @@ public sealed partial class MainWindow : WindowEx,
         DisposeAcrylic();
     }
 
+    void IRecipient<ShowPaletteAtMessage>.Receive(ShowPaletteAtMessage message) => Receive(message);
+
     public void Receive(ToggleDevRibbonMessage message)
     {
         _devRibbon?.Visibility = _devRibbon.Visibility == Visibility.Visible ? Visibility.Collapsed : Visibility.Visible;

src/modules/cmdpal/Microsoft.CmdPal.UI/Microsoft.CmdPal.UI.csproj

@@ -19,6 +19,9 @@
 
     <Version>$(CmdPalVersion)</Version>
 
+    <!-- For MVVM Toolkit Partial Properties/AOT support -->
+    <LangVersion>preview</LangVersion>
+    
     <!-- OutputPath is set in CmdPal.Branding.props  -->
 
     <AppendTargetFrameworkToOutputPath>false</AppendTargetFrameworkToOutputPath>
@@ -27,10 +30,10 @@
   </PropertyGroup>
 
   <!-- For debugging purposes, uncomment this block to enable AOT builds -->
-  <!--<PropertyGroup>
+	<!-- <PropertyGroup>
     <EnableCmdPalAOT>true</EnableCmdPalAOT>
     <GeneratePackageLocally>true</GeneratePackageLocally>
-  </PropertyGroup>-->
+  </PropertyGroup> -->
 
   <PropertyGroup Condition="'$(EnableCmdPalAOT)' == 'true'">
     <SelfContained>true</SelfContained>
@@ -39,13 +42,13 @@
     <PublishAot>true</PublishAot>
   </PropertyGroup>
 
-  <PropertyGroup Condition="'$(CIBuild)' == 'true' or '$(GeneratePackageLocally)' == 'true'">
-    <GenerateAppxPackageOnBuild>true</GenerateAppxPackageOnBuild>
-    <AppxBundle>Never</AppxBundle>
-    <AppxPackageTestDir>$(OutputPath)\AppPackages\Microsoft.CmdPal.UI_$(Version)_Test\</AppxPackageTestDir>
-  </PropertyGroup>
+	<PropertyGroup Condition="'$(CIBuild)' == 'true' or '$(GeneratePackageLocally)' == 'true'">
+		<GenerateAppxPackageOnBuild>true</GenerateAppxPackageOnBuild>
+		<AppxBundle>Never</AppxBundle>
+		<AppxPackageTestDir>$(OutputPath)\AppPackages\Microsoft.CmdPal.UI_$(Version)_Test\</AppxPackageTestDir>
+	</PropertyGroup>
 
-  <PropertyGroup>
+	<PropertyGroup>
     <!-- This lets us actually reference types from Microsoft.Terminal.UI and CmdPalKeyboardService -->
     <CsWinRTIncludes>Microsoft.Terminal.UI;CmdPalKeyboardService</CsWinRTIncludes>
     <CsWinRTGeneratedFilesDir>$(OutDir)</CsWinRTGeneratedFilesDir>
@@ -73,6 +76,7 @@
     <None Remove="Controls\DevRibbon.xaml" />
     <None Remove="Controls\FallbackRankerDialog.xaml" />
     <None Remove="Controls\ScreenPreview.xaml" />
+    <None Remove="Controls\ScrollContainer.xaml" />
     <None Remove="Controls\SearchBar.xaml" />
     <None Remove="ListDetailPage.xaml" />
     <None Remove="LoadingPage.xaml" />
@@ -83,8 +87,8 @@
     <None Remove="Settings\AppearancePage.xaml" />
     <None Remove="Settings\InternalPage.xaml" />
     <None Remove="ShellPage.xaml" />
-    <None Remove="Styles\Colors.xaml" />
     <None Remove="Styles\Settings.xaml" />
+    <None Remove="Styles\TeachingTip.xaml" />
     <None Remove="Styles\TextBox.xaml" />
     <None Remove="Styles\Theme.Normal.xaml" />
   </ItemGroup>
@@ -214,6 +218,24 @@
     </Content>
   </ItemGroup>
 
+  <ItemGroup>
+    <Page Update="Styles\TeachingTip.xaml">
+      <Generator>MSBuild:Compile</Generator>
+    </Page>
+  </ItemGroup>
+
+  <ItemGroup>
+    <Page Update="Dock\DockItemControl.xaml">
+      <Generator>MSBuild:Compile</Generator>
+    </Page>
+  </ItemGroup>
+
+  <ItemGroup>
+    <Page Update="Controls\ScrollContainer.xaml">
+      <Generator>MSBuild:Compile</Generator>
+    </Page>
+  </ItemGroup>
+
   <ItemGroup>
     <Page Update="Controls\CommandPalettePreview.xaml">
       <Generator>MSBuild:Compile</Generator>

src/modules/cmdpal/Microsoft.CmdPal.UI/NativeMethods.txt

@@ -59,15 +59,56 @@ GetModuleHandle
 GetWindowLong
 SetWindowLong
 WINDOW_EX_STYLE
+
 CreateWindowEx
 WNDCLASSEXW
 RegisterClassEx
 GetStockObject
 GetModuleHandle
 
+MoveWindow
+GetSystemMetrics
+SHAppBarMessage
+ABM_NEW
+ABM_QUERYPOS
+ABM_SETPOS
+ABM_REMOVE
+ABM_SETAUTOHIDEBAR
+ABS_AUTOHIDE
+ABN_POSCHANGED
+APPBARDATA
+ABE_TOP
+ABE_BOTTOM
+ABE_LEFT
+ABE_RIGHT
+SYSTEM_METRICS_INDEX
+GetDpiForWindow
+SHQueryUserNotificationState
+SYSTEM_PARAMETERS_INFO_ACTION
+WINDOWPOS
+WM_DISPLAYCHANGE
+WM_SYSCOMMAND
+WM_SETTINGCHANGE
+WM_WINDOWPOSCHANGING
+WM_SHOWWINDOW
+WM_SIZE
+WM_GETMINMAXINFO
+SetWinEventHook
+WINDOW_STYLE
+SC_MINIMIZE
+SC_MAXIMIZE
+SET_WINDOW_POS_FLAGS
+SIZE_MAXIMIZED
+SIZE_MINIMIZED
+HWND_NOTOPMOST
+HWND_TOP
+HTCAPTION
+GetClassName
+EVENT_SYSTEM_FOREGROUND
+WINEVENT_OUTOFCONTEXT
 GetWindowThreadProcessId
 AttachThreadInput
 
 GetWindowPlacement
 WINDOWPLACEMENT
-WM_DPICHANGED
+WM_DPICHANGED

src/modules/cmdpal/Microsoft.CmdPal.UI/Pages/ShellPage.xaml

@@ -200,14 +200,19 @@
 
                 <!--  Back button  -->
                 <StackPanel Orientation="Horizontal">
+                    <!--
+                        This border is to hold a bit of padding we need when
+                        the back button is hidden
+                    -->
+                    <Border Margin="20,0,0,0" Visibility="{x:Bind ViewModel.CurrentPage.HasBackButton, Mode=OneWay, Converter={StaticResource BoolToInvertedVisibilityConverter}}" />
                     <Image
                         Width="20"
-                        Margin="20,0,6,0"
+                        Margin="0,0,6,0"
                         HorizontalAlignment="Center"
                         ui:VisualExtensions.NormalizedCenterPoint="0.5,0.5"
                         AutomationProperties.AccessibilityView="Raw"
                         Source="ms-appx:///Assets/icon.svg"
-                        Visibility="{x:Bind ViewModel.CurrentPage.IsNested, Mode=OneWay, Converter={StaticResource BoolToInvertedVisibilityConverter}}">
+                        Visibility="{x:Bind ViewModel.CurrentPage.IsRootPage, Mode=OneWay}">
                         <animations:Implicit.ShowAnimations>
                             <animations:OpacityAnimation
                                 EasingMode="EaseIn"
@@ -250,7 +255,7 @@
                                               FontSize=14}"
                         FontSize="16"
                         Style="{StaticResource SubtleButtonStyle}"
-                        Visibility="{x:Bind ViewModel.CurrentPage.IsNested, Mode=OneWay}">
+                        Visibility="{x:Bind ViewModel.CurrentPage.HasBackButton, Mode=OneWay}">
                         <animations:Implicit.ShowAnimations>
                             <animations:OpacityAnimation
                                 EasingMode="EaseIn"
@@ -297,7 +302,7 @@
                         Foreground="{ThemeResource TextFillColorSecondaryBrush}"
                         SourceKey="{x:Bind ViewModel.CurrentPage.Icon, Mode=OneWay}"
                         SourceRequested="{x:Bind help:IconCacheProvider.SourceRequested20}"
-                        Visibility="{x:Bind ViewModel.CurrentPage.IsNested, Mode=OneWay}">
+                        Visibility="{x:Bind ViewModel.CurrentPage.IsRootPage, Mode=OneWay, Converter={StaticResource BoolToInvertedVisibilityConverter}}">
                         <animations:Implicit.ShowAnimations>
                             <animations:OpacityAnimation
                                 From="0"

src/modules/cmdpal/Microsoft.CmdPal.UI/Pages/ShellPage.xaml.cs

@@ -8,6 +8,7 @@ using System.Text;
 using CommunityToolkit.Mvvm.Messaging;
 using CommunityToolkit.WinUI;
 using ManagedCommon;
+using Microsoft.CmdPal.UI.Dock;
 using Microsoft.CmdPal.UI.Events;
 using Microsoft.CmdPal.UI.Helpers;
 using Microsoft.CmdPal.UI.Messages;
@@ -25,6 +26,7 @@ using Microsoft.UI.Xaml.Controls;
 using Microsoft.UI.Xaml.Input;
 using Microsoft.UI.Xaml.Media.Animation;
 using Windows.UI.Core;
+using WinUIEx;
 using DispatcherQueue = Microsoft.UI.Dispatching.DispatcherQueue;
 using VirtualKey = Windows.System.VirtualKey;
 
@@ -47,6 +49,7 @@ public sealed partial class ShellPage : Microsoft.UI.Xaml.Controls.Page,
     IRecipient<ShowConfirmationMessage>,
     IRecipient<ShowToastMessage>,
     IRecipient<NavigateToPageMessage>,
+    IRecipient<ShowHideDockMessage>,
     INotifyPropertyChanged,
     IDisposable
 {
@@ -64,6 +67,7 @@ public sealed partial class ShellPage : Microsoft.UI.Xaml.Controls.Page,
     private readonly CompositeFormat _pageNavigatedAnnouncement;
 
     private SettingsWindow? _settingsWindow;
+    private DockWindow? _dockWindow;
 
     private CancellationTokenSource? _focusAfterLoadedCts;
     private WeakReference<Page>? _lastNavigatedPageRef;
@@ -96,6 +100,8 @@ public sealed partial class ShellPage : Microsoft.UI.Xaml.Controls.Page,
         WeakReferenceMessenger.Default.Register<ShowToastMessage>(this);
         WeakReferenceMessenger.Default.Register<NavigateToPageMessage>(this);
 
+        WeakReferenceMessenger.Default.Register<ShowHideDockMessage>(this);
+
         AddHandler(PreviewKeyDownEvent, new KeyEventHandler(ShellPage_OnPreviewKeyDown), true);
         AddHandler(KeyDownEvent, new KeyEventHandler(ShellPage_OnKeyDown), false);
         AddHandler(PointerPressedEvent, new PointerEventHandler(ShellPage_OnPointerPressed), true);
@@ -104,6 +110,12 @@ public sealed partial class ShellPage : Microsoft.UI.Xaml.Controls.Page,
 
         var pageAnnouncementFormat = ResourceLoaderInstance.GetString("ScreenReader_Announcement_NavigatedToPage0");
         _pageNavigatedAnnouncement = CompositeFormat.Parse(pageAnnouncementFormat);
+
+        if (App.Current.Services.GetService<SettingsModel>()!.EnableDock)
+        {
+            _dockWindow = new DockWindow();
+            _dockWindow.Show();
+        }
     }
 
     /// <summary>
@@ -145,7 +157,7 @@ public sealed partial class ShellPage : Microsoft.UI.Xaml.Controls.Page,
     public void Receive(NavigateToPageMessage message)
     {
         // TODO GH #526 This needs more better locking too
-        _ = _queue.TryEnqueue(() =>
+        _ = _queue.TryEnqueue(DispatcherQueuePriority.High, () =>
         {
             // Also hide our details pane about here, if we had one
             HideDetails();
@@ -250,10 +262,7 @@ public sealed partial class ShellPage : Microsoft.UI.Xaml.Controls.Page,
         }
     }
 
-    private void InitializeConfirmationDialog(ConfirmResultViewModel vm)
-    {
-        vm.SafeInitializePropertiesSynchronous();
-    }
+    private void InitializeConfirmationDialog(ConfirmResultViewModel vm) => vm.SafeInitializePropertiesSynchronous();
 
     public void Receive(OpenSettingsMessage message)
     {
@@ -346,10 +355,7 @@ public sealed partial class ShellPage : Microsoft.UI.Xaml.Controls.Page,
 
     public void Receive(ClearSearchMessage message) => SearchBox.ClearSearch();
 
-    public void Receive(HotkeySummonMessage message)
-    {
-        _ = DispatcherQueue.TryEnqueue(() => SummonOnUiThread(message));
-    }
+    public void Receive(HotkeySummonMessage message) => _ = DispatcherQueue.TryEnqueue(() => SummonOnUiThread(message));
 
     public void Receive(SettingsWindowClosedMessage message) => _settingsWindow = null;
 
@@ -418,10 +424,7 @@ public sealed partial class ShellPage : Microsoft.UI.Xaml.Controls.Page,
         WeakReferenceMessenger.Default.Send<FocusSearchBoxMessage>();
     }
 
-    public void Receive(GoBackMessage message)
-    {
-        _ = DispatcherQueue.TryEnqueue(() => GoBack(message.WithAnimation, message.FocusSearch));
-    }
+    public void Receive(GoBackMessage message) => _ = DispatcherQueue.TryEnqueue(() => GoBack(message.WithAnimation, message.FocusSearch));
 
     private void GoBack(bool withAnimation = true, bool focusSearch = true)
     {
@@ -462,10 +465,7 @@ public sealed partial class ShellPage : Microsoft.UI.Xaml.Controls.Page,
         }
     }
 
-    public void Receive(GoHomeMessage message)
-    {
-        _ = DispatcherQueue.TryEnqueue(() => GoHome(withAnimation: message.WithAnimation, focusSearch: message.FocusSearch));
-    }
+    public void Receive(GoHomeMessage message) => _ = DispatcherQueue.TryEnqueue(() => GoHome(withAnimation: message.WithAnimation, focusSearch: message.FocusSearch));
 
     private void GoHome(bool withAnimation = true, bool focusSearch = true)
     {
@@ -483,6 +483,27 @@ public sealed partial class ShellPage : Microsoft.UI.Xaml.Controls.Page,
         }
     }
 
+    public void Receive(ShowHideDockMessage message)
+    {
+        _ = DispatcherQueue.TryEnqueue(() =>
+        {
+            if (message.ShowDock)
+            {
+                if (_dockWindow is null)
+                {
+                    _dockWindow = new DockWindow();
+                }
+
+                _dockWindow.Show();
+            }
+            else if (_dockWindow is not null)
+            {
+                _dockWindow.Close();
+                _dockWindow = null;
+            }
+        });
+    }
+
     private void BackButton_Clicked(object sender, Microsoft.UI.Xaml.RoutedEventArgs e) => WeakReferenceMessenger.Default.Send<NavigateBackMessage>(new());
 
     private void RootFrame_Navigated(object sender, Microsoft.UI.Xaml.Navigation.NavigationEventArgs e)
@@ -754,5 +775,7 @@ public sealed partial class ShellPage : Microsoft.UI.Xaml.Controls.Page,
         _focusAfterLoadedCts?.Cancel();
         _focusAfterLoadedCts?.Dispose();
         _focusAfterLoadedCts = null;
+
+        _dockWindow?.Dispose();
     }
 }

src/modules/cmdpal/Microsoft.CmdPal.UI/Services/ThemeService.cs

@@ -1,4 +1,4 @@
-// Copyright (c) Microsoft Corporation
+// 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.
 
@@ -7,6 +7,7 @@ using ManagedCommon;
 using Microsoft.CmdPal.UI.Helpers;
 using Microsoft.CmdPal.UI.ViewModels;
 using Microsoft.CmdPal.UI.ViewModels.Services;
+using Microsoft.CmdPal.UI.ViewModels.Settings;
 using Microsoft.UI;
 using Microsoft.UI.Dispatching;
 using Microsoft.UI.Xaml;
@@ -36,11 +37,14 @@ internal sealed partial class ThemeService : IThemeService, IDisposable
     private bool _isInitialized;
     private bool _disposed;
     private InternalThemeState _currentState;
+    private DockThemeSnapshot _currentDockState;
 
     public event EventHandler<ThemeChangedEventArgs>? ThemeChanged;
 
     public ThemeSnapshot Current => Volatile.Read(ref _currentState).Snapshot;
 
+    public DockThemeSnapshot CurrentDockTheme => Volatile.Read(ref _currentDockState);
+
     /// <summary>
     /// Initializes the theme service. Must be called after the application window is activated and on UI thread.
     /// </summary>
@@ -144,6 +148,60 @@ internal sealed partial class ThemeService : IThemeService, IDisposable
         // Atomic swap
         Interlocked.Exchange(ref _currentState, newState);
 
+        // Compute DockThemeSnapshot from DockSettings
+        var dockSettings = _settings.DockSettings;
+        var dockIntensity = Math.Clamp(dockSettings.CustomThemeColorIntensity, 0, 100);
+        IThemeProvider dockProvider = dockIntensity > 0 && dockSettings.ColorizationMode is ColorizationMode.CustomColor or ColorizationMode.WindowsAccentColor or ColorizationMode.Image
+                ? _colorfulThemeProvider
+                : _normalThemeProvider;
+
+        var dockTint = dockSettings.ColorizationMode switch
+        {
+            ColorizationMode.CustomColor => dockSettings.CustomThemeColor,
+            ColorizationMode.WindowsAccentColor => _uiSettings.GetColorValue(UIColorType.Accent),
+            ColorizationMode.Image => dockSettings.CustomThemeColor,
+            _ => Colors.Transparent,
+        };
+        var dockEffectiveTheme = GetElementTheme((ElementTheme)dockSettings.Theme);
+        var dockImageSource = dockSettings.ColorizationMode == ColorizationMode.Image
+            ? LoadImageSafe(dockSettings.BackgroundImagePath)
+            : null;
+        var dockStretch = dockSettings.BackgroundImageFit switch
+        {
+            BackgroundImageFit.Fill => Stretch.Fill,
+            _ => Stretch.UniformToFill,
+        };
+        var dockOpacity = Math.Clamp(dockSettings.BackgroundImageOpacity, 0, 100) / 100.0;
+
+        var dockContext = new ThemeContext
+        {
+            Tint = dockTint,
+            ColorIntensity = dockIntensity,
+            Theme = dockEffectiveTheme,
+            BackgroundImageSource = dockImageSource,
+            BackgroundImageStretch = dockStretch,
+            BackgroundImageOpacity = dockOpacity,
+        };
+        var dockBackdrop = dockProvider.GetBackdropParameters(dockContext);
+        var dockBlur = dockSettings.BackgroundImageBlurAmount;
+        var dockBrightness = dockSettings.BackgroundImageBrightness;
+
+        var dockSnapshot = new DockThemeSnapshot
+        {
+            Tint = dockTint,
+            TintIntensity = dockIntensity / 100f,
+            Theme = dockEffectiveTheme,
+            Backdrop = dockSettings.Backdrop,
+            BackgroundImageSource = dockImageSource,
+            BackgroundImageStretch = dockStretch,
+            BackgroundImageOpacity = dockOpacity,
+            BackdropParameters = dockBackdrop,
+            BlurAmount = dockBlur,
+            BackgroundBrightness = dockBrightness / 100f,
+        };
+
+        Interlocked.Exchange(ref _currentDockState, dockSnapshot);
+
         _resourceSwapper.TryActivateTheme(provider.ThemeKey);
         ThemeChanged?.Invoke(this, new ThemeChangedEventArgs());
     }
@@ -223,6 +281,20 @@ internal sealed partial class ThemeService : IThemeService, IDisposable
             },
             Provider = _normalThemeProvider,
         };
+
+        _currentDockState = new DockThemeSnapshot
+        {
+            Tint = Colors.Transparent,
+            TintIntensity = 1.0f,
+            Theme = ElementTheme.Light,
+            Backdrop = DockBackdrop.Acrylic,
+            BackdropParameters = new BackdropParameters(Colors.Black, Colors.Black, 0.5f, 0.5f),
+            BackgroundImageOpacity = 1,
+            BackgroundImageSource = null,
+            BackgroundImageStretch = Stretch.Fill,
+            BlurAmount = 0,
+            BackgroundBrightness = 0,
+        };
     }
 
     private void RequestReload()

src/modules/cmdpal/Microsoft.CmdPal.UI/Settings/DockSettingsPage.xaml

@@ -0,0 +1,254 @@
+<?xml version="1.0" encoding="utf-8" ?>
+<Page
+    x:Class="Microsoft.CmdPal.UI.Settings.DockSettingsPage"
+    xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
+    xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
+    xmlns:controls="using:CommunityToolkit.WinUI.Controls"
+    xmlns:converters="using:CommunityToolkit.WinUI.Converters"
+    xmlns:cpControls="using:Microsoft.CmdPal.UI.Controls"
+    xmlns:d="http://schemas.microsoft.com/expression/blend/2008"
+    xmlns:dockVm="using:Microsoft.CmdPal.UI.ViewModels.Dock"
+    xmlns:helpers="using:Microsoft.CmdPal.UI.Helpers"
+    xmlns:local="using:Microsoft.CmdPal.UI.Settings"
+    xmlns:mc="http://schemas.openxmlformats.org/markup-compatibility/2006"
+    xmlns:ptcontrols="using:Microsoft.PowerToys.Common.UI.Controls"
+    xmlns:ui="using:CommunityToolkit.WinUI"
+    xmlns:viewModels="using:Microsoft.CmdPal.UI.ViewModels"
+    mc:Ignorable="d">
+    <Grid>
+        <Grid.RowDefinitions>
+            <RowDefinition Height="Auto" />
+            <RowDefinition Height="*" />
+        </Grid.RowDefinitions>
+        <ScrollViewer Grid.Row="1">
+            <Grid Padding="16">
+                <StackPanel
+                    MaxWidth="1000"
+                    HorizontalAlignment="Stretch"
+                    Spacing="{StaticResource SettingsCardSpacing}">
+
+                    <!--
+                        I got these from the samples, but they break XAML hot-reloading,
+                        so I commented them out.
+                    -->
+
+                    <!--<StackPanel.ChildrenTransitions>
+                  <EntranceThemeTransition FromVerticalOffset="50" />
+                  <RepositionThemeTransition IsStaggeringEnabled="False" />
+              </StackPanel.ChildrenTransitions>-->
+
+                    <!--  Enable Dock  -->
+                    <controls:SettingsCard x:Uid="Settings_GeneralPage_EnableDock_SettingsCard" HeaderIcon="{ui:FontIcon Glyph=&#xF596;}">
+                        <ToggleSwitch IsOn="{x:Bind ViewModel.EnableDock, Mode=TwoWay}" />
+                    </controls:SettingsCard>
+
+                    <!--  Appearance Section  -->
+                    <TextBlock x:Uid="DockAppearanceSettingsHeader" Style="{StaticResource SettingsSectionHeaderTextBlockStyle}" />
+
+                    <!--  Dock Position  -->
+                    <controls:SettingsExpander x:Uid="DockAppearance_DockPosition_SettingsExpander" IsExpanded="True">
+                        <controls:SettingsExpander.HeaderIcon>
+                            <SymbolIcon Symbol="MoveToFolder" />
+                        </controls:SettingsExpander.HeaderIcon>
+                        <ComboBox
+                            x:Name="DockPositionComboBox"
+                            MinWidth="120"
+                            SelectedIndex="{x:Bind SelectedSideIndex, Mode=TwoWay}">
+                            <ComboBoxItem x:Uid="DockAppearance_DockPosition_Left" />
+                            <ComboBoxItem x:Uid="DockAppearance_DockPosition_Top" />
+                            <ComboBoxItem x:Uid="DockAppearance_DockPosition_Right" />
+                            <ComboBoxItem x:Uid="DockAppearance_DockPosition_Bottom" />
+                        </ComboBox>
+                        <controls:SettingsExpander.Items>
+
+                            <!--  Show Labels  -->
+                            <controls:SettingsCard ContentAlignment="Left">
+                                <ptcontrols:CheckBoxWithDescriptionControl x:Uid="DockAppearance_ShowLabels_CheckBox" IsChecked="{x:Bind ShowLabels, Mode=TwoWay}" />
+                            </controls:SettingsCard>
+                        </controls:SettingsExpander.Items>
+                    </controls:SettingsExpander>
+
+                    <!--  Theme Section  -->
+                    <TextBlock x:Uid="DockAppearance_ThemeSettingsHeader" Style="{StaticResource SettingsSectionHeaderTextBlockStyle}" />
+
+                    <controls:SettingsCard x:Uid="DockAppearance_AppTheme_SettingsCard" HeaderIcon="{ui:FontIcon Glyph=&#xE793;}">
+                        <ComboBox MinWidth="{StaticResource SettingActionControlMinWidth}" SelectedIndex="{x:Bind ViewModel.DockAppearance.ThemeIndex, Mode=TwoWay}">
+
+                            <ComboBoxItem x:Uid="Settings_GeneralPage_AppTheme_Mode_System_Automation" Tag="Default">
+                                <StackPanel Orientation="Horizontal" Spacing="8">
+                                    <FontIcon FontSize="16" Glyph="&#xE770;" />
+                                    <TextBlock x:Uid="Settings_GeneralPage_AppTheme_Mode_System" />
+                                </StackPanel>
+                            </ComboBoxItem>
+
+                            <ComboBoxItem x:Uid="Settings_GeneralPage_AppTheme_Mode_Light_Automation" Tag="Light">
+                                <StackPanel Orientation="Horizontal" Spacing="8">
+                                    <FontIcon FontSize="16" Glyph="&#xE706;" />
+                                    <TextBlock x:Uid="Settings_GeneralPage_AppTheme_Mode_Light" />
+                                </StackPanel>
+                            </ComboBoxItem>
+
+                            <ComboBoxItem x:Uid="Settings_GeneralPage_AppTheme_Mode_Dark_Automation" Tag="Dark">
+                                <StackPanel Orientation="Horizontal" Spacing="8">
+                                    <FontIcon FontSize="16" Glyph="&#xE708;" />
+                                    <TextBlock x:Uid="Settings_GeneralPage_AppTheme_Mode_Dark" />
+                                </StackPanel>
+                            </ComboBoxItem>
+
+                        </ComboBox>
+                    </controls:SettingsCard>
+
+                    <!--  Backdrop Style  -->
+                    <controls:SettingsCard x:Uid="DockAppearance_Backdrop_SettingsCard" HeaderIcon="{ui:FontIcon Glyph=&#xF5EF;}">
+                        <ComboBox
+                            x:Name="BackdropComboBox"
+                            MinWidth="{StaticResource SettingActionControlMinWidth}"
+                            SelectedIndex="{x:Bind ViewModel.DockAppearance.BackdropIndex, Mode=TwoWay}">
+                            <ComboBoxItem x:Uid="DockAppearance_Backdrop_Transparent" />
+                            <ComboBoxItem x:Uid="DockAppearance_Backdrop_Acrylic" />
+                        </ComboBox>
+                    </controls:SettingsCard>
+
+                    <!--  Background / Colorization Section  -->
+                    <controls:SettingsExpander
+                        x:Uid="DockAppearance_Background_SettingsExpander"
+                        HeaderIcon="{ui:FontIcon Glyph=&#xE790;}"
+                        IsExpanded="{x:Bind ViewModel.DockAppearance.IsColorizationDetailsExpanded, Mode=TwoWay}">
+                        <ComboBox MinWidth="{StaticResource SettingActionControlMinWidth}" SelectedIndex="{x:Bind ViewModel.DockAppearance.ColorizationModeIndex, Mode=TwoWay}">
+                            <ComboBoxItem x:Uid="Settings_GeneralPage_ColorizationMode_None" />
+                            <ComboBoxItem x:Uid="Settings_GeneralPage_ColorizationMode_WindowsAccent" />
+                            <ComboBoxItem x:Uid="Settings_GeneralPage_ColorizationMode_CustomColor" />
+                            <ComboBoxItem x:Uid="Settings_GeneralPage_ColorizationMode_Image" />
+                        </ComboBox>
+                        <controls:SettingsExpander.Items>
+                            <!--  none  -->
+                            <controls:SettingsCard
+                                x:Uid="DockAppearance_NoBackground_SettingsCard"
+                                HorizontalContentAlignment="Stretch"
+                                ContentAlignment="Vertical"
+                                Visibility="{x:Bind ViewModel.DockAppearance.IsNoBackgroundVisible, Mode=OneWay}">
+                                <TextBlock
+                                    x:Uid="DockAppearance_NoBackground_DescriptionTextBlock"
+                                    Margin="24"
+                                    HorizontalAlignment="Stretch"
+                                    Foreground="{ThemeResource TextFillColorSecondaryBrush}"
+                                    HorizontalTextAlignment="Center"
+                                    TextAlignment="Center"
+                                    TextWrapping="WrapWholeWords" />
+                            </controls:SettingsCard>
+
+                            <!--  system accent color  -->
+                            <controls:SettingsCard x:Uid="DockAppearance_WindowsAccentColor_SettingsCard" Visibility="{x:Bind ViewModel.DockAppearance.IsAccentColorControlsVisible, Mode=OneWay}">
+                                <controls:SettingsCard.Description>
+                                    <TextBlock>
+                                        <Run x:Uid="Settings_GeneralPage_WindowsAccentColor_SettingsCard_Description1" />
+                                        <Hyperlink
+                                            Click="OpenWindowsColorsSettings_Click"
+                                            TextDecorations="None"
+                                            UnderlineStyle="None">
+                                            <Run x:Uid="Settings_GeneralPage_WindowsAccentColor_OpenWindowsColorsLinkText" />
+                                        </Hyperlink>
+                                    </TextBlock>
+                                </controls:SettingsCard.Description>
+                                <controls:SettingsCard.Content>
+                                    <Border
+                                        MinWidth="32"
+                                        MinHeight="32"
+                                        CornerRadius="{ThemeResource ControlCornerRadius}">
+                                        <Border.Background>
+                                            <SolidColorBrush Color="{x:Bind ViewModel.DockAppearance.EffectiveThemeColor, Mode=OneWay}" />
+                                        </Border.Background>
+                                    </Border>
+                                </controls:SettingsCard.Content>
+                            </controls:SettingsCard>
+
+                            <!--  background image  -->
+                            <controls:SettingsCard
+                                x:Uid="DockAppearance_BackgroundImage_SettingsCard"
+                                Description="{x:Bind ViewModel.DockAppearance.BackgroundImagePath, Mode=OneWay}"
+                                Visibility="{x:Bind ViewModel.DockAppearance.IsBackgroundControlsVisible, Mode=OneWay}">
+                                <Button x:Uid="Settings_GeneralPage_BackgroundImage_ChooseImageButton" Click="PickBackgroundImage_Click" />
+                            </controls:SettingsCard>
+                            <controls:SettingsCard x:Uid="DockAppearance_BackgroundImageBrightness_SettingsCard" Visibility="{x:Bind ViewModel.DockAppearance.IsBackgroundControlsVisible, Mode=OneWay}">
+                                <Slider
+                                    MinWidth="{StaticResource SettingActionControlMinWidth}"
+                                    Maximum="100"
+                                    Minimum="-100"
+                                    StepFrequency="1"
+                                    Value="{x:Bind ViewModel.DockAppearance.BackgroundImageBrightness, Mode=TwoWay}" />
+                            </controls:SettingsCard>
+                            <controls:SettingsCard x:Uid="DockAppearance_BackgroundImageBlur_SettingsCard" Visibility="{x:Bind ViewModel.DockAppearance.IsBackgroundControlsVisible, Mode=OneWay}">
+                                <Slider
+                                    MinWidth="{StaticResource SettingActionControlMinWidth}"
+                                    Maximum="50"
+                                    Minimum="0"
+                                    StepFrequency="1"
+                                    Value="{x:Bind ViewModel.DockAppearance.BackgroundImageBlurAmount, Mode=TwoWay}" />
+                            </controls:SettingsCard>
+                            <controls:SettingsCard x:Uid="DockAppearance_BackgroundImageFit_SettingsCard" Visibility="{x:Bind ViewModel.DockAppearance.IsBackgroundControlsVisible, Mode=OneWay}">
+                                <ComboBox SelectedIndex="{x:Bind ViewModel.DockAppearance.BackgroundImageFitIndex, Mode=TwoWay}">
+                                    <ComboBoxItem x:Uid="BackgroundImageFit_ComboBoxItem_Fill" />
+                                    <ComboBoxItem x:Uid="BackgroundImageFit_ComboBoxItem_Stretch" />
+                                </ComboBox>
+                            </controls:SettingsCard>
+
+                            <!--  Background tint color and intensity  -->
+                            <controls:SettingsCard x:Uid="DockAppearance_BackgroundTint_SettingsCard" Visibility="{x:Bind ViewModel.DockAppearance.IsCustomTintVisible, Mode=OneWay}">
+                                <cpControls:ColorPickerButton
+                                    HasSelectedColor="True"
+                                    IsAlphaEnabled="False"
+                                    PaletteColors="{x:Bind ViewModel.DockAppearance.Swatches}"
+                                    SelectedColor="{x:Bind ViewModel.DockAppearance.ThemeColor, Mode=TwoWay}" />
+                            </controls:SettingsCard>
+                            <controls:SettingsCard x:Uid="DockAppearance_BackgroundTintIntensity_SettingsCard" Visibility="{x:Bind ViewModel.DockAppearance.IsCustomTintIntensityVisible, Mode=OneWay}">
+                                <Slider
+                                    MinWidth="{StaticResource SettingActionControlMinWidth}"
+                                    Maximum="100"
+                                    Minimum="1"
+                                    StepFrequency="1"
+                                    Value="{x:Bind ViewModel.DockAppearance.ColorIntensity, Mode=TwoWay}" />
+                            </controls:SettingsCard>
+
+                            <!--  Reset background image properties  -->
+                            <controls:SettingsCard x:Uid="DockAppearance_BackgroundImage_ResetProperties_SettingsCard" Visibility="{x:Bind ViewModel.DockAppearance.IsBackgroundControlsVisible, Mode=OneWay}">
+                                <Button x:Uid="Settings_GeneralPage_Background_ResetImagePropertiesButton" Command="{x:Bind ViewModel.DockAppearance.ResetBackgroundImagePropertiesCommand}" />
+                            </controls:SettingsCard>
+
+                        </controls:SettingsExpander.Items>
+                    </controls:SettingsExpander>
+
+                    <!--  Bands Section  -->
+                    <TextBlock x:Uid="DockBandsSettingsHeader" Style="{StaticResource SettingsSectionHeaderTextBlockStyle}" />
+
+                    <ItemsRepeater ItemsSource="{x:Bind AllDockBandItems}">
+                        <ItemsRepeater.Layout>
+                            <StackLayout Spacing="{StaticResource SettingsCardSpacing}" />
+                        </ItemsRepeater.Layout>
+                        <ItemsRepeater.ItemTemplate>
+                            <DataTemplate x:DataType="dockVm:DockBandSettingsViewModel">
+                                <controls:SettingsCard
+                                    Description="{x:Bind Description, Mode=OneWay}"
+                                    Header="{x:Bind Title, Mode=OneWay}"
+                                    IsClickEnabled="False">
+                                    <controls:SettingsCard.HeaderIcon>
+                                        <cpControls:ContentIcon>
+                                            <cpControls:ContentIcon.Content>
+                                                <cpControls:IconBox
+                                                    Width="20"
+                                                    Height="20"
+                                                    AutomationProperties.AccessibilityView="Raw"
+                                                    SourceKey="{x:Bind Icon, Mode=OneWay}"
+                                                    SourceRequested="{x:Bind helpers:IconCacheProvider.SourceRequested20}" />
+                                            </cpControls:ContentIcon.Content>
+                                        </cpControls:ContentIcon>
+                                    </controls:SettingsCard.HeaderIcon>
+                                    <ToggleSwitch IsOn="{x:Bind IsPinned, Mode=TwoWay}" />
+                                </controls:SettingsCard>
+                            </DataTemplate>
+                        </ItemsRepeater.ItemTemplate>
+                    </ItemsRepeater>
+                </StackPanel>
+            </Grid>
+        </ScrollViewer>
+    </Grid>
+</Page>

src/modules/cmdpal/Microsoft.CmdPal.UI/Settings/DockSettingsPage.xaml.cs

@@ -0,0 +1,218 @@
+// 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;
+using ManagedCommon;
+using Microsoft.CmdPal.UI.ViewModels;
+using Microsoft.CmdPal.UI.ViewModels.Dock;
+using Microsoft.CmdPal.UI.ViewModels.Services;
+using Microsoft.CmdPal.UI.ViewModels.Settings;
+using Microsoft.Extensions.DependencyInjection;
+using Microsoft.UI.Xaml;
+using Microsoft.UI.Xaml.Controls;
+using Microsoft.UI.Xaml.Documents;
+using Microsoft.Windows.Storage.Pickers;
+
+namespace Microsoft.CmdPal.UI.Settings;
+
+public sealed partial class DockSettingsPage : Page
+{
+    private readonly TaskScheduler _mainTaskScheduler = TaskScheduler.FromCurrentSynchronizationContext();
+
+    internal SettingsViewModel ViewModel { get; }
+
+    public List<DockBandSettingsViewModel> AllDockBandItems => GetAllBandSettings();
+
+    public DockSettingsPage()
+    {
+        this.InitializeComponent();
+
+        var settings = App.Current.Services.GetService<SettingsModel>()!;
+        var themeService = App.Current.Services.GetService<IThemeService>()!;
+        var topLevelCommandManager = App.Current.Services.GetService<TopLevelCommandManager>()!;
+
+        ViewModel = new SettingsViewModel(settings, topLevelCommandManager, _mainTaskScheduler, themeService);
+
+        // Initialize UI state
+        InitializeSettings();
+    }
+
+    private void InitializeSettings()
+    {
+        // Initialize UI controls to match current settings
+        DockPositionComboBox.SelectedIndex = SelectedSideIndex;
+        BackdropComboBox.SelectedIndex = SelectedBackdropIndex;
+    }
+
+    private async void PickBackgroundImage_Click(object sender, RoutedEventArgs e)
+    {
+        try
+        {
+            if (XamlRoot?.ContentIslandEnvironment is null)
+            {
+                return;
+            }
+
+            var windowId = XamlRoot?.ContentIslandEnvironment?.AppWindowId ?? new Microsoft.UI.WindowId(0);
+
+            var picker = new FileOpenPicker(windowId)
+            {
+                CommitButtonText = ViewModels.Properties.Resources.builtin_settings_appearance_pick_background_image_title!,
+                SuggestedStartLocation = PickerLocationId.PicturesLibrary,
+                ViewMode = PickerViewMode.Thumbnail,
+            };
+
+            string[] extensions = [".png", ".bmp", ".jpg", ".jpeg", ".jfif", ".gif", ".tiff", ".tif", ".webp", ".jxr"];
+            foreach (var ext in extensions)
+            {
+                picker.FileTypeFilter!.Add(ext);
+            }
+
+            var file = await picker.PickSingleFileAsync()!;
+            if (file != null)
+            {
+                ViewModel.DockAppearance.BackgroundImagePath = file.Path ?? string.Empty;
+            }
+        }
+        catch (Exception ex)
+        {
+            Logger.LogError("Failed to pick background image file for dock", ex);
+        }
+    }
+
+    private void OpenWindowsColorsSettings_Click(Hyperlink sender, HyperlinkClickEventArgs args)
+    {
+        // LOAD BEARING (or BEAR LOADING?): Process.Start with UseShellExecute inside a XAML input event can trigger WinUI reentrancy
+        // and cause FailFast crashes. Task.Run moves the call off the UI thread to prevent hard process termination.
+        Task.Run(() =>
+        {
+            try
+            {
+                _ = Process.Start(new ProcessStartInfo("ms-settings:colors") { UseShellExecute = true });
+            }
+            catch (Exception ex)
+            {
+                Logger.LogError("Failed to open Windows Settings", ex);
+            }
+        });
+    }
+
+    // Property bindings for ComboBoxes
+    public int SelectedDockSizeIndex
+    {
+        get => DockSizeToSelectedIndex(ViewModel.Dock_DockSize);
+        set => ViewModel.Dock_DockSize = SelectedIndexToDockSize(value);
+    }
+
+    public int SelectedSideIndex
+    {
+        get => SideToSelectedIndex(ViewModel.Dock_Side);
+        set => ViewModel.Dock_Side = SelectedIndexToSide(value);
+    }
+
+    public int SelectedBackdropIndex
+    {
+        get => BackdropToSelectedIndex(ViewModel.Dock_Backdrop);
+        set => ViewModel.Dock_Backdrop = SelectedIndexToBackdrop(value);
+    }
+
+    public bool ShowLabels
+    {
+        get => ViewModel.Dock_ShowLabels;
+        set => ViewModel.Dock_ShowLabels = value;
+    }
+
+    // Conversion methods for ComboBox bindings
+    private static int DockSizeToSelectedIndex(DockSize size) => size switch
+    {
+        DockSize.Small => 0,
+        DockSize.Medium => 1,
+        DockSize.Large => 2,
+        _ => 0,
+    };
+
+    private static DockSize SelectedIndexToDockSize(int index) => index switch
+    {
+        0 => DockSize.Small,
+        1 => DockSize.Medium,
+        2 => DockSize.Large,
+        _ => DockSize.Small,
+    };
+
+    private static int SideToSelectedIndex(DockSide side) => side switch
+    {
+        DockSide.Left => 0,
+        DockSide.Top => 1,
+        DockSide.Right => 2,
+        DockSide.Bottom => 3,
+        _ => 1,
+    };
+
+    private static DockSide SelectedIndexToSide(int index) => index switch
+    {
+        0 => DockSide.Left,
+        1 => DockSide.Top,
+        2 => DockSide.Right,
+        3 => DockSide.Bottom,
+        _ => DockSide.Top,
+    };
+
+    private static int BackdropToSelectedIndex(DockBackdrop backdrop) => backdrop switch
+    {
+        DockBackdrop.Transparent => 0,
+        DockBackdrop.Acrylic => 1,
+        _ => 1,
+    };
+
+    private static DockBackdrop SelectedIndexToBackdrop(int index) => index switch
+    {
+        0 => DockBackdrop.Transparent,
+        1 => DockBackdrop.Acrylic,
+        _ => DockBackdrop.Acrylic,
+    };
+
+    private List<TopLevelViewModel> GetAllBands()
+    {
+        var allBands = new List<TopLevelViewModel>();
+
+        var tlcManager = App.Current.Services.GetService<TopLevelCommandManager>()!;
+
+        foreach (var item in tlcManager.DockBands)
+        {
+            if (item.IsDockBand)
+            {
+                allBands.Add(item);
+            }
+        }
+
+        return allBands;
+    }
+
+    private List<DockBandSettingsViewModel> GetAllBandSettings()
+    {
+        var allSettings = new List<DockBandSettingsViewModel>();
+
+        // var allBands = GetAllBands();
+        var tlcManager = App.Current.Services.GetService<TopLevelCommandManager>()!;
+        var settingsModel = App.Current.Services.GetService<SettingsModel>()!;
+        var dockViewModel = App.Current.Services.GetService<DockViewModel>()!;
+        var allBands = tlcManager.DockBands;
+        foreach (var band in allBands)
+        {
+            var setting = band.DockBandSettings;
+            if (setting is not null)
+            {
+                var bandVm = dockViewModel.FindBandByTopLevel(band);
+                allSettings.Add(new(
+                    dockSettingsModel: setting,
+                    topLevelAdapter: band,
+                    bandViewModel: bandVm,
+                    settingsModel: settingsModel
+                ));
+            }
+        }
+
+        return allSettings;
+    }
+}