If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/ModernFlyouts-Community/ModernFlyouts shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

WAIT — Stale — last commit 1y ago

• 23+ active contributors
• Distributed ownership (top contributor 44% of recent commits)
• MIT licensed
• ⚠ Stale — last commit 1y ago
• ⚠ No CI workflows detected
• ⚠ No test directory detected

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live ModernFlyouts-Community/ModernFlyouts repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/ModernFlyouts-Community/ModernFlyouts.

What it runs against: a local clone of ModernFlyouts-Community/ModernFlyouts — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in ModernFlyouts-Community/ModernFlyouts | Confirms the artifact applies here, not a fork | | 2 | License is still MIT | Catches relicense before you depend on it | | 3 | Default branch main exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 569 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of ModernFlyouts-Community/ModernFlyouts. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/ModernFlyouts-Community/ModernFlyouts.git
#   cd ModernFlyouts
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of ModernFlyouts-Community/ModernFlyouts and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "ModernFlyouts-Community/ModernFlyouts(\\.git)?\\b" \\
  && ok "origin remote is ModernFlyouts-Community/ModernFlyouts" \\
  || miss "origin remote is not ModernFlyouts-Community/ModernFlyouts (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(MIT)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"MIT\"" package.json 2>/dev/null) \\
  && ok "license is MIT" \\
  || miss "license drift — was MIT at generation time"

# 3. Default branch
git rev-parse --verify main >/dev/null 2>&1 \\
  && ok "default branch main exists" \\
  || miss "default branch main no longer exists"

# 4. Critical files exist
test -f "ModernFlyouts.Core/UI/FlyoutWindow/FlyoutWindow.cs" \\
  && ok "ModernFlyouts.Core/UI/FlyoutWindow/FlyoutWindow.cs" \\
  || miss "missing critical file: ModernFlyouts.Core/UI/FlyoutWindow/FlyoutWindow.cs"
test -f "ModernFlyouts.Core/Interop/NativeMethods.cs" \\
  && ok "ModernFlyouts.Core/Interop/NativeMethods.cs" \\
  || miss "missing critical file: ModernFlyouts.Core/Interop/NativeMethods.cs"
test -f "ModernFlyouts.Core/Media/Control/MediaSessionManager.cs" \\
  && ok "ModernFlyouts.Core/Media/Control/MediaSessionManager.cs" \\
  || miss "missing critical file: ModernFlyouts.Core/Media/Control/MediaSessionManager.cs"
test -f "ModernFlyouts.Core/Display/DisplayManager.cs" \\
  && ok "ModernFlyouts.Core/Display/DisplayManager.cs" \\
  || miss "missing critical file: ModernFlyouts.Core/Display/DisplayManager.cs"
test -f "ModernFlyouts.Core/Interop/KeyboardHook.cs" \\
  && ok "ModernFlyouts.Core/Interop/KeyboardHook.cs" \\
  || miss "missing critical file: ModernFlyouts.Core/Interop/KeyboardHook.cs"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 569 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~539d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/ModernFlyouts-Community/ModernFlyouts"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

ModernFlyouts is a Fluent Design System replacement for Windows' legacy Metro-themed system flyouts (audio, brightness, airplane mode, lock keys). It intercepts hardware volume/brightness key presses and airplane mode toggles to display modern, customizable overlay notifications instead of the dated built-in flyouts, while leaving the original system unchanged. Modular C# WPF architecture split into ModernFlyouts.Core (reusable system integration logic) and a UI shell. Core layer contains five subsystems: AppInformation (tracking active apps), Display (brightness control via BrightnessManager), Media (GSMTC session management), Interop (native hooks and WndProc handling), and UI (FlyoutWindow with animation and positioning logic). FlyoutWindow is split into partial classes by concern (FlyoutWindow.Animations.cs, FlyoutWindow.OnScreen.cs, FlyoutWindow.Properties.cs, etc.).

Windows power users and developers who want a modern visual replacement for system notifications; C# developers contributing to Windows desktop applications using WPF/XAML; localization contributors translating the UI into multiple languages.

