Release v0.6.45: fix Far snippets and ship portable Utilities folder

CMakeLists.txt

@@ -1,5 +1,5 @@
 cmake_minimum_required(VERSION 3.24)
-project(KSwitcher VERSION 0.6.39 LANGUAGES CXX RC)
+project(KSwitcher VERSION 0.6.45 LANGUAGES CXX RC)
 if(NOT WIN32)
   message(FATAL_ERROR "KSwitcher uses native Windows APIs")
 endif()
@@ -30,6 +30,15 @@ target_link_libraries(KSwitcherScrollTests PRIVATE kscore)
 target_link_libraries(KSwitcherTests PRIVATE kscore)
 add_executable(KSwitcherIntegration tests/integration.cpp src/screenshot_launcher.cpp src/screenshot_activation.cpp src/app.cpp src/screenshot_notifications.cpp src/screenshot.cpp src/configuration.cpp src/ui.cpp resources/app.rc)
 target_link_libraries(KSwitcherIntegration PRIVATE kscore)
+# Opt-in interactive fixture: requires an installed Far Manager.
+add_executable(KSwitcherFarSnippetTests WIN32 tests/far_snippets.cpp src/screenshot_launcher.cpp src/screenshot_activation.cpp src/app.cpp src/screenshot_notifications.cpp src/screenshot.cpp src/configuration.cpp src/ui.cpp resources/app.rc)
+target_link_libraries(KSwitcherFarSnippetTests PRIVATE kscore)
+if(MSVC)
+  target_compile_options(KSwitcherFarSnippetTests PRIVATE /utf-8)
+  set_property(TARGET KSwitcherFarSnippetTests PROPERTY MSVC_RUNTIME_LIBRARY "MultiThreaded$<$<CONFIG:Debug>:Debug>")
+else()
+  target_link_options(KSwitcherFarSnippetTests PRIVATE -municode -static -static-libgcc -static-libstdc++)
+endif()
 add_executable(KSwitcherInputTests tests/input.cpp src/screenshot_launcher.cpp src/screenshot_activation.cpp src/app.cpp src/screenshot_notifications.cpp src/screenshot.cpp src/configuration.cpp src/ui.cpp resources/app.rc)
 target_link_libraries(KSwitcherInputTests PRIVATE kscore)
 target_compile_definitions(KSwitcherInputTests PRIVATE KS_SCREENSHOT_RESOURCES)
@@ -111,6 +120,13 @@ add_test(NAME dictionary-regressions COMMAND KSwitcherDictionaryTests)
 set_tests_properties(dictionary-regressions PROPERTIES WORKING_DIRECTORY "${CMAKE_CURRENT_SOURCE_DIR}")
 add_test(NAME sync-regressions COMMAND KSwitcherSyncTests)
 add_test(NAME native-regressions COMMAND KSwitcherTests)
+add_executable(KSwitcherUtilitiesTests tests/utilities.cpp)
+if(MSVC)
+  set_property(TARGET KSwitcherUtilitiesTests PROPERTY MSVC_RUNTIME_LIBRARY "MultiThreaded$<$<CONFIG:Debug>:Debug>")
+else()
+  target_link_options(KSwitcherUtilitiesTests PRIVATE -static -static-libgcc -static-libstdc++)
+endif()
+add_test(NAME utilities-regressions COMMAND KSwitcherUtilitiesTests)
 add_test(NAME scroll-regressions COMMAND KSwitcherScrollTests)
 add_test(NAME input-regressions COMMAND KSwitcherInputTests)
 add_test(NAME screenshot-ui-regressions COMMAND KSwitcherScreenshotUITests)

README.md

@@ -75,6 +75,9 @@ Ctrl+Alt+Delete and Win+L; these cannot be assigned.
 
 Keyboard and mouse input forwarded by Microsoft Mouse Without Borders follows the same input
 path as a local keyboard/mouse, including shortcuts, recent-word conversion and snippets.
+On the sending computer, KSwitcher ignores keyboard events consumed by another keyboard hook
+(including Mouse Without Borders forwarding). The receiving computer still processes delivered
+input normally, so both computers can run KSwitcher without starting duplicate snippet operations.
 KSwitcher marks its own generated input so copy/paste, selection, modifier releases and shell-mask
 keys cannot trigger recursive commands or overwrite the recorded typing run. Other injected input
 is accepted, including key-up events and VK-only keyboard events. Unicode packets do not provide
@@ -274,10 +277,24 @@ thumbnails and source labels aligned with the scaled fonts and spacing.
   of the complete expected text. Browser/editor compatibility depends on its handling of simulated input.
 - Selection conversion and verified recent input (physical scan codes, 2-second typing-run boundary).
 - Same-process clipboard ownership plus verified WebView2 descendants, including the Teams fix.
+  Clipboard synchronizers such as Mouse Without Borders may republish a copy only when
+  KSwitcher first observed it owned by the target application and the selection text and
+  editor selection metadata remain identical. Unobserved or altered foreign copies are rejected.
+  Snippets normally require accessibility verification of their selected trigger and pasted text,
+  even with logging disabled. If verification is unavailable or the paste differs, expansion
+  stops without running cursor or Enter actions. Clipboard changes during paste also cancel actions.
+  Far Manager uses its native Alt+Shift+Arrow selection, Ctrl+Insert copy and Shift+Insert
+  paste commands instead: both the trigger and inserted text must match verified clipboard
+  copies from Far. Cancellation restores the full temporary selection, not one cursor step.
+  Far supports nonempty single-line replacements up to 4096 caret steps, including
+  `{cursor}` and verified `{enter}` actions. Empty or multiline replacements are rejected
+  before selection; pasting a newline could execute a command before it can be verified.
 - Teams recent-word conversion uses a single word-selection command and validates the copied range.
   If the editor's word boundary differs from the recorded typing, it falls back to paced character
   selection: Teams can coalesce a burst of Shift+Left events into just one character.
 - Clipboard snapshot/restoration with concurrent-copy, foreground and input-version checks.
+  A snapshot interrupted by a concurrent clipboard publication is retried up to three total
+  attempts before selection starts, provided the foreground and input context remain unchanged.
   A silently dropped copy is retried up to three total attempts while the clipboard and input
   context remain unchanged. Temporary transaction contents are excluded from Windows clipboard
   history and cloud synchronization. Paste is not blindly retried: with manual paste readback
@@ -525,6 +542,22 @@ OpenBao administrator setup:
 and UI integration, so another service can be added without replacing the synchronization logic.
 Protocol and conflict regressions run with `build.ps1 -Test` or CMake's `sync-regressions` test.
 
+## Portable utilities
+
+The tray menu's **Utilities** submenu lists `.exe` files in a `tools` folder beside
+`KSwitcher.exe`, sorted by filename. For example, place `StayHere.exe` at
+`tools/StayHere.exe` and choose **Utilities → StayHere** to launch it manually.
+The folder is rescanned whenever the menu opens; no configuration or restart is needed.
+Only files directly in `tools` are listed (not subfolders, shortcuts, or KSwitcher's
+own executables beside the main program). Utilities start with `tools` as their working
+directory and are never started automatically. Their lifetime is independent of KSwitcher.
+An absent or empty folder displays a disabled placeholder; launch errors are reported.
+From v0.6.45, the release includes `tools/README.txt`, so extracting the ZIP or
+installing an update creates the folder. Add your own trusted portable executables;
+none are bundled or transferred by settings synchronization. Updates preserve your
+utility files and may refresh the bundled README. Repository development scripts
+are not included in the portable tools folder.
+
 ## Build
 
 The easiest reproducible local route uses the pinned portable w64devkit toolchain:
@@ -648,6 +681,7 @@ Run `./package.ps1 -PublishRelease` after building and testing to refresh the tr
 .\build.ps1 -Test          # Pure/native regression checks; does not touch the user's clipboard
 .\build.ps1 -Ocr           # Render a synthetic image, decode it with WIC and recognize it with Windows OCR
 .\build.ps1 -Integration   # Interactive, isolated test editor; avoid input for about 10 seconds
