source-map.md

Source map

Use this page to find the implementation behind a feature and the documentation that explains its contracts. The inventory follows the tracked source and WSGM.slnx, not leftover bin, obj, publish or staging directories. Architecture follows the cross-system runtime flow; this page maps that flow back to projects and folders.

This is a map of all first-party source areas, not a claim that every private method has a separate API article or that every Windows path has been tested on hardware. Public C# XML documentation is emitted by Directory.Build.props; signatures and their local comments remain the API reference alongside the behavior documents. LibHandheld contracts have a dedicated reference. Dated observations in the documents retain their original scope and are not current test results.

Executables and reusable projects

Project paths below are relative to src/. Every first-party project in the solution appears here. The desktop application uses CoreCLR and Avalonia; the smaller executables have their own entry points and should not be assumed to initialize a resident UI session.

Two disposable web-content executables also live in the solution:

• Browser/WSGM.BrowserHost hosts the Overlay browser at medium integrity; Shell/BrowserSession supervises it. See Browser.
• Screensaver/WSGM.ScreensaverHost hosts allowlisted image playlists and restricted scenes; Shell/ScreensaverService owns discovery, configuration and process cleanup. See Screensavers.

Project	Start reading	Purpose and documentation
WSGM	Program.cs, StartupOptions.cs, App.axaml.cs	Early recovery and command modes, then Settings, resident shell or overlay preview. Boot and shell, UI, and the application map below.
WSGM.LogonService	Program.cs, ServiceHost.cs, SessionLauncher.cs, LogonDecision.cs	Service registration, logon/session observation and per-user process launch. Boot and shell.
WSGM.Launch	Program.cs, CommandLine.cs, LaunchPayload.cs, ScheduledTaskLauncher.cs, SteamInputLeaseHost.cs	De-elevation, suspended-child/job ownership and a game-lifetime Steam Input lease. Elevation and launch wrappers, Steam Input.
WSGM.PackagedLaunch	Program.cs, RawCommandLine.cs, Strategies/, Session/	Imported package activation, Steam-overlay routes, controller-only routes and following launcher-spawned games. Packaging/ owns identity/exemption recovery, Injection/ owns overlay loading and object access, Bridge/ is the native UWP bridge, and Diagnostics/ records outcomes. Packaged-game launcher.
WSGM.Setup	Program.cs, SetupOptions.cs, QuietSetup.cs, Engine/SetupEngine.cs, UI/	Interactive/quiet install, update, repair and uninstall; staged file transactions and runtime shutdown. Setup.
WSGM.Install	BundleManifest.cs, SetupComponents.cs, SetupUserIdentity.cs, PluginOffers.cs	Installer/app shared bundle and component contracts, target-user identity, device/GPU offers and failure information. Setup.
Avalonia.LiveBackdrop	LiveBackdrop.cs, NativeMethods.cs, Native/Backdrop.cpp	One managed attachment and native compositor session per transparent overlay window. Library API and support limits.
WSGM.Plugin.Sdk	PluginContracts.cs, PluginManifestReader.cs, PluginConfiguration.cs, PluginState.cs, PluginActions.cs, PluginSteamUi.cs, PluginSteamFrontend.cs, PluginCapabilities.cs	Independent plugin lifecycle, configuration, capabilities, actions/widgets and Steam frontends. Shared/ contains retained historical capability/lifecycle namespaces in this one assembly. SDK README, host system.
LibHandheld	HandheldDevice, Contracts/, Families/, Internal/Devices/, Internal/Transports/, Internal/Windows/	Native handheld identification, transports, typed input and controls, recovery and glyphs. API.
LibGPUDriverInteract	DriverRuntime, Intel/, Amd/, Nvidia/	Direct vendor driver interaction, native settings and profiles, caller-owned persistence and restoration. Library API.
WSGM.Plugin.Ir	IrPlugin.cs, IrEndpoint.cs, IrPayload.cs, Firmware/	Network IR commands and companion firmware. README and wire protocol define its development status and limits.

Application layers

All paths in this section are relative to src/WSGM.