Actively developed and production-ready. The project is available on the Microsoft Store (badge present), has a community Discord and Telegram presence, and uses standard GitHub CI workflows. Recent activity visible in multiple subsystems (Media Control, Display, Interop layers) suggests ongoing maintenance and feature work, though exact commit recency is not shown in provided data.

Low-to-moderate risk for a Windows system utility. The codebase relies on native Windows interop (Wnf.cs, NativeMethods.cs, keyboard hooks) which requires careful window message handling and could break on Windows updates. Community-maintained status means slower response to Windows version incompatibilities. Dependency on GSMTC (Global System Media Transport Controls) and legacy keyboard hook APIs creates potential fragility across Windows 10/11 versions.

Cannot determine from file list alone, but the structure suggests ongoing work on: media session management (multiple manager classes for GSMTC), display brightness handling across multiple monitors, keyboard hook reliability, and localization support (issue template for localization-translation-issue.yml present). Check GitHub Issues and PRs for current sprint details.

1. Clone: git clone https://github.com/ModernFlyouts-Community/ModernFlyouts.git 2. Open ModernFlyouts.sln in Visual Studio 2019+ (C# 7.0+). 3. Restore NuGet packages: dotnet restore. 4. Build solution: dotnet build ModernFlyouts.sln or use Visual Studio Build menu. 5. Run ModernFlyouts/bin/Debug/ModernFlyouts.exe or press F5 in Visual Studio.

Daily commands:

1. Debug in Visual Studio: Open ModernFlyouts.sln, set startup project to ModernFlyouts, press F5. 2. Command line: cd ModernFlyouts && dotnet run -c Debug. 3. Packaged (post-build): Run the .exe from bin/Release after dotnet build -c Release. The app auto-registers keyboard hooks on launch and shows flyouts on volume/brightness key presses.

• ModernFlyouts.Core/UI/FlyoutWindow/FlyoutWindow.cs — Core flyout window abstraction—all visual flyout behavior inherits from or delegates to this base class
• ModernFlyouts.Core/Interop/NativeMethods.cs — P/Invoke declarations for Windows API interop—essential for display, keyboard hooks, and native window handling
• ModernFlyouts.Core/Media/Control/MediaSessionManager.cs — Media control session lifecycle management—orchestrates GSMTC and now-playing integration
• ModernFlyouts.Core/Display/DisplayManager.cs — Display event monitoring and brightness control routing—core handler for display-related flyouts
• ModernFlyouts.Core/Interop/KeyboardHook.cs — Low-level keyboard hook for capturing Windows media/volume keys—triggers all keyboard-driven flyouts
• ModernFlyouts.Core/Interop/WndProcHookManager.cs — Window message interception for native flyout suppression and event delegation
• Directory.Build.props — Project-wide build configuration and assembly versioning—defines output structure for all projects

Add a new Flyout Type (e.g., Network, Brightness)

1. Create a manager class inheriting from a base monitor/watcher in ModernFlyouts.Core/Display/ or ModernFlyouts.Core/Utilities/ (ModernFlyouts.Core/Display/BrightnessManager.cs)
2. Add P/Invoke declarations for any new Win32 APIs needed in NativeMethods.cs (ModernFlyouts.Core/Interop/NativeMethods.cs)
3. Create a UI control/XAML in your main app project and bind to the manager's observable properties (ModernFlyouts.Core/UI/FlyoutWindow/FlyoutWindow.cs)
4. Register keyboard shortcuts in KeyboardHook.cs for triggering the new flyout (ModernFlyouts.Core/Interop/KeyboardHook.cs)
5. Wire up event subscriptions in the main application startup code

Add Media Control Command (e.g., Play, Pause, Next)

