hrynco-kswitcher/README.md

# KSwitcher

Native C++20 / Win32 rewrite of the Windows functionality of Typlo. Windows 10/11 x64.
No .NET, Avalonia, WebView, Qt, external graphics engine, or separately installed C++ runtime.
The original Typlo project and its data remain separate.

## Run

Run `build/KSwitcher.exe`, or extract `dist/KSwitcher-win-x64.zip` and run the executable.
The build also refreshes the release copy in `build/release/`. Exit KSwitcher before rebuilding.
The application lives in the notification area. Right-click its icon for Settings, Snippets and history.
Double-click the tray icon to open Settings, the bold default menu item.
In Settings, enable **Start with Windows** and **Start with Windows as administrator**
to use a per-user Task Scheduler logon task with highest privileges. Enabling or changing
the elevated task requests UAC approval if the app is not already elevated. No password is stored;
the task runs in the signed-in user's interactive session, including on battery power.
Disabling the administrator option restores ordinary per-user startup; disabling startup stops
future automatic launches. Saving unrelated settings does not recreate startup entries.
`KSwitcher.exe --settings` opens Settings, including when the app is already running.
Exit Typlo when using overlapping shortcuts to avoid competing keyboard hooks.

### Change a shortcut

1. Open **Settings** and click a shortcut field.
2. Press the desired combination. The field records the actual keys; no typing of names is needed.
3. Click **Save**. Duplicate shortcuts within KSwitcher and protected Windows combinations are reported.

This also works for each layout's **Direct layout shortcut**. Backspace or Delete without modifiers
clears a shortcut. Tab moves to the next field. The recorded shortcut is suppressed while the field
has focus, so recording the conversion shortcut does not perform a conversion.
All configured shortcuts use the existing keyboard hook and can replace ordinary Windows/app
shortcuts, including **Win+V** and **Win+Shift+S**, while KSwitcher is running. Only exact configured
combinations are intercepted. Unassigned shortcuts and simulated copy/paste pass through.
Choose another shortcut or exit KSwitcher to restore the original action. Windows protects
Ctrl+Alt+Delete and Win+L; these cannot be assigned.

## Implemented

- Installed Windows keyboard layouts, configurable cycle/order and direct shortcuts; IMEs are switch-only.
- 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.
- 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.
- Case cycling, Russian/Ukrainian transliteration, verified undo and repeated conversion.
- Text snippets across layouts, multiline insertion and a verified `{cursor}` position;
  `{{cursor}}` inserts the literal marker. Snippets are stored as plaintext settings, as in Typlo.
- Clipboard history for text, HTML/RTF, file lists, DIB and PNG images; plain-text paste;
  full-text search, pinning, deletion, full text viewing and image previews.
- Image thumbnails and text/file icons appear directly in the history list. Only visible rows
  load thumbnails; the 32-entry thumbnail cache is bounded to about 3.3 MiB and released on close.
- Text rows render RTF and basic clipboard HTML emphasis (bold, italic, underline, strike-through),
  paragraphs, line breaks and list bullets using native Windows RichEdit. Previews are bounded to
  4096 characters / 64 KiB RTF, with at most 32 cached text previews; original paste formats are unchanged.
  HTML is parsed as text, without a browser, scripts or external resources. Complex web layouts and
  stylesheet rules are not reproduced; preview text uses the list's colors for readability.