Area	Entry files and families	Behavior documentation
Startup and composition	Program.cs, StartupOptions.cs, App.axaml.cs, App.axaml, app.manifest	Boot and shell, architecture, elevation. Shell-anchor/probe/restore paths run before the normal UI initialization.
Configuration	Core/ConfigStore.cs, ConfigReadResult.cs, ConfigRepair.cs, ConfigJson*, AppConfig*, UserDataContext.cs, WsgmSharedSettings.cs	UI persistence, profiles, setup. Reload replaces configuration; strict mutations preserve recovery data.
Session and shell	Shell/ShellSession.cs and .Modes, .Config, .Actions, .Shutdown partials; SessionModes, GameModeEntryTransaction, DesktopReturnSequence, GameModeReturnRecovery, Core/Explorer*	Boot and shell. Serialized transitions own Explorer, Steam, displays, controller routing and shutdown.
Startup apps and activation	Shell/StartupAppWatcher, SettingsActivation, SessionActivation, SettingsSurface, Core/DesktopAppLifecycle, AppLauncher, KnownStartupApps, WindowFinder	Boot and shell, elevation, Steam Input.
Shell status and windows	Shell/DesktopTray, TrayHost, SystemStatus, ForegroundWindowWatcher, WindowIcons, GameWindowReturn, LaunchedWindowFocus, Core/TrayProtocol	Overlay/input, boot and shell.
Settings presentation	Settings/SettingsWindow*, SettingsWindowServices, SettingsViewModel*, SettingsSaveMerge, Pages/, display/splash/profile/plugin editors	UI. Settings captures user edits and reports intent; it does not own a second runtime integration.
Overlay presentation	Overlay/OverlayController*, OverlayWindow*, OverlayNavigation, OverlaySources, descriptor rows, utility panels and content views	Overlay code/lifetime map, UI.
Input observation and output	Input/SdlGamepads, GamepadService, GamepadNavigation, FocusSearch, recorders/chord helpers, ManagedControllerRouter, ControllerOutputRouter, VIIPER backend and report encoders	Overlay/input, device integration, Steam Input.
Shared controls/themes	Controls/, Themes/, Assets/Glyphs/, Core/PhysicalGlyphCatalog, Shell/PhysicalGlyphPlans	UI, device runtime. Asset credits are beside the glyphs.
Native seams	Interop/NativeMethods, NativeShellProcess*, NativeStorage, NativeViiper, MessageWindow, display/power/keyboard/shell-link helpers	Follow the owning feature document. These declarations implement Windows access, not product policy.
Device host	Shell/DeviceCoordinator, HandheldDeviceRuntime, DeviceCapabilityRouter, CapabilityUserWrites, CapabilityDesiredReconciler, device profiles/presets/assignments, DeviceOverlayBridge	Device runtime, device integration, profiles.
Controller lifecycle	Shell/ControllerManager, ControllerTargetSelection, HidHideOwnership, UiCaptureState, DeviceOemActionRouter	Device integration, overlay/input. LibHandheld owns physical transport and firmware behavior.
Independent plugins and GPU	Core/PluginPackage*, CommonPlugin*, Shell/PluginLoader, PluginHost, CommonPluginManager, settings/action/publication adapters, GpuCoordinator, GraphicsOverlaySource, SteamGraphicsService	Plugin system, profiles, overlay graphics, GPU library API.
Running application and performance	Shell/RunningApplicationCoordinator, ProfileService, ProfileFanOut, ApplicationPerformanceReconciler, Core/PerformanceService, Core/Profiles/, Rtss*	Profiles, RTSS, power/display.
AutoTDP	Core/AutoTdp, AutoTdpTrace, Shell/AutoTdpService, AutoTdpTraceRecorder	Controller algorithm. Device Integration off means no AutoTDP lifecycle or hardware write.
Windows power/display	Core/WindowsPower*, PowerSchemes, HybridCores, CpuBoost, Display*, PrimaryDisplayModes, RefreshRatePairingService; Shell/Display*, KeepAwakeService, ModernStandbyGuard	Power/display, profiles, overlay display controls.
Windows audio/radios	Shell/AudioManager, AudioProfileService, RadioManager, BluetoothDeviceCatalog, NativeQam*Service, volume-button helpers	Radios, power/display, WindowsDeviceControl. Session owners are shared by native Overlay and Steam.
Steam lifetime and input	Core/Steam, SteamAutostart*, SteamInput*, SteamGuideChordMirror; Shell/SteamMonitor, SteamUiReadiness, SteamExitPolicy	Boot and shell, Steam Input host map.
Steam frontend host	Shell/SteamUiSessionHost, SteamUiBackends, Steam*Surface, NativeQam*Service, Core/SteamUiAssetCatalog, Core/SteamUiAssets/Source/	Steam CEF architecture, feature behavior, frontend source order.
Library and artwork	Core/Library/, Core/Artwork/, Shell/GameLibraryService, GameLibraryArtwork, SteamArtworkBrowserSource, ArtworkStateStore	Game Library, packaged launcher, Steam CEF.
Game Tools	Core/GameTools/, Core/PeImage, Shell/GameToolsService, SteamGameToolsSurface	Game Tools. Per-game tools installed into a game folder as a journaled transaction with a WSGM-owned manifest.
Storage and custom tabs	Shell/StorageInventory, RemovableDriveManager, SdFormatManager, LibraryPolicy, CardVolumeMonitor, CardAcfWatcher, LibraryTabManager, SteamStorageBridge; Core/SteamLibrary*, LibraryFilter*	SD cards, Steam CEF. Physical media identity and registration policy have different owners.
Themes, movies and sounds	Core/Themes/, Core/Animations/, Core/Sounds/, Shell/ThemeService, ThemeBrowseSession, AnimationService, AnimationBrowseSession, SoundPackService	Steam CEF, Steam sounds, Overlay content workflows. Durable services and transient browser contexts are separate.
Splash and images	Core/Splash*, ImageHeader, Shell/BootSplash*, SplashDecode, SplashStyle, SplashPolicy	UI splash engine.
Updates, logging and recovery helpers	Core/UpdateChecker, UpdateExitWatcher, Installer, ApplicationShutdown, Log, TaskFaults, JsonRead, BoundedHttp, FileCleanup, SelfElevation, WindowsPolicyOperation; Shell/UpdateMonitor	Setup, logging, boot and shell. Small utility files support the owning feature rather than creating another service lifetime.