1. Define the command enum in ModernFlyouts.Core/Media/MediaPlaybackType.cs (ModernFlyouts.Core/Media/MediaPlaybackType.cs)
2. Implement command dispatch in MediaSession.cs or GSMTCMediaSession.cs (ModernFlyouts.Core/Media/Control/GSMTCMediaSession.cs)
3. Add corresponding Win32/COM call in NativeMethods.cs if system-level interaction needed (ModernFlyouts.Core/Interop/NativeMethods.cs)
4. Expose command property on MediaSessionManager for UI binding (ModernFlyouts.Core/Media/Control/MediaSessionManager.cs)

Hook a New System Event (e.g., Display Disconnection, USB Device)

1. Add WMI query or Win32 listener class in ModernFlyouts.Core/Utilities/ (ModernFlyouts.Core/Utilities/BrightnessWatcher.cs)
2. Add required P/Invoke signatures to NativeMethods.cs (ModernFlyouts.Core/Interop/NativeMethods.cs)
3. Create manager class in relevant subsystem (Display, Media, etc.) that subscribes to watcher events (ModernFlyouts.Core/Display/DisplayManager.cs)
4. Expose observables (properties, events) from manager for UI databinding (ModernFlyouts.Core/UI/FlyoutWindow/FlyoutWindow.Properties.cs)

• WPF/XAML — Fluent Design visual styling; tight Windows integration; animation framework support
• Win32 P/Invoke — Low-level keyboard hooks, display enumeration, native flyout suppression; no managed equivalent
• GlobalSystemMediaTransportControls (GSMTC) — Modern UWP-era media session API; unified playback control for all media sources
• WMI / Windows Notification Facility (WNF) — System state change monitoring (brightness, displays, airplane mode) without polling overhead
• COM Interop (ITaskbarList3, MMDevice, WASAPI) — Taskbar integration, audio device enumeration, hardware-level media controls

• Low-level keyboard hooking instead of listening to OS events
  • Why: Provides earliest intercept point to suppress native flyouts
  • Consequence: undefined

Windows version specificity: NativeMethods.cs relies on specific Windows 10/11 APIs; breaking changes between versions will require conditional compilation or feature detection. Keyboard hook permissions: KeyboardHook requires admin elevation to intercept global hotkeys; non-admin instances silently fail to hook. GSMTC availability: GSMTCMediaSessionManager depends on Windows 10+ GSMTC API; fallback to older SMTC on Windows 7 requires separate code path (not evident in file list—verify if maintained). Display scaling: BrightnessManager must account for multi-monitor setups with different DPI scaling; brightness values are often monitor-specific. Wnf (Windows Notification Facility): Wnf.cs uses undocumented Windows APIs for state subscription; prone to breaking on new Windows builds without warning.

• P/Invoke (Platform Invoke) — ModernFlyouts intercepts low-level Windows messages via P/Invoke declarations in NativeMethods.cs; understanding how managed C# calls unmanaged Windows APIs is critical for debugging interop issues
• Window Message Hooks (WndProc, WinEventHook) — KeyboardHook.cs and WndProcHookManager.cs use Windows message hooks to intercept keyboard input and window events; essential for understanding how the flyout triggers on key presses
• GSMTC (Global System Media Transport Controls) — GSMTCMediaSessionManager wraps the Windows 10+ GSMTC API to detect and display active media playback; this is the primary mechanism for showing 'now playing' flyouts
• WMI (Windows Management Instrumentation) for Hardware Control — BrightnessManager likely uses WMI to query and adjust monitor brightness levels; understanding WMI classes like WmiMonitorBrightness is needed for display control features
• Debouncing & Throttling in UI — DebounceDispatcher.cs prevents the flyout from flickering when a user holds down a volume key; understanding debounce delay timing is crucial for responsive UX
• WNF (Windows Notification Facility) — Wnf.cs uses undocumented WNF state subscription to detect airplane mode and other system state changes without polling; fragile but performant approach to system monitoring
• XAML Fluent Design System — ModernFlyouts' entire UI goal is to replicate Microsoft's Fluent Design visual language; understanding Fluent principles (acrylic, depth, subtle motion) guides all UI/animation decisions