- Consecutive screenshot copies are compared by image content, ignoring changing OLE transport
  metadata (including Snipping Tool's repeated clipboard publication).
- Windows OCR, entirely native and offline. Right-click an image in history and select
  **Copy text from image**. Requires a Windows OCR language installed for the user profile.
- History exclusion flags and excluded processes, pause/resume, count/size limits.
- Per-user Windows DPAPI encryption for both history payloads and the preview index.
- Autostart, keep-screen-awake, idle-only F15 activity signal, settings import/export.
- Single instance and `--history`, `--convert`, `--case`, `--transliterate`, `--settings`,
  `--snippets`, `--exit` commands. `--convert` cycles layouts.

Default shortcuts match Typlo: Ctrl+Alt+Shift+Space (cycle), C (case), T (transliteration),
Z (undo), 1/2/3 (first layouts), and Ctrl+Shift+V (history).

History controls: Enter to paste, Shift+Enter for plain text, Ctrl+1…9 for quick paste,
Ctrl+P to pin/unpin, Delete to delete, Ctrl+O for the full item, Escape to hide.
Pressing the history shortcut a second time pastes the second-most-recent item.

## Data and migration

Data is in `data/` beside the executable, falling back to `%LOCALAPPDATA%/KSwitcher` when
the executable's directory is not writable. Each clipboard payload is an encrypted disk file;
only bounded previews/metadata stay in memory. Image data is loaded on demand and released when
the history popup is hidden. The log contains operational messages, never copied text or keystrokes.

Settings **Import** accepts a Typlo `settings.json`, preserving supported Windows layout IDs,
hotkeys, snippets, exclusions and limits. Import is staged until Save. Existing Typlo files are
never modified. Typlo's encrypted SQLite history is **not migrated** to the new DPAPI file format.
DPAPI data belongs to the Windows account/machine; copying the portable folder is not a cross-account backup.

## Differences still to port

This is a working native implementation, not a claim of complete UI/release parity:

- UI currently uses English and the native Windows control appearance. Typlo's ten-language UI and
  explicit light/dark theme selector are not yet ported.
- Automatic release download/replacement is not enabled. KSwitcher has no configured release feed;
  using Typlo's feed would install the wrong application. Updates are manual.
- No import of old encrypted clipboard history. Export/import applies to settings.
- The clipboard popup is fixed-size with per-monitor DPI scaling; PNG/DIB previews use Windows WIC/GDI.

The Windows focus/injection rules still apply: an unelevated process cannot edit an elevated app.
Conversion is cancelled rather than pasting into a different window or replacing unverified recent text.

## Build

The easiest reproducible local route uses the pinned portable w64devkit toolchain:

```powershell
.\setup-toolchain.ps1
.\build.ps1 -Test
.\package.ps1
```

`setup-toolchain.ps1` downloads the compiler from its upstream GitHub release and verifies SHA-256.
`.tools/`, build objects, test executables and compiler headers are development-only. **Do not distribute
the entire source/build folder.** The package contains just the application and notices/documentation.
The vendored JSON header is nlohmann/json 3.12.0 (MIT); it is compiled into the executable.

Alternatively open this directory as a CMake project in Visual Studio with the C++ desktop workload
and Windows SDK installed, or use CMake with a Windows GCC toolchain. CMake/MSVC is provided but the
verified local build uses GCC/w64devkit.

## Verification

```powershell
.\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
```

The interactive test requires installed English-US and Russian layouts. It opens its own editor,
tests real copy/paste, undo, repeat conversion, recent-input verification and snippet cursor placement,
then restores the clipboard. Test data is stored in its own temporary directory. It never sends messages
to Teams or other user applications. Do not run it while typing elsewhere.

`KSwitcher.exe --smoke-test` starts a normal tray instance and exits after ten seconds for idle-memory checks.
It still uses the normal instance lock; close a running KSwitcher first if measuring a fresh process.

## Structure

- `core.*`: conversion, transliteration, snippets, shortcut parsing/formatting, recent-input model.
- `platform.*`: Win32 layouts, clipboard, input, ownership, DPAPI and file primitives.
- `storage.*`: settings and encrypted, disk-backed history.
- `app.*`: message loop, hooks, background work and guarded text transactions.
- `ui.cpp`: native windows and shortcut recording.
- `ocr.*`: Windows WIC and OCR via the native Windows Runtime ABI.
- `tests/`: regression checks, real editor integration and OCR fixture.

MIT licensed; preserves the original Typlo attribution in `LICENSE`.