+.\build.ps1 -Far           # Explicit integration test using an isolated Far Manager profile
 .\tests\configuration.ps1 # Separate-process settings tests; close KSwitcher first
 ```
 
@@ -720,9 +754,13 @@ Consecutive duplicates use SHA-256 fingerprints inside the encrypted history ind
 
 Moving OCR isolates its temporary memory rather than reducing the combined processing peak. A controlled three-run comparison retained about 0.8 MiB less private RAM in the caller after recognition; combined peak RAM was about 55.6 MiB before and 56.6 MiB with the helper. Results depend on the image, OCR engine and system.
 
-### History process and clipboard memory — v0.6.39
+### Pinned history checkbox — v0.6.42
 
-History opens in a separate, short-lived instance of **KSwitcher.exe**. **Esc** closes it even when focus is on the window or an action button, releasing Windows UI allocations with the process. The resident keeps keyboard hooks, clipboard capture and history storage. Search, selection and the top entry are preserved in encrypted view state. If a full-text item viewer is still open, the helper stays alive until the last viewer closes. Pin/delete, formatted/plain paste and OCR remain available; settings and default shortcuts are unchanged.
+Check **★ Pinned only** beside the history search box to show only pinned entries; uncheck it to show all entries. The checkbox sits on the left, immediately followed by the search box; its right edge stays aligned with the history list when resizing. The text search applies within that filter. Unpinning an item removes it from the pinned view immediately. The checkbox state and search are remembered after closing and reopening history. **Clear history…** still deletes the entire history after confirmation, including entries hidden by the filter.
+
+### History process and clipboard memory — v0.6.40
+
+History opens in a separate, short-lived instance of **KSwitcher.exe**. **Esc** closes it even when focus is on the window or an action button, releasing Windows UI allocations with the process. The resident keeps keyboard hooks, clipboard capture and history storage. Search and the pinned-only filter are preserved in encrypted view state. Each fresh opening selects and reveals the newest matching entry; background refreshes preserve the selected record while browsing. If a full-text item viewer is still open, the helper stays alive until the last viewer closes. Pin/delete, formatted/plain paste and OCR remain available; settings and default shortcuts are unchanged.
 
 Image thumbnails are decoded in **KSwitcher.Screenshot.exe**, returning only bounded preview pixels. Image clipboard backup/restore also uses that helper and encrypted temporary files, with clipboard-sequence checks before restoring. Selection reads avoid loading image formats. Keep all three executables together; no fourth executable is required. Paste allows a brief foreground handoff after history closes while preserving cancellation checks. UI Automation remains in the resident.
 

Release/README.md

@@ -1,22 +1,21 @@
 # Latest Windows release
 
-## v0.6.39 — 2026-11-04
+## v0.6.45 — 2026-11-05
 
 ## Changes
-- Clipboard history runs in a separate, short-lived instance of KSwitcher.exe. Closing history with Esc releases its UI process instead of retaining Windows UI allocations in the resident. Esc also works when the window itself or an action button has focus.
+- Fix Far Manager snippet expansion and caret placement. Far uses Alt+Shift+Arrow selection, Ctrl+Insert copy and Shift+Insert paste, with exact trigger and inserted-text verification. Cancellation restores the full temporary selection. Both visible and hidden panels are supported.
-- Search, selected/top entry, pinning, deletion, formatted/plain paste and OCR remain available. Search and selection are saved in encrypted view state. An open full-text viewer keeps the history process alive until that viewer closes.
+- Run Far `{cursor}` and `{enter}` actions only after verified insertion. Far replacements must be nonempty, single-line and no longer than 4096 caret steps. Unsupported templates are rejected before selection; multiline clipboard pastes could execute commands before verification. Other applications retain accessibility verification.
-- Large image clipboard backups and image thumbnail decoding run in KSwitcher.Screenshot.exe. Encrypted temporary files and clipboard-sequence checks preserve the clipboard without keeping full backup images in the resident. Selection reads avoid unnecessary image copies.
+- Add the tray **Utilities** menu. It scans trusted `.exe` files directly in `tools` beside the running KSwitcher.exe, sorted by filename and refreshed whenever the menu opens. Utilities run only when selected, use `tools` as their working directory and remain running independently.
-- History paste waits briefly for the target application's foreground activation after the history process closes, while retaining input and clipboard ownership checks. Settings and default shortcuts are unchanged; UI Automation remains in the resident.
+- Include **tools/README.txt** in the release ZIP and manifest. Both extraction and automatic updates create the folder. Personal utility executables are preserved by updates; none are bundled or transferred through settings synchronization. Source-repository development scripts are excluded.
+- Retain v0.6.44's newest-item selection when reopening clipboard history, including after a screenshot. Saved search/pinned filters remain active; background refreshes preserve the selected record while browsing.
 
-## Validation and memory
+## Validation
-The complete staged build passed dictionary equivalence (140,939 words), 105 sync checks, 315 native checks, 561 input checks, screenshot UI/save/registration, 48 updater checks and progress UI, clipboard snapshot/image capture integration, conversion/snippet integration and Windows OCR. Dedicated 500-entry history tests cover repeated Esc, search persistence, pin/delete, full-viewer lifetime, text/image paste, clipboard restoration, rejected foreign requests and helper shutdown. Actual selected/repeated Viber conversion and live Esc were also checked during development.
+Passed Utilities, dictionary equivalence (140,939 words), 105 sync checks, shared wheel regressions, 319 native checks, 574 input checks, screenshot UI/save/registration, 52 updater checks and updater progress UI. Updater tests cover creation of tools, preserving personal utilities and rollback. The actual ZIP was validated and installed through the unchanged v0.6.44 updater; all installed manifest hashes matched, tools/README.txt was created, and a staging-only utility was excluded from the ZIP. An 18-check real-Far integration run passed during development (visible/hidden panels, caret restoration, cursor markers and verified Enter). The final release-build Far run was canceled by an unrelated foreground change before expansion; an uninterrupted final-build desktop run remains outstanding.
-
-A local live development-build comparison measured **4.37 MiB before opening history and 4.35 MiB after two open/Esc cycles**, versus an earlier roughly 8–9 MiB plateau after closing history. A same-image backup benchmark reduced retained private resident memory from 12.78 MiB to 0.05 MiB. These are workload-specific observations, not a guaranteed footprint. Count all helper processes while history/OCR is active: combined active memory can be higher. No forced working-set trimming was used.
 
 ## Upgrade
 Choose **Update** in the tray menu. Legacy v0.3.0–v0.4.1 clients first receive the v0.4.2 compatibility bridge, then the current full release. v0.2.3 and earlier require manual installation.
-For manual installation, exit KSwitcher, close screenshot editors and extract the entire ZIP into its installation folder. Keep personal `data/` and customized dictionaries.
+For manual installation, exit KSwitcher, close its configurator and screenshot editors, and extract the entire ZIP into its installation folder. Keep personal `data/`, customized dictionaries and your own tools. Look for `tools` beside the executable actually running.
 
-Download **KSwitcher-win-x64.zip** with **SHA256SUMS.txt**. Keep all three executables together; history uses another instance of KSwitcher.exe, so no fourth executable is required. The package contains no personal settings, credentials or clipboard history.
+Download **KSwitcher-win-x64.zip** with **SHA256SUMS.txt**. Keep all three executables together; history uses another instance of KSwitcher.exe. The package contains no personal settings, credentials or clipboard history.
 
 Publish stable `release-vX.Y.Z` tags matching the executable version. Keep `v0.4.2` as the last legacy tag.

Release/SHA256SUMS.txt

@@ -1 +1 @@
-bf3a0fed23ea73dd8422b63fe2f2724e5b02e70c4c66f014c7ebb59222aa91fb  KSwitcher-win-x64.zip
+94b4a3e86c218a42ef4fe0c75c1a621af62e1dfd6b395eea2040d6c1e7f138a8  KSwitcher-win-x64.zip

build.ps1

@@ -1,4 +1,4 @@
-param([switch]$Test, [switch]$Integration, [switch]$Ocr, [switch]$Stage)
+param([switch]$Test, [switch]$Integration, [switch]$Ocr, [switch]$Stage, [switch]$Far)
 $ErrorActionPreference = 'Stop'
 $root = $PSScriptRoot
 $compiler = Join-Path $root '.tools\w64devkit\bin\g++.exe'
@@ -41,6 +41,10 @@ try {
     if ($LASTEXITCODE) { throw 'Screenshot link failed' }
     Copy-Item -LiteralPath $screenshotPath -Destination build/release/KSwitcher.Screenshot.exe -Force
     if ($Test) {
+        & $compiler @common tests/utilities.cpp -static -s -o build/KSwitcherUtilitiesTests.exe
+        if ($LASTEXITCODE) { throw 'Utilities test build failed' }
+        & .\build\KSwitcherUtilitiesTests.exe
+        if ($LASTEXITCODE) { throw 'Utilities tests failed' }
         & $compiler @common tests/dictionary.cpp build/core.o build/platform.o build/autocorrect.o @libs -lpsapi -static -s -o build/KSwitcherDictionaryTests.exe
         if ($LASTEXITCODE) { throw 'Dictionary test build failed' }
         & .\build\KSwitcherDictionaryTests.exe
@@ -80,6 +84,13 @@ try {
         & "$env:SystemRoot\System32\WindowsPowerShell\v1.0\powershell.exe" -NoProfile -ExecutionPolicy Bypass -File tests/update_progress.ps1
         if ($LASTEXITCODE) { throw 'Updater progress UI tests failed' }
     }
+    if ($Far) {
+        & $compiler @common tests/far_snippets.cpp build/core.o build/platform.o build/autostart.o build/autocorrect.o build/storage.o build/sync.o build/ocr.o build/richtext.o build/update.o build/screenshot.o build/screenshot_launcher.o build/screenshot_activation.o build/screenshot_notifications.o build/app.o build/configuration.o build/ui.o build/screenshot-res.o @libs -mwindows -municode -static -s -o build/KSwitcherFarSnippetTests.exe
+        if ($LASTEXITCODE) { throw 'Far snippet test build failed' }
+        $fixture = Start-Process -FilePath (Join-Path $outDir 'KSwitcherFarSnippetTests.exe') -WindowStyle Hidden -Wait -PassThru
+        Get-Content -LiteralPath (Join-Path $outDir 'far-snippets.log')
+        if ($fixture.ExitCode) { throw 'Far snippet tests failed' }
+    }
     if ($Integration) {
         $historyFixture = Join-Path (Resolve-Path build) ('history-host-fixture-' + [guid]::NewGuid().ToString('N'))
         New-Item -ItemType Directory $historyFixture | Out-Null

package.ps1

@@ -10,8 +10,10 @@ Copy-Item -LiteralPath (Join-Path $root 'LICENSE') -Destination $destination
 Copy-Item -LiteralPath (Join-Path $root 'vendor\json-LICENSE.txt') -Destination $destination
 Copy-Item -LiteralPath (Join-Path $root 'README.md') -Destination $destination
 Copy-Item -LiteralPath (Join-Path $root 'dictionaries') -Destination $destination -Recurse -Force
+New-Item -ItemType Directory -Force (Join-Path $destination 'tools') | Out-Null
+Copy-Item -LiteralPath (Join-Path $root 'resources\portable-tools-README.txt') -Destination (Join-Path $destination 'tools\README.txt') -Force
 # Enumerate the distributable files explicitly; do not include a user's data directory.
-$files = @('KSwitcher.exe','KSwitcher.Config.exe','KSwitcher.Screenshot.exe','LICENSE','json-LICENSE.txt','README.md','dictionaries') | ForEach-Object { Join-Path $destination $_ }
+$files = @('KSwitcher.exe','KSwitcher.Config.exe','KSwitcher.Screenshot.exe','LICENSE','json-LICENSE.txt','README.md','dictionaries','tools\README.txt') | ForEach-Object { Join-Path $destination $_ }
 $entries = foreach ($path in $files) {
     foreach ($file in @(Get-ChildItem -LiteralPath $path -File -Recurse)) {
         @{path=$file.FullName.Substring($destination.Length+1).Replace('\','/'); size=$file.Length; sha256=(Get-FileHash -LiteralPath $file.FullName -Algorithm SHA256).Hash.ToLowerInvariant()}
@@ -22,7 +24,16 @@ $manifest=Join-Path $destination 'release-files.json'
 @{schema=1; version=$version; files=@($entries)} | ConvertTo-Json -Depth 4 | Set-Content -LiteralPath $manifest -Encoding utf8
 $files += $manifest
 $archive = Join-Path $root 'dist\KSwitcher-win-x64.zip'
-Compress-Archive -LiteralPath $files -DestinationPath $archive -Force
+# Archive only manifest-listed files, preserving relative paths. Never sweep up
+# personal utilities or leftover developer files from the staging directory.
+Add-Type -AssemblyName System.IO.Compression.FileSystem
+$stream = [IO.File]::Open($archive,[IO.FileMode]::Create)
+$zip = [IO.Compression.ZipArchive]::new($stream,[IO.Compression.ZipArchiveMode]::Create)
+try {
+    foreach ($name in @($entries | ForEach-Object { $_.path }) + @('release-files.json')) {
+        [IO.Compression.ZipFileExtensions]::CreateEntryFromFile($zip,(Join-Path $destination $name),$name,[IO.Compression.CompressionLevel]::Optimal) | Out-Null
+    }
+} finally { $zip.Dispose(); $stream.Dispose() }
 Get-FileHash -LiteralPath $archive -Algorithm SHA256
 if ($PublishRelease) {
     $release = Join-Path $root 'Release'

resources/app.rc

@@ -9,8 +9,8 @@ IDC_SCREENSHOT_PENCIL CURSOR "icons/lucide/pencil.cur"
 1 RT_MANIFEST "app.manifest"
 201 RCDATA "update.ps1"
 1 VERSIONINFO
- FILEVERSION 0,6,38,0
+ FILEVERSION 0,6,45,0
- PRODUCTVERSION 0,6,38,0
+ PRODUCTVERSION 0,6,45,0
  FILEOS VOS_NT_WINDOWS32
  FILETYPE VFT_APP
 BEGIN
@@ -20,7 +20,7 @@ BEGIN
   BEGIN
    VALUE "FileDescription", "KSwitcher — native keyboard and clipboard utility"
    VALUE "ProductName", "KSwitcher"
-   VALUE "FileVersion", "0.6.38"
+   VALUE "FileVersion", "0.6.45"
   END
  END
  BLOCK "VarFileInfo"

resources/portable-tools-README.txt

@@ -0,0 +1,13 @@
+KSwitcher portable utilities
+
+Put your trusted portable .exe utilities directly in this tools folder,
+beside this README.txt. Right-click the KSwitcher tray icon and open Utilities.
+For example: tools/StayHere.exe appears as Utilities > StayHere.
+
+The list refreshes each time the tray menu opens. Subfolders and shortcuts
+are not listed. Utilities start only when you choose them, with this folder
+as their working directory. Closing KSwitcher does not close a utility.
+
+No utility executables are bundled. Supply them separately on each computer.
+Normal KSwitcher updates preserve your own files in this folder; this README
+may be refreshed. Utilities are not transferred by settings synchronization.

src/app.cpp

@@ -6,6 +6,7 @@
 #include "configuration.h"
 #include "diagnostics.h"
 #include "paste_probe.h"
+#include "utilities.h"
 #include "screenshot_notifications.h"
 #include <algorithm>
 #include <commctrl.h>
@@ -78,19 +79,40 @@ class Transaction
     mutable bool invalidLogged{};
     unsigned copyNumber{};
     std::wstring adopted;
+    Bytes adoptedFormats;
+    bool trustedContentsObserved{};
     std::unique_ptr<PasteProbe> selectionProof;
     std::wstring provenSelection;
+    bool farSnippet{};
+    size_t farSelectedSteps{};
 
   public:
-    Transaction(App &a, HWND t, uint64_t v) : app(a), target(t), version(v)
+    Transaction(App &a, HWND t, uint64_t v, bool farEditor = false)
+        : app(a), target(t), version(v), farSnippet(farEditor)
     {
         app.suspended = true;
         try
+        {
+            for (unsigned attempt = 0; ; ++attempt)
             {
                 expected = GetClipboardSequenceNumber();
+                try
+                {
                     snapshot.capture(app.window, expected);
                     if (expected != GetClipboardSequenceNumber())
                         throw std::runtime_error("Clipboard changed while taking snapshot");
+                    break;
+                }
+                catch (...)
+                {
+                    // No selection or clipboard write has happened yet. Recapture
+                    // the latest clipboard after a concurrent publisher settles.
+                    if (attempt >= 2 || !valid() || expected == GetClipboardSequenceNumber())
+                        throw;
+                    diagnosticEvent(L"Snapshot retry: clipboard changed during capture");
+                    Sleep(20);
+                }
+            }
             captured = true;
         }
         catch (...)
@@ -101,6 +123,7 @@ class Transaction
     }
     ~Transaction()
     {
+        if (farSnippet) finishSelection(false);
         if (captured && GetClipboardSequenceNumber() == expected)
             try
             {
@@ -132,9 +155,19 @@ class Transaction
         if (GetClipboardSequenceNumber() != expected)
         {
             auto now = GetClipboardSequenceNumber();
-            if (adopted.empty() || !ownsClipboard(target) || readClipboard(app.window, 32 * 1024 * 1024, ClipboardRead::Selection).text() != adopted ||
+            auto current = readClipboard(app.window, 32 * 1024 * 1024, ClipboardRead::Selection);
-                GetClipboardSequenceNumber() != now)
+            const bool sameContents = selectionClipboardIdentity(current) == adoptedFormats;
+            if (adopted.empty() || (!trustedContentsObserved && !ownsClipboard(target)) ||
+                !sameContents || GetClipboardSequenceNumber() != now)
+            {
+                diagnosticEvent(L"Clipboard check rejected: expectedSequence=" + std::to_wstring(expected) +
+                    L" readSequence=" + std::to_wstring(now) + L" currentSequence=" +
+                    std::to_wstring(GetClipboardSequenceNumber()) + L" owner=" +
+                    std::to_wstring((uintptr_t)GetClipboardOwner()) + L" sameContents=" +
+                    std::to_wstring(sameContents) + L" expectedText=" + diagnosticText(adopted) +
+                    L" currentText=" + diagnosticText(current.text()));
                 throw std::runtime_error("Operation cancelled: another application changed the clipboard");
+            }
             expected = now;
         }
     }
@@ -142,6 +175,8 @@ class Transaction
     {
         check();
         adopted.clear();
+        adoptedFormats.clear();
+        trustedContentsObserved = false;
         // These are temporary transaction contents, not a user's clipboard entry.
         // In particular, do not invite the Windows history service to read our
         // sentinel while the target editor is trying to open the clipboard.
@@ -164,11 +199,13 @@ class Transaction
         const auto number = ++copyNumber;
         if (!valid())
             return {};
-        write(textClip(L"\x2063KSwitcher-" + std::to_wstring(GetTickCount64())));
+        const auto sentinel = L"\x2063KSwitcher-" + std::to_wstring(GetTickCount64());
+        write(textClip(sentinel));
         DWORD before = expected;
         diagnosticEvent(L"Copy begin number=" + std::to_wstring(number) + L" sentinelSequence=" +
-            std::to_wstring(before) + L" target=" + std::to_wstring((uintptr_t)target));
+            std::to_wstring(before) + L" target=" + std::to_wstring((uintptr_t)target) +
-        if (!valid() || !chord(L'C', MOD_CONTROL))
+            L" sentinel=" + diagnosticText(sentinel));
+        if (!valid() || !chord(farSnippet ? VK_INSERT : L'C', MOD_CONTROL))
         {
             diagnosticEvent(L"Copy failed: context changed or simulated Ctrl+C blocked");
             return {};
@@ -179,6 +216,7 @@ class Transaction
         DWORD changed = before;
         ULONGLONG stable = 0;
         bool changedAgain = false;
+        std::optional<Bytes> observedTargetCopy;
         while (GetTickCount64() < deadline)
         {
             if (!valid())
@@ -193,6 +231,18 @@ class Transaction
                 changedAgain |= changed != before;
                 changed = now;
                 stable = GetTickCount64();
+                // Clipboard synchronizers can republish a legitimate copy under
+                // their own HWND. Record provenance before that handoff; an
+                // unobserved or altered foreign copy must still be rejected.
+                if (ownsClipboard(target))
+                {
+                    auto candidate = readClipboard(app.window, 32 * 1024 * 1024, ClipboardRead::Selection);
+                    if (GetClipboardSequenceNumber() == now && ownsClipboard(target) && !candidate.text().empty())
+                    {
+                        observedTargetCopy = selectionClipboardIdentity(candidate);
+                        diagnosticEvent(L"Copy: target-owned selection observed number=" + std::to_wstring(number));
+                    }
+                }
             }
             if (changed != before && GetTickCount64() - stable >= 60)
                 break;
@@ -205,7 +255,7 @@ class Transaction
                 check();
                 if (!valid() || GetClipboardSequenceNumber() != before)
                     return {};
-                if (!chord(L'C', MOD_CONTROL))
+                if (!chord(farSnippet ? VK_INSERT : L'C', MOD_CONTROL))
                     return {};
                 diagnosticEvent(L"Copy retry: clipboard unchanged after Ctrl+C number=" + std::to_wstring(number) +
                     L" attempt=" + std::to_wstring(attempts + 1) + L" elapsedMs=" + std::to_wstring(GetTickCount64() - started));
@@ -224,16 +274,31 @@ class Transaction
                                     L"Copy failed: context changed");
             return {};
         }
-        if ((GetClipboardOwner() ? !ownsClipboard(target) : changedAgain) ||
+        const bool targetOwned = ownsClipboard(target);
-            changed != GetClipboardSequenceNumber())
-            throw std::runtime_error("Operation cancelled: copy did not belong to the target application");
-        expected = changed;
         auto clip = readClipboard(app.window, 32 * 1024 * 1024, ClipboardRead::Selection);
+        const auto formats = selectionClipboardIdentity(clip);
+        const bool verifiedRelay = observedTargetCopy && *observedTargetCopy == formats;
+        if (((GetClipboardOwner() ? !targetOwned : changedAgain) && !verifiedRelay) ||
+            changed != GetClipboardSequenceNumber())
+        {
+            diagnosticEvent(L"Copy rejected: observedTarget=" + std::to_wstring(observedTargetCopy.has_value()) +
+                L" verifiedRelay=" + std::to_wstring(verifiedRelay) + L" expectedSequence=" +
+                std::to_wstring(changed) + L" currentSequence=" + std::to_wstring(GetClipboardSequenceNumber()) +
+                L" owner=" + std::to_wstring((uintptr_t)GetClipboardOwner()) + L" targetText=" +
+                diagnosticText(observedTargetCopy ? decodeClip(*observedTargetCopy).text() : L"") +
+                L" currentText=" + diagnosticText(clip.text()));
+            throw std::runtime_error("Operation cancelled: copy did not belong to the target application");
+        }
+        if (!targetOwned && verifiedRelay)
+            diagnosticEvent(L"Copy: identical target selection republished by clipboard synchronizer");
+        expected = changed;
         auto text = clip.text();
         diagnosticEvent(L"Copy result number=" + std::to_wstring(number) + L" attempts=" +
             std::to_wstring(attempts) + L" elapsedMs=" + std::to_wstring(GetTickCount64() - started) +
             L" text=" + diagnosticText(text));
         adopted = text;
+        adoptedFormats = formats;
+        trustedContentsObserved = targetOwned || verifiedRelay;
         check();
         for (auto &f : clip.formats)
         {
@@ -277,8 +342,44 @@ class Transaction
     bool recoveredSelection() const { return selectionProof != nullptr; }
     bool select(size_t n)
     {
+        if (farSnippet)
+        {
+            if (n > 4096 || farSelectedSteps) return false;
+            for (size_t i = 0; i < n; ++i)
+            {
+                if (!valid() || !chord(VK_LEFT, MOD_ALT | MOD_SHIFT)) return false;
+                ++farSelectedSteps;
+            }
+            return valid();
+        }
         return selectPrevious(n, [&] { return valid(); });
     }
+    bool finishSelection(bool atStart)
+    {
+        if (!farSnippet) return valid() && chord(atStart ? VK_LEFT : VK_RIGHT);
+        if (!farSelectedSteps) return valid();
+        if (atStart)
+        {
+            // Far arrows move one character, rather than collapsing a selection
+            // to its edge. Move into the nonempty selected range and back.
+            if (!valid() || !chord(VK_RIGHT)) return false;
+            farSelectedSteps = 0;
+            return valid() && chord(VK_LEFT);
+        }
+        while (farSelectedSteps && valid())
+        {
+            if (!chord(VK_RIGHT, MOD_ALT | MOD_SHIFT)) return false;
+            --farSelectedSteps;
+        }
+        return !farSelectedSteps && valid();
+    }
+    std::optional<std::wstring> readFarSnippet(size_t count)
+    {
+        if (!farSnippet || !count || !select(count)) return {};
+        auto observed = copy();
+        if (!finishSelection(false) || observed.empty()) return {};
+        return observed;
+    }
     std::wstring copyRange(size_t count, const std::wstring &wordCandidate,
                            const std::function<bool(const std::wstring &)> &matches,
                            const std::function<bool(const std::wstring &)> &suffixMatches = {})
@@ -359,6 +460,14 @@ class Transaction
         if (!valid())
             return false;
         write(clip);
+        // Our verified payload is also trusted across an identical relay. The
+        // sentinel written by copy() deliberately does not get this allowance.
+        if (clip.formats.size() == 1 && clip.formats.front().id == CF_UNICODETEXT)
+        {
+            adopted = clip.text();
+            adoptedFormats = selectionClipboardIdentity(clip);
+            trustedContentsObserved = true;
+        }
         // Viber's Qt editor observes clipboard changes asynchronously. Give it
         // a chance to discard the data object from Ctrl+C before requesting paste.
         // Recheck ownership and input below; never retry a possibly applied paste.
@@ -373,9 +482,16 @@ class Transaction
             if (!valid())
                 return false;
         }
-        if (!chord(L'V', MOD_CONTROL))
+        if (!chord(farSnippet ? VK_INSERT : L'V', farSnippet ? MOD_SHIFT : MOD_CONTROL))
             throw std::runtime_error("Windows blocked simulated input; check application privilege levels");
+        // The selected trigger was replaced. Do not restore its old caret range
+        // if clipboard verification below subsequently rejects a concurrent copy.
+        if (farSnippet) farSelectedSteps = 0;
         Sleep(300);
+        // A clipboard synchronizer may replace our payload after Ctrl+V is
+        // queued but before the editor consumes it. Do not run snippet actions
+        // (especially Enter) after such a race.
+        check();
         return true;
     }
     bool nativeSelectionIs(const std::wstring &original) const
@@ -955,6 +1071,15 @@ void App::replayTyping()
 }
 LRESULT CALLBACK App::keyProc(int code, WPARAM wp, LPARAM lp)
 {
+    // MWB suppresses source-machine events that it forwards elsewhere. Let
+    // downstream hooks route the event before tracking it or starting a snippet.
+    // Call the chain exactly once; a local event can still be consumed below.
+    const auto routed = CallNextHookEx(nullptr, code, wp, lp);
+    return keyboardAfterHooks(code, wp, lp, routed);
+}
+LRESULT App::keyboardAfterHooks(int code, WPARAM wp, LPARAM lp, LRESULT routed)
+{
+    if (routed) return routed;
     if (code == HC_ACTION && current &&
         (wp == WM_KEYDOWN || wp == WM_SYSKEYDOWN || wp == WM_KEYUP || wp == WM_SYSKEYUP))
     {
@@ -969,7 +1094,7 @@ LRESULT CALLBACK App::keyProc(int code, WPARAM wp, LPARAM lp)
                                     wp == WM_KEYDOWN || wp == WM_SYSKEYDOWN, mods))
             return 1;
     }
-    return CallNextHookEx(nullptr, code, wp, lp);
+    return routed;
 }
 LRESULT CALLBACK App::mouseProc(int code, WPARAM wp, LPARAM lp)
 {
@@ -1213,14 +1338,16 @@ void App::transform(int command, int snippet)
                 }
                 // Collapse a temporary selection on every failed auto-correction,
                 // including clipboard exceptions, before queued typing is replayed.
+                const bool farSnippet = snippet >= 0 && lower(processName(target)) == L"far";
                 bool autoSelected = false;
                 struct SelectionReset
                 {
                     bool &selected;
                     std::function<bool()> valid;
-                    ~SelectionReset() { if (selected && valid()) chord(VK_RIGHT); }
+                    bool farEditor;
-                } selectionReset{autoSelected, valid};
+                    ~SelectionReset() { if (selected && !farEditor && valid()) chord(VK_RIGHT); }
-                Transaction tx(*this, target, version);
+                } selectionReset{autoSelected, valid, farSnippet};
+                Transaction tx(*this, target, version, farSnippet);
                 reason = L"selection-unavailable";
                 diagnosticEvent(L"Transform target=" + processName(target) + L" command=" + std::to_wstring(command) +
                     L" recent=" + std::to_wstring(config.recent) + L" keys=" +
@@ -1300,6 +1427,15 @@ void App::transform(int command, int snippet)
                     const auto &sn = config.snippets[snippet];
                     if (recent.keys.size() < sn.trigger.size())
                         return;
+                    result = parseTemplate(sn.text).text;
+                    // A multiline clipboard paste can execute a console command
+                    // before readback. Only explicit, verified {enter} may do so.
+                    if (farSnippet && (result.empty() || result.find_first_of(L"\r\n") != result.npos ||
+                                       caretSteps(result) > 4096))
+                    {
+                        reason = L"far-snippet-template-unsupported";
+                        return;
+                    }
                     Run tail = recent;
                     tail.keys = tail.keys.substr(tail.keys.size() - sn.trigger.size());
                     if (!tx.select(sn.trigger.size()))
@@ -1309,7 +1445,6 @@ void App::transform(int command, int snippet)
                     text = tx.copy();
                     if (tail.match(text, available, physicalLayout()) < 0)
                         return;
-                    result = parseTemplate(sn.text).text;
                     automatic = true;
                 }
                 else if (config.recent && recent.window == target && !recent.keys.empty() && !recent.overflow)
@@ -1398,11 +1533,12 @@ void App::transform(int command, int snippet)
                     }
                 }
                 bool sent = false;
-                const bool requireReadback = tx.recoveredSelection();
+                const bool requireReadback = tx.recoveredSelection() || snippet >= 0;
-                PasteProbe probe(((config.writeLog && manual) || requireReadback) && result != text, text, target);
+                PasteProbe probe(!farSnippet && ((config.writeLog && manual) || requireReadback) && result != text, text, target);
-                if (requireReadback && result != text && probe.status != L"ready")
+                if (requireReadback && !farSnippet && result != text && probe.status != L"ready")
                 {
-                    reason = L"recovered-selection-unavailable";
+                    verification = probe.status;
+                    reason = snippet >= 0 ? L"snippet-verification-unavailable" : L"recovered-selection-unavailable";
                     std::lock_guard lock(stateMutex);
                     last.reset();
                     run.reset();
@@ -1413,10 +1549,10 @@ void App::transform(int command, int snippet)
                 if (result != text)
                     sent = tx.paste(textClip(result));
                 else if (automatic && tx.valid())
-                    chord(VK_RIGHT);
+                    tx.finishSelection(false);
                 if (requireReadback && result != text && !sent)
                 {
-                    reason = L"recovered-selection-paste-cancelled";
+                    reason = snippet >= 0 ? L"snippet-paste-cancelled" : L"recovered-selection-paste-cancelled";
                     std::lock_guard lock(stateMutex);
                     last.reset();
                     run.reset();
@@ -1436,11 +1572,12 @@ void App::transform(int command, int snippet)
                     verification = probe.status;
                     if (tx.valid())
                     {
-                        auto observed = probe.read((int)caretSteps(result));
+                        auto observed = farSnippet ? tx.readFarSnippet(caretSteps(result)) :
+                                                     probe.read((int)caretSteps(result));
                         // A native Edit may silently ignore Ctrl+V while the clipboard is busy.
                         // Retry once only with fresh native proof that the exact original range
                         // is still selected. Never retry an unknown or changed editor state.
-                        if (observed && newlines(*observed) == newlines(text) && tx.nativeSelectionIs(text))
+                        if (!farSnippet && observed && newlines(*observed) == newlines(text) && tx.nativeSelectionIs(text))
                         {
                             diagnosticEvent(L"Paste retry: native Edit still selects the unchanged original");
                             if (tx.paste(textClip(result)) && tx.valid())
@@ -1448,7 +1585,8 @@ void App::transform(int command, int snippet)
                             else
                                 observed.reset();
                         }
-                        verification = probe.status;
+                        verification = farSnippet ? (observed ? L"read-back-via-far-clipboard" :
+                                                                 L"far-readback-unavailable") : probe.status;
                         if (observed && tx.valid())
                         {
                             actual = *observed;
@@ -1492,6 +1630,7 @@ void App::transform(int command, int snippet)
                 }
                 if (snippet >= 0 && sent && tx.valid())
                 {
+                    tx.check();
                     auto t = parseTemplate(config.snippets[snippet].text);
                     if (!t.suffix.empty())
                     {
@@ -1500,16 +1639,19 @@ void App::transform(int command, int snippet)
                         if (!tx.valid()) return;
                         if (newlines(suffix) != newlines(t.suffix))
                         {
-                            chord(VK_RIGHT);
+                            tx.finishSelection(false);
                             return;
                         }
-                        if (!chord(VK_LEFT)) return;
+                        if (!tx.finishSelection(true)) return;
                     }
                     // Action markers run after insertion and cursor placement,
                     // before any physical typing buffered during expansion.
                     for (int i = 0; i < t.enters && tx.valid(); ++i)
+                    {
+                        tx.check();
                         if (!chord(VK_RETURN)) break;
                     }
+                }
                 if (to >= 0 && config.switchLayout && tx.valid() && (sent || result == text))
                 {
                     bool switched = switchWindowLayout(target, available[to].handle, valid);
@@ -1680,6 +1822,10 @@ void App::recognizeEntry(std::wstring id)
 }
 void App::trayMenu()
 {
+    constexpr int utilityCommandBase = 1000;
+    std::error_code utilitiesError;
+    auto utilities = discoverUtilities(std::filesystem::path(executable()).parent_path() / L"tools", utilitiesError);
+    if (utilities.size() > 50000) utilities.resize(50000);
     HMENU menu = CreatePopupMenu();
     AppendMenuW(menu, MF_STRING, 10, L"Clipboard &history");
     AppendMenuW(menu, MF_STRING, 24, L"&Capture screen region…");
@@ -1687,6 +1833,13 @@ void App::trayMenu()
     SetMenuDefaultItem(menu, 11, FALSE);
     AppendMenuW(menu, MF_STRING, 12, L"S&nippets…");
     AppendMenuW(menu, MF_STRING, 13, L"&Keyboard shortcuts…");
+    HMENU utilityMenu = CreatePopupMenu();
+    for (size_t i = 0; i < utilities.size(); ++i)
+        AppendMenuW(utilityMenu, MF_STRING, utilityCommandBase + i, utilityMenuLabel(utilities[i]).c_str());
+    if (utilities.empty())
+        AppendMenuW(utilityMenu, MF_STRING | MF_GRAYED, 0,
+                    utilitiesError ? L"Cannot read tools folder" : L"No utilities in tools folder");
+    AppendMenuW(menu, MF_POPUP, (UINT_PTR)utilityMenu, L"&Utilities");
     AppendMenuW(menu, MF_SEPARATOR, 0, nullptr);
     AppendMenuW(menu, MF_STRING | (settings.awake ? MF_CHECKED : 0), 14, L"Keep screen a&wake");
     HMENU pause = CreatePopupMenu();
@@ -1713,6 +1866,20 @@ void App::trayMenu()
     PostMessageW(window, WM_NULL, 0, 0);
     try
     {
+        if (cmd >= utilityCommandBase && size_t(cmd - utilityCommandBase) < utilities.size())
+        {
+            const auto &path = utilities[cmd - utilityCommandBase];
+            auto command = L"\"" + path.wstring() + L"\"";
+            STARTUPINFOW startup{sizeof(startup)};
+            PROCESS_INFORMATION process{};
+            if (!CreateProcessW(path.c_str(), command.data(), nullptr, nullptr, FALSE, 0, nullptr,
+                                path.parent_path().c_str(), &startup, &process))
+                throw std::runtime_error(utf8(lastError(L"Cannot start utility " + path.filename().wstring())));
+            AllowSetForegroundWindow(process.dwProcessId);
+            CloseHandle(process.hThread);
+            CloseHandle(process.hProcess);
+            return;
+        }
         switch (cmd)
         {
         case 24:
@@ -1900,7 +2067,9 @@ LRESULT CALLBACK App::windowProc(HWND hwnd, UINT msg, WPARAM wp, LPARAM lp)
         app->replayTyping();
         return 0;
     case TrayMessage:
-        if (LOWORD(lp) == WM_CONTEXTMENU)
+        if (LOWORD(lp) == NIN_BALLOONUSERCLICK)
+            showLogs(*app);
+        else if (LOWORD(lp) == WM_CONTEXTMENU)
             app->trayMenu();
         else if (LOWORD(lp) == WM_LBUTTONDBLCLK)
             // The shell still owns the mouse gesture on the second button-down.
@@ -2078,6 +2247,7 @@ int App::execute()
             historySelection = wide(state.value("selection", std::string{}));
             historyTop = wide(state.value("top", std::string{}));
             historyQuery = wide(state.value("query", std::string{}));
+            historyPinnedOnly = state.value("pinnedOnly", false);
         } catch (...) {}
         showHistory(*this);
         remoteHistory("ready", std::to_wstring(reinterpret_cast<uintptr_t>(historyWindow)));

src/app.h

@@ -37,6 +37,7 @@ class App
     bool isolateHistory{};
     unsigned historyEntryWindows{};
     std::wstring historySelection, historyTop, historyQuery;
+    bool historyPinnedOnly{};
     HINSTANCE instance{};
     std::filesystem::path data;
     std::vector<Layout> layouts;
@@ -80,7 +81,7 @@ class App
     void refreshHistoryProcess();
     void remoteHistory(const char *action, const std::wstring &id = {}, bool plain = false);
     LRESULT historyRequest(HWND, const COPYDATASTRUCT &);
-    void saveHistoryView(const std::wstring &, const std::wstring &, const std::wstring &);
+    void saveHistoryView(const std::wstring &, const std::wstring &, const std::wstring &, bool);
     void clearLog(bool previous);
     void setHotkeyCapture(HWND);
     bool isHotkey(DWORD, UINT);
@@ -142,6 +143,7 @@ class App
     void replayTyping();
     static LRESULT CALLBACK windowProc(HWND, UINT, WPARAM, LPARAM);
     static LRESULT CALLBACK keyProc(int, WPARAM, LPARAM);
+    static LRESULT keyboardAfterHooks(int, WPARAM, LPARAM, LRESULT);
     static LRESULT CALLBACK mouseProc(int, WPARAM, LPARAM);
 };
 void showHistory(App &, bool visible = true);

src/app_history.inl

@@ -90,11 +90,11 @@ LRESULT App::historyRequest(HWND sender, const COPYDATASTRUCT &message)
         return TRUE;
     } catch (...) { return FALSE; }
 }
-void App::saveHistoryView(const std::wstring &selection, const std::wstring &top, const std::wstring &query)
+void App::saveHistoryView(const std::wstring &selection, const std::wstring &top, const std::wstring &query, bool pinnedOnly)
 {
     if (!historyService) return;
     try {
-        auto text = HistoryJson{{"selection", utf8(selection)}, {"top", utf8(top)}, {"query", utf8(query)}}.dump();
+        auto text = HistoryJson{{"selection", utf8(selection)}, {"top", utf8(top)}, {"query", utf8(query)}, {"pinnedOnly", pinnedOnly}}.dump();
         atomicWrite(data / L"history-view.bin", protect(Bytes(text.begin(), text.end())));
     } catch (...) {} // Closing the UI must still release its process if state cannot be saved.
 }

src/storage.cpp

@@ -344,6 +344,20 @@ Bytes encodeClip(const Clip &clip)
     }
     return b;
 }
+Bytes selectionClipboardIdentity(const Clip &clip)
+{
+    auto normalized = clip;
+    // GlobalSize includes allocation slack. A clipboard relay may allocate a
+    // different-sized block for the same NUL-terminated Unicode string.
+    for (auto &format : normalized.formats)
+        if (format.id == CF_UNICODETEXT)
+            format = textClip(clip.text()).formats.front();
+    std::sort(normalized.formats.begin(), normalized.formats.end(), [](const Format &a, const Format &b)
+    {
+        return std::tie(a.name, a.id) < std::tie(b.name, b.id);
+    });
+    return encodeClip(normalized);
+}
 Clip decodeClip(const Bytes &b)
 {
     size_t p = 0;
@@ -924,9 +938,10 @@ std::optional<std::wstring> History::ocrText(const std::wstring &id, const std::
     if (bytes.empty() || bytes.front() != 1) throw std::runtime_error("Invalid OCR text format");
     return wide(std::string(bytes.begin() + 1, bytes.end()));
 }
-std::vector<Entry> History::search(const std::wstring &query) const
+std::vector<Entry> History::search(const std::wstring &query, bool pinnedOnly) const
 {
     auto items = entries();
+    if (pinnedOnly) std::erase_if(items, [](const Entry &entry) { return !entry.pinned; });
     if (query.empty())
         return items;
     auto q = lower(query);

src/storage.h

@@ -43,9 +43,10 @@ class History
     void remove(const std::wstring &);
     void pin(const std::wstring &);
     void clear();
-    std::vector<Entry> search(const std::wstring &) const;
+    std::vector<Entry> search(const std::wstring &, bool pinnedOnly = false) const;
 };
 Bytes encodeClip(const Clip &);
+Bytes selectionClipboardIdentity(const Clip &);
 Clip decodeClip(const Bytes &);
 bool sameClipboardImage(const Clip &, const Clip &);
 int runImageHistoryCapture(const std::filesystem::path &request);

src/ui.cpp

@@ -493,6 +493,7 @@ struct HistoryView
     std::set<std::wstring> pending;
     bool scrolling{};
     bool closed{};
+    bool selectFirstOnResults{};
 };
 bool selectedImage(HWND w, HistoryView *v)
 {
@@ -514,15 +515,16 @@ void search(HWND w, HistoryView *v)
     v->previewActive = std::make_shared<std::atomic<bool>>(true);
     v->closed = false;
     auto q = value(w, 101);
+    const bool pinnedOnly = SendDlgItemMessageW(w, 117, BM_GETCHECK, 0, 0) == BST_CHECKED;
     auto generation = ++v->generation;
     v->pending.clear();
     auto *app = v->app;
     app->enqueueHistorySearch(
-        [w, app, q, generation]
+        [w, app, q, generation, pinnedOnly]
         {
             try
             {
-                auto result = new SearchResult{generation, app->history->search(q)};
+                auto result = new SearchResult{generation, app->history->search(q, pinnedOnly)};
                 if (!PostMessageW(w, ResultsMessage, 0, (LPARAM)result))
                     delete result;
             }
@@ -739,6 +741,12 @@ LRESULT CALLBACK historyProc(HWND w, UINT msg, WPARAM wp, LPARAM lp)
         case WM_COMMAND:
         {
             int id = LOWORD(wp);
+            if (id == 117 && HIWORD(wp) == BN_CLICKED)
+            {
+                KillTimer(w, 1);
+                search(w, v);
+                return 0;
+            }
             if (id == 101 && HIWORD(wp) == EN_CHANGE)
             {
                 // Reject an older result even during the debounce interval.
@@ -809,6 +817,14 @@ LRESULT CALLBACK historyProc(HWND w, UINT msg, WPARAM wp, LPARAM lp)
             int top=(int)SendDlgItemMessageW(w,102,LB_GETTOPINDEX,0,0);
             auto topId=top>=0 && top<(int)v->items.size()?v->items[top].id:L"";
             if (topId.empty()) topId = v->rememberedTop;
+            if (v->selectFirstOnResults)
+            {
+                old.clear();
+                topId.clear();
+                v->rememberedSelection.clear();
+                v->rememberedTop.clear();
+                v->selectFirstOnResults = false;
+            }
             v->items = std::move(result->items);
             SendDlgItemMessageW(w, 102, WM_SETREDRAW, FALSE, 0);
             SendDlgItemMessageW(w, 102, LB_RESETCONTENT, 0, 0);
@@ -910,7 +926,8 @@ LRESULT CALLBACK historyProc(HWND w, UINT msg, WPARAM wp, LPARAM lp)
             v->rememberedSelection = selected(w, v);
             int top = (int)SendDlgItemMessageW(w,102,LB_GETTOPINDEX,0,0);
             v->rememberedTop = top >= 0 && top < (int)v->items.size() ? v->items[top].id : L"";
-            v->app->saveHistoryView(v->rememberedSelection, v->rememberedTop, value(w, 101));
+            v->app->saveHistoryView(v->rememberedSelection, v->rememberedTop, value(w, 101),
+                                   SendDlgItemMessageW(w, 117, BM_GETCHECK, 0, 0) == BST_CHECKED);
             KillTimer(w, 1);
             v->closed = true;
             v->previewActive->store(false);
@@ -1737,8 +1754,11 @@ void showHistory(App &app, bool visible)
         HWND w = makeWindow(app, L"KSwitcher.History", L"Clipboard history", historyProc, 760, 500);
         app.historyWindow = w;
         windowLayoutState(w)->history = true;
-        label(w, L"&Search clipboard history", 16, 12, 500);
+        auto filter = control(w, L"BUTTON", L"★ Pinned only", WS_TABSTOP | BS_AUTOCHECKBOX,
-        edit(w, 101, 16, 38, 728);
+                              117, 16, 38, 112, 25);
+        SendMessageW(filter, BM_SETCHECK, app.historyPinnedOnly ? BST_CHECKED : BST_UNCHECKED, 0);
+        label(w, L"&Search clipboard history", 136, 12, 500);
+        edit(w, 101, 136, 38, 608);
         auto list = control(w, L"LISTBOX", L"",
                             WS_TABSTOP | WS_VSCROLL | LBS_NOTIFY | LBS_NOINTEGRALHEIGHT | WS_BORDER |
                                 LBS_OWNERDRAWFIXED | LBS_HASSTRINGS,
@@ -1760,6 +1780,10 @@ void showHistory(App &app, bool visible)
         }
     }
     if (!visible) return;
+    // A fresh invocation starts at the newest matching item. Background search
+    // and OCR refreshes still preserve the user's selection while browsing.
+    auto *view = (HistoryView *)GetWindowLongPtrW(app.historyWindow, GWLP_USERDATA);
+    view->selectFirstOnResults = true;
     POINT cursor;
     GetCursorPos(&cursor);
     MONITORINFO monitor{sizeof(monitor)};

src/update.h

@@ -2,7 +2,7 @@
 #include "platform.h"
 namespace ks
 {
-inline constexpr wchar_t AppVersion[] = L"0.6.39";
+inline constexpr wchar_t AppVersion[] = L"0.6.45";
 inline constexpr UINT UpdateMessage = WM_APP + 7;
 inline constexpr UINT UpdateCheckIntervalMs = 6 * 60 * 60 * 1000;
 inline constexpr UINT UpdateNotificationRetryMs = 5 * 60 * 1000;

src/utilities.h

@@ -0,0 +1,41 @@
+#pragma once
+#include <algorithm>
+#include <cwchar>
+#include <filesystem>
+#include <string>
+#include <vector>
+
+namespace ks
+{
+// Scan each time the menu opens, relative to the resident executable, not its working directory.
+inline std::vector<std::filesystem::path> discoverUtilities(const std::filesystem::path &folder,
+                                                          std::error_code &error)
+{
+    error.clear();
+    std::vector<std::filesystem::path> result;
+    std::filesystem::directory_iterator it(folder, error), end;
+    if (error == std::errc::no_such_file_or_directory) error.clear();
+    while (!error && it != end)
+    {
+        std::error_code entryError;
+        if (_wcsicmp(it->path().extension().c_str(), L".exe") == 0 && it->is_regular_file(entryError))
+            result.push_back(it->path());
+        it.increment(error);
+    }
+    if (error) result.clear();
+    std::sort(result.begin(), result.end(), [](const auto &a, const auto &b) {
+        return _wcsicmp(a.filename().c_str(), b.filename().c_str()) < 0;
+    });
+    return result;
+}
+inline std::wstring utilityMenuLabel(const std::filesystem::path &path)
+{
+    std::wstring label;
+    for (wchar_t ch : path.stem().wstring())
+    {
+        label += ch;
+        if (ch == L'&') label += ch; // Win32 uses ampersands for access keys.
+    }
+    return label;
+}
+}

tests/far_snippets.cpp

@@ -0,0 +1,129 @@
+// Explicit Windows integration test. Opens an isolated Far profile and never
+// types into an existing Far window. Requires Far Manager at its default path.
+#include "app.h"
+#include <cstdlib>
+#include <cwctype>
+#include <fstream>
+#include <future>
+
+namespace ks {
+struct InputRegressionAccess {
+    static void runQueued(App &app) {
+        std::function<void()> job;
+        { std::lock_guard lock(app.jobsMutex);
+          if (app.jobs.empty()) throw std::runtime_error("snippet did not queue");
+          job=std::move(app.jobs.front());app.jobs.pop_front(); }
+        auto future=std::async(std::launch::async,[job=std::move(job)] {
+            CoInitializeEx(nullptr,COINIT_APARTMENTTHREADED);job();CoUninitialize();
+        });
+        while(future.wait_for(std::chrono::milliseconds(5))!=std::future_status::ready) {
+            MSG message{};while(PeekMessageW(&message,nullptr,0,0,PM_REMOVE)) {
+                TranslateMessage(&message);DispatchMessageW(&message);
+            }
+        }
+        future.get();app.replayTyping();
+    }
+};
+}
+int WINAPI wWinMain(HINSTANCE instance,HINSTANCE,PWSTR,int) {
+    auto base=std::filesystem::path(ks::executable()).parent_path();
+    std::ofstream log(base/L"far-snippets.log");
+    int checks=0;
+    auto require=[&](bool ok,const char *message) {
+        if(!ok)throw std::runtime_error(message);
+        ++checks;log<<"PASS "<<message<<'\n';log.flush();
+    };
+    auto folder=std::filesystem::temp_directory_path()/(L"ks-far-snippets-"+ks::newSnippetId());
+    std::filesystem::create_directories(folder);
+    CoInitializeEx(nullptr,COINIT_APARTMENTTHREADED);
+    ks::Clip saved;bool captured=false;PROCESS_INFORMATION child{};
+    HANDLE input=INVALID_HANDLE_VALUE,output=INVALID_HANDLE_VALUE;
+    HWND farWindow{};
+    HWND owner=CreateWindowExW(0,L"STATIC",L"Far snippet fixture clipboard",0,0,0,0,0,HWND_MESSAGE,nullptr,instance,nullptr);
+    auto originalForeground=GetForegroundWindow();
+    int result=1;
+    try {
+        saved=ks::readClipboard(owner,128*1024*1024);captured=true;
+        auto sentinel=ks::textClip(L"KSwitcher Far fixture clipboard");
+        sentinel.formats.push_back({0,L"ExcludeClipboardContentFromMonitorProcessing",ks::Bytes{0}});
+        ks::writeClipboard(owner,sentinel);
+        const auto programFiles=_wgetenv(L"ProgramFiles");
+        if(!programFiles)throw std::runtime_error("ProgramFiles is unavailable");
+        auto farExecutable=std::filesystem::path(programFiles)/L"Far Manager/Far.exe";
+        std::wstring command=L"\""+farExecutable.wstring()+L"\" -m -p -s \""+folder.wstring()+L"\\profile\" \""+folder.wstring()+L"\"";
+        STARTUPINFOW startup{sizeof(startup)};startup.dwFlags=STARTF_USESHOWWINDOW;startup.wShowWindow=SW_HIDE;
+        require(CreateProcessW(nullptr,command.data(),nullptr,nullptr,FALSE,CREATE_NEW_CONSOLE,nullptr,folder.c_str(),&startup,&child),"start isolated Far without plugins/macros");
+        CloseHandle(child.hThread);Sleep(1800);
+        require(AttachConsole(child.dwProcessId),"attach isolated console for test-only input and observation");
+        input=CreateFileW(L"CONIN$",GENERIC_READ|GENERIC_WRITE,FILE_SHARE_READ|FILE_SHARE_WRITE,nullptr,OPEN_EXISTING,0,nullptr);
+        output=CreateFileW(L"CONOUT$",GENERIC_READ|GENERIC_WRITE,FILE_SHARE_READ|FILE_SHARE_WRITE,nullptr,OPEN_EXISTING,0,nullptr);
+        require(input!=INVALID_HANDLE_VALUE && output!=INVALID_HANDLE_VALUE,"open isolated console buffers");
+        auto target=GetConsoleWindow();farWindow=target;ShowWindow(target,SW_SHOW);
+        require(ks::activateWindow(target),"activate only the isolated Far window");
+        auto key=[&](WORD vk,wchar_t c=0,DWORD mods=0) {
+            INPUT_RECORD records[2]{};
+            for(int i=0;i<2;++i) {
+                auto &r=records[i];r.EventType=KEY_EVENT;
+                r.Event.KeyEvent={BOOL(i==0),1,vk,WORD(MapVirtualKeyW(vk,MAPVK_VK_TO_VSC)),{c},mods};
+            }
+            DWORD written{};
+            if(!WriteConsoleInputW(input,records,2,&written)||written!=2)throw std::runtime_error("test input failed");
+            Sleep(60);
+        };
+        auto position=[&] {CONSOLE_SCREEN_BUFFER_INFO info{};if(!GetConsoleScreenBufferInfo(output,&info))throw std::runtime_error("console position unavailable");return info.dwCursorPosition;};
+        auto row=[&] {
+            CONSOLE_SCREEN_BUFFER_INFO info{};GetConsoleScreenBufferInfo(output,&info);
+            std::wstring text(info.dwSize.X,L' ');DWORD count{};
+            if(!ReadConsoleOutputCharacterW(output,text.data(),DWORD(text.size()),{0,info.dwCursorPosition.Y},&count))throw std::runtime_error("console row unavailable");
+            return text;
+        };
+        {
+            ks::App app(instance,false,folder/L"data");app.window=owner;
+            app.settings.history=false;app.settings.autoCorrect=false;app.settings.writeLog=true;
+            auto prepare=[&](wchar_t last=L'r') {
+                if(!ks::activateWindow(target))throw std::runtime_error("isolated Far lost foreground");
+                key(VK_ESCAPE);key('Y',0,LEFT_CTRL_PRESSED);key(VK_OEM_1,L':',SHIFT_PRESSED);key(WORD(towupper(last)),last);
+                app.run.reset();app.run.window=target;app.run.layout=ks::windowLayout(target);
+                app.run.at=GetTickCount64();app.run.keys=L":r";
+            };
+            auto expand=[&](const std::wstring &replacement) {
+                app.settings.snippets={{L":r",replacement}};
+                app.transform(0,0);ks::InputRegressionAccess::runQueued(app);Sleep(120);
+            };
+            for(int panels=0;panels<2;++panels) {
+                prepare();auto before=position();auto original=row();expand(L"rider .");
+                auto expected=original;expected.replace(before.X-2,2,L"rider .");expected.resize(original.size());
+                // Far's rightmost scroll indicator is redrawn rather than shifted.
+                require(row().substr(0,before.X+5)==expected.substr(0,before.X+5),"actual snippet replaces :r with rider .");
+                require(position().X==before.X+5,"successful expansion leaves cursor after replacement");
+                require(ks::readClipboard(owner).text()==sentinel.text(),"snippet restores original clipboard");
+                prepare(L'x');before=position();original=row();expand(L"rider .{enter}");
+                require(row()==original && position().X==before.X,"mismatched trigger restores original caret and never executes Enter");
+                prepare();before=position();original=row();expand(L"left{cursor}right");
+                require(row().substr(before.X-2,9)==L"leftright" && position().X==before.X+2,"cursor marker uses Far selection semantics");
+                prepare();before=position();original=row();expand(L"first\nsecond{enter}");
+                require(row()==original && position().X==before.X,"multiline console template rejected before changing text or caret");
+                prepare();before=position();original=row();expand(L"echo KSWITCHER_FAR_FIXTURE{enter}");
+                for(int wait=0;wait<30 && position().X!=before.X-2;++wait)Sleep(100);
+                require(position().X==before.X-2 && row().substr(before.X-2,2)==L"  ",
+                        "verified Enter runs only the harmless fixture echo and returns to an empty command line");
+                key('O',0,LEFT_CTRL_PRESSED);
+            }
+            app.window=nullptr;
+        }
+        log<<"Passed "<<checks<<" Far snippet integration checks\n";result=0;
+    }catch(const std::exception &e){log<<"FAIL "<<e.what()<<" win32="<<GetLastError()<<'\n';}
+    // A real user or clipboard synchronizer can copy during this explicit test.
+    // Never replace that newer content with the fixture's original snapshot.
+    const auto restoreSequence=GetClipboardSequenceNumber();
+    const bool restoreClipboard=GetClipboardOwner()==owner || (farWindow && ks::ownsClipboard(farWindow));
+    if(input!=INVALID_HANDLE_VALUE)CloseHandle(input);
+    if(output!=INVALID_HANDLE_VALUE)CloseHandle(output);
+    FreeConsole();
+    if(child.hProcess){TerminateProcess(child.hProcess,0);WaitForSingleObject(child.hProcess,5000);CloseHandle(child.hProcess);}
+    if(captured && restoreClipboard && GetClipboardSequenceNumber()==restoreSequence)
+        try{ks::writeClipboard(owner,saved);}catch(...){result=1;}
+    DestroyWindow(owner);
+    if(IsWindow(originalForeground))ks::activateWindow(originalForeground);
+    CoUninitialize();return result;
+}

tests/history_host.cpp

@@ -112,9 +112,24 @@ int main() {
         auto w=open();send(w,WM_COMMAND,112);
         until([&]{history.reload();return history.entries().front().pinned;},"resident pin mutation");
         require(history.entries().front().id==textId,"pin preserves history identity");
+        auto filter=[&](HWND window,int index) {
+            auto checkbox=GetDlgItem(window,117);
+            if(send(checkbox,BM_GETCHECK)!=(index ? BST_CHECKED : BST_UNCHECKED)) send(checkbox,BM_CLICK);
+        };
+        filter(w,1);
+        until([&]{return send(GetDlgItem(w,102),LB_GETCOUNT)==1;},"pinned filter hides unpinned entries");
+        send(GetDlgItem(w,101),WM_SETTEXT,0,LPARAM(L"History fixture 497"));
+        until([&]{return send(GetDlgItem(w,102),LB_GETCOUNT)==0;},"search cannot match an unpinned item in pinned view");
         send(GetDlgItem(w,101),WM_SETTEXT,0,LPARAM(L"History fixture 498"));
         until([&]{return send(GetDlgItem(w,102),LB_GETCOUNT)==1;},"history search");
+        send(w,WM_COMMAND,112);
+        until([&]{return send(GetDlgItem(w,102),LB_GETCOUNT)==0;},"unpin removes the last pinned result");
+        filter(w,0);
+        until([&]{return send(GetDlgItem(w,102),LB_GETCOUNT)==1;},"all items restores the matching unpinned entry");
+        send(w,WM_COMMAND,112);
+        filter(w,1);
         close(w);w=open();
+        require(send(GetDlgItem(w,117),BM_GETCHECK)==BST_CHECKED,"pinned checkbox survives helper restart");
         wchar_t query[100]{};send(GetDlgItem(w,101),WM_GETTEXT,100,LPARAM(query));
         require(std::wstring(query)==L"History fixture 498","search survives helper restart");
         send(w,WM_COMMAND,114);
@@ -124,7 +139,7 @@ int main() {
         require(WaitForSingleObject(child,0)==WAIT_TIMEOUT && IsWindow(entry),"full item remains usable after closing history");
         send(entry,WM_CLOSE);
         until([&]{return WaitForSingleObject(child,0)==WAIT_OBJECT_0;},"helper exits after last full item closes");CloseHandle(child);
-        w=open();send(GetDlgItem(w,101),WM_SETTEXT,0,LPARAM(L""));
+        w=open();filter(w,0);send(GetDlgItem(w,101),WM_SETTEXT,0,LPARAM(L""));
         until([&]{return send(GetDlgItem(w,102),LB_GETCOUNT)==500;},"clear search");close(w);
         ks::writeClipboard(target,excluded(image));
         w=open();send(w,WM_COMMAND,111);

tests/input.cpp

@@ -2,6 +2,7 @@
 #include "ui_scroll.h"
 #include "ui_geometry.h"
 #include "screenshot.h"
+#include "ocr.h"
 #include <commctrl.h>
 #include <iostream>
 #include <cmath>
@@ -94,6 +95,9 @@ struct InputRegressionAccess {
     }
     static void notificationSetup(App &a) { a.updateNotifier = notify; }
     static void setup(App &a) { a.hookBindings = {{Toggle,{MOD_CONTROL,VK_F12}}, {Case,{MOD_CONTROL|MOD_SHIFT,'U'}}}; }
+    static LRESULT routedKey(int code, UINT message, const KBDLLHOOKSTRUCT &key, LRESULT routed) {
+        return App::keyboardAfterHooks(code,message,(LPARAM)&key,routed);
+    }
     static bool updateTimer(App &a) {
         a.updateRunning=true; // Exercise timer scheduling without launching a network request.
         App::windowProc(a.window,WM_TIMER,5,0);
@@ -120,7 +124,7 @@ int main(int argc, char **argv) {
             return result.state == L"current" || result.state == L"available" ? 0 : 1;
         } catch (const std::exception &e) { std::cerr << e.what() << '\n'; return 1; }
     }
-    auto temp=std::filesystem::temp_directory_path()/(L"KSwitcher-input-tests-"+std::to_wstring(GetCurrentProcessId()));
+    auto temp=std::filesystem::temp_directory_path()/(L"KSwitcher-input-tests-"+ks::newSnippetId());
     int checks=0;
     auto require=[&](bool ok,const char* text) { if(!ok) throw std::runtime_error(text); ++checks; };
     try {
@@ -648,6 +652,22 @@ int main(int argc, char **argv) {
             };
             auto commands=[&] { MSG m{}; int n=0; while(PeekMessageW(&m,app.window,WM_HOTKEY,WM_HOTKEY,PM_REMOVE)) ++n; return n; };
             auto f12=event(VK_F12);
+            {
+                const auto before = app.inputVersion.load();
+                const auto recorded = app.run.keys;
+                for (UINT message : {WM_KEYDOWN, WM_KEYUP, WM_SYSKEYDOWN, WM_SYSKEYUP})
+                    require(ks::InputRegressionAccess::routedKey(HC_ACTION,message,event('A',30),7)==7,
+                            "forwarded keyboard events preserve downstream suppression");
+                require(app.inputVersion==before && app.run.keys==recorded && commands()==0,
+                        "forwarded events never track text, invalidate transactions or dispatch shortcuts");
+                require(ks::InputRegressionAccess::routedKey(-1,WM_KEYDOWN,event('A',30),0)==0 &&
+                        app.inputVersion==before,"negative hook codes do not process keyboard input");
+                require(ks::InputRegressionAccess::routedKey(HC_ACTION,WM_KEYDOWN,event('A',30,true),0)==0 &&
+                        app.inputVersion==before,"own input remains excluded after downstream routing");
+                require(ks::InputRegressionAccess::routedKey(HC_ACTION,WM_KEYDOWN,event('A',30),0)==0 &&
+                        app.inputVersion>before,"delivered remote input is still processed on the receiver");
+                app.run.reset();
+            }
             require(!app.handleKeyboard(event(VK_LCONTROL),true,0),"remote modifier passes through");
             require(app.handleKeyboard(f12,true,MOD_CONTROL),"remote Ctrl+F12 handled");
             require(app.handleKeyboard(f12,true,MOD_CONTROL),"remote repeat suppressed");
@@ -961,6 +981,22 @@ int main(int argc, char **argv) {
                 require(pumpUntil(2),"history reloads after releasing hidden rows");
                 require(SendDlgItemMessageW(history,102,LB_GETCURSEL,0,0)==1,
                         "history retains selected record across close and reload");
+                SendMessageW(history,WM_CLOSE,0,0);
+                ks::Pixels screenshot{2,2,ks::Bytes(16,255)};
+                app.history->add(ks::Clip{{ks::imageDib(screenshot)}},L"screenshot",app.settings);
+                require(app.history->entries().front().image,"new screenshot is the newest history entry");
+                ks::showHistory(app);
+                require(pumpUntil(3),"reopening history loads the new screenshot");
+                require(SendDlgItemMessageW(history,102,LB_GETCURSEL,0,0)==0 &&
+                        SendDlgItemMessageW(history,102,LB_GETTOPINDEX,0,0)==0,
+                        "fresh history invocation selects and reveals newest screenshot instead of saved selection");
+                SendDlgItemMessageW(history,102,LB_SETCURSEL,2,0);
+                app.history->add(ks::textClip(L"background clipboard update"),L"test",app.settings);
+                ks::refreshHistory(app);
+                require(pumpUntil(4),"background refresh loads a new item");
+                require(SendDlgItemMessageW(history,102,LB_GETCURSEL,0,0)==3,
+                        "background refresh preserves the selected record while browsing");
+                ShowWindow(history,SW_HIDE);
             }
             auto childRect=[&](int id) { RECT r{}; GetWindowRect(GetDlgItem(history,id),&r); MapWindowPoints(nullptr,history,(POINT*)&r,2); return r; };
             RECT historyFrame{}; GetWindowRect(history,&historyFrame);

tests/integration.cpp

@@ -33,6 +33,17 @@ bool trimCopiedSpaces = false;
 int trimmedCopies = 0;
 bool temporaryClipboardExcluded = true;
 bool clipboardAccessTimedOut = false;
+uint64_t forwardedVersion{};
+int forwardedEvents{};
+LRESULT CALLBACK forwardingHook(int code, WPARAM wp, LPARAM lp)
+{
+    if (code == HC_ACTION && reinterpret_cast<KBDLLHOOKSTRUCT *>(lp)->dwExtraInfo == 456)
+    {
+        ++forwardedEvents;
+        return 1; // Model MWB consuming source input routed to another machine.
+    }
+    return CallNextHookEx(nullptr, code, wp, lp);
+}
 LRESULT CALLBACK observeEnter(HWND w, UINT message, WPARAM wp, LPARAM lp, UINT_PTR, DWORD_PTR)
 {
     if (message == WM_KEYDOWN && wp == VK_LEFT && droppedSelectionKeys > 0 &&
@@ -577,10 +588,41 @@ LRESULT CALLBACK procedure(HWND w, UINT msg, WPARAM wp, LPARAM lp)
                 require(ks::readClipboard(app->window).text() == sentinel, "selected and repeated conversions restore clipboard");
                 finish();
                 break;
+            case 62:
+                saved = ks::readClipboard(app->window, 64 * 1024 * 1024);
+                captured = true;
+                app->ownSequence = ks::writeClipboard(app->window, ks::textClip(sentinel));
+                app->settings.snippets = {{L";r", L"unexpected{enter}"}};
+                ActivateKeyboardLayout(app->layouts[en].handle, 0);
+                prepare(L"prefix ", false);
+                forwardedVersion = app->inputVersion.load();
+                copyRequests = forwardedEvents = 0;
+                {
+                    std::vector<INPUT> inputs;
+                    for (WORD key : {WORD(VK_OEM_1), WORD('R')})
+                        for (DWORD flags : {DWORD(0), DWORD(KEYEVENTF_KEYUP)})
+                        {
+                            auto input = ks::keyboardInput(key, flags);
+                            input.ki.dwExtraInfo = 456;
+                            inputs.push_back(input);
+                        }
+                    require(SendInput((UINT)inputs.size(),inputs.data(),sizeof(INPUT))==inputs.size(),
+                            "forwarded snippet input submitted to real hook chain");
+                }
+                break;
+            case 63:
+                require(forwardedEvents==4,"downstream forwarding hook consumed every key event");
+                require(app->inputVersion==forwardedVersion && copyRequests==0,
+                        "forwarded snippet does not start tracking or clipboard work on source computer");
+                require(text()==L"prefix " && ks::readClipboard(app->window).text()==sentinel,
+                        "forwarded snippet leaves source editor and clipboard untouched");
+                stage = 30;
+                break;
             case 30:
             case 32:
             case 34:
             case 37:
+            case 60:
                 // Earlier password/word tests replace the original multiline
                 // editor with a single-line EDIT. Restore the snippet fixture:
                 // a single-line control cannot insert the tested Enter action.
@@ -609,6 +651,11 @@ LRESULT CALLBACK procedure(HWND w, UINT msg, WPARAM wp, LPARAM lp)
                 enterPresses = 0;
                 copyRequests = 0;
                 copyFailuresRemaining = stage == 38 ? 10 : stage == 33 ? 1 : 0;
+                if (stage == 61)
+                {
+                    pasteBehavior = 2; // Editor inserts unrelated clipboard text.
+                    app->settings.writeLog = false;
+                }
                 temporaryClipboardExcluded = true;
                 ActivateKeyboardLayout(app->layouts[en].handle, 0);
                 prepare(L"prefix ", false);
@@ -672,6 +719,13 @@ LRESULT CALLBACK procedure(HWND w, UINT msg, WPARAM wp, LPARAM lp)
                 require(ks::readClipboard(app->window).text() == sentinel,
                         "exhausted copy retries restore the clipboard");
                 copyFailuresRemaining = 0;
+                stage = 60;
+                break;
+            case 61:
+                require(text() == L"prefix other! x", "incorrect snippet paste preserves following typing");
+                require(enterPresses == 0, "unverified snippet never submits Enter even without logging");
+                require(ks::readClipboard(app->window).text() == sentinel, "rejected snippet restores clipboard");
+                pasteBehavior = 0;
                 finish();
                 break;
             case 20:
@@ -985,9 +1039,12 @@ int main(int argc, char **argv)
             if (typosOnly || (argc > 1 && std::string(argv[1]) == "--typing-only"))
                 stage = 20;
             if (argc > 1 && std::string(argv[1]) == "--snippets-only")
-                stage = 30;
+                stage = 62;
             SetTimer(host, 1, 100, nullptr);
+            auto forwarding = SetWindowsHookExW(WH_KEYBOARD_LL,forwardingHook,GetModuleHandleW(nullptr),0);
+            require(forwarding!=nullptr,"downstream forwarding fixture installed before application hook");
             app->execute();
+            UnhookWindowsHookEx(forwarding);
         }
         std::filesystem::remove_all(root);
     }

tests/tests.cpp

@@ -517,6 +517,24 @@ int main(int argc, char **argv)
         auto encoded = ks::encodeClip(clip);
         require(ks::decodeClip(encoded).text() == clip.text(), "clipboard Unicode roundtrip");
         require(ks::decodeClip(encoded).formats[1].name == L"HTML Format", "registered format identity");
+        auto selection = ks::textClip(L";pa");
+        selection.formats.push_back({0, L"vscode-editor-data", {1, 2, 3}});
+        auto relayed = selection;
+        relayed.formats.front().data.resize(128, 0xab);
+        std::reverse(relayed.formats.begin(), relayed.formats.end());
+        require(ks::selectionClipboardIdentity(selection) == ks::selectionClipboardIdentity(relayed),
+                "clipboard relay tolerates Unicode allocation slack and format order");
+        relayed.formats.front().data[0] ^= 1;
+        require(ks::selectionClipboardIdentity(selection) != ks::selectionClipboardIdentity(relayed),
+                "clipboard relay rejects changed editor metadata");
+        relayed = selection;
+        relayed.formats.pop_back();
+        require(ks::selectionClipboardIdentity(selection) != ks::selectionClipboardIdentity(relayed),
+                "clipboard relay rejects missing editor metadata");
+        relayed = selection;
+        relayed.formats.front() = ks::textClip(L";pb").formats.front();
+        require(ks::selectionClipboardIdentity(selection) != ks::selectionClipboardIdentity(relayed),
+                "clipboard relay rejects changed Unicode text");
         auto encrypted = ks::protect(encoded);
         require(encrypted != encoded, "history ciphertext differs");
         require(ks::unprotect(encrypted) == encoded, "Windows DPAPI roundtrip");

tests/update.ps1

@@ -50,6 +50,8 @@ try {
     foreach ($name in @('LICENSE','json-LICENSE.txt','README.md')) { [IO.File]::WriteAllText((Join-Path $source $name),'fixture') }
     [IO.Directory]::CreateDirectory((Join-Path $source 'dictionaries')) | Out-Null
     [IO.File]::WriteAllText((Join-Path $source 'dictionaries/en.txt'),'new dictionary')
+    [IO.Directory]::CreateDirectory((Join-Path $source 'tools')) | Out-Null
+    [IO.File]::WriteAllText((Join-Path $source 'tools/README.txt'),'portable utilities instructions')
     function Write-TestManifest($Folder) {
         $entries=@(Get-ChildItem -LiteralPath $Folder -File -Recurse | Where-Object Name -ne 'release-files.json' | ForEach-Object {
             @{path=$_.FullName.Substring($Folder.Length+1).Replace('\','/');size=$_.Length;sha256=(Get-FileHash -LiteralPath $_.FullName).Hash}
@@ -92,8 +94,17 @@ try {
     $null=$z.CreateEntry('undeclared.dll'); $z.Dispose()
     Reject { Expand-Release $extra (Join-Path $root 'extrastage') $binaryVersion } 'undeclared file rejected'
     $target=Join-Path $root 'install'; $backup=Join-Path $root 'backup'
+    $freshTarget=Join-Path $root 'fresh-install'
+    [IO.Directory]::CreateDirectory($freshTarget) | Out-Null
+    $freshChanges=[Collections.Generic.List[string]]::new()
+    $freshStage=Join-Path $root 'fresh-stage'
+    Copy-Item -LiteralPath $stage -Destination $freshStage -Recurse
+    Install-Files $freshStage $freshTarget (Join-Path $root 'fresh-backup') $freshChanges
+    Assert (Test-Path -LiteralPath (Join-Path $freshTarget 'tools/README.txt')) 'update creates portable tools folder'
     [IO.Directory]::CreateDirectory((Join-Path $target 'data')) | Out-Null
     [IO.Directory]::CreateDirectory((Join-Path $target 'dictionaries')) | Out-Null
+    [IO.Directory]::CreateDirectory((Join-Path $target 'tools')) | Out-Null
+    [IO.File]::WriteAllText((Join-Path $target 'tools/Personal.exe'),'personal utility fixture')
     [IO.File]::WriteAllText((Join-Path $target 'data/settings.json'),'personal settings')
     [IO.File]::WriteAllText((Join-Path $target 'dictionaries/en.txt'),'personal dictionary')
     [IO.File]::WriteAllText((Join-Path $target 'KSwitcher.exe'),'old binary fixture')
@@ -105,9 +116,12 @@ try {
     }
     Assert ([IO.File]::ReadAllText((Join-Path $target 'future-tool.exe')) -eq 'future companion fixture') 'new companion name installs without changing updater'
     Assert ([IO.File]::ReadAllText((Join-Path $target 'data/settings.json')) -eq 'personal settings') 'settings preserved'
+    Assert ([IO.File]::ReadAllText((Join-Path $target 'tools/Personal.exe')) -eq 'personal utility fixture') 'personal utilities preserved'
+    Assert ([IO.File]::ReadAllText((Join-Path $target 'tools/README.txt')) -eq 'portable utilities instructions') 'bundled tools documentation installed'
     Assert ([IO.File]::ReadAllText((Join-Path $target 'dictionaries/en.txt')) -eq 'personal dictionary') 'dictionary preserved'
     Undo-Files $target $backup $changed
     Assert ([IO.File]::ReadAllText((Join-Path $target 'KSwitcher.exe')) -eq 'old binary fixture') 'rollback restores original'
+    Assert ([IO.File]::ReadAllText((Join-Path $target 'tools/Personal.exe')) -eq 'personal utility fixture') 'rollback preserves personal utilities'
     Assert (!(Test-Path -LiteralPath (Join-Path $target 'README.md'))) 'rollback removes newly introduced files'
     Assert (!(Test-Path -LiteralPath (Join-Path $target 'KSwitcher.Config.exe'))) 'rollback removes newly introduced configurator'
     Assert (!(Test-Path -LiteralPath (Join-Path $target 'KSwitcher.Screenshot.exe'))) 'rollback removes newly introduced screenshot editor'

tests/utilities.cpp

@@ -0,0 +1,43 @@
+#include <windows.h>
+#include "../src/utilities.h"
+#include <fstream>
+#include <iostream>
+#include <stdexcept>
+
+int main()
+{
+    namespace fs = std::filesystem;
+    auto root = fs::temp_directory_path() / (L"KSwitcher-utilities-" + std::to_wstring(GetCurrentProcessId()));
+    try
+    {
+        std::error_code error;
+        if (!ks::discoverUtilities(root / L"missing", error).empty() || error)
+            throw std::runtime_error("Missing folder must be empty, not an error");
+        fs::create_directories(root / L"tools" / L"nested");
+        fs::create_directory(root / L"tools" / L"directory.exe");
+        for (auto name : {L"Zed.exe", L"alpha.EXE", L"A & B.exe", L"readme.txt", L"shortcut.lnk"})
+            std::ofstream(root / L"tools" / name).put('x');
+        std::ofstream(root / L"tools" / L"nested" / L"hidden.exe").put('x');
+        auto found = ks::discoverUtilities(root / L"tools", error);
+        if (error || found.size() != 3 || found[0].filename() != L"A & B.exe" ||
+            found[1].filename() != L"alpha.EXE" || found[2].filename() != L"Zed.exe")
+            throw std::runtime_error("Scan must filter direct executable files and sort names");
+        if (ks::utilityMenuLabel(found[0]) != L"A && B")
+            throw std::runtime_error("Ampersand must be displayed literally");
+        fs::remove(found[1]);
+        if (ks::discoverUtilities(root / L"tools", error).size() != 2)
+            throw std::runtime_error("Scan must refresh after a file is removed");
+        ks::discoverUtilities(root / L"tools" / L"readme.txt", error);
+        if (!error) throw std::runtime_error("Non-directory must report an error");
+        fs::remove_all(root);
+        std::cout << "Utilities regression tests passed\n";
+        return 0;
+    }
+    catch (const std::exception &e)
+    {
+        std::error_code ignored;
+        fs::remove_all(root, ignored);
+        std::cerr << e.what() << '\n';
+        return 1;
+    }
+}