Linked sources and native payloads

src/Shared has no standalone project. Its source is linked explicitly by the consuming .csproj files, so a change can affect several executables:

Folder	Shared contract
Boot/	Atomic files and the minimal service boot manifest.
Process/	Command-line encoding, scheduled tasks, Explorer-parent process startup, session names, child Steam controller-exclusion cleanup and rotating logs.
Install/	Canonical install/staging layout shared by setup and runtime.
Launch/	Packaged-launcher command serialization and parsing.
Interop/	Common Kernel32 and HidHide control declarations/helpers.

The C++ sources maintained here are Avalonia.LiveBackdrop/Native/Backdrop.cpp and WSGM.PackagedLaunch/Bridge/. IR firmware sources and its build-time remote embedding tool live in WSGM.Plugin.Ir/Firmware/. src/WSGM/Native/ and the packaged launcher's Native/UwpBridge/ are staging destinations for built payloads, not an additional managed project or a place to edit the original native implementation.

Dependencies and generated boundaries

The external/libgpu-driver-interact submodule contains the production driver backends and their tests. WSGM references that library directly; its library-owned contracts have no WSGM SDK dependency. Standalone builds use the library's own WindowsDeviceControl submodule, while this checkout reuses the sibling external/windows-device-control project. external/libhandheld contains the direct typed device API, 113 exact definitions, native helpers, glyphs and regression sources. Its independent contracts have no WSGM SDK dependency. Application integration is described in device integration.

Boundary	Ownership
external/libgpu-driver-interact	Pinned Intel, AMD and NVIDIA driver library, library-owned contracts, recovery state and regression tests. Application policy and both graphics surfaces remain in WSGM.
external/steam-ui-toolkit	Pinned repository for CDP, patches, bridge/modules, typed Steam operations and reusable frontend mechanics. Its C# library and tests are included in WSGM.slnx; WSGM owns product surfaces and policy.
external/windows-device-control	Pinned repository for reusable Windows audio, radio, brightness and display operations. Library and tests are in the solution. WSGM owns session/UI/profile orchestration.
external/steam-input-lease	Pinned native gate/client/wrapper and linked managed bindings. It owns its own ABI and native tests; the host owns deployment and claims.
external/viiper	Pinned controller backend on its wsgm branch. Host-side ownership/report routing is in Input/; native behavior stays in the submodule.
external/controller/, external/pawnio/	Version/receipt/license records and prerequisite payloads; acquisition/staging scripts enforce pins.
external/minhook/, external/LoadingIndicators.Avalonia/	Vendored upstream source with local notices/porting notes. Read upstream contracts and preserved attribution rather than treating them as authored WSGM APIs.
Core/SteamUiAssets/NativeQamBootstrap.js	Emitted from the ordered TypeScript source fragments by eng/build-steam-assets.mjs; edit the source fragments and check asset drift.
_ref/, _plan/, work/, artifacts/, TestResults/, bin/, obj/	Reference evidence, historical/planning material, working files and outputs. None overrides the current source topology.

The tracked root WindowsRadio.WlanNative.cs is empty and is not included by a project; it is not the Windows radio implementation. That implementation is in the WindowsDeviceControl submodule.