• ADeltaX/AudioFlyout — Direct predecessor of ModernFlyouts; the original audio-only flyout this project evolved from and still maintains compatibility concepts with
• CommunityToolkit/WindowsCommunityToolkit — Provides reusable Fluent Design XAML controls and WPF utilities that ModernFlyouts could integrate for consistent UI patterns
• microsoft/microsoft-ui-xaml — Official source of WinUI/Fluent Design XAML components; ModernFlyouts aims to replicate this visual language in WPF
• lostindark/ContextMenuForWindows11 — Similar Windows system UI replacement project; shares native interop and keyboard hook challenges in modern Windows
• martinchrzan/Flyouts — Alternative flyout customization project; useful for understanding competing approaches to system notification interception

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add unit tests for ModernFlyouts.Core media control classes

The Media/Control directory contains critical business logic (GSMTCMediaSession.cs, MediaSessionManager.cs, NowPlayingMediaSessionManager.cs) with no corresponding test files visible in the repo. These classes handle Windows media session management and are core to the app's functionality. Adding unit tests would improve reliability and make future refactoring safer, especially for contributors unfamiliar with Windows media APIs.

• [ ] Create ModernFlyouts.Core.Tests project alongside ModernFlyouts.Core
• [ ] Add test class for GSMTCMediaSessionManager covering session creation, enumeration, and lifecycle
• [ ] Add test class for NowPlayingMediaSessionManager covering media control commands and state changes
• [ ] Add test fixtures for mocking Windows Runtime COM interfaces (IGlobalSystemMediaTransportControlsSessionManager)
• [ ] Ensure tests run in GitHub Actions CI pipeline

Add GitHub Actions workflow for building and testing WinAppSDK/MSIX packages

The repo contains ModernFlyouts.Package directory with tile assets and manifest configuration, indicating MSIX/Store distribution. However, no visible CI workflow exists for validating package builds. A build workflow would catch packaging regressions early and verify the app can be packaged correctly on every PR, critical for a Microsoft Store application.

• [ ] Create .github/workflows/package-build.yml that runs on push to main/PR branches
• [ ] Add steps to restore NuGet dependencies, build Release configuration, and validate .csproj files
• [ ] Add step to build MSIX package using MsixPackagingToolsPath or similar tooling
• [ ] Configure workflow to verify assets in ModernFlyouts.Package/Images exist at correct scales (100, 125, 150, 200, 400)
• [ ] Add artifact upload of built MSIX for testing without publishing to Store

Refactor interop P/Invoke declarations into separate Windows API wrapper classes

NativeMethods.cs in ModernFlyouts.Core/Interop likely contains many P/Invoke declarations mixed together. Based on the other interop files (WndProcHookManager, KeyboardHook, WindowsTaskbar, Wnf.cs), there are distinct Windows API domains that should be separated. This improves maintainability, testability, and makes the codebase easier for new contributors to navigate.

• [ ] Audit NativeMethods.cs and identify P/Invoke groups (e.g., window management, WNF notifications, keyboard hooks, display)
• [ ] Create focused wrapper classes: WindowInterop.cs, NotificationInterop.cs, DisplayInterop.cs following existing patterns
• [ ] Move related P/Invoke methods from NativeMethods.cs into appropriate wrapper classes with clear domain responsibility
• [ ] Update all call sites across ModernFlyouts.Core to use new wrapper classes
• [ ] Add XML documentation comments to each wrapper class explaining the Windows API domain it covers

• Add unit tests for DebounceDispatcher.cs—currently no test project visible; test rapid key presses are properly debounced and only one flyout shows per 500ms: Improves code reliability and prevents regressions in core flyout throttling logic
• Document the Interop layer with a README explaining NativeMethods.cs P/Invoke signatures and which Windows versions each API targets (e.g., GSMTC is Win10+, older code paths for Win7): Clarifies Windows version constraints for contributors and reduces future debugging of cross-version issues
• Add localization tests or a CI check that validates all strings in FlyoutWindow XAML are pulled from resource files, not hardcoded, to support the active localization-translation-issue workflow: Prevents accidentally blocking translators by discovering hardcoded strings before merge

