Windows integrations

A Windows app is a set of entry points around the system, not one window. This skill picks the API for each entry point and the limit it runs into. Code for every row marked "recipe" is in recipes.md. Rows marked with another file have their code there:

• overlays.md: borderless and click-through overlay windows, placing panels, capture exclusion, the low-level mouse hook.
• capture.md: screen freeze, pickers, screen recording to MP4, live window thumbnails, and testing captures safely.
• system.md: the window list for a switcher, app icons, Windows Search, live tray icons, UI Automation, power requests, process command lines and ports.

Pick the API

Prefer the row with no limit when two rows solve the same job.

From macOS permissions to Windows limits

BAMA's Mac apps ask for permissions. Windows asks for almost none, and has other walls instead:

Limits the user can see

• Ask nothing up front. Show a limit at the moment it bites, in one line that says what broke and what to do: "This window runs as administrator. MyApp cannot paste into it."
• Show the state of every hook on one Settings page: the hotkey (works, or "used by another app"), launch at login (on, off, or "turned off in Task Manager"), notifications (AppNotificationManager.Default.Setting), the capture border (read with CheckAccess, which never prompts), and the tray icon. Each gets a button that fixes it or opens the right page: ms-settings:startupapps, ms-settings:notifications, ms-settings:privacy-microphone, ms-settings:privacy-webcam.
• Read the state when Settings opens and when the window gets focus. Windows calls nothing when the user changes these elsewhere.
• Run as the normal user. Never mark the app requireAdministrator.

Tray icons, taskbar, and toasts

• A tray icon shows a menu on right-click and opens the main window on left-click or Enter. Its .ico has 16, 20, 24, and 32 px sizes that read on light and dark taskbars. People can turn it off in Settings, and nothing is reachable only through it: the main window and the agent CLI offer the same actions.
• Tell the user once how to pin the icon: Settings > Personalization > Taskbar > Other system tray icons. The app cannot pin itself.
• A toast says one thing that happened, with a click that opens the exact place. Never put anything in a toast that the app does not also show.
• A note meant for the person while they record (a "Keystrokes on" pill) is an overlay excluded from capture, not a toast: toasts land in the recording and in the notification center.
• Badge the taskbar button (ITaskbarList3.SetOverlayIcon) only with a count of unread items.

The install path keeps registrations

The Run key, the URL protocol, the toast registration, and every tray icon store the exe's path. To keep them working across rebuilds:

• Install to the same path every time. build.ps1 installs to %LOCALAPPDATA%\Programs\<App>\<App>.exe.
• Register from the installed exe only, never from a build folder or a test run (APP_STORE set). That includes NIM_ADD: Windows 11 writes a key per exe path and icon id under HKCU\Control Panel\NotifyIconSettings and never removes it. One dev PC had dozens of entries for old dev folders. A test run draws its icons but never adds them.
• Remove every registration in the uninstall step: the Run value, the HKCU\Software\Classes\<scheme> key, and AppNotificationManager.Default.UnregisterAll().
• Files built on this PC carry no Mark of the Web, so SmartScreen does not warn about them. A copy downloaded from the internet gets a warning until it is signed (ship stage).

If a hook works from the build folder but not after install, a registration still points at the old path. Remove it and register again from the installed exe.

Suites

In a PowerToys-shaped app (one tray app, many features), the host owns every integration that Windows allows only once per process or per person, and features subscribe. The new-windows-app skill's suite.md has the whole shape. For integrations:

The shared keyboard hook is the one that matters most. Windows removes a hook that takes over a second, and ten hooks in one process are ten chances. The shape:

public readonly record struct KeyEvent(int VirtualKey, int ScanCode, bool Down, bool Injected,
    bool AltDown, uint Time, bool Extended, nuint ExtraInfo);

// In a feature's Start, and Dispose in Stop:
_subscription = Host.Input.Subscribe(e =>
{
    if (e.Injected && e.ExtraInfo == MyMarker) return false;   // our own SendInput
    _queue.Enqueue(e);                                          // copy, then return at once
    Host.Dispatcher.TryEnqueue(Drain);
    return false;                                               // true only to swallow the key
});

Rules for the shared hook:

• The event carries everything a subscriber needs: the injected flag, the extended-key flag (for key names and keypad Enter), Alt, and dwExtraInfo. Each feature filters for itself: the keystroke overlay drops injected keys, a switcher may want them. A first version without Extended and ExtraInfo pushed two features into workarounds.
• Expose a subscriber count, so a feature's self-test can check that its own subscription went away while others still listen.
• Other one-per-process jobs follow the same rule: a feature that needs a mouse hook, a clipboard listener, or a message window brings one only until the host has one. Move it into the host when a second feature needs it.
• Run background samplers with EcoQoS on their own thread, never on the whole process: a throttled process slows every other feature (performance skill, "Timers, polling, and energy").

Make every feature reachable three ways

Each feature gets: a command with a KeyboardAccelerator, a URL (<app>://action/<name>), and an agent CLI command (agent-cli skill). The same action enum backs all three, so a new action shows up everywhere at once. Add a self-test check that every action has a command label, a URL name, and a CLI command. The URL and the CLI also let test-windows-app drive the feature from a script.

Self-tests of these integrations act only on the app's own test windows: feed hook handlers synthetic events, read captures from a test window, and check GetForegroundWindow before every SendInput. Each recipe ends with how it was tested safely.

Done when every entry point in the brief's "System hooks" works from a clean install, Settings shows the state of every hook it needs, and no test run left a registration or a tray icon entry behind.