Build, tools and examples

Start with build.ps1 and setup for a distributable build. The common .NET SDK/compiler policy lives in global.json, Directory.Build.props, .editorconfig and WSGM.slnx.DotSettings; version stamping lives in eng/wsgm-revision.targets and eng/stamp-version.ps1. SkipNativeArtifacts supports compilation and headless work, and does not prove the installer contains its native prerequisites.

Area	Entry points and documentation
Packaging	eng/build-bundle.ps1, build-common.ps1, package-plugin.ps1, plugin-manifest.cs, plugin-package-common.ps1; setup, handheld contributions, plugin system.
Native/prerequisite staging	eng/build-viiper.ps1, build-steam-input-lease.ps1, build-uwp-bridge.ps1, acquire-controller-dependencies.ps1, acquire-pawnio.ps1, stage-webview2-runtime.ps1, lock files and assert-* scripts.
Generation	eng/build-steam-assets.mjs, new-plugin.ps1, eng/templates/; frontend sources.
Verification	eng/verify.ps1, check-*, steam-fingerprints*, update-ui-baselines.ps1, package.json, .github/workflows/ci.yml; UI verification and root contributor guide.
Deployment/publishing helpers	eng/dev-deploy.ps1, .github/workflows/release.yml; setup. Deployment changes the installed machine.
Overlay rendering	tools/OverlayPreview exports production controls with explicit synthetic fixtures.
Native backdrop sample	tools/LiveBackdropSample exercises a real Windows compositor attachment independently of WSGM.
Performance capture	tools/PerfLab records/analyzes ETW evidence; performance findings.
Live Steam diagnostics	tools/WsgmLibTest talks to the attended Steam client and can mutate it. It is not an offline test suite.
External plugin example	examples/SteamCefPlugin is a separate buildable common plugin with a frontend bundle.
Package catalog	plugins/README.md, plugins/curated/ describe reviewed package offers, not compiled plugin source.

Tools and the example are outside WSGM.slnx. Their project files remain authoritative for their builds and references. The verification script builds selected tool projects separately.

Verification map

Project/area	Coverage boundary
tests/WSGM.Tests	Application/Core/Shell/Overlay/Input/Settings policies and seams, plus Setup, Install, Launch, LogonService and PackagedLaunch behavior. Tests use Fakes/, Fixtures/, builders and tests/Shared/.
tests/WSGM.UiTests	Production Avalonia layouts, interactions, focus, saves, lifetime and reviewed PNG baselines with explicit fake service compositions.
tests/Avalonia.LiveBackdrop.Tests	Managed attachment lifecycle and failure generations with a fake native seam, not compositor pixels.
tests/WSGM.Plugin.Sdk.Tests	Common manifest, shared capability/lifecycle, configuration and serialization contracts.
external/libhandheld/tests	Migrated Claw/Ally regression sources and fixtures; source tests do not establish a new hardware pass.
external/libgpu-driver-interact/tests/LibGPUDriverInteract.Tests	Vendor mapping, native contracts, persistence/write behavior and runtime admission. Hardware acceptance is separate.
tests/WSGM.Plugin.Ir.Tests	IR endpoint, encoding, configuration and protocol behavior. Firmware acceptance is separate.
SteamUiToolkit.Tests, WindowsDeviceControl.Tests	Listed under /tests/ in the solution but owned by their submodule repositories.

Follow the repository's manual-first validation policy. Documentation/source/format checks can run before the maintainer's manual pass; test-bearing gates wait for that pass unless explicitly requested earlier. No fixture suite establishes live Steam compatibility, firmware behavior, physical display visibility, touch timing or installation success.

Following one request end to end

1. Find the entry point: Program/App for process modes, ShellSession for a resident service, an Overlay/Settings handler for a local action, or SteamUiSessionHost and a typed backend for a Steam page command.
2. Follow the owner of the state. Core stores and pure policy decide persisted intent; Shell coordinates live work. Views read projections and submit intent.
3. Follow the reusable boundary: device/common SDK, SteamUiToolkit, WindowsDeviceControl, Steam Input pipe, VIIPER or the relevant native interop seam. Do not infer implementation from the UI label alone.
4. Follow the result back: observed state, command outcomes and generation checks become a dispatcher update or a Steam state publication. Uncertain writes remain distinguishable from rejected or never-sent work.
5. Read the paired leave/stop/dispose path and the focused test cases. Surface close, generation replacement, disconnect, suspend and whole-session shutdown need not have identical lifetimes.