ModernFlyouts is a Windows desktop application with moderate security posture. The primary security concerns involve native interop and low-level Windows API interactions (keyboard hooks, window message handling, native method calls) which require careful implementation to prevent memory corruption, privilege escalation, and keystroke logging vulnerabilities. No obvious hardcoded secrets or SQL injection risks were detected

• Medium · Potential Unsafe Native Interop — ModernFlyouts.Core/Interop/NativeMethods.cs, ModernFlyouts.Core/Interop/KeyboardHook.cs, ModernFlyouts.Core/Interop/WndProcHookManager.cs. The codebase contains multiple native interop modules (NativeMethods.cs, WndProcHookManager.cs, KeyboardHook.cs) that interact with Windows APIs through P/Invoke. Without reviewing the actual implementation, unsafe pointer operations and improper marshaling could lead to memory corruption, buffer overflows, or privilege escalation vulnerabilities. Fix: Conduct a thorough code review of all P/Invoke declarations and native method calls. Ensure proper bounds checking, validate all pointer operations, use SafeHandle for unmanaged resources, and avoid unsafe code blocks where possible. Apply the principle of least privilege for Windows API calls.
• Medium · Global Keyboard Hook Implementation — ModernFlyouts.Core/Interop/KeyboardHook.cs. The KeyboardHook.cs module implements global keyboard hooking, which captures all keyboard input system-wide. This could be abused to log sensitive keystrokes or intercept passwords if not properly secured. Malicious code injection or DLL hijacking attacks could compromise this hook. Fix: Implement robust input validation and filtering. Use code signing to prevent DLL hijacking. Consider restricting keyboard hook functionality to specific key combinations only. Document security implications for users. Implement anti-tampering measures and validate the integrity of the hooking mechanism at runtime.
• Medium · Potential Privilege Escalation Through Window Hooks — ModernFlyouts.Core/Interop/WndProcHookManager.cs, ModernFlyouts.Core/Interop/BandWindow.cs. The WndProcHookManager and BandWindow modules hook into Windows messaging. If exploited, these could be leveraged for privilege escalation or to bypass security measures. The interaction with native window procedures requires careful validation. Fix: Validate all window messages and parameters before processing. Implement strict type checking. Use code access security attributes if applicable. Ensure hooks are registered with appropriate security context. Monitor for suspicious window manipulation attempts.
• Low · Missing Input Validation in App Information Handlers — ModernFlyouts.Core/AppInformation/SourceAppInfo.cs, ModernFlyouts.Core/AppInformation/SourceDesktopAppInfo.cs, ModernFlyouts.Core/AppInformation/SourceModernAppInfo.cs. The SourceAppInfo, SourceDesktopAppInfo, and SourceModernAppInfo classes process application information. Without visible input validation, there could be risks from malformed or malicious app metadata. Fix: Implement comprehensive input validation for all app metadata. Use whitelisting for expected values. Sanitize any strings that may be displayed to users. Validate package names and paths against known safe patterns.
• Low · Icon Extraction Potential DoS Risk — ModernFlyouts.Core/Utilities/IconExtractor.cs. The IconExtractor.cs utility extracts icons from applications. Large or malformed icon resources could potentially cause denial of service or resource exhaustion. Fix: Implement resource limits on icon extraction (file size, dimensions, processing time). Add timeout mechanisms. Validate icon format before processing. Implement safe exception handling to prevent crashes from malformed icons.
• Low · Potential Information Disclosure via Media Session Data — ModernFlyouts.Core/Media/Control/GSMTCMediaSession.cs, ModernFlyouts.Core/Media/Control/NowPlayingMediaSession.cs. The media control modules (GSMTCMediaSession.cs, NowPlayingMediaSession.cs) handle media metadata which could contain sensitive information about user activity. Fix: Implement proper access controls around media session data. Encrypt sensitive metadata in memory if stored. Ensure logging doesn't expose user activity. Provide privacy settings to allow users to opt-out of media tracking.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.