matt
945adb6277
macOS reserves about a tenth of the canvas as margin on every side because its icon grid says so, and an icon built that way reads a size smaller than everything beside it in the taskbar. The squircle is now cropped out of that margin and re-centred with roughly a 3% one — a single pixel at the sizes where a pixel is all the antialiased edge needs. Same artwork, 81% of the canvas at 32 where it was, 94% where it now is. Every frame comes off the 1024 source rather than the matching macOS PNG. The smaller ones carry that margin baked in, so reaching these proportions from them would mean upscaling a bitmap already too small to lose anything. Claude-Session: https://claude.ai/code/session_01695o1YiF8Bv4B7nABACUWN |
||
|---|---|---|
| docs | ||
| runtime | ||
| samples | ||
| src | ||
| tests/WProxy.Core.Tests | ||
| .gitattributes | ||
| .gitignore | ||
| CONTEXT.md | ||
| README.md | ||
| WProxyWindows.sln | ||
WProxy Windows
WProxy Windows is an independent Windows 11 desktop client that directly supervises one WPRO runtime
process (wkernel.exe). Its v1 scope is deliberately narrow: WPRO Source Bundles as the only editable
configuration state, and Transparent TUN Mode as the only traffic-capture mode. A single Windows Client
renders, launches, monitors, and stops exactly one Direct Runtime Session — no Windows Service, no IPC
layer — relaunching itself through UAC before a session starts and holding a machine-wide named mutex so
at most one session is active per machine across all Windows users. See CONTEXT.md for terminology and
docs/adr/ for the decisions behind this shape.
Status: functional development client. The WinUI client owns the complete Direct Runtime Session lifecycle: UAC relaunch, machine-wide ownership, WPRO validation/rendering/kernel-check, child-process supervision, Safe TUN recovery, Clash API controls, runtime logs, and remote subscription refresh.
Layout
| Path | What it is |
|---|---|
src/WProxy.Core |
UI-free runtime, recovery, Clash API, source-bundle, and subscription logic. |
src/WProxy.App |
Unpackaged WinUI 3 (Windows App SDK) desktop client. |
src/WProxy.App/Assets/WProxy.ico |
The macOS client's AppIcon.appiconset, rebuilt as a Windows icon: the same artwork cropped out of macOS's icon margin and re-centred with a ~3% one, so it carries the weight a Windows icon does beside its neighbours. Regenerate it from that asset catalogue rather than editing it, so both clients keep the one icon. |
src/WProxy.Cli |
Console diagnostics and session-recovery harness. |
docs/adr/ |
Architecture decision records 0001–0015. |
docs/spike-checklist.md |
Manual verification checklist for the ADR-0014 spike (Chinese). |
Prerequisites (Windows 11)
- Visual Studio 2026 (18.0 or newer) with the .NET Desktop Development workload and the
.NET WinUI app development tools individual component — VS 2022 called the latter
"Windows App SDK C# Templates", and in VS 2026 it is also what carries the PRI build tasks
that
EnableMsixToolingneeds (there is no separate MSIX component to search for any more). Without VS, the .NET 10 SDK plus the Windows App SDK restored via NuGet. Targetingnet10.0is only supported from Visual Studio 18.0; VS 2022 (17.x) cannot build this solution. - Windows 11 SDK (10.0.22621 or newer).
- x64 or arm64.
AnyCPUis not a supported platform forWProxy.App.
Both the .NET target and the Windows App SDK track the vendors' currently-serviced release rather than whatever shipped when a file was first written: .NET 10 is LTS through 2028-11-14, and the Windows App SDK 2.0 line is serviced through 2027-04-29. Bump them when a newer supported release lands, before the pinned one ages out.
Build
WProxy.App requires an explicit platform because Windows App SDK self-contained deployment needs a
RuntimeIdentifier.
dotnet restore WProxyWindows.sln
dotnet build WProxyWindows.sln -c Debug -p:Platform=x64
If dotnet build fails with MSB4062 (ExpandPriContent / Microsoft.Build.Packaging.Pri.Tasks.dll),
build with Visual Studio's MSBuild instead — the PRI tasks ship with VS, not the .NET SDK.
From a Developer PowerShell for VS 2026:
msbuild WProxyWindows.sln /restore /p:Configuration=Debug /p:Platform=x64
(Opening WProxyWindows.sln in Visual Studio 2026 and building works equally well.)
Publish (unpackaged, self-contained)
dotnet publish src\WProxy.App\WProxy.App.csproj -c Release -r win-x64 --self-contained true -p:Platform=x64
dotnet publish src\WProxy.App\WProxy.App.csproj -c Release -r win-arm64 --self-contained true -p:Platform=arm64
Output: src\WProxy.App\bin\<Platform>\Release\net10.0-windows10.0.19041.0\<rid>\publish\WProxy.exe.
Running the client
Launch WProxy.exe without "Run as administrator" and work through
docs/spike-checklist.md. It covers the four ADR-0014 goals (UAC self-relaunch,
tray icon while elevated, login-time autostart, unpackaged self-contained deployment) plus the mutex and
fallback criteria.
Select a WPRO Source Bundle directory containing profile.json, rules.txt, and resources.json, then
select the matching wkernel.exe. Starting Transparent TUN Mode requests UAC elevation when needed.
Remote subscriptions
The subscription URL is bound to the selected Source Bundle and stored as user-scoped client metadata. The refresh button accepts the same subscription forms as the macOS and Android clients:
- plain or Base64-encoded share-link lists containing
ss,vmess,vless,trojan,hysteria2/hy2, andanytlslinks; - Surge configurations with supported
[Proxy],[Proxy Group],[WireGuard name],[Script], and[Rule]sections.
A refresh first downloads the payload using the shared WProxyClient/1.0 user agent, creates candidate
profile.json and rules.txt content, and runs the complete matching-runtime validate, render, and
check path. Only a successful candidate replaces the source files; each replacement is atomic, and a
second-file failure rolls the first one back. An empty, malformed, or kernel-invalid subscription leaves
the existing Bundle untouched. Share-link subscriptions preserve existing rules and viable policy-group
selections; a Surge template replaces its policy groups and stored script/rule sections.
The durable rules.txt remains portable. Windows removes foreign PACKAGE-NAME and
PACKAGE-NAME-REGEX rules only from the transient view passed to the runtime; it never writes that
projection back to the subscription or Source Bundle. See ADR-0015.
Development wkernel build (ADR-0011: dev aid, never a release input)
The WPRO Runtime source lives in the sibling repo WProxyClient/wkernel (a Go sing-box fork) and
cross-compiles from any host. Two flags are required and easy to miss: the toolchain must match the
module's go directive (newer Go breaks go:linkname references into crypto/tls/net internals),
and -checklinkname=0 is needed for tfo-go:
cd ../WProxyClient/wkernel
TAGS=$(cat release/DEFAULT_BUILD_TAGS_OTHERS)
CGO_ENABLED=0 GOOS=windows GOARCH=amd64 GOTOOLCHAIN=go1.24.7 \
go build -trimpath -tags "$TAGS" -ldflags "-s -w -buildid= -checklinkname=0" \
-o ../../WProxyWindows/runtime/bin/wkernel.exe ./cmd/sing-box
runtime/bin/ is gitignored. Release builds go through the digest pin in runtime/pin.json instead.
Note: Transparent TUN Mode on Windows additionally requires wintun.dll next to the kernel executable;
wpro validate/render/check do not.
Decisions
Architecture decisions live in docs/adr/. The ones that shape the client:
- ADR-0010 — one client directly supervises one WPRO runtime child process; UAC relaunch before a session.
- ADR-0012 — machine-wide single session via a
Global\named mutex. - ADR-0013 — network-state snapshot and repair at startup.
- ADR-0014 — clean-room native C# on WinUI 3, unpackaged; Win32
NOTIFYICONtray; WPF is the fallback if the spike fails. - ADR-0015 — remote subscriptions share macOS/Android parsing semantics and retain portable rule source while applying a transient Windows matcher projection.