Fix DesktopGrass.Native.Tests source/include paths for the module layout

The test project references the app's sources and headers; upstream they sit at
../../src/DesktopGrass.Native (tests/ vs src/ layout). In the PowerToys module the
app and tests are siblings under src/modules/DesktopGrass/, so the references are
now ../DesktopGrass.Native. Verified: builds in-tree and passes all 305 Catch2 cases.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

.github/actions/spell-check/allow/code.txt

@@ -365,7 +365,10 @@ FILESYSONLY
 URLIS
 WAITTIMEOUT
 DEFAULTTONEAREST
-
+DWRITE
+LWIN
+VCENTER
+VREDRAW
 
 # COM/WinRT interface prefixes and type fragments
 BAlt

.github/actions/spell-check/excludes.txt

@@ -105,7 +105,9 @@
 ^src/common/ManagedCommon/ColorFormatHelper\.cs$
 ^src/common/notifications/BackgroundActivatorDLL/cpp\.hint$
 ^src/common/sysinternals/Eula/
-^doc/devdocs/modules/cmdpal/initial-sdk-spec/list-elements-mock-002\.pdn$
+^src/modules/cmdpal/Tests/Microsoft\.CommandPalette\.Extensions\.Toolkit\.UnitTests/FuzzyMatcherComparisonTests.cs$
+^src/modules/cmdpal/Tests/Microsoft\.CommandPalette\.Extensions\.Toolkit\.UnitTests/FuzzyMatcherDiacriticsTests.cs$
+^src/modules/cmdpal/doc/initial-sdk-spec/list-elements-mock-002\.pdn$
 ^src/modules/cmdpal/ext/SamplePagesExtension/Pages/SampleMarkdownImagesPage\.cs$
 ^src/modules/cmdpal/Microsoft\.CmdPal\.UI/Settings/InternalPage\.SampleData\.cs$
 ^src/modules/cmdpal/Tests/Microsoft\.CmdPal\.Common\.UnitTests/.*\.TestData\.cs$

.github/actions/spell-check/expect.txt

@@ -1,7 +1,6 @@
 AAAAs
 abcdefghjkmnpqrstuvxyz
 abgr
-ABlocked
 ABORTIFHUNG
 ABOUTBOX
 Abug
@@ -11,18 +10,13 @@ ACCESSDENIED
 ACCESSTOKEN
 acfs
 ACIE
-AClient
-AColumn
-ACR
 acrt
 ACTIVATEAPP
 ACTIVATEOPTIONS
 activationaction
 adaptivecards
-ADate
 ADDSTRING
 ADDUNDORECORD
-ADifferent
 ADMINS
 adml
 admx
@@ -36,10 +30,8 @@ AFX
 agentskills
 AGGREGATABLE
 AHK
-AHybrid
 AIUI
 akv
-ALarger
 ALIGNRIGHT
 ALLAPPS
 ALLCHILDREN
@@ -51,17 +43,13 @@ ALLOWUNDO
 ALLVIEW
 ALPHATYPE
 altkey
-AModifier
 amr
 ANDSCANS
 animatedvisuals
 Animnate
-ANull
 AOC
 aocfnapldcnfbofgmbbllojgocaelgdd
-AOklab
 aot
-APeriod
 apicontract
 apidl
 APIENTRY
@@ -75,6 +63,7 @@ APPEXECLINK
 appext
 apphost
 APPLICATIONFRAMEHOST
+Applocal
 appmanifest
 APPMODEL
 APPNAME
@@ -87,9 +76,7 @@ appxpackage
 APSTUDIO
 AQS
 Aquadrant
-ARandom
 ARCHITEW
-ARemapped
 ARPINSTALLLOCATION
 ARPPRODUCTICON
 ARRAYSIZE
@@ -100,11 +87,9 @@ ARTIFACTSTAGINGDIRECTORY
 asf
 Ashcraft
 AShortcut
-ASingle
 ASSOCCHANGED
 ASSOCF
 ASSOCSTR
-ASUS
 ASYNCWINDOWPLACEMENT
 ASYNCWINDOWPOS
 atl
@@ -135,7 +120,6 @@ Badmode
 Badparam
 bbwe
 BCIE
-bck
 BESTEFFORT
 bezelled
 bhid
@@ -162,9 +146,7 @@ bluelightreductionstate
 BLURBEHIND
 BLURREGION
 bmi
-BNumber
 BODGY
-BOklab
 BOOTSTRAPPERINSTALLFOLDER
 Bootstrappers
 BOTTOMALIGN
@@ -184,11 +166,10 @@ bugreport
 bugreportfile
 BUILDARCH
 BUILDNUMBER
+buildsystems
 buildtransitive
 builttoroam
 BUNDLEINFO
-BVal
-BValue
 byapp
 BYCOMMAND
 BYPOSITION
@@ -204,18 +185,13 @@ CAPTURECHANGED
 CARETBLINKING
 carlos
 Carlseibert
-CAtl
 caub
 CBN
 cch
 CCHDEVICENAME
 CCHFORMNAME
-CCom
-CContext
-CDeclaration
 CDPX
 Cds
-CElems
 CENTERALIGN
 cer
 certlm
@@ -229,12 +205,10 @@ CHILDACTIVATE
 CHILDWINDOW
 CHOOSEFONT
 chu
-Chunghwa
 CIBUILD
 cidl
 CIELCh
 cim
-CImage
 cla
 CLASSDC
 classguid
@@ -263,7 +237,6 @@ CMIC
 CMINVOKECOMMANDINFO
 CMINVOKECOMMANDINFOEX
 CMN
-CMock
 CMONITORS
 cmph
 CNF
@@ -320,7 +293,6 @@ Cowait
 cpcontrols
 cph
 cplusplus
-CPower
 cpptools
 cppvsdbg
 cppwinrt
@@ -339,14 +311,9 @@ CROPTOSQUARE
 Crossdevice
 crt
 csdevkit
-CSearch
-CSettings
 cso
-CSOT
 CSRW
-CStyle
 cswin
-CTest
 CTEXT
 CTLCOLORSTATIC
 CURRENTDIR
@@ -357,9 +324,7 @@ cursorwrap
 customaction
 CUSTOMACTIONTEST
 CUSTOMFORMATPLACEHOLDER
-CVal
 cvd
-CVirtual
 CWMO
 CXSCREEN
 CXSMICON
@@ -372,7 +337,6 @@ Dac
 dacl
 DAffine
 DAFFINETRANSFORM
-DArchitectures
 datareader
 Datasheet
 datatracker
@@ -388,7 +352,6 @@ DBT
 DCapabilities
 DCBA
 DCOM
-DComposition
 DCR
 ddc
 DDEIf
@@ -405,7 +368,6 @@ DEFAULTICON
 defaultlib
 DEFAULTONLY
 DEFAULTSIZE
-defaulttonearest
 DEFAULTTONULL
 DEFAULTTOPRIMARY
 DEFERERASE
@@ -438,6 +400,7 @@ DEVMODE
 DEVMODEW
 DEVNODES
 devpal
+devpackages
 DEVTYP
 dfx
 DIALOGEX
@@ -454,7 +417,6 @@ DISPLAYFREQUENCY
 displayname
 DISPLAYORIENTATION
 DISPLAYPORT
-diu
 divyan
 DLGFRAME
 dlgmodalframe
@@ -482,9 +444,9 @@ drawingcolor
 dreamsofameaningfullife
 drivedetectionwarning
 DROPFILES
+DSPDLOG
 DSTINVERT
 DString
-DSVG
 dto
 DUMMYUNIONNAME
 dumpbin
@@ -510,12 +472,10 @@ DWMWINDOWATTRIBUTE
 DWMWINDOWMAXIMIZEDCHANGE
 DWORDLONG
 dworigin
-dwrite
 DWRITE
 dxgi
 Dxva
 eab
-EAccess
 easeofaccess
 ecount
 edid
@@ -523,8 +483,6 @@ EDITKEYBOARD
 EDITSHORTCUTS
 EDITTEXT
 eep
-EFile
-EInvalid
 eku
 emojis
 ENABLEDELAYEDEXPANSION
@@ -534,28 +492,24 @@ ENABLETEMPLATE
 encodedlaunch
 encryptor
 ENDSESSION
-ENot
 ENSUREVISIBLE
 ENTERSIZEMOVE
 ENTRYW
 ENU
 environmentvariables
 EPO
-EProvider
 epu
 ERASEBKGND
 EREOF
 EResize
 ERRORIMAGE
 ERRORTITLE
-ESettings
 esrp
 etd
 ETDT
 etl
 etw
 eula
-eurochange
 eventvwr
 evt
 EWXFORCE
@@ -591,7 +545,6 @@ FANCYZONESEDITOR
 FARPROC
 fdw
 fdx
-FErase
 fesf
 FFFF
 fffffffzzz
@@ -618,16 +571,13 @@ FILESYSPATH
 Filetime
 FILEVERSION
 FILTERMODE
-FInc
 findfast
 findmymouse
 FIXEDFILEINFO
 FIXEDSYS
 flac
 flyouts
-FMask
 fmtid
-FNumber
 FOF
 FOFX
 FOLDERID
@@ -640,7 +590,6 @@ formatetc
 FORPARSING
 foundrylocal
 framechanged
-FRestore
 frm
 FROMTOUCH
 fsanitize
@@ -680,7 +629,6 @@ gfx
 GHND
 gitmodules
 GMEM
-GNumber
 googleai
 googlegemini
 Gotchas
@@ -701,12 +649,10 @@ GSM
 gtm
 guiddata
 GUITHREADINFO
-GValue
 gwl
 GWLP
 GWLSTYLE
 hangeul
-Hann
 Hantai
 Hanzi
 Hardlines
@@ -739,7 +685,6 @@ hgdiobj
 HGFE
 hglobal
 hhk
-HHmmssfff
 hhx
 Hiber
 Hiberboot
@@ -779,7 +724,6 @@ HORZSIZE
 Hostbackdropbrush
 hostfxr
 hostsfileeditor
-Hostx
 hotfixes
 hotkeycontrol
 HOTKEYF
@@ -787,7 +731,6 @@ hotkeys
 hotlight
 hotspot
 HPAINTBUFFER
-HPhysical
 HPS
 HRAWINPUT
 HREDRAW
@@ -798,15 +741,11 @@ HROW
 hsb
 HSCROLL
 hsi
-HSpeed
-HSync
 HTCLIENT
 hthumbnail
 HTOUCHINPUT
 HTTRANSPARENT
 hutchinsoniana
-HVal
-HValue
 Hvci
 hwb
 HWHEEL
@@ -817,7 +756,6 @@ HWNDLAST
 HWNDNEXT
 HWNDPARENT
 HWNDPREV
-HWP
 hyjiacan
 IAI
 icf
@@ -899,7 +837,6 @@ INVALIDARG
 invalidoperatioexception
 invokecommand
 ipcmanager
-IPREVIEW
 ipreviewhandlervisualssetfont
 IPTC
 irow
@@ -915,10 +852,8 @@ issuecomment
 istep
 Italicise
 ith
-ITHUMBNAIL
 IUI
 IUWP
-IVO
 IWIC
 jeli
 jfif
@@ -936,7 +871,6 @@ jsonval
 jxr
 Kantai
 KBSC
-kdc
 keybd
 KEYBDDATA
 KEYBDINPUT
@@ -954,6 +888,7 @@ keynum
 keyremaps
 keyring
 keyvault
+kfull
 KILLFOCUS
 killrunner
 kmph
@@ -980,7 +915,6 @@ LEFTTEXT
 Lenovo
 LError
 LEVELID
-LExit
 LFU
 LGD
 lhwnd
@@ -1020,7 +954,6 @@ lowlevel
 LOWORD
 lparam
 LPBITMAPINFOHEADER
-LPCFHOOKPROC
 lpch
 LPCITEMIDLIST
 LPCLSID
@@ -1039,7 +972,6 @@ LPMONITORINFO
 LPOSVERSIONINFOEXW
 LPQUERY
 lprc
-LPrivate
 LPSAFEARRAY
 lpstr
 lpsz
@@ -1053,7 +985,6 @@ LPW
 lpwcx
 lpwndpl
 lquadrant
-LReader
 LRESULT
 LSTATUS
 lstrcmp
@@ -1061,14 +992,12 @@ lstrcmpi
 lstrcpyn
 lstrlen
 LTEXT
+LTM
 LTRREADING
 luid
-LUMA
 lusrmgr
-LVal
 LVDS
 LWA
-lwin
 LWIN
 LZero
 MAGTRANSFORM
@@ -1138,7 +1067,6 @@ mkdn
 mlcfg
 mmc
 mmcexe
-MMdd
 mmi
 mmsys
 mobileredirect
@@ -1164,7 +1092,6 @@ mouseutils
 MOVESIZEEND
 MOVESIZESTART
 MRM
-MRT
 mru
 msaccess
 MSAL
@@ -1175,8 +1102,6 @@ msdata
 msdia
 MSDL
 MSGFLT
-MSHCTX
-MSHLFLAGS
 msiexec
 MSIFASTINSTALL
 MSIHANDLE
@@ -1213,7 +1138,6 @@ myorg
 myrepo
 NAMECHANGE
 namespaceanddescendants
-Nanjing
 nao
 NCACTIVATE
 ncc
@@ -1239,7 +1163,6 @@ netcpl
 netframework
 netsetup
 netsh
-newcolor
 NEWDIALOGSTYLE
 NEWFILE
 NEWFILEHEADER
@@ -1252,7 +1175,6 @@ newrow
 nicksnettravels
 NIF
 nightlight
-NLog
 NLSTEXT
 NMAKE
 NNN
@@ -1342,7 +1264,6 @@ OFN
 ofs
 OICI
 OICIIO
-oldcolor
 olditem
 oldpath
 oldtheme
@@ -1373,7 +1294,6 @@ OUTOFCONTEXT
 Outptr
 outputtype
 outsettings
-outsourced
 OVERLAPPEDWINDOW
 Oversampling
 OVERWRITEPROMPT
@@ -1400,7 +1320,6 @@ PATINVERT
 PATPAINT
 pbc
 pbi
-PBlob
 PBP
 pbrush
 pcb
@@ -1411,6 +1330,7 @@ pchast
 PCIDLIST
 PCTSTR
 PCWSTR
+pdbs
 PDBs
 PDEVMODE
 PDFs
@@ -1422,7 +1342,6 @@ pdto
 pdtobj
 pdw
 Peb
-PElems
 Pels
 PELSHEIGHT
 PELSWIDTH
@@ -1439,7 +1358,6 @@ pguid
 phbm
 phbmp
 phicon
-PHL
 Photoshop
 photoshop
 phwnd
@@ -1447,7 +1365,6 @@ pici
 pidl
 PIDLIST
 pii
-pinboard
 pinfo
 pinvoke
 pipename
@@ -1472,6 +1389,7 @@ Pokedex
 Pomodoro
 popups
 POPUPWINDOW
+portfile
 POSITIONITEM
 POWERBROADCAST
 powerdisplay
@@ -1548,7 +1466,6 @@ psrm
 psrree
 pstatstg
 pstm
-PStr
 pstream
 pstrm
 PSYSTEM
@@ -1559,7 +1476,6 @@ PTCHAR
 ptcontrols
 ptd
 PTOKEN
-PToy
 ptstr
 ptsym
 pui
@@ -1570,7 +1486,6 @@ PWSTR
 pwsz
 pwtd
 qdc
-QDS
 qit
 QITAB
 QITABENT
@@ -1585,9 +1500,7 @@ quicklinks
 quickmask
 QUNS
 RAII
-RAlt
 randi
-RAquadrant
 rasterization
 Rasterize
 rasterizing
@@ -1605,7 +1518,6 @@ READMODE
 READOBJECTS
 recents
 RECTDESTINATION
-rectp
 RECTSOURCE
 recursesubdirs
 recyclebin
@@ -1664,8 +1576,6 @@ RIDEV
 RIGHTBUTTON
 RIGHTSCROLLBAR
 riid
-RKey
-RNumber
 rollups
 rop
 ROUNDSMALL
@@ -1695,9 +1605,9 @@ SAMESHORTCUTPREVIOUSLYMAPPED
 samsung
 sancov
 SAVEFAILED
-scanled
 schedtasks
 SCID
+SCL
 Scode
 SCREENFONTS
 screenruler
@@ -1873,6 +1783,7 @@ STDAPI
 stdc
 stdcpp
 stdcpplatest
+stdext
 STDMETHODCALLTYPE
 STDMETHODIMP
 steamapps
@@ -1903,7 +1814,6 @@ sublang
 SUBMODULEUPDATE
 subresource
 sug
-suntimes
 Superbar
 SUPPRESSMSGBOXES
 sut
@@ -1979,7 +1889,6 @@ thickframe
 THISCOMPONENT
 threadpool
 throughs
-Tianma
 TILEDWINDOW
 TILLSON
 timedate
@@ -1997,6 +1906,7 @@ TNP
 Toggleable
 tontrager
 Toolhelp
+toolsets
 toolwindow
 TOPDOWNDIB
 TOUCHEVENTF
@@ -2029,16 +1939,11 @@ UACUI
 UAL
 uap
 UBR
-UBreak
 ubrk
-UCallback
 ucrt
 ucrtd
 uefi
-UError
 uesc
-UFlags
-UHash
 UIA
 UIDs
 UIEx
@@ -2047,8 +1952,6 @@ uitests
 UITo
 ULONGLONG
 Ultrawide
-UMax
-UMin
 ums
 uncompilable
 UNCPRIORITY
@@ -2067,12 +1970,11 @@ UNORM
 unparsable
 unremapped
 Unsend
-unsubscribes
+Unsubscribes
 untriaged
 unvirtualized
 unwide
 unzoom
-UOffset
 UOI
 UPDATENOW
 updown
@@ -2088,7 +1990,6 @@ USEINSTALLERFORTEST
 USESHOWWINDOW
 USESTDHANDLES
 USRDLL
-UType
 uuidv
 uwp
 uxt
@@ -2099,17 +2000,16 @@ valuegenerator
 VARTYPE
 vbcscompiler
 vcamp
-vcenter
 VCENTER
 vcgtq
 VCINSTALLDIR
 vcp
 Vcpkg
+vcpkg
 vcpname
 VCRT
 vcruntime
 vcvars
-VDesktop
 vdupq
 VERBSONLY
 VERBW
@@ -2138,7 +2038,6 @@ vorrq
 VOS
 vpaddlq
 vqsubq
-vredraw
 VREDRAW
 vreinterpretq
 VSC
@@ -2151,24 +2050,20 @@ VSINSTALLDIR
 VSM
 vso
 vsonline
-VSpeed
 vstemplate
 vstest
 VSTHRD
 vstprintf
 VSTT
 vswhere
-VSync
 Vtbl
 WANTNUKEWARNING
 WANTPALM
 WASDK
 wbem
-WBounds
 Wca
 WCE
 wcex
-WClass
 WCRAPI
 wcsicmp
 wcsncpy
@@ -2251,7 +2146,6 @@ WNDCLASSW
 wndproc
 wnode
 wom
-workerw
 WORKSPACESEDITOR
 WORKSPACESLAUNCHER
 WORKSPACESSNAPSHOTTOOL
@@ -2266,7 +2160,6 @@ wpr
 wprp
 wql
 wregex
-WReserved
 WResize
 WRITEOBJECTS
 Wrk
@@ -2284,49 +2177,23 @@ Wubi
 WUX
 Wwanpp
 xap
-XAxis
-XButton
 Xbuttondown
 xclip
 xcopy
-XDeployment
 xdf
-XDimension
-XDocument
-XElement
 xfd
-XFile
-XIncrement
-XLoc
 xmp
-XNamespace
 Xoshiro
-XPels
-XPixel
-XPos
-XResource
 xsi
-XSpeed
-XStr
 xstyler
-XTimer
 XUP
 XVIRTUALSCREEN
 XXL
 xxxxxx
-YAxis
 ycombinator
-YDimension
-YIncrement
 yinle
 yinyue
 yoko
-YPels
-YPos
-YResolution
-YSpeed
-YStr
-YTimer
 YVIRTUALSCREEN
 zamora
 Zenbook

.github/policies/resourceManagement.yml

@@ -163,7 +163,7 @@ configuration:
             association: Collaborator
       then:
       - addReply:
-          reply: Hi! We've identified this issue as a duplicate of another one that already exists on this Issue Tracker. This specific instance is being closed in favor of tracking the concern over on the referenced thread. Thanks for your report!
+          reply: We've identified this issue as a duplicate of an existing one and are closing this thread so discussion stays in one place.<br/><br/>Please see the comment above for the link to the original tracking issue, and feel free to subscribe there for updates.
       - closeIssue
       - removeLabel:
           label: Needs-Triage

.github/scripts/telemetry-pr-check.js

@@ -9,21 +9,22 @@
  */
 
 const fs = require('node:fs');
+const REVIEWER_LOGIN = 'chatasweetie';
+const REVIEWER_MENTION = `@${REVIEWER_LOGIN}`;
 
 const COMMENT_MARKER = '<!-- telemetry-event-check -->';
 const COMMENT_BODY_WITH_PRIVACY_UPDATE = `${COMMENT_MARKER}
-THIS IS A TEST | @chatasweetie is testing this functionality
-Thanks for contributing to PowerToys. This change might include a new or modified telemetry event, and we want to help make sure you can get your data end to end.
+Thank you for contributing to PowerToys. We've detected that this PR might include a new or modified telemetry event. After this PR is merged, please follow these next steps:
 
-1. Reach out to Jessica (@chatasweetie) to follow up on the next steps to add these telemetry events to our pipelines.`;
+- [ ] Reach out to Jessica (${REVIEWER_MENTION}) to follow up on the next steps: https://aka.ms/pt-telemetry-process
+`;
 
 const COMMENT_BODY_WITHOUT_PRIVACY_UPDATE = `${COMMENT_MARKER}
-THIS IS A TEST | @chatasweetie is testing this functionality
-Thanks for contributing to PowerToys. This change might include a new or modified telemetry event, and we want to help make sure you can get your data end to end.
+Thank you for contributing to PowerToys. We've detected that this PR might include a new or modified telemetry event. Please ensure the following before merging:
 
-1. Make sure to add your telemetry events to DATA_AND_PRIVACY.md.
+- [ ] Add your telemetry events to [DATA_AND_PRIVACY](https://github.com/microsoft/PowerToys/blob/main/DATA_AND_PRIVACY.md).md within this PR.
 
-2. Reach out to Jessica (@chatasweetie) to follow up on the next steps to add these telemetry events to our pipelines.`;
+- [ ] Reach out to Jessica (${REVIEWER_MENTION}) to follow up on the next steps: https://aka.ms/pt-telemetry-process`;
 
 const TELEMETRY_PATH_PATTERNS = [
   /(^|\/)trace\.(h|hpp|cpp|cs)$/i,
@@ -191,6 +192,48 @@ async function getAllPullFiles(apiBaseUrl, repository, pullNumber) {
   return files;
 }
 
+async function getPullRequest(apiBaseUrl, repository, pullNumber) {
+  const url = `${apiBaseUrl}/repos/${repository}/pulls/${pullNumber}`;
+  const pullRequest = await apiRequest(url);
+  if (!pullRequest || typeof pullRequest !== 'object') {
+    throw new Error('Unexpected response while fetching pull request details.');
+  }
+  return pullRequest;
+}
+
+async function ensureReviewerRequested(apiBaseUrl, repository, pullNumber, pullRequest) {
+  const authorLogin = String(pullRequest?.user?.login || '').toLowerCase();
+  const targetReviewer = REVIEWER_LOGIN.toLowerCase();
+
+  if (authorLogin === targetReviewer) {
+    console.log(`Skipping reviewer request: ${REVIEWER_LOGIN} is the PR author.`);
+    return;
+  }
+
+  const requestedReviewers = Array.isArray(pullRequest?.requested_reviewers)
+    ? pullRequest.requested_reviewers
+    : [];
+  const alreadyRequested = requestedReviewers.some(
+    (reviewer) => String(reviewer?.login || '').toLowerCase() === targetReviewer
+  );
+
+  if (alreadyRequested) {
+    console.log(`Reviewer ${REVIEWER_LOGIN} is already requested.`);
+    return;
+  }
+
+  const url = `${apiBaseUrl}/repos/${repository}/pulls/${pullNumber}/requested_reviewers`;
+  try {
+    await apiRequest(url, 'POST', { reviewers: [REVIEWER_LOGIN] });
+    console.log(`Requested reviewer ${REVIEWER_LOGIN}.`);
+  } catch (error) {
+    // Reviewer request should not fail the telemetry guidance workflow.
+    console.warn(
+      `Unable to request reviewer ${REVIEWER_LOGIN}: ${error instanceof Error ? error.message : String(error)}`
+    );
+  }
+}
+
 async function findExistingTelemetryComment(apiBaseUrl, repository, pullNumber) {
   let page = 1;
 
@@ -310,6 +353,16 @@ async function main() {
     );
   }
 
+  try {
+    const pullRequest = await getPullRequest(parsedApiBaseUrl.origin, repository, pullNumber);
+    await ensureReviewerRequested(parsedApiBaseUrl.origin, repository, pullNumber, pullRequest);
+  } catch (error) {
+    console.warn(
+      'Failed to fetch PR details or request reviewer; continuing to post telemetry guidance comment.'
+    );
+    console.warn(error instanceof Error ? error.stack || error.message : error);
+  }
+
   const commentBody = dataAndPrivacyChanged
     ? COMMENT_BODY_WITH_PRIVACY_UPDATE
     : COMMENT_BODY_WITHOUT_PRIVACY_UPDATE;

.gitignore

@@ -370,3 +370,8 @@ installer/*/*.wxs.bk
 .squad-workstream
 .github/agents/**squad**.md
 .github/workflows/**squad**.yml
+
+# vcpkg manifest mode installed packages
+vcpkg_installed/
+
+deps/vcpkg/

.gitmodules

@@ -1,6 +0,0 @@
-[submodule "deps/spdlog"]
-	path = deps/spdlog
-	url = https://github.com/gabime/spdlog.git
-[submodule "deps/expected-lite"]
-	path = deps/expected-lite
-	url = https://github.com/martinmoene/expected-lite.git

.pipelines/ESRPSigning_core.json

@@ -212,6 +212,7 @@
             "WinUI3Apps\\PowerToys.NewPlus.ShellExtension.win10.dll",
 
             "PowerAccent.Core.dll",
+            "PowerAccent.Common.dll",
             "PowerToys.PowerAccent.dll",
             "PowerToys.PowerAccent.exe",
             "PowerToys.PowerAccentModuleInterface.dll",
@@ -391,6 +392,7 @@
                 "WinUI3Apps\\Google.Apis.Auth.dll",
                 "WinUI3Apps\\Google.Apis.Core.dll",
                 "WinUI3Apps\\Google.GenAI.dll",
+                "WinUI3Apps\\YamlDotNet.dll",
 
                 "boost_regex-vc143-mt-gd-x32-1_87.dll",
                 "boost_regex-vc143-mt-gd-x64-1_87.dll",

.pipelines/v2/release.yml

@@ -104,6 +104,10 @@ extends:
               # Have msbuild use the release nuget config profile
               additionalBuildOptions: /p:RestoreConfigFile="$(Build.SourcesDirectory)\.pipelines\release-nuget.config" /p:EnableCmdPalAOT=true
               beforeBuildSteps:
+                # Install the Terrapin retrieval tool, which replaces vcpkg's download handler
+                # to redirect it to a safe Microsoft-controlled location
+                - template: .pipelines/v2/templates/steps-install-terrapin.yml@self
+
                 # Sets versions for all PowerToy created DLLs
                 - pwsh: |-
                     .pipelines/versionSetting.ps1 -versionNumber '${{ parameters.versionNumber }}' -DevEnvironment ''
@@ -140,6 +144,10 @@ extends:
                 signCertName: $(SigningSignCertName)
                 useManagedIdentity: $(SigningUseManagedIdentity)
                 clientId: $(SigningOriginalClientId)
+              beforeBuildSteps:
+                # Install the Terrapin retrieval tool, which replaces vcpkg's download handler
+                # to redirect it to a safe Microsoft-controlled location
+                - template: .pipelines/v2/templates/steps-install-terrapin.yml@self
 
       - stage: Publish
         displayName: Publish

.pipelines/v2/templates/job-build-project.yml

@@ -270,6 +270,34 @@ jobs:
       parameters:
         directory: $(build.sourcesdirectory)\src\modules\cmdpal
 
+  # --- vcpkg detection + binary cache --------------------------------------
+  # PowerToys consumes spdlog (and, over time, other native deps) via vcpkg in
+  # manifest mode. steps-install-vcpkg.yml prefers the vcpkg shipped with
+  # Visual Studio (Microsoft.VisualStudio.Component.Vcpkg) and falls back to a
+  # fresh clone of microsoft/vcpkg into deps/vcpkg if VS doesn't have it.
+  # Either way it sets the VCPKG_ROOT pipeline variable; MSBuild integration
+  # is wired globally from Cpp.Build.props (with vcpkg.targets in
+  # Cpp.Build.targets) using the three-tier VcpkgRoot fallback
+  # (env var > VS-shipped > deps/vcpkg runtime clone).
+  #
+  # Vcpkg's MSBuild integration runs `vcpkg install` once per project, so the
+  # binary cache below saves ~3-5 minutes per triplet on cache hits.
+  - template: .\steps-install-vcpkg.yml
+    parameters:
+      useVSPreview: ${{ parameters.useVSPreview }}
+
+  - ${{ if eq(parameters.enablePackageCaching, true) }}:
+    - task: Cache@2
+      displayName: 'Cache vcpkg binary archives'
+      inputs:
+        # Key on the inputs vcpkg uses to compute its package ABI: the manifest,
+        # configuration, every overlay-port file, and the agent OS.
+        key: '"vcpkg" | "$(Agent.OS)" | vcpkg.json | vcpkg-configuration.json | deps/vcpkg-overlays/**'
+        restoreKeys: |
+           "vcpkg" | "$(Agent.OS)"
+           "vcpkg"
+        path: $(LOCALAPPDATA)\vcpkg\archives
+
 
 
   - ${{ parameters.beforeBuildSteps }}

.pipelines/v2/templates/job-build-sdk.yml

@@ -15,6 +15,9 @@ parameters:
   - name: signingIdentity
     type: object
     default: {}
+  - name: beforeBuildSteps
+    type: stepList
+    default: []
 
 jobs:
 - job: "BuildSDK"
@@ -45,6 +48,8 @@ jobs:
       parameters:
         directory: $(build.sourcesdirectory)\src\modules\cmdpal
 
+  - ${{ parameters.beforeBuildSteps }}
+
   - pwsh: |-
       & "$(build.sourcesdirectory)\src\modules\cmdpal\extensionsdk\nuget\BuildSDKHelper.ps1" -Configuration "Release" -BuildStep "build" -IsAzurePipelineBuild
     displayName: Build SDK

.pipelines/v2/templates/steps-install-terrapin.yml

@@ -0,0 +1,6 @@
+steps:
+- pwsh: |-
+    nuget install -source "https://microsoft.pkgs.visualstudio.com/Dart/_packaging/PowerToysDependencies/nuget/v3/index.json" TerrapinRetrievalTool -Prerelease -OutputDirectory _trt -Config "$(Build.SourcesDirectory)\.pipelines\release-nuget.config"
+    $TerrapinRetrievalToolPath = (Get-Item _trt\TerrapinRetrievalTool.*\win-x64\TerrapinRetrievalTool.exe).FullName
+    Write-Host "##vso[task.setvariable variable=X_VCPKG_ASSET_SOURCES]x-script,${TerrapinRetrievalToolPath} -b https://vcpkg.storage.devpackages.microsoft.io/artifacts/ -a true -u None -p {url} -s {sha512} -d {dst};x-block-origin"
+  displayName: Set up the Terrapin Retrieval Tool (vcpkg cache)

.pipelines/v2/templates/steps-install-vcpkg.yml

@@ -0,0 +1,41 @@
+# Adapted from microsoft/terminal build/pipelines/templates-v2/steps-install-vcpkg.yml.
+#
+# Detects vcpkg from (in order):
+#   1. The Visual Studio installation (Microsoft.VisualStudio.Component.Vcpkg,
+#      declared in the repo-root .vsconfig).
+#   2. A local clone at deps/vcpkg, cloned and bootstrapped on demand.
+#
+# Sets the pipeline-scoped VCPKG_ROOT variable; the rest of the build
+# resolves vcpkg through it (see the three-tier VcpkgRoot fallback in
+# Cpp.Build.props). No repo-level vcpkg submodule required.
+parameters:
+- name: useVSPreview
+  type: boolean
+  default: false
+
+steps:
+  - pwsh: |-
+      # vswhere -prerelease is opt-in via the useVSPreview parameter so CI on
+      # stable VS doesn't accidentally pick up a Preview install when both
+      # are present. Matches the existing useVSPreview plumbing for
+      # verifyAndSetLatestVCToolsVersion.ps1.
+      $vswhereArgs = @('-latest', '-requires', 'Microsoft.VisualStudio.Component.Vcpkg', '-property', 'installationPath')
+      $useVSPreview = '${{ parameters.useVSPreview }}' -eq 'True'
+      if ($useVSPreview) { $vswhereArgs = @('-prerelease') + $vswhereArgs }
+      $VsInstallRoot = & 'C:\Program Files (x86)\Microsoft Visual Studio\Installer\vswhere.exe' @vswhereArgs
+      If ([String]::IsNullOrEmpty($VsInstallRoot)) {
+        Remove-Item -Recurse -Force deps/vcpkg -ErrorAction:Ignore
+        git clone https://github.com/microsoft/vcpkg deps/vcpkg
+        if ($LASTEXITCODE -ne 0) { throw "git clone vcpkg failed (exit $LASTEXITCODE)" }
+        Push-Location deps/vcpkg
+        & ./bootstrap-vcpkg.bat -disableMetrics
+        if ($LASTEXITCODE -ne 0) { Pop-Location; throw "bootstrap-vcpkg failed (exit $LASTEXITCODE)" }
+        $VcpkgRoot = $PWD
+        Pop-Location
+        Write-Host "Using vcpkg from local checkout ($VcpkgRoot)"
+      } Else {
+        $VcpkgRoot = Join-Path $VsInstallRoot 'VC\vcpkg'
+        Write-Host "Using vcpkg from Visual Studio installation ($VcpkgRoot)"
+      }
+      Write-Host "##vso[task.setvariable variable=VCPKG_ROOT]$VcpkgRoot"
+    displayName: Detect VS vcpkg or bootstrap locally

.pipelines/verifyCommonProps.ps1

@@ -48,6 +48,11 @@ foreach ($csprojFile in $csprojFilesArray) {
         continue
     }
 
+    # The PowerAccent.Common project does not target WinRT, so skip it
+    if ($csprojFile -like '*PowerAccent.Common.csproj') {
+        continue
+    }
+
     $importExists = Test-ImportSharedCsWinRTProps -filePath $csprojFile
     if (!$importExists) {
         Write-Output "$csprojFile need to import 'Common.Dotnet.CsWinRT.props'."

.vsconfig

@@ -18,6 +18,7 @@
     "Microsoft.VisualStudio.Component.VC.ATL.ARM64.Spectre",
     "Microsoft.VisualStudio.Component.VC.ATL",
     "Microsoft.VisualStudio.Component.VC.ATL.Spectre",
+    "Microsoft.VisualStudio.Component.Vcpkg",
     "Microsoft.VisualStudio.ComponentGroup.WindowsAppSDK.Cs"
   ]
 }

Cpp.Build.props

@@ -39,7 +39,8 @@
   <PropertyGroup>
     <PreferredToolArchitecture>x64</PreferredToolArchitecture>
     <PreferredToolArchitecture Condition="'$(PROCESSOR_ARCHITECTURE)' == 'ARM64' or '$(PROCESSOR_ARCHITEW6432)' == 'ARM64'">arm64</PreferredToolArchitecture>
-    <VcpkgEnabled>false</VcpkgEnabled>
+    <!-- vcpkg.targets is imported via Cpp.Build.targets after Microsoft.Cpp.targets. -->
+    <ForceImportAfterCppTargets>$(MSBuildThisFileDirectory)Cpp.Build.targets</ForceImportAfterCppTargets>
     <ReplaceWildcardsInProjectItems>true</ReplaceWildcardsInProjectItems>
     <ExternalIncludePath>$(MSBuildThisFileDirectory)deps;$(MSBuildThisFileDirectory)packages;$(ExternalIncludePath)</ExternalIncludePath>
     <!-- Enable control flow guard for C++ projects that don't consume any C++ files -->
@@ -121,6 +122,48 @@
     <SpectreMitigation>Spectre</SpectreMitigation>
   </PropertyGroup>
 
+  <!--
+    vcpkg integration. Set globally and loaded before Microsoft.Cpp.props (via
+    ForceImportBeforeCppProps) so that vcpkg.props' ClCompile hook is in place
+    before the C++ targets run. VcpkgRoot is resolved via the same three-tier
+    fallback used by microsoft/terminal (env var → VS-shipped → deps/vcpkg).
+  -->
+  <PropertyGroup Label="vcpkg">
+    <VcpkgEnabled>true</VcpkgEnabled>
+    <VcpkgEnableManifest>true</VcpkgEnableManifest>
+    <VcpkgManifestEnabled>true</VcpkgManifestEnabled>
+    <VcpkgManifestRoot>$(MSBuildThisFileDirectory)</VcpkgManifestRoot>
+    <VcpkgOSTarget>windows</VcpkgOSTarget>
+    <VcpkgUseStatic>true</VcpkgUseStatic>
+    <!--
+      Force VcpkgConfiguration to follow $(Configuration). Without this,
+      vcpkg.props infers VcpkgConfiguration from $(UseDebugLibraries), which
+      Microsoft.Cpp.Default.props has already defaulted to 'false' by the
+      time vcpkg.props is imported here (the PowerToys-wide Debug override
+      below runs LATER). That would silently link the Release-built spdlog
+      into Debug consumers and trigger LNK2038 (MT/MTd, _ITERATOR_DEBUG_LEVEL).
+    -->
+    <VcpkgConfiguration>$(Configuration)</VcpkgConfiguration>
+    <!-- vcpkg validates triplets case-sensitively; PowerToys uses ARM64 capital-case. -->
+    <VcpkgPlatformTarget Condition="'$(Platform)' == 'ARM64'">arm64</VcpkgPlatformTarget>
+    <VcpkgApplocalDeps>false</VcpkgApplocalDeps>
+    <VcpkgInstalledDir>$(MSBuildThisFileDirectory)vcpkg_installed\$(Platform)\</VcpkgInstalledDir>
+    <VcpkgRoot Condition="'$(VcpkgRoot)' == ''">$(VCPKG_ROOT)</VcpkgRoot>
+    <VcpkgRoot Condition="'$(VcpkgRoot)' == '' and '$(VsInstallRoot)' != ''">$(VsInstallRoot)\VC\vcpkg</VcpkgRoot>
+    <VcpkgRoot Condition="'$(VcpkgRoot)' == '' or !Exists('$(VcpkgRoot)\vcpkg.exe')">$(MSBuildThisFileDirectory)deps\vcpkg</VcpkgRoot>
+    <CAExcludePath>$(CAExcludePath);$(VcpkgInstalledDir)</CAExcludePath>
+    <VCPkgLocalAppDataDisabled>true</VCPkgLocalAppDataDisabled>
+  </PropertyGroup>
+  <!-- Fail fast with an actionable message instead of opaque C1083 spdlog/spdlog.h errors. -->
+  <Target Name="PowerToysEnsureVcpkgAvailable"
+          BeforeTargets="PrepareForBuild"
+          Condition="'$(MSBuildProjectExtension)' == '.vcxproj' and '$(VcpkgEnabled)' == 'true' and !Exists('$(VcpkgRoot)\scripts\buildsystems\msbuild\vcpkg.props')">
+    <Error Text="PowerToys requires the 'vcpkg' Visual Studio component, but it was not found.%0A%0AOpen the Visual Studio Installer, click Modify on your VS install, search for 'vcpkg', enable 'C++ vcpkg package manager', and click Modify. (Visual Studio will also prompt you to install missing .vsconfig components when you open PowerToys.slnx.)%0A%0AIf you have vcpkg installed elsewhere, set the VCPKG_ROOT environment variable to its root before building.%0A%0ASearched: '$(VcpkgRoot)\scripts\buildsystems\msbuild\vcpkg.props'" />
+  </Target>
+  <Import Project="$(VcpkgRoot)\scripts\buildsystems\msbuild\vcpkg.props"
+          Condition="'$(MSBuildProjectExtension)' == '.vcxproj' and Exists('$(VcpkgRoot)\scripts\buildsystems\msbuild\vcpkg.props')" />
+
+
   <!-- Debug/Release props -->
   <PropertyGroup Condition="'$(Configuration)'=='Debug'" Label="Configuration">
     <UseDebugLibraries>true</UseDebugLibraries>

Cpp.Build.targets

@@ -0,0 +1,16 @@
+<?xml version="1.0" encoding="utf-8"?>
+<Project>
+  <!--
+    PowerToys global C++ post-targets. Wired in via
+    <ForceImportAfterCppTargets> in Cpp.Build.props so MSBuild loads this
+    file AFTER Microsoft.Cpp.targets for every .vcxproj.
+
+    Conditionally imports vcpkg.targets to hook ClCompile into vcpkg's
+    VcpkgInstallManifestDependencies target so spdlog headers are
+    auto-discovered on the include path and spdlog.lib is auto-linked.
+    vcpkg.props is imported in Cpp.Build.props (before Microsoft.Cpp.props);
+    vcpkg.targets needs the matching "after" hook here.
+  -->
+  <Import Project="$(VcpkgRoot)\scripts\buildsystems\msbuild\vcpkg.targets"
+          Condition="'$(MSBuildProjectExtension)' == '.vcxproj' and '$(VcpkgEnabled)' == 'true' and Exists('$(VcpkgRoot)\scripts\buildsystems\msbuild\vcpkg.targets')" />
+</Project>

Directory.Packages.props

@@ -41,21 +41,21 @@
     <PackageVersion Include="MessagePack" Version="3.1.3" />
     <PackageVersion Include="Microsoft.CodeAnalysis.NetAnalyzers" Version="10.0.102" />
     <PackageVersion Include="Microsoft.CommandPalette.Extensions" Version="0.9.260303001" />
-    <PackageVersion Include="Microsoft.Data.Sqlite" Version="10.0.7" />
+    <PackageVersion Include="Microsoft.Data.Sqlite" Version="10.0.8" />
     <!-- Including Microsoft.Bcl.AsyncInterfaces to force version, since it's used by Microsoft.SemanticKernel. -->
-    <PackageVersion Include="Microsoft.Bcl.AsyncInterfaces" Version="10.0.7" />
+    <PackageVersion Include="Microsoft.Bcl.AsyncInterfaces" Version="10.0.8" />
     <PackageVersion Include="Microsoft.Graphics.Win2D" Version="1.3.2" />
     <PackageVersion Include="Microsoft.Windows.CppWinRT" Version="2.0.250303.1" />
     <PackageVersion Include="Microsoft.Diagnostics.Tracing.TraceEvent" Version="3.1.16" />
     <PackageVersion Include="Microsoft.Extensions.AI" Version="10.2.0" />
     <PackageVersion Include="Microsoft.Extensions.AI.OpenAI" Version="10.0.1-preview.1.25571.5" />
-    <PackageVersion Include="Microsoft.Extensions.Caching.Abstractions" Version="10.0.7" />
-    <PackageVersion Include="Microsoft.Extensions.Caching.Memory" Version="10.0.7" />
-    <PackageVersion Include="Microsoft.Extensions.DependencyInjection" Version="10.0.7" />
-    <PackageVersion Include="Microsoft.Extensions.Logging" Version="10.0.7" />
-    <PackageVersion Include="Microsoft.Extensions.Logging.Abstractions" Version="10.0.7" />
-    <PackageVersion Include="Microsoft.Extensions.Hosting" Version="10.0.7" />
-    <PackageVersion Include="Microsoft.Extensions.Hosting.WindowsServices" Version="10.0.7" />
+    <PackageVersion Include="Microsoft.Extensions.Caching.Abstractions" Version="10.0.8" />
+    <PackageVersion Include="Microsoft.Extensions.Caching.Memory" Version="10.0.8" />
+    <PackageVersion Include="Microsoft.Extensions.DependencyInjection" Version="10.0.8" />
+    <PackageVersion Include="Microsoft.Extensions.Logging" Version="10.0.8" />
+    <PackageVersion Include="Microsoft.Extensions.Logging.Abstractions" Version="10.0.8" />
+    <PackageVersion Include="Microsoft.Extensions.Hosting" Version="10.0.8" />
+    <PackageVersion Include="Microsoft.Extensions.Hosting.WindowsServices" Version="10.0.8" />
     <PackageVersion Include="Microsoft.AI.Foundry.Local" Version="0.3.0" />
     <PackageVersion Include="Microsoft.SemanticKernel" Version="1.71.0" />
     <PackageVersion Include="Microsoft.SemanticKernel.Connectors.OpenAI" Version="1.71.0" />
@@ -66,9 +66,9 @@
     <PackageVersion Include="Microsoft.Toolkit.Uwp.Notifications" Version="7.1.2" />
     <PackageVersion Include="Microsoft.Web.WebView2" Version="1.0.3719.77" />
     <!-- Package Microsoft.Win32.SystemEvents added as a hack for being able to exclude the runtime assets so they don't conflict with 8.0.1. This is a dependency of System.Drawing.Common but the 8.0.1 version wasn't published to nuget. -->
-    <PackageVersion Include="Microsoft.Win32.SystemEvents" Version="10.0.7" />
+    <PackageVersion Include="Microsoft.Win32.SystemEvents" Version="10.0.8" />
     <PackageVersion Include="Microsoft.WindowsPackageManager.ComInterop" Version="1.10.340" />
-    <PackageVersion Include="Microsoft.Windows.Compatibility" Version="10.0.7" />
+    <PackageVersion Include="Microsoft.Windows.Compatibility" Version="10.0.8" />
     <PackageVersion Include="Microsoft.Windows.CsWin32" Version="0.3.269" />
     <!-- CsWinRT version needs to be set to have a WinRT.Runtime.dll at the same version contained inside the NET SDK we're currently building on CI. -->
     <!-- 
@@ -106,28 +106,28 @@
     <PackageVersion Include="StreamJsonRpc" Version="2.21.69" />
     <PackageVersion Include="StyleCop.Analyzers" Version="1.2.0-beta.556" />
     <!-- Package System.CodeDom added as a hack for being able to exclude the runtime assets so they don't conflict with 8.0.1. This is a dependency of System.Management but the 8.0.1 version wasn't published to nuget. -->
-    <PackageVersion Include="System.CodeDom" Version="10.0.7" />
+    <PackageVersion Include="System.CodeDom" Version="10.0.8" />
     <PackageVersion Include="System.CommandLine" Version="2.0.0-beta4.22272.1" />
-    <PackageVersion Include="System.ComponentModel.Composition" Version="10.0.7" />
-    <PackageVersion Include="System.Configuration.ConfigurationManager" Version="10.0.7" />
-    <PackageVersion Include="System.Data.OleDb" Version="10.0.7" />
+    <PackageVersion Include="System.ComponentModel.Composition" Version="10.0.8" />
+    <PackageVersion Include="System.Configuration.ConfigurationManager" Version="10.0.8" />
+    <PackageVersion Include="System.Data.OleDb" Version="10.0.8" />
     <!-- Package System.Diagnostics.EventLog added as a hack for being able to exclude the runtime assets so they don't conflict with 8.0.1. This is a dependency of System.Data.OleDb but the 8.0.1 version wasn't published to nuget. -->
-    <PackageVersion Include="System.Diagnostics.EventLog" Version="10.0.7" />
+    <PackageVersion Include="System.Diagnostics.EventLog" Version="10.0.8" />
     <!-- Package System.Diagnostics.PerformanceCounter added as a hack for being able to exclude the runtime assets so they don't conflict with 8.0.11. -->
-    <PackageVersion Include="System.Diagnostics.PerformanceCounter" Version="10.0.7" />
+    <PackageVersion Include="System.Diagnostics.PerformanceCounter" Version="10.0.8" />
     <PackageVersion Include="System.ClientModel" Version="1.8.1" />
-    <PackageVersion Include="System.Drawing.Common" Version="10.0.7" />
+    <PackageVersion Include="System.Drawing.Common" Version="10.0.8" />
     <PackageVersion Include="System.IO.Abstractions" Version="22.0.13" />
     <PackageVersion Include="System.IO.Abstractions.TestingHelpers" Version="22.0.13" />
-    <PackageVersion Include="System.Management" Version="10.0.7" />
+    <PackageVersion Include="System.Management" Version="10.0.8" />
     <PackageVersion Include="System.Net.Http" Version="4.3.4" />
     <PackageVersion Include="System.Numerics.Tensors" Version="10.0.2" />
     <PackageVersion Include="System.Private.Uri" Version="4.3.2" />
     <PackageVersion Include="System.Reactive" Version="6.0.1" />
-    <PackageVersion Include="System.Runtime.Caching" Version="10.0.7" />
-    <PackageVersion Include="System.ServiceProcess.ServiceController" Version="10.0.7" />
-    <PackageVersion Include="System.Text.Encoding.CodePages" Version="10.0.7" />
-    <PackageVersion Include="System.Text.Json" Version="10.0.7" />
+    <PackageVersion Include="System.Runtime.Caching" Version="10.0.8" />
+    <PackageVersion Include="System.ServiceProcess.ServiceController" Version="10.0.8" />
+    <PackageVersion Include="System.Text.Encoding.CodePages" Version="10.0.8" />
+    <PackageVersion Include="System.Text.Json" Version="10.0.8" />
     <PackageVersion Include="System.Text.RegularExpressions" Version="4.3.1" />
     <PackageVersion Include="ToolGood.Words.Pinyin" Version="3.1.0.3" />
     <PackageVersion Include="UnicodeInformation" Version="2.6.0" />

PowerToys.slnx

@@ -57,6 +57,7 @@
     <Project Path="src/common/UnitTests-CommonLib/UnitTests-CommonLib.vcxproj" Id="1a066c63-64b3-45f8-92fe-664e1cce8077" />
     <Project Path="src/common/UnitTests-CommonUtils/UnitTests-CommonUtils.vcxproj" Id="8b5cfb38-ccba-40a8-ad7a-89c57b070884" />
     <Project Path="src/common/updating/updating.vcxproj" Id="17da04df-e393-4397-9cf0-84dabe11032e" />
+    <Project Path="src/common/updating/UnitTests/UpdatingUnitTests.vcxproj" Id="a1b2c3d4-e5f6-7890-abcd-ef1234567890" />
     <Project Path="src/common/version/version.vcxproj" Id="cc6e41ac-8174-4e8a-8d22-85dd7f4851df" />
   </Folder>
   <Folder Name="/common/interop/">
@@ -67,10 +68,7 @@
     <Project Path="src/common/interop/PowerToys.Interop.vcxproj" Id="f055103b-f80b-4d0c-bf48-057c55620033" />
   </Folder>
   <Folder Name="/common/log/">
-    <Project Path="src/common/logger/logger.vcxproj" Id="d9b8fc84-322a-4f9f-bbb9-20915c47ddfd">
-      <BuildDependency Project="src/logging/logging.vcxproj" />
-    </Project>
-    <Project Path="src/logging/logging.vcxproj" Id="7e1e3f13-2bd6-3f75-a6a7-873a2b55c60f" />
+    <Project Path="src/common/logger/logger.vcxproj" Id="d9b8fc84-322a-4f9f-bbb9-20915c47ddfd" />
   </Folder>
   <Folder Name="/common/notifications/">
     <Project Path="src/common/notifications/BackgroundActivator/BackgroundActivator.vcxproj" Id="0b593a6c-4143-4337-860e-db5710fb87db" />
@@ -470,6 +468,12 @@
       <Platform Solution="*|x64" Project="x64" />
     </Project>
   </Folder>
+  <Folder Name="/modules/DesktopGrass/">
+    <Project Path="src/modules/DesktopGrass/DesktopGrass.Native/DesktopGrass.Native.vcxproj" Id="b0d4e1b0-1f5e-4c2d-9f44-da8c3f1a2a11" />
+  </Folder>
+  <Folder Name="/modules/DesktopGrass/Tests/">
+    <Project Path="src/modules/DesktopGrass/DesktopGrass.Native.Tests/DesktopGrass.Native.Tests.vcxproj" />
+  </Folder>
   <Folder Name="/modules/imageresizer/">
     <Project Path="src/modules/imageresizer/dll/ImageResizerExt.vcxproj" Id="0b43679e-edfa-4da0-ad30-f4628b308b1b" />
     <Project Path="src/modules/imageresizer/ImageResizerCLI/ImageResizerCLI.csproj">
@@ -801,6 +805,14 @@
     <Project Path="src/modules/peek/peek/peek.vcxproj" Id="a1425b53-3d61-4679-8623-e64a0d3d0a48" />
   </Folder>
   <Folder Name="/modules/PowerAccent/">
+    <Project Path="src/modules/poweraccent/PowerAccent.Common.UnitTests/PowerAccent.Common.UnitTests.csproj">
+      <Platform Solution="*|ARM64" Project="ARM64" />
+      <Platform Solution="*|x64" Project="x64" />
+    </Project>
+    <Project Path="src/modules/poweraccent/PowerAccent.Common/PowerAccent.Common.csproj">
+      <Platform Solution="*|ARM64" Project="ARM64" />
+      <Platform Solution="*|x64" Project="x64" />
+    </Project>
     <Project Path="src/modules/poweraccent/PowerAccent.Core/PowerAccent.Core.csproj">
       <Platform Solution="*|ARM64" Project="ARM64" />
       <Platform Solution="*|x64" Project="x64" />
@@ -1133,3 +1145,5 @@
   <Project Path="src/Update/PowerToys.Update.vcxproj" Id="44ce9ae1-4390-42c5-bacc-0fd6b40aa203" />
   <Project Path="tools/project_template/ModuleTemplate/ModuleTemplateCompileTest.vcxproj" Id="64a80062-4d8b-4229-8a38-dfa1d7497749" />
 </Solution>
+
+

deps/expected.props

@@ -1,7 +0,0 @@
-<Project>
-	<ItemDefinitionGroup>
-		<ClCompile>
-			<AdditionalIncludeDirectories>$(MSBuildThisFileDirectory)expected-lite\include\nonstd\;%(AdditionalIncludeDirectories)</AdditionalIncludeDirectories>
-		</ClCompile>
-	</ItemDefinitionGroup>
-</Project>

deps/spdlog-msvc-fix/include/spdlog-msvc-fix.h

@@ -1,94 +0,0 @@
-// spdlog-msvc-fix.h
-//
-// Workaround for MSVC 14.51 (compiler version 19.51, _MSC_VER >= 1951) removing
-// stdext::checked_array_iterator. Force-included for all spdlog consumers via
-// deps/spdlog.props, because spdlog v1.8.5's bundled fmt format.h(357) still
-// references this type inside #if defined(_SECURE_SCL) && _SECURE_SCL -- a
-// branch entered in Debug builds where _ITERATOR_DEBUG_LEVEL > 0.
-//
-// On MSVC 14.50 and earlier, the type still exists in <iterator>, so this shim
-// is a no-op via the _MSC_VER guard. On MSVC 14.51+, it provides a minimal
-// pointer-backed substitute that satisfies the bundled fmt's usage:
-//
-//   template <typename T> using checked_ptr = stdext::checked_array_iterator<T*>;
-//   template <typename T> checked_ptr<T> make_checked(T* p, size_t size) {
-//     return {p, size};
-//   }
-//   ... return make_checked(get_data(c) + size, n);
-//
-// When deps/spdlog is bumped past v1.14 (which ships fmt 10.2 and drops this
-// dependency), this shim and its <ForcedIncludeFiles> entry in deps/spdlog.props
-// can be deleted.
-
-#pragma once
-
-#if defined(__cplusplus) && defined(_MSC_VER) && _MSC_VER >= 1951
-
-#include <cstddef>
-#include <iterator>
-#include <type_traits>
-
-namespace stdext
-{
-    template <typename _Ptr>
-    class checked_array_iterator
-    {
-        _Ptr _Myarray = nullptr;
-        std::size_t _Mysize = 0;
-        std::size_t _Myindex = 0;
-
-    public:
-        using iterator_category = std::random_access_iterator_tag;
-        using value_type = std::remove_cv_t<std::remove_pointer_t<_Ptr>>;
-        using difference_type = std::ptrdiff_t;
-        using pointer = _Ptr;
-        using reference = std::remove_pointer_t<_Ptr>&;
-
-        constexpr checked_array_iterator() = default;
-
-        constexpr checked_array_iterator(_Ptr arr, std::size_t size, std::size_t idx = 0) noexcept
-            : _Myarray(arr), _Mysize(size), _Myindex(idx)
-        {
-        }
-
-        constexpr reference operator*() const noexcept { return _Myarray[_Myindex]; }
-        constexpr pointer operator->() const noexcept { return _Myarray + _Myindex; }
-        constexpr reference operator[](difference_type n) const noexcept
-        {
-            return _Myarray[_Myindex + static_cast<std::size_t>(n)];
-        }
-
-        constexpr checked_array_iterator& operator++() noexcept { ++_Myindex; return *this; }
-        constexpr checked_array_iterator operator++(int) noexcept { auto t = *this; ++_Myindex; return t; }
-        constexpr checked_array_iterator& operator--() noexcept { --_Myindex; return *this; }
-        constexpr checked_array_iterator operator--(int) noexcept { auto t = *this; --_Myindex; return t; }
-
-        constexpr checked_array_iterator& operator+=(difference_type n) noexcept
-        {
-            _Myindex = static_cast<std::size_t>(static_cast<difference_type>(_Myindex) + n);
-            return *this;
-        }
-        constexpr checked_array_iterator& operator-=(difference_type n) noexcept
-        {
-            _Myindex = static_cast<std::size_t>(static_cast<difference_type>(_Myindex) - n);
-            return *this;
-        }
-
-        friend constexpr checked_array_iterator operator+(checked_array_iterator it, difference_type n) noexcept { it += n; return it; }
-        friend constexpr checked_array_iterator operator+(difference_type n, checked_array_iterator it) noexcept { return it + n; }
-        friend constexpr checked_array_iterator operator-(checked_array_iterator it, difference_type n) noexcept { it -= n; return it; }
-        friend constexpr difference_type operator-(checked_array_iterator a, checked_array_iterator b) noexcept
-        {
-            return static_cast<difference_type>(a._Myindex) - static_cast<difference_type>(b._Myindex);
-        }
-
-        friend constexpr bool operator==(checked_array_iterator a, checked_array_iterator b) noexcept { return a._Myindex == b._Myindex; }
-        friend constexpr bool operator!=(checked_array_iterator a, checked_array_iterator b) noexcept { return !(a == b); }
-        friend constexpr bool operator<(checked_array_iterator a, checked_array_iterator b) noexcept { return a._Myindex < b._Myindex; }
-        friend constexpr bool operator>(checked_array_iterator a, checked_array_iterator b) noexcept { return b < a; }
-        friend constexpr bool operator<=(checked_array_iterator a, checked_array_iterator b) noexcept { return !(b < a); }
-        friend constexpr bool operator>=(checked_array_iterator a, checked_array_iterator b) noexcept { return !(a < b); }
-    };
-} // namespace stdext
-
-#endif // __cplusplus && _MSC_VER >= 1951

deps/spdlog.props

@@ -1,9 +1,14 @@
+<?xml version="1.0" encoding="utf-8"?>
 <Project>
-	<ItemDefinitionGroup>
-		<ClCompile>
-			<AdditionalIncludeDirectories>$(MSBuildThisFileDirectory)spdlog\include;%(AdditionalIncludeDirectories)</AdditionalIncludeDirectories>
-			<PreprocessorDefinitions>SPDLOG_WCHAR_TO_UTF8_SUPPORT;SPDLOG_COMPILED_LIB;SPDLOG_WCHAR_FILENAMES;%(PreprocessorDefinitions)</PreprocessorDefinitions>
-			<ForcedIncludeFiles>$(MSBuildThisFileDirectory)spdlog-msvc-fix\include\spdlog-msvc-fix.h;%(ForcedIncludeFiles)</ForcedIncludeFiles>
-		</ClCompile>
-	</ItemDefinitionGroup>
+  <!--
+    SPDLOG_* preprocessor defines for spdlog consumers. The actual vcpkg
+    integration (VcpkgEnabled, VcpkgRoot, triplet, manifest install) lives
+    in Cpp.Build.props; this file just carries the defines that match how
+    the pre-vcpkg in-tree build was configured.
+  -->
+  <ItemDefinitionGroup>
+    <ClCompile>
+      <PreprocessorDefinitions>SPDLOG_WCHAR_TO_UTF8_SUPPORT;SPDLOG_COMPILED_LIB;SPDLOG_WCHAR_FILENAMES;%(PreprocessorDefinitions)</PreprocessorDefinitions>
+    </ClCompile>
+  </ItemDefinitionGroup>
 </Project>

deps/vcpkg-overlays/spdlog/msvc-14.51-stdext-checked-array-iterator.patch

@@ -0,0 +1,16 @@
+--- a/include/spdlog/fmt/bundled/format.h
++++ b/include/spdlog/fmt/bundled/format.h
+@@ -354,7 +354,12 @@ inline typename Container::value_type* get_data(Container& c) {
+   return c.data();
+ }
+ 
+-#if defined(_SECURE_SCL) && _SECURE_SCL
++// PowerToys: stdext::checked_array_iterator was deprecated in VS 2019 16.10
++// and removed entirely in MSVC 14.51 (compiler 19.51, _MSC_VER >= 1951;
++// see microsoft/STL STL4043). Skip the broken branch on those toolsets so the
++// pointer-based fallback below is used instead. Drop this guard once
++// deps/spdlog is bumped past v1.14 (which ships fmt 10.2 and removes this code).
++#if defined(_SECURE_SCL) && _SECURE_SCL && (!defined(_MSC_VER) || _MSC_VER < 1951)
+ // Make a checked iterator to avoid MSVC warnings.
+ template <typename T> using checked_ptr = stdext::checked_array_iterator<T*>;
+ template <typename T> checked_ptr<T> make_checked(T* p, size_t size) {

deps/vcpkg-overlays/spdlog/portfile.cmake

@@ -0,0 +1,43 @@
+# PowerToys overlay port for spdlog.
+#
+# Pinned to the same git commit that the deleted deps/spdlog submodule pointed
+# at, so this is a 1:1 submodule->vcpkg migration with no version change
+# (per the maintainer guidance: convert one submodule at a time, atomic
+# commit, don't also bump the version).
+#
+# A single hunk patch works around MSVC 14.51 STL4043 (removal of
+# stdext::checked_array_iterator) in spdlog's bundled fmt 7. Drop this overlay
+# (and switch to upstream vcpkg's spdlog port) once PowerToys bumps spdlog
+# past v1.14, which ships fmt 10.2 and removes the affected code path.
+
+vcpkg_from_github(
+    OUT_SOURCE_PATH SOURCE_PATH
+    REPO gabime/spdlog
+    REF 616866fcf40340ea25a8f218369bad810ef58e72
+    SHA512 2076c527c7768627e6856b2f7ef663b185fd6251894cffd9299203d00f3d2de5696461060442dd72b96c9d3f0fd27f7f63ad2edfdf295e9b06c5fac6d6212faf
+    HEAD_REF v1.x
+    PATCHES
+        msvc-14.51-stdext-checked-array-iterator.patch
+)
+
+vcpkg_cmake_configure(
+    SOURCE_PATH "${SOURCE_PATH}"
+    OPTIONS
+        -DSPDLOG_BUILD_EXAMPLE=OFF
+        -DSPDLOG_BUILD_TESTS=OFF
+        -DSPDLOG_BUILD_BENCH=OFF
+        -DSPDLOG_FMT_EXTERNAL=OFF
+        -DSPDLOG_WCHAR_SUPPORT=ON
+        -DSPDLOG_WCHAR_FILENAMES=ON
+        -DSPDLOG_NO_EXCEPTIONS=OFF
+        -DSPDLOG_BUILD_SHARED=OFF
+)
+
+vcpkg_cmake_install()
+vcpkg_cmake_config_fixup(PACKAGE_NAME spdlog CONFIG_PATH lib/cmake/spdlog)
+vcpkg_fixup_pkgconfig()
+vcpkg_copy_pdbs()
+
+file(REMOVE_RECURSE "${CURRENT_PACKAGES_DIR}/debug/include")
+
+vcpkg_install_copyright(FILE_LIST "${SOURCE_PATH}/LICENSE")

deps/vcpkg-overlays/spdlog/vcpkg.json

@@ -0,0 +1,18 @@
+{
+  "name": "spdlog",
+  "version-string": "1.8.5-pt-616866fc",
+  "port-version": 0,
+  "description": "Very fast, header-only/compiled, C++ logging library. PowerToys overlay pinned to gabime/spdlog@616866fc (the exact submodule commit before this migration), with a single-hunk patch that works around MSVC 14.51 removing stdext::checked_array_iterator (STL4043).",
+  "homepage": "https://github.com/gabime/spdlog",
+  "license": "MIT",
+  "dependencies": [
+    {
+      "name": "vcpkg-cmake",
+      "host": true
+    },
+    {
+      "name": "vcpkg-cmake-config",
+      "host": true
+    }
+  ]
+}

doc/devdocs/development/debugging.md

@@ -97,6 +97,10 @@ The Shell Process Debugging Tool is a Visual Studio extension that helps debug m
 - Check Event Viewer for application crashes related to `PowerToys.Settings.exe`
 - Crash dumps can be obtained from Event Viewer
 
+### Debugging Command Palette
+Command Palette can be easily debugged using the solution filter in `src/modules/cmdpal/Command Palette.slnf`. This will open Command Palette as its own Visual Studio solution that can be run and debugged directly in Visual Studio without the need for the Shell Process Debugging Tool.
+
+
 ## Troubleshooting Build Errors
 
 ### Missing Image Files or Corrupted Build State

doc/specs/WinGet Manifest Keyboard Shortcuts schema.md

@@ -87,7 +87,7 @@ Per Application/Package one or more Keyboard manifests can be declared. Every ma
 <details>
  <summary><b>WindowFilter</b> - The filter of window processes to which the shortcuts apply to</summary>
 
- This field declares for which process name the shortcuts should be showed (To rephrase: For which processes the shortcut will have an effect if pressed). You can use an asterisk to leave out a certain part. For example `*.PowerToys.*.exe` targets all PowerToys processes and `*` apply to any process.
+ This field declares for which process name the shortcuts should be shown (To rephrase: For which processes the shortcut will have an effect if pressed). The value can be either an exact process executable name, for example `explorer.exe` or `chrome.exe`, or a single asterisk (`*`) to apply to any process. No other wildcard patterns are supported by this specification.
 
 </details>
 

doc/thirdPartyRunPlugins.md

@@ -79,3 +79,4 @@ Below are community created plugins that target a website or software.  They are
 | [Linear](https://github.com/vednig/powertoys-linear) | [vednig](https://github.com/vednig) | Create Linear Issues directly from Powertoys Run |
 | [PerplexitySearchShortcut](https://github.com/0x6f677548/PowerToys-Run-PerplexitySearchShortcut) | [0x6f677548](https://github.com/0x6f677548) | Search Perplexity |
 | [SpeedTest](https://github.com/ruslanlap/PowerToysRun-SpeedTest) | [ruslanlap](https://github.com/ruslanlap) | One-command internet speed tests with real-time results, modern UI, and shareable links. |
+| [DiskAnalyzer](https://github.com/thetsaw/PowerToys.Plugin) | [thetsaw](https://github.com/thetsaw) | Scan folders, find the largest files, and view drive space usage with visual progress bars. |

installer/PowerToysSetup.slnx

@@ -8,9 +8,6 @@
   </Project>
   <Project Path="../src/common/Telemetry/EtwTrace/EtwTrace.vcxproj" Id="8f021b46-362b-485c-bfba-ccf83e820cbd" />
   <Project Path="../src/common/version/version.vcxproj" Id="cc6e41ac-8174-4e8a-8d22-85dd7f4851df" />
-  <Project Path="../src/logging/logging.vcxproj" Id="7e1e3f13-2bd6-3f75-a6a7-873a2b55c60f">
-    <Build Solution="Debug|ARM64" Project="false" />
-  </Project>
   <Project Path="PowerToysSetupCustomActionsVNext/PowerToysSetupCustomActionsVNext.vcxproj" Id="b3a354b0-1e54-4b55-a962-fb5af9330c19">
     <Build Solution="Debug|ARM64" Project="false" />
   </Project>

installer/PowerToysSetupVNext/DesktopGrass.wxs

@@ -0,0 +1,25 @@
+<Wix xmlns="http://wixtoolset.org/schemas/v4/wxs">
+
+  <?include $(sys.CURRENTDIR)\Common.wxi?>
+
+  <Fragment>
+    <!--
+      DesktopGrass ships a single statically-linked native executable
+      (DesktopGrass.Native.exe, /MT CRT, no external runtime dependencies). It is
+      emitted to the root build output and harvested automatically by the root
+      sweep in generateAllFileComponents.ps1 into BaseApplicationsComponentGroup.
+
+      This component group only carries the module's uninstall marker so the
+      feature can be referenced explicitly from Product.wxs, matching the
+      per-module convention used by Awake/Hosts/etc.
+    -->
+    <ComponentGroup Id="DesktopGrassComponentGroup">
+      <Component Id="RemoveDesktopGrassRegistry" Guid="42C1C544-8FD8-422A-85A2-139D99D38B52" Directory="INSTALLFOLDER">
+        <RegistryKey Root="$(var.RegistryScope)" Key="Software\Classes\powertoys\components">
+          <RegistryValue Type="string" Name="RemoveDesktopGrassRegistry" Value="" KeyPath="yes" />
+        </RegistryKey>
+      </Component>
+    </ComponentGroup>
+
+  </Fragment>
+</Wix>

installer/PowerToysSetupVNext/PowerToysInstallerVNext.wixproj

@@ -115,6 +115,7 @@ call powershell.exe -NonInteractive -executionpolicy Unrestricted -File $(MSBuil
     <Compile Include="BaseApplications.wxs" />
     <Compile Include="CmdPal.wxs" />
     <Compile Include="ColorPicker.wxs" />
+    <Compile Include="DesktopGrass.wxs" />
     <Compile Include="EnvironmentVariables.wxs" />
     <Compile Include="FileExplorerPreview.wxs" />
     <Compile Include="FileLocksmith.wxs" />

installer/PowerToysSetupVNext/Product.wxs

@@ -45,6 +45,7 @@
       <ComponentGroupRef Id="WinUI3ApplicationsComponentGroup" />
       <ComponentGroupRef Id="AwakeComponentGroup" />
       <ComponentGroupRef Id="ColorPickerComponentGroup" />
+      <ComponentGroupRef Id="DesktopGrassComponentGroup" />
       <ComponentGroupRef Id="FileExplorerPreviewComponentGroup" />
       <ComponentGroupRef Id="FileLocksmithComponentGroup" />
       <ComponentGroupRef Id="HostsComponentGroup" />

installer/PowerToysSetupVNext/ShortcutGuide.wxs

@@ -4,15 +4,23 @@
 
   <?define ShortcutGuideAssetsFiles=?>
   <?define ShortcutGuideAssetsFilesPath=$(var.BinDir)WinUI3Apps\Assets\ShortcutGuide\?>
+  <?define ShortcutGuideManifestsFiles=?>
+  <?define ShortcutGuideManifestsFilesPath=$(var.BinDir)WinUI3Apps\Assets\ShortcutGuide\Manifests\?>
 
   <Fragment>
     <DirectoryRef Id="WinUI3AppsAssetsFolder">
-      <Directory Id="ShortcutGuideAssetsFolder" Name="ShortcutGuide" />
+      <Directory Id="ShortcutGuideAssetsFolder" Name="ShortcutGuide">
+        <Directory Id="ShortcutGuideManifestsFolder" Name="Manifests" />
+      </Directory>
     </DirectoryRef>
     <DirectoryRef Id="ShortcutGuideAssetsFolder" FileSource="$(var.ShortcutGuideAssetsFilesPath)">
     <!-- Generated by generateFileComponents.ps1 -->
     <!--ShortcutGuideAssetsFiles_Component_Def-->
     </DirectoryRef>
+    <DirectoryRef Id="ShortcutGuideManifestsFolder" FileSource="$(var.ShortcutGuideManifestsFilesPath)">
+    <!-- Generated by generateFileComponents.ps1 -->
+    <!--ShortcutGuideManifestsFiles_Component_Def-->
+    </DirectoryRef>
 
     <!-- Shortcut guide -->
     <ComponentGroup Id="ShortcutGuideComponentGroup" >
@@ -22,6 +30,12 @@
         </RegistryKey>
         <RemoveFolder Id="RemoveFolderShortcutGuideAssetsInstallFolder" Directory="ShortcutGuideAssetsFolder" On="uninstall"/>
       </Component>
+      <Component Id="RemoveShortcutGuideManifestsFolder" Guid="F47E2C3A-8D91-4B6F-A2E5-9C8D7F6A1B3E" Directory="ShortcutGuideManifestsFolder" >
+        <RegistryKey Root="$(var.RegistryScope)" Key="Software\Classes\powertoys\components">
+          <RegistryValue Type="string" Name="RemoveShortcutGuideManifestsFolder" Value="" KeyPath="yes"/>
+        </RegistryKey>
+        <RemoveFolder Id="RemoveFolderShortcutGuideManifestsInstallFolder" Directory="ShortcutGuideManifestsFolder" On="uninstall"/>
+      </Component>
     </ComponentGroup>
 
   </Fragment>

installer/PowerToysSetupVNext/generateAllFileComponents.ps1

@@ -28,7 +28,7 @@ Function Generate-FileList() {
 
     $fileExclusionList = @("*.pdb", "*.lastcodeanalysissucceeded", "createdump.exe", "powertoys.exe")
 
-    $fileInclusionList = @("*.dll", "*.exe", "*.json", "*.msix", "*.png", "*.gif", "*.ico", "*.cur", "*.svg", "index.html", "reg.js", "gitignore.js", "srt.js", "monacoSpecialLanguages.js", "customTokenThemeRules.js", "*.pri")
+    $fileInclusionList = @("*.dll", "*.exe", "*.json", "*.msix", "*.png", "*.gif", "*.ico", "*.cur", "*.svg", "index.html", "reg.js", "gitignore.js", "srt.js", "monacoSpecialLanguages.js", "customTokenThemeRules.js", "*.pri", "*.yml")
 
     # MFC DLLs leak into the output via WindowsAppSDKSelfContained but no PowerToys binary imports them.
     # Verified with dumpbin /dependents across all 2176 binaries — zero consumers.
@@ -112,6 +112,8 @@ Function Generate-FileComponents() {
 
     foreach ($file in $fileList) {
         $fileTmp = $file -replace "-", "_"
+        $fileTmp = $fileTmp -replace "[^A-Za-z0-9_.]", "_"
+        if ($fileTmp -match "^[^A-Za-z_]") { $fileTmp = "_$fileTmp" }
         $componentDefs +=
     @"
               <File Id="$($fileListName)_File_$($fileTmp)" Source="`$(var.$($fileListName)Path)\$($file)" />`r`n
@@ -397,8 +399,24 @@ Generate-FileComponents -fileListName "ValueGeneratorImagesCmpFiles" -wxsFilePat
 ## Plugins
 
 #ShortcutGuide
+# Ensure manifest yml files are in the build output (the Build target's CopyToOutputDirectory
+# may not run reliably under -graph mode in solution builds).
+$sgManifestsSrc = "$PSScriptRoot..\..\..\src\modules\ShortcutGuide\ShortcutGuide.Ui\Assets\ShortcutGuide\Manifests"
+$sgManifestsDst = "$PSScriptRoot..\..\..\$platform\Release\WinUI3Apps\Assets\ShortcutGuide\Manifests"
+Write-Host "ShortcutGuide manifests: src=$sgManifestsSrc exists=$(Test-Path $sgManifestsSrc)"
+Write-Host "ShortcutGuide manifests: dst=$sgManifestsDst exists=$(Test-Path $sgManifestsDst)"
+if (Test-Path $sgManifestsSrc) {
+    New-Item -Path $sgManifestsDst -ItemType Directory -Force | Out-Null
+    Copy-Item "$sgManifestsSrc\*.yml" -Destination $sgManifestsDst -Force
+    $copied = (Get-ChildItem "$sgManifestsDst\*.yml" -ErrorAction SilentlyContinue).Count
+    Write-Host "ShortcutGuide manifests: copied $copied yml files to build output"
+} else {
+    Write-Host "WARNING: ShortcutGuide manifest source not found at $sgManifestsSrc"
+}
 Generate-FileList -fileDepsJson "" -fileListName ShortcutGuideAssetsFiles -wxsFilePath $PSScriptRoot\ShortcutGuide.wxs -depsPath "$PSScriptRoot..\..\..\$platform\Release\WinUI3Apps\Assets\ShortcutGuide\"
-Generate-FileComponents -fileListName "ShortcutGuideAssetsFiles" -wxsFilePath $PSScriptRoot\ShortcutGuide.wxs -regroot $registryroot
+Generate-FileComponents -fileListName "ShortcutGuideAssetsFiles" -wxsFilePath $PSScriptRoot\ShortcutGuide.wxs
+Generate-FileList -fileDepsJson "" -fileListName ShortcutGuideManifestsFiles -wxsFilePath $PSScriptRoot\ShortcutGuide.wxs -depsPath "$PSScriptRoot..\..\..\$platform\Release\WinUI3Apps\Assets\ShortcutGuide\Manifests\"
+Generate-FileComponents -fileListName "ShortcutGuideManifestsFiles" -wxsFilePath $PSScriptRoot\ShortcutGuide.wxs
 
 #Settings
 Generate-FileList -fileDepsJson "" -fileListName SettingsV2AssetsFiles -wxsFilePath $PSScriptRoot\Settings.wxs -depsPath "$PSScriptRoot..\..\..\$platform\Release\WinUI3Apps\Assets\Settings\"

src/ActionRunner/actionRunner.vcxproj

@@ -14,7 +14,6 @@
   <PropertyGroup Label="Configuration">
     
   </PropertyGroup>
-  <Import Project="$(RepoRoot)deps\expected.props" />
   <PropertyGroup>
     <ConfigurationType>Application</ConfigurationType>
   </PropertyGroup>

src/Update/PowerToys.Update.cpp

@@ -14,6 +14,8 @@
 #include <common/updating/updating.h>
 #include <common/updating/updateState.h>
 #include <common/updating/installer.h>
+#include <common/updating/configBackup.h>
+#include <common/updating/updateLifecycle.h>
 
 #include <common/utils/elevation.h>
 #include <common/utils/HttpClient.h>
@@ -21,6 +23,8 @@
 #include <common/utils/resources.h>
 #include <common/utils/timeutil.h>
 
+#include <wil/resource.h>
+
 #include <common/SettingsAPI/settings_helpers.h>
 
 #include <common/logger/logger.h>
@@ -36,17 +40,59 @@ using namespace cmdArg;
 
 namespace fs = std::filesystem;
 
+void CleanupStaleTempUpdaters()
+{
+    // Remove orphaned PowerToys.Update.*.exe files from previous runs
+    try
+    {
+        std::error_code ec;
+        const auto tempDir = fs::temp_directory_path();
+        for (const auto& entry : fs::directory_iterator(tempDir, ec))
+        {
+            if (ec)
+            {
+                break;
+            }
+
+            if (!entry.is_regular_file())
+            {
+                continue;
+            }
+
+            const auto filename = entry.path().filename().wstring();
+            if (filename.starts_with(L"PowerToys.Update.") && filename.ends_with(L".exe"))
+            {
+                // Skip our own file (current PID)
+                const auto ownFilename = L"PowerToys.Update." + std::to_wstring(GetCurrentProcessId()) + L".exe";
+                if (filename == ownFilename)
+                {
+                    continue;
+                }
+
+                fs::remove(entry.path(), ec);
+                // Failure to delete is expected if another updater is still running
+            }
+        }
+    }
+    catch (...)
+    {
+        // Best-effort cleanup; don't block the update
+    }
+}
+
 std::optional<fs::path> CopySelfToTempDir()
 {
+    CleanupStaleTempUpdaters();
+
     std::error_code error;
-    auto dst_path = fs::temp_directory_path() / "PowerToys.Update.exe";
+    auto dst_path = fs::temp_directory_path() / (L"PowerToys.Update." + std::to_wstring(GetCurrentProcessId()) + L".exe");
     fs::copy_file(get_module_filename(), dst_path, fs::copy_options::overwrite_existing, error);
     if (error)
     {
         return std::nullopt;
     }
 
-    return std::move(dst_path);
+    return dst_path;
 }
 
 std::optional<fs::path> ObtainInstaller(bool& isUpToDate)
@@ -57,34 +103,9 @@ std::optional<fs::path> ObtainInstaller(bool& isUpToDate)
 
     auto state = UpdateState::read();
 
-    const auto new_version_info = std::move(get_github_version_info_async()).get();
-    if (std::holds_alternative<version_up_to_date>(*new_version_info))
-    {
-        isUpToDate = true;
-        Logger::error("Invoked with -update_now argument, but no update was available");
-        return std::nullopt;
-    }
-
-    if (state.state == UpdateState::readyToDownload || state.state == UpdateState::errorDownloading)
-    {
-        if (!new_version_info)
-        {
-            Logger::error(L"Couldn't obtain github version info: {}", new_version_info.error());
-            return std::nullopt;
-        }
-
-        // Cleanup old updates before downloading the latest
-        updating::cleanup_updates();
-
-        auto downloaded_installer = std::move(download_new_version_async(std::get<new_version_download_info>(*new_version_info))).get();
-        if (!downloaded_installer)
-        {
-            Logger::error("Couldn't download new installer");
-        }
-
-        return downloaded_installer;
-    }
-    else if (state.state == UpdateState::readyToInstall)
+    // Handle readyToInstall first — the installer is already on disk,
+    // so we don't need a GitHub API call (which may fail if offline).
+    if (state.state == UpdateState::readyToInstall)
     {
         fs::path installer{ get_pending_updates_path() / state.downloadedInstallerFilename };
         if (fs::is_regular_file(installer))
@@ -97,12 +118,44 @@ std::optional<fs::path> ObtainInstaller(bool& isUpToDate)
             return std::nullopt;
         }
     }
-    else if (state.state == UpdateState::upToDate)
+
+    if (state.state == UpdateState::upToDate)
     {
         isUpToDate = true;
         return std::nullopt;
     }
 
+    const auto new_version_info = std::move(get_github_version_info_async()).get();
+
+    // Check for error BEFORE dereferencing — the old code crashed here
+    // when GitHub API was unreachable (new_version_info held an error string).
+    if (!new_version_info)
+    {
+        Logger::error(L"Couldn't obtain github version info: {}", new_version_info.error());
+        return std::nullopt;
+    }
+
+    if (std::holds_alternative<version_up_to_date>(*new_version_info))
+    {
+        isUpToDate = true;
+        Logger::error("Invoked with -update_now argument, but no update was available");
+        return std::nullopt;
+    }
+
+    if (state.state == UpdateState::readyToDownload || state.state == UpdateState::errorDownloading)
+    {
+        // Cleanup old updates before downloading the latest
+        updating::cleanup_updates();
+
+        auto downloaded_installer = std::move(download_new_version_async(std::get<new_version_download_info>(*new_version_info))).get();
+        if (!downloaded_installer)
+        {
+            Logger::error("Couldn't download new installer");
+        }
+
+        return downloaded_installer;
+    }
+
     Logger::error("Invoked with -update_now argument, but update state was invalid");
     return std::nullopt;
 }
@@ -116,13 +169,32 @@ bool InstallNewVersionStage1(fs::path installer)
 
         if (pt_main_window != nullptr)
         {
-            SendMessageW(pt_main_window, WM_CLOSE, 0, 0);
+            // Get the process that owns the tray window so we can wait for it to exit
+            DWORD ptProcessId = 0;
+            GetWindowThreadProcessId(pt_main_window, &ptProcessId);
+
+            // Use SendMessageTimeoutW to avoid blocking indefinitely if the
+            // tray window thread is hung or unresponsive.
+            DWORD_PTR result = 0;
+            SendMessageTimeoutW(pt_main_window, WM_CLOSE, 0, 0, SMTO_ABORTIFHUNG, 5000, &result);
+
+            // Wait for PT to actually exit before launching installer.
+            // Without this, the installer may find PT files locked.
+            if (ptProcessId != 0)
+            {
+                wil::unique_handle ptProcess{ OpenProcess(SYNCHRONIZE, FALSE, ptProcessId) };
+                if (ptProcess)
+                {
+                    WaitForSingleObject(ptProcess.get(), 10000); // 10 second timeout
+                }
+            }
         }
 
-        std::wstring arguments{ UPDATE_NOW_LAUNCH_STAGE2 };
-        arguments += L" \"";
-        arguments += installer.c_str();
-        arguments += L"\"";
+        // Pass the install directory so Stage 2 can relaunch PowerToys after install
+        const std::wstring installDir = get_module_folderpath();
+
+        std::wstring arguments = updating::BuildStage2Arguments(
+            UPDATE_NOW_LAUNCH_STAGE2, installer, fs::path(installDir));
         SHELLEXECUTEINFOW sei{ sizeof(sei) };
         sei.fMask = { SEE_MASK_FLAG_NO_UI | SEE_MASK_NOASYNC };
         sei.lpFile = copy_in_temp->c_str();
@@ -190,9 +262,16 @@ int WINAPI WinMain(HINSTANCE, HINSTANCE, LPSTR, int)
     LPWSTR* args = CommandLineToArgvW(GetCommandLineW(), &nArgs);
     if (!args || nArgs < 2)
     {
+        if (args)
+        {
+            LocalFree(args);
+        }
         return 1;
     }
 
+    // D3 fix: ensure args is freed on all exit paths
+    auto freeArgs = wil::scope_exit([&] { LocalFree(args); });
+
     std::wstring_view action{ args[1] };
 
     std::filesystem::path logFilePath(PTSettingsHelper::get_root_save_folder_location());
@@ -201,6 +280,11 @@ int WINAPI WinMain(HINSTANCE, HINSTANCE, LPSTR, int)
 
     if (action == UPDATE_NOW_LAUNCH_STAGE1)
     {
+        // Backup config files before the update to protect against corruption
+        Logger::info("Backing up config files before update");
+        auto backupResult = updating::BackupConfigFiles(fs::path(PTSettingsHelper::get_root_save_folder_location()));
+        Logger::info("Config backup complete: {} files backed up, {} errors", backupResult.filesBackedUp, backupResult.errors);
+
         bool isUpToDate = false;
         auto installerPath = ObtainInstaller(isUpToDate);
         bool failed = !installerPath.has_value();
@@ -217,6 +301,12 @@ int WINAPI WinMain(HINSTANCE, HINSTANCE, LPSTR, int)
     }
     else if (action == UPDATE_NOW_LAUNCH_STAGE2)
     {
+        if (nArgs < 3)
+        {
+            Logger::error("Stage 2 invoked without installer path argument");
+            return 1;
+        }
+
         using namespace std::string_view_literals;
         const bool failed = !InstallNewVersionStage2(args[2]);
         if (failed)
@@ -227,6 +317,39 @@ int WINAPI WinMain(HINSTANCE, HINSTANCE, LPSTR, int)
                 state.state = UpdateState::errorDownloading;
             });
         }
+
+        // Always check for corrupted configs after Stage 2, regardless
+        // of install success/failure. A failed install may still corrupt configs.
+        Logger::info("Checking for corrupted config files after update");
+        auto restoreResult = updating::RestoreCorruptedConfigs(fs::path(PTSettingsHelper::get_root_save_folder_location()));
+        Logger::info("Config restore check complete: {}/{} files restored, {} errors",
+                     restoreResult.filesRestored, restoreResult.filesChecked, restoreResult.errors);
+
+        if (!failed)
+        {
+            // Relaunch PowerToys from the install directory
+            if (updating::CanRelaunchAfterUpdate(nArgs))
+            {
+                std::wstring ptExePath = updating::BuildPowerToysExePath(args[3]);
+
+                Logger::info(L"Relaunching PowerToys after update: {}", ptExePath);
+
+                SHELLEXECUTEINFOW sei{ sizeof(sei) };
+                sei.fMask = { SEE_MASK_FLAG_NO_UI | SEE_MASK_NOASYNC };
+                sei.lpFile = ptExePath.c_str();
+                sei.nShow = SW_SHOWNORMAL;
+                sei.lpParameters = UPDATE_REPORT_SUCCESS;
+
+                if (!ShellExecuteExW(&sei))
+                {
+                    Logger::error(L"Failed to relaunch PowerToys after update");
+                }
+            }
+            else
+            {
+                Logger::warn("Install directory not provided to Stage 2 - cannot relaunch PowerToys");
+            }
+        }
         return failed;
     }
 

src/Update/PowerToys.Update.vcxproj

@@ -14,7 +14,6 @@
   <PropertyGroup Label="Configuration">
     
   </PropertyGroup>
-  <Import Project="$(RepoRoot)deps\expected.props" />
   <PropertyGroup>
     <ConfigurationType>Application</ConfigurationType>
   </PropertyGroup>

src/common/UnitTests-CommonUtils/UnitTests-CommonUtils.vcxproj

@@ -27,7 +27,7 @@
   <PropertyGroup Label="UserMacros" />
   <ItemDefinitionGroup>
     <ClCompile>
-      <AdditionalIncludeDirectories>..\;..\utils;..\Telemetry;..\..\;..\..\..\deps\;..\..\..\deps\spdlog\include;..\..\..\packages\Microsoft.Windows.ImplementationLibrary.1.0.260126.7\include;$(VCInstallDir)UnitTest\include;%(AdditionalIncludeDirectories)</AdditionalIncludeDirectories>
+      <AdditionalIncludeDirectories>..\;..\utils;..\Telemetry;..\..\;..\..\..\deps\;..\..\..\packages\Microsoft.Windows.ImplementationLibrary.1.0.260126.7\include;$(VCInstallDir)UnitTest\include;%(AdditionalIncludeDirectories)</AdditionalIncludeDirectories>
       <LanguageStandard>stdcpp23</LanguageStandard>
       <PreprocessorDefinitions>SPDLOG_WCHAR_TO_UTF8_SUPPORT;SPDLOG_HEADER_ONLY;%(PreprocessorDefinitions)</PreprocessorDefinitions>
     </ClCompile>

src/common/logger/logger.vcxproj

@@ -70,9 +70,6 @@
     </ClCompile>
   </ItemGroup>
   <ItemGroup>
-    <ProjectReference Include="..\..\logging\logging.vcxproj">
-      <Project>{7e1e3f13-2bd6-3f75-a6a7-873a2b55c60f}</Project>
-    </ProjectReference>
     <ProjectReference Include="..\version\version.vcxproj">
       <Project>{cc6e41ac-8174-4e8a-8d22-85dd7f4851df}</Project>
     </ProjectReference>

src/common/updating/UnitTests/UpdatingTests.cpp

@@ -0,0 +1,679 @@
+// Copyright (c) Microsoft Corporation
+// The Microsoft Corporation licenses this file to you under the MIT license.
+// See the LICENSE file in the project root for more information.
+
+#include "pch.h"
+
+#include <algorithm>
+#include <filesystem>
+#include <fstream>
+#include <iterator>
+#include <string>
+#include <vector>
+
+#include <common/updating/configBackup.h>
+#include <common/updating/updateLifecycle.h>
+
+using namespace Microsoft::VisualStudio::CppUnitTestFramework;
+
+namespace fs = std::filesystem;
+
+namespace UpdatingUnitTests
+{
+    // Helper to create a temp directory for test isolation.
+    // Each instance gets a unique subdirectory to prevent test interference.
+    class TempDir
+    {
+    public:
+        TempDir()
+        {
+            wchar_t tempPath[MAX_PATH + 1];
+            GetTempPathW(MAX_PATH, tempPath);
+            static std::atomic<int> counter{0};
+            m_path = fs::path(tempPath) / (L"PowerToysUpdateTests_" + std::to_wstring(counter++));
+
+            // Ensure clean state
+            std::error_code ec;
+            fs::remove_all(m_path, ec);
+            fs::create_directories(m_path, ec);
+        }
+
+        ~TempDir()
+        {
+            std::error_code ec;
+            fs::remove_all(m_path, ec);
+        }
+
+        const fs::path& path() const { return m_path; }
+
+        // Write a file with the given content
+        void WriteFile(const fs::path& relativePath, const std::string& content)
+        {
+            auto fullPath = m_path / relativePath;
+            fs::create_directories(fullPath.parent_path());
+            std::ofstream file(fullPath, std::ios::binary);
+            file.write(content.data(), content.size());
+        }
+
+        // Write a file with raw bytes (including null bytes for corruption testing)
+        void WriteFileBytes(const fs::path& relativePath, const std::vector<char>& bytes)
+        {
+            auto fullPath = m_path / relativePath;
+            fs::create_directories(fullPath.parent_path());
+            std::ofstream file(fullPath, std::ios::binary);
+            file.write(bytes.data(), bytes.size());
+        }
+
+        // Read file content as string
+        std::string ReadFile(const fs::path& relativePath)
+        {
+            auto fullPath = m_path / relativePath;
+            std::ifstream file(fullPath, std::ios::binary);
+            return std::string(std::istreambuf_iterator<char>(file), std::istreambuf_iterator<char>());
+        }
+
+        bool FileExists(const fs::path& relativePath)
+        {
+            return fs::exists(m_path / relativePath);
+        }
+
+    private:
+        fs::path m_path;
+    };
+
+    TEST_CLASS(IsJsonFileCorruptedTests)
+    {
+    public:
+        // Tests IsJsonFileCorrupted: valid JSON with no null bytes returns false.
+        // Covers: configBackup.h IsJsonFileCorrupted — happy path, full file scan.
+        TEST_METHOD(CleanJsonFileIsNotCorrupted)
+        {
+            TempDir dir;
+            dir.WriteFile(L"settings.json", R"({"theme":"dark","startup":true})");
+
+            Assert::IsFalse(updating::IsJsonFileCorrupted(dir.path() / L"settings.json"));
+        }
+
+        // Tests IsJsonFileCorrupted: zero-length file returns false (empty is not corrupted).
+        // Covers: configBackup.h IsJsonFileCorrupted — file.read returns 0 bytes immediately.
+        TEST_METHOD(EmptyFileIsNotCorrupted)
+        {
+            TempDir dir;
+            dir.WriteFile(L"empty.json", "");
+
+            Assert::IsFalse(updating::IsJsonFileCorrupted(dir.path() / L"empty.json"));
+        }
+
+        // Tests IsJsonFileCorrupted: file containing embedded null bytes returns true.
+        // Covers: configBackup.h IsJsonFileCorrupted — null byte detection within buffer.
+        TEST_METHOD(FileWithNullBytesIsCorrupted)
+        {
+            TempDir dir;
+            std::vector<char> corrupted = { '{', '"', 'a', '"', ':', '\0', '\0', '\0', '}' };
+            dir.WriteFileBytes(L"corrupted.json", corrupted);
+
+            Assert::IsTrue(updating::IsJsonFileCorrupted(dir.path() / L"corrupted.json"));
+        }
+
+        // Tests IsJsonFileCorrupted: file entirely filled with 0x00 bytes returns true.
+        // Reproduces the exact bug from #46179 where installer zeroed out JSON files.
+        // Covers: configBackup.h IsJsonFileCorrupted — first byte is null.
+        TEST_METHOD(FileFilledWithNullBytesIsCorrupted)
+        {
+            TempDir dir;
+            std::vector<char> allNulls(1024, '\0');
+            dir.WriteFileBytes(L"workspaces.json", allNulls);
+
+            Assert::IsTrue(updating::IsJsonFileCorrupted(dir.path() / L"workspaces.json"));
+        }
+
+        // Tests IsJsonFileCorrupted: path that does not exist returns false.
+        // Covers: configBackup.h IsJsonFileCorrupted — file.is_open() check.
+        TEST_METHOD(NonExistentFileIsNotCorrupted)
+        {
+            TempDir dir;
+
+            Assert::IsFalse(updating::IsJsonFileCorrupted(dir.path() / L"missing.json"));
+        }
+
+        // Tests IsJsonFileCorrupted: file larger than the 4096-byte read chunk
+        // with no null bytes returns false.
+        // Covers: configBackup.h IsJsonFileCorrupted — multi-chunk while loop.
+        TEST_METHOD(LargeCleanFileIsNotCorrupted)
+        {
+            TempDir dir;
+            std::string largeContent(8192, 'x');
+            dir.WriteFile(L"large.json", largeContent);
+
+            Assert::IsFalse(updating::IsJsonFileCorrupted(dir.path() / L"large.json"));
+        }
+
+        // Tests IsJsonFileCorrupted: null byte placed after the first 4096-byte
+        // chunk boundary is still detected.
+        // Covers: configBackup.h IsJsonFileCorrupted — second chunk scan.
+        TEST_METHOD(NullByteAtEndOfLargeFileIsDetected)
+        {
+            TempDir dir;
+            std::string content(5000, 'x');
+            content[4999] = '\0';
+            std::vector<char> bytes(content.begin(), content.end());
+            dir.WriteFileBytes(L"sneaky.json", bytes);
+
+            Assert::IsTrue(updating::IsJsonFileCorrupted(dir.path() / L"sneaky.json"));
+        }
+    };
+
+    TEST_CLASS(BackupConfigFilesTests)
+    {
+    public:
+        // Tests BackupConfigFiles: root-level .json files are copied to ConfigBackup.
+        // Covers: configBackup.h BackupConfigFiles — root directory_iterator,
+        //         is_regular_file && extension == ".json" branch.
+        // Setup: Two root-level JSON files.
+        TEST_METHOD(BackupCopiesRootJsonFiles)
+        {
+            TempDir dir;
+            dir.WriteFile(L"settings.json", R"({"theme":"dark"})");
+            dir.WriteFile(L"UpdateState.json", R"({"state":0})");
+
+            updating::BackupConfigFiles(dir.path());
+
+            Assert::IsTrue(dir.FileExists(L"ConfigBackup\\settings.json"));
+            Assert::IsTrue(dir.FileExists(L"ConfigBackup\\UpdateState.json"));
+            Assert::AreEqual(std::string(R"({"theme":"dark"})"), dir.ReadFile(L"ConfigBackup\\settings.json"));
+        }
+
+        // Tests BackupConfigFiles: .json files inside module subdirectories are
+        // copied to ConfigBackup/<module>/.
+        // Covers: configBackup.h BackupConfigFiles — is_directory branch,
+        //         module directory_iterator with extension filter.
+        // Setup: Root JSON + two module directories with JSON files.
+        TEST_METHOD(BackupCopiesModuleJsonFiles)
+        {
+            TempDir dir;
+            dir.WriteFile(L"settings.json", R"({"theme":"dark"})");
+            dir.WriteFile(L"FancyZones\\settings.json", R"({"zones":[]})");
+            dir.WriteFile(L"Workspaces\\workspaces.json", R"({"workspaces":[]})");
+
+            updating::BackupConfigFiles(dir.path());
+
+            Assert::IsTrue(dir.FileExists(L"ConfigBackup\\FancyZones\\settings.json"));
+            Assert::IsTrue(dir.FileExists(L"ConfigBackup\\Workspaces\\workspaces.json"));
+            Assert::AreEqual(std::string(R"({"zones":[]})"),
+                dir.ReadFile(L"ConfigBackup\\FancyZones\\settings.json"));
+        }
+
+        // Tests BackupConfigFiles: non-.json files at root level are not copied.
+        // Covers: configBackup.h BackupConfigFiles — extension filter excludes .log.
+        // Setup: One JSON file + one .log file at root.
+        TEST_METHOD(BackupSkipsNonJsonFiles)
+        {
+            TempDir dir;
+            dir.WriteFile(L"settings.json", R"({"theme":"dark"})");
+            dir.WriteFile(L"debug.log", "log data");
+
+            updating::BackupConfigFiles(dir.path());
+
+            Assert::IsTrue(dir.FileExists(L"ConfigBackup\\settings.json"));
+            Assert::IsFalse(dir.FileExists(L"ConfigBackup\\debug.log"));
+        }
+
+        // Tests BackupConfigFiles: the "Updates" directory is explicitly skipped.
+        // Covers: configBackup.h BackupConfigFiles — dirName == L"Updates" continue.
+        // Setup: Root JSON + Updates directory containing a file.
+        TEST_METHOD(BackupSkipsUpdatesDirectory)
+        {
+            TempDir dir;
+            dir.WriteFile(L"settings.json", R"({"theme":"dark"})");
+            dir.WriteFile(L"Updates\\installer.exe", "fake exe");
+
+            updating::BackupConfigFiles(dir.path());
+
+            Assert::IsFalse(dir.FileExists(L"ConfigBackup\\Updates"));
+        }
+
+        // Tests BackupConfigFiles: running backup twice overwrites the previous
+        // backup with current file content.
+        // Covers: configBackup.h BackupConfigFiles — fs::remove_all(backupDir) +
+        //         copy_options::overwrite_existing.
+        // Setup: Backup, modify original, backup again.
+        TEST_METHOD(BackupOverwritesPreviousBackup)
+        {
+            TempDir dir;
+            dir.WriteFile(L"settings.json", R"({"version":1})");
+            updating::BackupConfigFiles(dir.path());
+
+            // Update the original
+            dir.WriteFile(L"settings.json", R"({"version":2})");
+            updating::BackupConfigFiles(dir.path());
+
+            Assert::AreEqual(std::string(R"({"version":2})"), dir.ReadFile(L"ConfigBackup\\settings.json"));
+        }
+
+        // Tests BackupConfigFiles: non-.json files inside module subdirectories
+        // (e.g., FancyZones/zones.dat) should NOT be backed up.
+        // Covers: configBackup.h BackupConfigFiles — extension filter in module loop.
+        TEST_METHOD(BackupSkipsNonJsonFilesInModuleDirs)
+        {
+            TempDir dir;
+            dir.WriteFile(L"settings.json", R"({})");
+            dir.WriteFile(L"FancyZones\\settings.json", R"({"zones":[]})");
+            dir.WriteFile(L"FancyZones\\zones.dat", "binary data");
+
+            updating::BackupConfigFiles(dir.path());
+
+            Assert::IsTrue(dir.FileExists(L"ConfigBackup\\FancyZones\\settings.json"));
+            Assert::IsFalse(dir.FileExists(L"ConfigBackup\\FancyZones\\zones.dat"));
+        }
+
+        // Tests BackupConfigFiles: empty root directory with no files produces
+        // an empty ConfigBackup dir without errors.
+        // Covers: configBackup.h BackupConfigFiles — empty directory_iterator.
+        TEST_METHOD(BackupEmptyRootDirSucceeds)
+        {
+            TempDir dir;
+            // Root dir exists but has no files
+
+            updating::BackupConfigFiles(dir.path());
+
+            Assert::IsTrue(dir.FileExists(L"ConfigBackup"));
+        }
+    };
+
+    TEST_CLASS(RestoreCorruptedConfigsTests)
+    {
+    public:
+        // Tests RestoreCorruptedConfigs: corrupted root-level JSON file is restored
+        // from the good backup copy.
+        // Covers: configBackup.h RestoreCorruptedConfigs — root file restore branch,
+        //         fs::exists + IsJsonFileCorrupted + backup integrity check.
+        // Setup: Good file -> backup -> corrupt original -> restore.
+        TEST_METHOD(RestoreFixesCorruptedRootFile)
+        {
+            TempDir dir;
+            const std::string goodContent = R"({"theme":"dark"})";
+            dir.WriteFile(L"settings.json", goodContent);
+
+            // Backup
+            updating::BackupConfigFiles(dir.path());
+
+            // Corrupt the original
+            std::vector<char> corrupted(goodContent.size(), '\0');
+            dir.WriteFileBytes(L"settings.json", corrupted);
+            Assert::IsTrue(updating::IsJsonFileCorrupted(dir.path() / L"settings.json"));
+
+            // Restore
+            updating::RestoreCorruptedConfigs(dir.path());
+
+            Assert::IsFalse(updating::IsJsonFileCorrupted(dir.path() / L"settings.json"));
+            Assert::AreEqual(goodContent, dir.ReadFile(L"settings.json"));
+        }
+
+        // Tests RestoreCorruptedConfigs: corrupted module-level JSON file is restored
+        // from the good backup copy.
+        // Covers: configBackup.h RestoreCorruptedConfigs — module directory branch,
+        //         moduleBackupEntry restore with integrity check.
+        // Setup: Module file + root file -> backup -> corrupt module file -> restore.
+        TEST_METHOD(RestoreFixesCorruptedModuleFile)
+        {
+            TempDir dir;
+            const std::string goodContent = R"({"workspaces":[]})";
+            dir.WriteFile(L"Workspaces\\workspaces.json", goodContent);
+            dir.WriteFile(L"settings.json", R"({})");
+
+            updating::BackupConfigFiles(dir.path());
+
+            // Corrupt the module file
+            std::vector<char> corrupted(goodContent.size(), '\0');
+            dir.WriteFileBytes(L"Workspaces\\workspaces.json", corrupted);
+
+            updating::RestoreCorruptedConfigs(dir.path());
+
+            Assert::AreEqual(goodContent, dir.ReadFile(L"Workspaces\\workspaces.json"));
+        }
+
+        // Tests RestoreCorruptedConfigs: clean (non-corrupted) files are NOT
+        // overwritten by backup — preserves user changes made after backup.
+        // Covers: configBackup.h RestoreCorruptedConfigs — IsJsonFileCorrupted
+        //         returns false, copy_file is skipped.
+        // Setup: File -> backup -> modify (but keep valid) -> restore.
+        TEST_METHOD(RestoreLeavesCleanFilesUntouched)
+        {
+            TempDir dir;
+            dir.WriteFile(L"settings.json", R"({"version":1})");
+
+            updating::BackupConfigFiles(dir.path());
+
+            // Modify original (but keep it clean JSON)
+            dir.WriteFile(L"settings.json", R"({"version":2})");
+
+            updating::RestoreCorruptedConfigs(dir.path());
+
+            // Should NOT have been restored since it's not corrupted
+            Assert::AreEqual(std::string(R"({"version":2})"), dir.ReadFile(L"settings.json"));
+        }
+
+        // Tests RestoreCorruptedConfigs: when no ConfigBackup directory exists,
+        // restore silently does nothing (no crash, no data loss).
+        // Covers: configBackup.h RestoreCorruptedConfigs — !fs::exists(backupDir)
+        //         early return.
+        // Setup: File with no prior backup.
+        TEST_METHOD(RestoreHandlesMissingBackupDirectory)
+        {
+            TempDir dir;
+            dir.WriteFile(L"settings.json", R"({"theme":"dark"})");
+
+            // No backup was created - restore should silently do nothing
+            updating::RestoreCorruptedConfigs(dir.path());
+
+            Assert::AreEqual(std::string(R"({"theme":"dark"})"), dir.ReadFile(L"settings.json"));
+        }
+
+        // Tests RestoreCorruptedConfigs: end-to-end scenario with multiple modules,
+        // some corrupted and some clean, verifying selective restore.
+        // Covers: configBackup.h RestoreCorruptedConfigs — both root and module
+        //         branches, selective restore based on corruption status.
+        // Setup: 4 modules -> backup -> corrupt 2 -> restore -> verify all 4.
+        TEST_METHOD(FullBackupAndRestoreRoundTrip)
+        {
+            TempDir dir;
+
+            // Set up a realistic config structure
+            dir.WriteFile(L"settings.json", R"({"startup":true,"theme":"dark"})");
+            dir.WriteFile(L"FancyZones\\settings.json", R"({"zones":[{"id":1}]})");
+            dir.WriteFile(L"Workspaces\\workspaces.json", R"({"workspaces":[{"name":"dev"}]})");
+            dir.WriteFile(L"KeyboardManager\\default.json", R"({"remaps":[]})");
+
+            // Backup
+            updating::BackupConfigFiles(dir.path());
+
+            // Corrupt some files (simulating #46179 scenario)
+            dir.WriteFileBytes(L"Workspaces\\workspaces.json", std::vector<char>(100, '\0'));
+            dir.WriteFileBytes(L"settings.json", std::vector<char>(50, '\0'));
+            // Leave FancyZones and KBM clean
+
+            // Restore
+            updating::RestoreCorruptedConfigs(dir.path());
+
+            // Corrupted files should be restored
+            Assert::AreEqual(std::string(R"({"startup":true,"theme":"dark"})"), dir.ReadFile(L"settings.json"));
+            Assert::AreEqual(std::string(R"({"workspaces":[{"name":"dev"}]})"), dir.ReadFile(L"Workspaces\\workspaces.json"));
+
+            // Clean files should be unchanged
+            Assert::AreEqual(std::string(R"({"zones":[{"id":1}]})"), dir.ReadFile(L"FancyZones\\settings.json"));
+            Assert::AreEqual(std::string(R"({"remaps":[]})"), dir.ReadFile(L"KeyboardManager\\default.json"));
+        }
+
+        // Tests RestoreCorruptedConfigs: when the original file has been deleted
+        // (not corrupted), restore should NOT recreate it from backup. The installer
+        // may have intentionally removed obsolete config files.
+        // Covers: configBackup.h RestoreCorruptedConfigs — fs::exists guard.
+        TEST_METHOD(RestoreSkipsDeletedOriginals)
+        {
+            TempDir dir;
+            dir.WriteFile(L"obsolete.json", R"({"old":true})");
+            updating::BackupConfigFiles(dir.path());
+
+            // Installer deletes the file
+            std::error_code ec;
+            fs::remove(dir.path() / L"obsolete.json", ec);
+
+            updating::RestoreCorruptedConfigs(dir.path());
+
+            // Should NOT be recreated
+            Assert::IsFalse(dir.FileExists(L"obsolete.json"));
+        }
+
+        // Tests RestoreCorruptedConfigs: when the backup file itself is corrupted
+        // (e.g., disk error during backup), restore should NOT copy corrupted
+        // backup over the original — that would make things worse.
+        // Covers: configBackup.h RestoreCorruptedConfigs — backup integrity check (B2 fix).
+        TEST_METHOD(RestoreSkipsCorruptedBackup)
+        {
+            TempDir dir;
+            dir.WriteFile(L"settings.json", R"({"theme":"dark"})");
+            updating::BackupConfigFiles(dir.path());
+
+            // Corrupt BOTH the original AND the backup
+            std::vector<char> nulls(50, '\0');
+            dir.WriteFileBytes(L"settings.json", nulls);
+            dir.WriteFileBytes(L"ConfigBackup\\settings.json", nulls);
+
+            updating::RestoreCorruptedConfigs(dir.path());
+
+            // Original should still be corrupted — we don't restore from bad backup
+            Assert::IsTrue(updating::IsJsonFileCorrupted(dir.path() / L"settings.json"));
+        }
+    };
+
+    // Simulates what actually happens during a PowerToys upgrade:
+    // 1. User has settings from normal use
+    // 2. Updater backs up before install (Stage 1)
+    // 3. Installer runs and corrupts some files (simulated)
+    // 4. Updater restores corrupted files (Stage 2)
+    // 5. PT relaunches and finds working configs
+    TEST_CLASS(UpgradeSimulationTests)
+    {
+    public:
+        // Tests full upgrade simulation: backup -> installer corrupts files -> restore.
+        // Verifies that corrupted files are restored and clean files are untouched.
+        // Covers: configBackup.h BackupConfigFiles + RestoreCorruptedConfigs —
+        //         end-to-end with 5 modules, 2 corrupted, 3 clean.
+        // Setup: Realistic config structure with multiple modules.
+        TEST_METHOD(SimulateUpgradeWithCorruption)
+        {
+            TempDir dir;
+
+            // === User's real config state before upgrade ===
+            dir.WriteFile(L"settings.json",
+                R"({"startup":true,"theme":"dark","run_elevated":false,"download_updates_automatically":true})");
+            dir.WriteFile(L"FancyZones\\settings.json",
+                R"({"zones":[{"id":1,"rect":{"x":0,"y":0,"w":960,"h":1080}}]})");
+            dir.WriteFile(L"Workspaces\\workspaces.json",
+                R"({"workspaces":[{"name":"dev","apps":["code","terminal"]}]})");
+            dir.WriteFile(L"KeyboardManager\\default.json",
+                R"({"remapKeys":{"inProcess":[{"original":"0x41","new":"0x42"}]}})");
+            dir.WriteFile(L"MouseWithoutBorders\\settings.json",
+                R"({"machineKey":"abc123","connectToAll":true})");
+
+            // Non-JSON files that should be left alone
+            dir.WriteFile(L"update.log", "2026-04-11 update started");
+
+            // === Stage 1: Backup before killing PT ===
+            updating::BackupConfigFiles(dir.path());
+
+            // Verify backup was created correctly
+            Assert::IsTrue(dir.FileExists(L"ConfigBackup\\settings.json"));
+            Assert::IsTrue(dir.FileExists(L"ConfigBackup\\FancyZones\\settings.json"));
+            Assert::IsTrue(dir.FileExists(L"ConfigBackup\\Workspaces\\workspaces.json"));
+            Assert::IsTrue(dir.FileExists(L"ConfigBackup\\KeyboardManager\\default.json"));
+            Assert::IsTrue(dir.FileExists(L"ConfigBackup\\MouseWithoutBorders\\settings.json"));
+            Assert::IsFalse(dir.FileExists(L"ConfigBackup\\update.log"));
+
+            // === Installer runs: some files get corrupted (the #46179 scenario) ===
+            // Workspaces JSON filled with null bytes
+            dir.WriteFileBytes(L"Workspaces\\workspaces.json", std::vector<char>(512, '\0'));
+            // Main settings partially corrupted (null bytes injected)
+            std::vector<char> partialCorrupt = { '{', '"', 's', '\0', '\0', '\0', '\0', '}' };
+            dir.WriteFileBytes(L"settings.json", partialCorrupt);
+
+            // FancyZones, KBM, and MWB survive the install fine
+            // (this is realistic - not all files get corrupted)
+
+            // === Stage 2: Restore after install completes ===
+            updating::RestoreCorruptedConfigs(dir.path());
+
+            // === Verify: PT relaunches and finds working configs ===
+
+            // Corrupted files should be restored from backup
+            Assert::IsFalse(updating::IsJsonFileCorrupted(dir.path() / L"settings.json"));
+            Assert::IsFalse(updating::IsJsonFileCorrupted(dir.path() / L"Workspaces\\workspaces.json"));
+            Assert::AreEqual(
+                std::string(R"({"startup":true,"theme":"dark","run_elevated":false,"download_updates_automatically":true})"),
+                dir.ReadFile(L"settings.json"));
+            Assert::AreEqual(
+                std::string(R"({"workspaces":[{"name":"dev","apps":["code","terminal"]}]})"),
+                dir.ReadFile(L"Workspaces\\workspaces.json"));
+
+            // Clean files should be untouched (not overwritten with backup)
+            Assert::AreEqual(
+                std::string(R"({"zones":[{"id":1,"rect":{"x":0,"y":0,"w":960,"h":1080}}]})"),
+                dir.ReadFile(L"FancyZones\\settings.json"));
+            Assert::AreEqual(
+                std::string(R"({"remapKeys":{"inProcess":[{"original":"0x41","new":"0x42"}]}})"),
+                dir.ReadFile(L"KeyboardManager\\default.json"));
+            Assert::AreEqual(
+                std::string(R"({"machineKey":"abc123","connectToAll":true})"),
+                dir.ReadFile(L"MouseWithoutBorders\\settings.json"));
+        }
+
+        // Tests upgrade from an old version that has fewer modules than the new version.
+        // Verifies that new module configs (created by the installer) are not touched
+        // by restore, while corrupted old configs are restored.
+        // Covers: configBackup.h RestoreCorruptedConfigs — module dir in root that
+        //         has no corresponding backup entry.
+        // Setup: Old version with 1 module -> backup -> new installer adds module -> corrupt old -> restore.
+        TEST_METHOD(SimulateUpgradeFromVeryOldVersion)
+        {
+            TempDir dir;
+
+            // Old version had fewer modules - only settings.json
+            dir.WriteFile(L"settings.json", R"({"theme":"dark","powertoys_version":"v0.60.0"})");
+
+            // Backup
+            updating::BackupConfigFiles(dir.path());
+
+            // New installer creates new module dirs that didn't exist before
+            dir.WriteFile(L"NewModule\\settings.json", R"({"enabled":true})");
+
+            // Old settings get corrupted during upgrade
+            dir.WriteFileBytes(L"settings.json", std::vector<char>(100, '\0'));
+
+            // Restore
+            updating::RestoreCorruptedConfigs(dir.path());
+
+            // Old settings restored
+            Assert::AreEqual(
+                std::string(R"({"theme":"dark","powertoys_version":"v0.60.0"})"),
+                dir.ReadFile(L"settings.json"));
+
+            // New module settings untouched (no backup existed for them)
+            Assert::AreEqual(
+                std::string(R"({"enabled":true})"),
+                dir.ReadFile(L"NewModule\\settings.json"));
+        }
+    };
+
+    // Tests for the update lifecycle: argument passing between Stage 1 and Stage 2,
+    // relaunch path construction, and the handoff that was broken in #42004/#43011/#44071.
+    TEST_CLASS(UpdateLifecycleTests)
+    {
+    public:
+        // Tests BuildStage2Arguments: output contains the stage 2 flag, installer path,
+        // and install directory — all three components needed for Stage 2.
+        // Covers: updateLifecycle.h BuildStage2Arguments — concatenation logic.
+        // Setup: Typical paths with spaces (Program Files).
+        TEST_METHOD(BuildStage2ArgumentsContainsInstallerAndInstallDir)
+        {
+            const auto args = updating::BuildStage2Arguments(
+                L"-update_now_stage_2",
+                L"C:\\Users\\test\\AppData\\Local\\PowerToys\\Updates\\powertoyssetup-x64.exe",
+                L"C:\\Program Files\\PowerToys");
+
+            // Must contain the stage 2 flag
+            Assert::IsTrue(args.find(L"-update_now_stage_2") != std::wstring::npos);
+            // Must contain the installer path (quoted)
+            Assert::IsTrue(args.find(L"powertoyssetup-x64.exe") != std::wstring::npos);
+            // Must contain the install directory (quoted) — this was MISSING before our fix
+            Assert::IsTrue(args.find(L"C:\\Program Files\\PowerToys") != std::wstring::npos);
+        }
+
+        // Tests BuildStage2Arguments: both paths are wrapped in double quotes to
+        // survive CommandLineToArgvW parsing when paths contain spaces.
+        // Covers: updateLifecycle.h BuildStage2Arguments — quote wrapping.
+        // Setup: Installer path with spaces.
+        TEST_METHOD(BuildStage2ArgumentsQuotesBothPaths)
+        {
+            const auto args = updating::BuildStage2Arguments(
+                L"-update_now_stage_2",
+                L"C:\\path with spaces\\installer.exe",
+                L"C:\\Program Files\\PowerToys");
+
+            // Count quotes — should have 4 (open/close for each path)
+            size_t quoteCount = std::count(args.begin(), args.end(), L'"');
+            Assert::AreEqual(size_t{ 4 }, quoteCount);
+        }
+
+        // Tests BuildPowerToysExePath: appends "PowerToys.exe" to the install dir.
+        // Covers: updateLifecycle.h BuildPowerToysExePath — fs::path / operator.
+        // Setup: Standard install path without trailing backslash.
+        TEST_METHOD(BuildPowerToysExePathAppendsExeName)
+        {
+            const auto path = updating::BuildPowerToysExePath(L"C:\\Program Files\\PowerToys");
+            Assert::AreEqual(std::wstring(L"C:\\Program Files\\PowerToys\\PowerToys.exe"), path);
+        }
+
+        // Tests BuildPowerToysExePath: trailing backslash does not produce double
+        // backslash (e.g., "...PowerToys\\PowerToys.exe").
+        // Covers: updateLifecycle.h BuildPowerToysExePath — fs::path normalizes separators.
+        // Setup: Install path with trailing backslash.
+        TEST_METHOD(BuildPowerToysExePathHandlesTrailingBackslash)
+        {
+            const auto path = updating::BuildPowerToysExePath(L"C:\\Program Files\\PowerToys\\");
+            Assert::AreEqual(std::wstring(L"C:\\Program Files\\PowerToys\\PowerToys.exe"), path);
+        }
+
+        // Tests BuildPowerToysExePath: empty string produces just "PowerToys.exe".
+        // Covers: updateLifecycle.h BuildPowerToysExePath — fs::path with empty input.
+        // Setup: Empty install directory string.
+        TEST_METHOD(BuildPowerToysExePathHandlesEmptyString)
+        {
+            const auto path = updating::BuildPowerToysExePath(L"");
+            Assert::AreEqual(std::wstring(L"PowerToys.exe"), path);
+        }
+
+        // Tests CanRelaunchAfterUpdate: returns true when Stage 2 receives
+        // the install directory (argCount >= 4), false otherwise.
+        // This is the gate that prevents relaunch when using an old Stage 1
+        // that didn't pass the install dir (#42004/#43011/#44071).
+        // Covers: updateLifecycle.h CanRelaunchAfterUpdate.
+        TEST_METHOD(CanRelaunchReflectsArgCount)
+        {
+            // Old Stage 1 (pre-fix): only passed action + installer = 3 args
+            Assert::IsFalse(updating::CanRelaunchAfterUpdate(0));
+            Assert::IsFalse(updating::CanRelaunchAfterUpdate(1));
+            Assert::IsFalse(updating::CanRelaunchAfterUpdate(2));
+            Assert::IsFalse(updating::CanRelaunchAfterUpdate(3));
+
+            // New Stage 1 (post-fix): passes action + installer + installDir = 4 args
+            Assert::IsTrue(updating::CanRelaunchAfterUpdate(4));
+            Assert::IsTrue(updating::CanRelaunchAfterUpdate(5));
+        }
+
+        // Tests BuildStage2Arguments + CommandLineToArgvW round-trip: the exact
+        // scenario where Stage 1 builds args and Windows parses them in Stage 2.
+        // Verifies quoting is correct so paths with spaces survive the round trip.
+        // Covers: updateLifecycle.h BuildStage2Arguments — quote correctness.
+        // Setup: Realistic paths with spaces and version numbers.
+        TEST_METHOD(Stage2ArgumentsCanBeRoundTrippedThroughCommandLineToArgvW)
+        {
+            const std::wstring installerPath = L"C:\\Users\\test user\\AppData\\Local\\PowerToys\\Updates\\powertoyssetup-0.86.0-x64.exe";
+            const std::wstring installDir = L"C:\\Program Files\\PowerToys";
+
+            const auto args = updating::BuildStage2Arguments(L"-update_now_stage_2", installerPath, installDir);
+
+            // Simulate what Windows does: prepend a fake exe name and parse
+            std::wstring commandLine = L"PowerToys.Update.exe " + args;
+
+            int argc = 0;
+            LPWSTR* argv = CommandLineToArgvW(commandLine.c_str(), &argc);
+            Assert::IsNotNull(argv);
+            Assert::AreEqual(4, argc);
+            Assert::AreEqual(std::wstring(L"-update_now_stage_2"), std::wstring(argv[1]));
+            Assert::AreEqual(installerPath, std::wstring(argv[2]));
+            Assert::AreEqual(installDir, std::wstring(argv[3]));
+
+            LocalFree(argv);
+        }
+    };
+}

src/common/updating/UnitTests/UpdatingUnitTests.vcxproj

@@ -0,0 +1,45 @@
+<?xml version="1.0" encoding="utf-8"?>
+<Project DefaultTargets="Build" xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
+  <Import Project="$(VCTargetsPath)\Microsoft.Cpp.Default.props" />
+  <PropertyGroup Label="Globals">
+    <VCProjectVersion>16.0</VCProjectVersion>
+    <ProjectGuid>{A1B2C3D4-E5F6-7890-ABCD-EF1234567890}</ProjectGuid>
+    <Keyword>Win32Proj</Keyword>
+    <RootNamespace>UpdatingUnitTests</RootNamespace>
+    <ProjectSubType>NativeUnitTestProject</ProjectSubType>
+    <ProjectName>Updating.UnitTests</ProjectName>
+  </PropertyGroup>
+  <PropertyGroup Label="Configuration">
+    <ConfigurationType>DynamicLibrary</ConfigurationType>
+    <UseOfMfc>false</UseOfMfc>
+
+    <OutDir>$(SolutionDir)$(Platform)\$(Configuration)\tests\UpdatingUnitTests\</OutDir>
+  </PropertyGroup>
+  <Import Project="$(VCTargetsPath)\Microsoft.Cpp.props" />
+  <ImportGroup Label="ExtensionSettings">
+  </ImportGroup>
+  <ImportGroup Label="Shared">
+  </ImportGroup>
+  <ImportGroup Label="PropertySheets">
+    <Import Project="$(UserRootDir)\Microsoft.Cpp.$(Platform).user.props" Condition="exists('$(UserRootDir)\Microsoft.Cpp.$(Platform).user.props')" Label="LocalAppDataPlatform" />
+  </ImportGroup>
+  <PropertyGroup Label="UserMacros" />
+  <ItemDefinitionGroup>
+    <ClCompile>
+      <AdditionalIncludeDirectories>..\;..\..\;..\..\..\;$(VCInstallDir)UnitTest\include;%(AdditionalIncludeDirectories)</AdditionalIncludeDirectories>
+    </ClCompile>
+    <Link>
+      <AdditionalLibraryDirectories>$(VCInstallDir)UnitTest\lib;%(AdditionalLibraryDirectories)</AdditionalLibraryDirectories>
+    </Link>
+  </ItemDefinitionGroup>
+  <ItemGroup>
+    <ClCompile Include="UpdatingTests.cpp" />
+    <ClCompile Include="pch.cpp">
+      <PrecompiledHeader Condition="'$(UsePrecompiledHeaders)' != 'false'">Create</PrecompiledHeader>
+    </ClCompile>
+  </ItemGroup>
+  <ItemGroup>
+    <ClInclude Include="pch.h" />
+  </ItemGroup>
+  <Import Project="$(VCTargetsPath)\Microsoft.Cpp.targets" />
+</Project>

src/common/updating/UnitTests/pch.cpp

@@ -0,0 +1,5 @@
+// Copyright (c) Microsoft Corporation
+// The Microsoft Corporation licenses this file to you under the MIT license.
+// See the LICENSE file in the project root for more information.
+
+#include "pch.h"

src/common/updating/UnitTests/pch.h

@@ -0,0 +1,17 @@
+// Copyright (c) Microsoft Corporation
+// The Microsoft Corporation licenses this file to you under the MIT license.
+// See the LICENSE file in the project root for more information.
+
+#ifndef PCH_H
+#define PCH_H
+
+#include <atomic>
+#include <Windows.h>
+
+// Suppressing 26466 - Don't use static_cast downcasts - in CppUnitTest.h
+#pragma warning(push)
+#pragma warning(disable : 26466)
+#include "CppUnitTest.h"
+#pragma warning(pop)
+
+#endif //PCH_H

src/common/updating/configBackup.h

@@ -0,0 +1,228 @@
+// Copyright (c) Microsoft Corporation
+// The Microsoft Corporation licenses this file to you under the MIT license.
+// See the LICENSE file in the project root for more information.
+
+#pragma once
+
+#include <filesystem>
+#include <fstream>
+#include <string>
+
+namespace updating
+{
+    namespace fs = std::filesystem;
+
+    struct BackupResult
+    {
+        int filesBackedUp{ 0 };
+        int errors{ 0 };
+    };
+
+    struct RestoreResult
+    {
+        int filesRestored{ 0 };
+        int filesChecked{ 0 };
+        int errors{ 0 };
+    };
+
+    // Check if a JSON file is corrupted (contains null bytes, as seen in #46179)
+    inline bool IsJsonFileCorrupted(const fs::path& filePath)
+    {
+        try
+        {
+            std::ifstream file(filePath, std::ios::binary);
+            if (!file.is_open())
+            {
+                return false;
+            }
+
+            constexpr size_t c_readChunkSize{ 4096 };
+            char buffer[c_readChunkSize];
+            while (file.read(buffer, c_readChunkSize) || file.gcount() > 0)
+            {
+                const auto bytesRead = file.gcount();
+                for (std::streamsize i = 0; i < bytesRead; ++i)
+                {
+                    if (buffer[i] == '\0')
+                    {
+                        return true;
+                    }
+                }
+            }
+
+            return false;
+        }
+        catch (...)
+        {
+            return true;
+        }
+    }
+
+    // Backup all JSON config files before update to protect against corruption (#46179)
+    inline BackupResult BackupConfigFiles(const fs::path& rootPath)
+    {
+        BackupResult result{};
+        try
+        {
+            const fs::path backupDir = rootPath / L"ConfigBackup";
+
+            std::error_code ec;
+            fs::remove_all(backupDir, ec);
+            fs::create_directories(backupDir, ec);
+            if (ec)
+            {
+                result.errors++;
+                return result;
+            }
+
+            for (const auto& entry : fs::directory_iterator(rootPath, ec))
+            {
+                if (ec)
+                {
+                    result.errors++;
+                    break;
+                }
+
+                if (entry.is_regular_file() && entry.path().extension() == L".json")
+                {
+                    std::error_code copyEc;
+                    fs::copy_file(entry.path(), backupDir / entry.path().filename(), fs::copy_options::overwrite_existing, copyEc);
+                    if (copyEc)
+                    {
+                        result.errors++;
+                    }
+                    else
+                    {
+                        result.filesBackedUp++;
+                    }
+                }
+                else if (entry.is_directory())
+                {
+                    const auto dirName = entry.path().filename().wstring();
+                    if (dirName == L"ConfigBackup" || dirName == L"Updates")
+                    {
+                        continue;
+                    }
+
+                    const auto moduleBackup = backupDir / entry.path().filename();
+                    fs::create_directories(moduleBackup, ec);
+
+                    std::error_code moduleEc;
+                    for (const auto& moduleEntry : fs::directory_iterator(entry.path(), moduleEc))
+                    {
+                        if (moduleEc)
+                        {
+                            result.errors++;
+                            break;
+                        }
+
+                        if (moduleEntry.is_regular_file() && moduleEntry.path().extension() == L".json")
+                        {
+                            std::error_code copyEc;
+                            fs::copy_file(moduleEntry.path(), moduleBackup / moduleEntry.path().filename(), fs::copy_options::overwrite_existing, copyEc);
+                            if (copyEc)
+                            {
+                                result.errors++;
+                            }
+                            else
+                            {
+                                result.filesBackedUp++;
+                            }
+                        }
+                    }
+                }
+            }
+        }
+        catch (...)
+        {
+            result.errors++;
+        }
+        return result;
+    }
+
+    // Restore JSON configs from backup if corruption is detected after update.
+    // Cleans up the backup directory afterward.
+    inline RestoreResult RestoreCorruptedConfigs(const fs::path& rootPath)
+    {
+        RestoreResult result{};
+        try
+        {
+            const fs::path backupDir = rootPath / L"ConfigBackup";
+
+            if (!fs::exists(backupDir))
+            {
+                return result;
+            }
+
+            std::error_code ec;
+            for (const auto& backupEntry : fs::directory_iterator(backupDir, ec))
+            {
+                if (ec)
+                {
+                    result.errors++;
+                    break;
+                }
+
+                if (backupEntry.is_regular_file() && backupEntry.path().extension() == L".json")
+                {
+                    const auto originalPath = rootPath / backupEntry.path().filename();
+                    result.filesChecked++;
+                    if (fs::exists(originalPath) && IsJsonFileCorrupted(originalPath) && !IsJsonFileCorrupted(backupEntry.path()))
+                    {
+                        std::error_code copyEc;
+                        fs::copy_file(backupEntry.path(), originalPath, fs::copy_options::overwrite_existing, copyEc);
+                        if (copyEc)
+                        {
+                            result.errors++;
+                        }
+                        else
+                        {
+                            result.filesRestored++;
+                        }
+                    }
+                }
+                else if (backupEntry.is_directory())
+                {
+                    const auto moduleDir = rootPath / backupEntry.path().filename();
+
+                    std::error_code moduleEc;
+                    for (const auto& moduleBackupEntry : fs::directory_iterator(backupEntry.path(), moduleEc))
+                    {
+                        if (moduleEc)
+                        {
+                            result.errors++;
+                            break;
+                        }
+
+                        if (moduleBackupEntry.is_regular_file() && moduleBackupEntry.path().extension() == L".json")
+                        {
+                            const auto originalModulePath = moduleDir / moduleBackupEntry.path().filename();
+                            result.filesChecked++;
+                            if (fs::exists(originalModulePath) && IsJsonFileCorrupted(originalModulePath) && !IsJsonFileCorrupted(moduleBackupEntry.path()))
+                            {
+                                std::error_code copyEc;
+                                fs::copy_file(moduleBackupEntry.path(), originalModulePath, fs::copy_options::overwrite_existing, copyEc);
+                                if (copyEc)
+                                {
+                                    result.errors++;
+                                }
+                                else
+                                {
+                                    result.filesRestored++;
+                                }
+                            }
+                        }
+                    }
+                }
+            }
+
+            // Clean up backup directory after restore check
+            fs::remove_all(backupDir, ec);
+        }
+        catch (...)
+        {
+            result.errors++;
+        }
+        return result;
+    }
+}

src/common/updating/pch.h

@@ -24,8 +24,6 @@
 #include <regex>
 #include <charconv>
 
-#include <expected.hpp>
-
 #include <winrt/Windows.Foundation.h>
 #include <winrt/Windows.Foundation.Collections.h>
 #include <winrt/Windows.ApplicationModel.h>

src/common/updating/updateLifecycle.h

@@ -0,0 +1,47 @@
+// Copyright (c) Microsoft Corporation
+// The Microsoft Corporation licenses this file to you under the MIT license.
+// See the LICENSE file in the project root for more information.
+
+#pragma once
+
+#include <filesystem>
+#include <string>
+
+namespace updating
+{
+    namespace fs = std::filesystem;
+
+    // Build the command-line arguments for Stage 2.
+    // Stage 1 passes the installer path and the PT install directory
+    // so Stage 2 can run the installer and relaunch PowerToys afterward.
+    // Note: paths containing embedded double-quote characters are not supported.
+    // This is safe because install paths come from get_module_folderpath().
+    inline std::wstring BuildStage2Arguments(
+        const std::wstring& stage2Flag,
+        const fs::path& installerPath,
+        const fs::path& installDir)
+    {
+        std::wstring arguments{ stage2Flag };
+        arguments += L" \"";
+        arguments += installerPath.c_str();
+        arguments += L"\" \"";
+        arguments += installDir.c_str();
+        arguments += L"\"";
+        return arguments;
+    }
+
+    // Build the full path to PowerToys.exe from the install directory.
+    // Used by Stage 2 to relaunch PT after a successful update.
+    inline std::wstring BuildPowerToysExePath(const std::wstring& installDir)
+    {
+        return (std::filesystem::path(installDir) / L"PowerToys.exe").wstring();
+    }
+
+    // Determine whether Stage 2 has enough information to relaunch PT.
+    // Returns true if the install directory argument was provided.
+    inline bool CanRelaunchAfterUpdate(int argCount)
+    {
+        // args[0]=exe, args[1]=action, args[2]=installer, args[3]=installDir
+        return argCount >= 4;
+    }
+}

src/common/updating/updating.cpp

@@ -87,11 +87,7 @@ namespace updating
         // If the current version starts with 0.0.*, it means we're on a local build from a farm and shouldn't check for updates.
         if constexpr (VERSION_MAJOR == 0 && VERSION_MINOR == 0)
         {
-#if USE_STD_EXPECTED
             co_return std::unexpected(LOCAL_BUILD_ERROR);
-#else
-            co_return nonstd::make_unexpected(LOCAL_BUILD_ERROR);
-#endif
         }
 
         try
@@ -143,11 +139,7 @@ namespace updating
         catch (...)
         {
         }
-#if USE_STD_EXPECTED
         co_return std::unexpected(NETWORK_ERROR);
-#else
-        co_return nonstd::make_unexpected(NETWORK_ERROR);
-#endif
     }
 #pragma warning(pop)
 

src/common/updating/updating.h

@@ -5,14 +5,7 @@
 #include <filesystem>
 #include <variant>
 #include <winrt/Windows.Foundation.h>
-//#if __MSVC_VERSION__ >= 1933 // MSVC begin to support std::unexpected in 19.33
-#if __has_include(<expected> ) // use the same way with excepted-lite to detect std::unexcepted, as using it as backup
 #include <expected>
-#define USE_STD_EXPECTED 1
-#else
-#include <expected.hpp>
-#define USE_STD_EXPECTED 0
-#endif
 
 #include <common/version/helper.h>
 #include <wil/coroutine.h>
@@ -31,12 +24,7 @@ namespace updating
         std::wstring installer_filename;
     };
     using github_version_info = std::variant<new_version_download_info, version_up_to_date>;
-
-#if USE_STD_EXPECTED
     using github_version_result = std::expected<github_version_info, std::wstring>;
-#else
-    using github_version_result = nonstd::expected<github_version_info, std::wstring>;
-#endif
 
     wil::task<github_version_result> get_github_version_info_async(bool prerelease = false);
     wil::task<std::optional<std::filesystem::path>> download_new_version_async(new_version_download_info new_version);

src/common/updating/updating.vcxproj

@@ -9,7 +9,6 @@
     <ProjectName>ApplicationUpdate</ProjectName>
   </PropertyGroup>
   <Import Project="$(VCTargetsPath)\Microsoft.Cpp.Default.props" />
-  <Import Project="..\..\..\deps\expected.props" />
   <PropertyGroup Label="Configuration">
     <ConfigurationType>StaticLibrary</ConfigurationType>
     

src/logging/logging.vcxproj

@@ -1,164 +0,0 @@
-<?xml version="1.0" encoding="utf-8"?>
-<Project DefaultTargets="Build" ToolsVersion="16.0" xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
-  <Import Project="$(VCTargetsPath)\Microsoft.Cpp.Default.props" />
-  <ItemGroup Label="ProjectConfigurations">
-    <ProjectConfiguration Include="Debug|Win32">
-      <Configuration>Debug</Configuration>
-      <Platform>Win32</Platform>
-    </ProjectConfiguration>
-    <ProjectConfiguration Include="Debug|x64">
-      <Configuration>Debug</Configuration>
-      <Platform>x64</Platform>
-    </ProjectConfiguration>
-    <ProjectConfiguration Include="Release|Win32">
-      <Configuration>Release</Configuration>
-      <Platform>Win32</Platform>
-    </ProjectConfiguration>
-    <ProjectConfiguration Include="Release|x64">
-      <Configuration>Release</Configuration>
-      <Platform>x64</Platform>
-    </ProjectConfiguration>
-    <ProjectConfiguration Include="Debug|ARM64">
-      <Configuration>Debug</Configuration>
-      <Platform>ARM64</Platform>
-    </ProjectConfiguration>
-    <ProjectConfiguration Include="Release|ARM64">
-      <Configuration>Release</Configuration>
-      <Platform>ARM64</Platform>
-    </ProjectConfiguration>
-  </ItemGroup>
-  <PropertyGroup Label="Globals">
-    <ProjectGuid>{7E1E3F13-2BD6-3F75-A6A7-873A2B55C60F}</ProjectGuid>
-    <Keyword>Win32Proj</Keyword>
-    <ProjectName>spdlog</ProjectName>
-  </PropertyGroup>
-  <Import Project="$(RepoRoot)deps\spdlog.props" />
-  <PropertyGroup Label="Configuration">
-    <ConfigurationType>StaticLibrary</ConfigurationType>
-    <CharacterSet>MultiByte</CharacterSet>
-    
-    <OutDir>$(RepoRoot)$(Platform)\$(Configuration)\</OutDir>
-  </PropertyGroup>
-  <Import Project="$(VCTargetsPath)\Microsoft.Cpp.props" />
-  <ImportGroup Label="ExtensionSettings">
-  </ImportGroup>
-  <ImportGroup Label="PropertySheets">
-    <Import Project="$(UserRootDir)\Microsoft.Cpp.$(Platform).user.props" Condition="exists('$(UserRootDir)\Microsoft.Cpp.$(Platform).user.props')" Label="LocalAppDataPlatform" />
-  </ImportGroup>
-  <PropertyGroup Label="UserMacros" />
-  <ItemDefinitionGroup>
-    <ClCompile>
-      <BasicRuntimeChecks>Default</BasicRuntimeChecks>
-      <DebugInformationFormat>None</DebugInformationFormat>
-      <ExceptionHandling>Sync</ExceptionHandling>
-      <InlineFunctionExpansion>AnySuitable</InlineFunctionExpansion>
-      <PrecompiledHeader>NotUsing</PrecompiledHeader>
-      <RuntimeTypeInfo>true</RuntimeTypeInfo>
-      <WarningLevel>Level4</WarningLevel>
-      <PreprocessorDefinitions>WIN32;_WINDOWS;SPDLOG_COMPILED_LIB;SPDLOG_WCHAR_FILENAMES;%(PreprocessorDefinitions)</PreprocessorDefinitions>
-      <ObjectFileName>$(IntDir)</ObjectFileName>
-      <FunctionLevelLinking>true</FunctionLevelLinking>
-      <EnableParallelCodeGeneration>true</EnableParallelCodeGeneration>
-    </ClCompile>
-    <Lib>
-      <AdditionalOptions>%(AdditionalOptions)</AdditionalOptions>
-    </Lib>
-  </ItemDefinitionGroup>
-  <ItemGroup>
-    <ClCompile Include="$(RepoRoot)deps\spdlog\src\spdlog.cpp" />
-    <ClCompile Include="$(RepoRoot)deps\spdlog\src\stdout_sinks.cpp" />
-    <ClCompile Include="$(RepoRoot)deps\spdlog\src\color_sinks.cpp" />
-    <ClCompile Include="$(RepoRoot)deps\spdlog\src\file_sinks.cpp" />
-    <ClCompile Include="$(RepoRoot)deps\spdlog\src\async.cpp" />
-    <ClCompile Include="$(RepoRoot)deps\spdlog\src\cfg.cpp" />
-    <ClCompile Include="$(RepoRoot)deps\spdlog\src\fmt.cpp" />
-    <ClInclude Include="$(RepoRoot)deps\spdlog\include\spdlog\async.h" />
-    <ClInclude Include="$(RepoRoot)deps\spdlog\include\spdlog\async_logger-inl.h" />
-    <ClInclude Include="$(RepoRoot)deps\spdlog\include\spdlog\async_logger.h" />
-    <ClInclude Include="$(RepoRoot)deps\spdlog\include\spdlog\common-inl.h" />
-    <ClInclude Include="$(RepoRoot)deps\spdlog\include\spdlog\common.h" />
-    <ClInclude Include="$(RepoRoot)deps\spdlog\include\spdlog\formatter.h" />
-    <ClInclude Include="$(RepoRoot)deps\spdlog\include\spdlog\fwd.h" />
-    <ClInclude Include="$(RepoRoot)deps\spdlog\include\spdlog\logger-inl.h" />
-    <ClInclude Include="$(RepoRoot)deps\spdlog\include\spdlog\logger.h" />
-    <ClInclude Include="$(RepoRoot)deps\spdlog\include\spdlog\pattern_formatter-inl.h" />
-    <ClInclude Include="$(RepoRoot)deps\spdlog\include\spdlog\pattern_formatter.h" />
-    <ClInclude Include="$(RepoRoot)deps\spdlog\include\spdlog\spdlog-inl.h" />
-    <ClInclude Include="$(RepoRoot)deps\spdlog\include\spdlog\spdlog.h" />
-    <ClInclude Include="$(RepoRoot)deps\spdlog\include\spdlog\stopwatch.h" />
-    <ClInclude Include="$(RepoRoot)deps\spdlog\include\spdlog\tweakme.h" />
-    <ClInclude Include="$(RepoRoot)deps\spdlog\include\spdlog\version.h" />
-    <ClInclude Include="$(RepoRoot)deps\spdlog\include\spdlog\details\backtracer-inl.h" />
-    <ClInclude Include="$(RepoRoot)deps\spdlog\include\spdlog\details\backtracer.h" />
-    <ClInclude Include="$(RepoRoot)deps\spdlog\include\spdlog\details\circular_q.h" />
-    <ClInclude Include="$(RepoRoot)deps\spdlog\include\spdlog\details\console_globals.h" />
-    <ClInclude Include="$(RepoRoot)deps\spdlog\include\spdlog\details\file_helper-inl.h" />
-    <ClInclude Include="$(RepoRoot)deps\spdlog\include\spdlog\details\file_helper.h" />
-    <ClInclude Include="$(RepoRoot)deps\spdlog\include\spdlog\details\fmt_helper.h" />
-    <ClInclude Include="$(RepoRoot)deps\spdlog\include\spdlog\details\log_msg-inl.h" />
-    <ClInclude Include="$(RepoRoot)deps\spdlog\include\spdlog\details\log_msg.h" />
-    <ClInclude Include="$(RepoRoot)deps\spdlog\include\spdlog\details\log_msg_buffer-inl.h" />
-    <ClInclude Include="$(RepoRoot)deps\spdlog\include\spdlog\details\log_msg_buffer.h" />
-    <ClInclude Include="$(RepoRoot)deps\spdlog\include\spdlog\details\mpmc_blocking_q.h" />
-    <ClInclude Include="$(RepoRoot)deps\spdlog\include\spdlog\details\null_mutex.h" />
-    <ClInclude Include="$(RepoRoot)deps\spdlog\include\spdlog\details\os-inl.h" />
-    <ClInclude Include="$(RepoRoot)deps\spdlog\include\spdlog\details\os.h" />
-    <ClInclude Include="$(RepoRoot)deps\spdlog\include\spdlog\details\periodic_worker-inl.h" />
-    <ClInclude Include="$(RepoRoot)deps\spdlog\include\spdlog\details\periodic_worker.h" />
-    <ClInclude Include="$(RepoRoot)deps\spdlog\include\spdlog\details\registry-inl.h" />
-    <ClInclude Include="$(RepoRoot)deps\spdlog\include\spdlog\details\registry.h" />
-    <ClInclude Include="$(RepoRoot)deps\spdlog\include\spdlog\details\synchronous_factory.h" />
-    <ClInclude Include="$(RepoRoot)deps\spdlog\include\spdlog\details\tcp_client-windows.h" />
-    <ClInclude Include="$(RepoRoot)deps\spdlog\include\spdlog\details\tcp_client.h" />
-    <ClInclude Include="$(RepoRoot)deps\spdlog\include\spdlog\details\thread_pool-inl.h" />
-    <ClInclude Include="$(RepoRoot)deps\spdlog\include\spdlog\details\thread_pool.h" />
-    <ClInclude Include="$(RepoRoot)deps\spdlog\include\spdlog\details\windows_include.h" />
-    <ClInclude Include="$(RepoRoot)deps\spdlog\include\spdlog\sinks\android_sink.h" />
-    <ClInclude Include="$(RepoRoot)deps\spdlog\include\spdlog\sinks\ansicolor_sink-inl.h" />
-    <ClInclude Include="$(RepoRoot)deps\spdlog\include\spdlog\sinks\ansicolor_sink.h" />
-    <ClInclude Include="$(RepoRoot)deps\spdlog\include\spdlog\sinks\base_sink-inl.h" />
-    <ClInclude Include="$(RepoRoot)deps\spdlog\include\spdlog\sinks\base_sink.h" />
-    <ClInclude Include="$(RepoRoot)deps\spdlog\include\spdlog\sinks\basic_file_sink-inl.h" />
-    <ClInclude Include="$(RepoRoot)deps\spdlog\include\spdlog\sinks\basic_file_sink.h" />
-    <ClInclude Include="$(RepoRoot)deps\spdlog\include\spdlog\sinks\daily_file_sink.h" />
-    <ClInclude Include="$(RepoRoot)deps\spdlog\include\spdlog\sinks\dist_sink.h" />
-    <ClInclude Include="$(RepoRoot)deps\spdlog\include\spdlog\sinks\dup_filter_sink.h" />
-    <ClInclude Include="$(RepoRoot)deps\spdlog\include\spdlog\sinks\msvc_sink.h" />
-    <ClInclude Include="$(RepoRoot)deps\spdlog\include\spdlog\sinks\null_sink.h" />
-    <ClInclude Include="$(RepoRoot)deps\spdlog\include\spdlog\sinks\ostream_sink.h" />
-    <ClInclude Include="$(RepoRoot)deps\spdlog\include\spdlog\sinks\ringbuffer_sink.h" />
-    <ClInclude Include="$(RepoRoot)deps\spdlog\include\spdlog\sinks\rotating_file_sink-inl.h" />
-    <ClInclude Include="$(RepoRoot)deps\spdlog\include\spdlog\sinks\rotating_file_sink.h" />
-    <ClInclude Include="$(RepoRoot)deps\spdlog\include\spdlog\sinks\sink-inl.h" />
-    <ClInclude Include="$(RepoRoot)deps\spdlog\include\spdlog\sinks\sink.h" />
-    <ClInclude Include="$(RepoRoot)deps\spdlog\include\spdlog\sinks\stdout_color_sinks-inl.h" />
-    <ClInclude Include="$(RepoRoot)deps\spdlog\include\spdlog\sinks\stdout_color_sinks.h" />
-    <ClInclude Include="$(RepoRoot)deps\spdlog\include\spdlog\sinks\stdout_sinks-inl.h" />
-    <ClInclude Include="$(RepoRoot)deps\spdlog\include\spdlog\sinks\stdout_sinks.h" />
-    <ClInclude Include="$(RepoRoot)deps\spdlog\include\spdlog\sinks\syslog_sink.h" />
-    <ClInclude Include="$(RepoRoot)deps\spdlog\include\spdlog\sinks\systemd_sink.h" />
-    <ClInclude Include="$(RepoRoot)deps\spdlog\include\spdlog\sinks\tcp_sink.h" />
-    <ClInclude Include="$(RepoRoot)deps\spdlog\include\spdlog\sinks\win_eventlog_sink.h" />
-    <ClInclude Include="$(RepoRoot)deps\spdlog\include\spdlog\sinks\wincolor_sink-inl.h" />
-    <ClInclude Include="$(RepoRoot)deps\spdlog\include\spdlog\sinks\wincolor_sink.h" />
-    <ClInclude Include="$(RepoRoot)deps\spdlog\include\spdlog\fmt\bin_to_hex.h" />
-    <ClInclude Include="$(RepoRoot)deps\spdlog\include\spdlog\fmt\chrono.h" />
-    <ClInclude Include="$(RepoRoot)deps\spdlog\include\spdlog\fmt\fmt.h" />
-    <ClInclude Include="$(RepoRoot)deps\spdlog\include\spdlog\fmt\ostr.h" />
-    <ClInclude Include="$(RepoRoot)deps\spdlog\include\spdlog\fmt\bundled\chrono.h" />
-    <ClInclude Include="$(RepoRoot)deps\spdlog\include\spdlog\fmt\bundled\color.h" />
-    <ClInclude Include="$(RepoRoot)deps\spdlog\include\spdlog\fmt\bundled\compile.h" />
-    <ClInclude Include="$(RepoRoot)deps\spdlog\include\spdlog\fmt\bundled\core.h" />
-    <ClInclude Include="$(RepoRoot)deps\spdlog\include\spdlog\fmt\bundled\format-inl.h" />
-    <ClInclude Include="$(RepoRoot)deps\spdlog\include\spdlog\fmt\bundled\format.h" />
-    <ClInclude Include="$(RepoRoot)deps\spdlog\include\spdlog\fmt\bundled\locale.h" />
-    <ClInclude Include="$(RepoRoot)deps\spdlog\include\spdlog\fmt\bundled\os.h" />
-    <ClInclude Include="$(RepoRoot)deps\spdlog\include\spdlog\fmt\bundled\ostream.h" />
-    <ClInclude Include="$(RepoRoot)deps\spdlog\include\spdlog\fmt\bundled\posix.h" />
-    <ClInclude Include="$(RepoRoot)deps\spdlog\include\spdlog\fmt\bundled\printf.h" />
-    <ClInclude Include="$(RepoRoot)deps\spdlog\include\spdlog\fmt\bundled\ranges.h" />
-  </ItemGroup>
-  <Import Project="$(VCTargetsPath)\Microsoft.Cpp.targets" />
-  <ImportGroup Label="ExtensionTargets">
-  </ImportGroup>
-</Project>

src/logging/logging.vcxproj.filters

@@ -1,122 +0,0 @@
-<?xml version="1.0" encoding="utf-8"?>
-<Project ToolsVersion="16.0" xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
-  <ItemGroup>
-    <ClCompile Include="$(ProjectDir)..\..\deps\spdlog\src\spdlog.cpp" />
-    <ClCompile Include="$(ProjectDir)..\..\deps\spdlog\src\stdout_sinks.cpp" />
-    <ClCompile Include="$(ProjectDir)..\..\deps\spdlog\src\color_sinks.cpp" />
-    <ClCompile Include="$(ProjectDir)..\..\deps\spdlog\src\file_sinks.cpp" />
-    <ClCompile Include="$(ProjectDir)..\..\deps\spdlog\src\async.cpp" />
-    <ClCompile Include="$(ProjectDir)..\..\deps\spdlog\src\cfg.cpp" />
-    <ClCompile Include="$(ProjectDir)..\..\deps\spdlog\src\fmt.cpp" />
-  </ItemGroup>
-  <ItemGroup>
-    <ClInclude Include="$(ProjectDir)..\..\deps\spdlog\include\spdlog\async.h" />
-    <ClInclude Include="$(ProjectDir)..\..\deps\spdlog\include\spdlog\async_logger-inl.h" />
-    <ClInclude Include="$(ProjectDir)..\..\deps\spdlog\include\spdlog\async_logger.h" />
-    <ClInclude Include="$(ProjectDir)..\..\deps\spdlog\include\spdlog\common-inl.h" />
-    <ClInclude Include="$(ProjectDir)..\..\deps\spdlog\include\spdlog\common.h" />
-    <ClInclude Include="$(ProjectDir)..\..\deps\spdlog\include\spdlog\formatter.h" />
-    <ClInclude Include="$(ProjectDir)..\..\deps\spdlog\include\spdlog\fwd.h" />
-    <ClInclude Include="$(ProjectDir)..\..\deps\spdlog\include\spdlog\logger-inl.h" />
-    <ClInclude Include="$(ProjectDir)..\..\deps\spdlog\include\spdlog\logger.h" />
-    <ClInclude Include="$(ProjectDir)..\..\deps\spdlog\include\spdlog\pattern_formatter-inl.h" />
-    <ClInclude Include="$(ProjectDir)..\..\deps\spdlog\include\spdlog\pattern_formatter.h" />
-    <ClInclude Include="$(ProjectDir)..\..\deps\spdlog\include\spdlog\spdlog-inl.h" />
-    <ClInclude Include="$(ProjectDir)..\..\deps\spdlog\include\spdlog\spdlog.h" />
-    <ClInclude Include="$(ProjectDir)..\..\deps\spdlog\include\spdlog\stopwatch.h" />
-    <ClInclude Include="$(ProjectDir)..\..\deps\spdlog\include\spdlog\tweakme.h" />
-    <ClInclude Include="$(ProjectDir)..\..\deps\spdlog\include\spdlog\version.h" />
-    <ClInclude Include="$(ProjectDir)..\..\deps\spdlog\include\spdlog\details\backtracer-inl.h" />
-    <ClInclude Include="$(ProjectDir)..\..\deps\spdlog\include\spdlog\details\backtracer.h" />
-    <ClInclude Include="$(ProjectDir)..\..\deps\spdlog\include\spdlog\details\circular_q.h" />
-    <ClInclude Include="$(ProjectDir)..\..\deps\spdlog\include\spdlog\details\console_globals.h" />
-    <ClInclude Include="$(ProjectDir)..\..\deps\spdlog\include\spdlog\details\file_helper-inl.h" />
-    <ClInclude Include="$(ProjectDir)..\..\deps\spdlog\include\spdlog\details\file_helper.h" />
-    <ClInclude Include="$(ProjectDir)..\..\deps\spdlog\include\spdlog\details\fmt_helper.h" />
-    <ClInclude Include="$(ProjectDir)..\..\deps\spdlog\include\spdlog\details\log_msg-inl.h" />
-    <ClInclude Include="$(ProjectDir)..\..\deps\spdlog\include\spdlog\details\log_msg.h" />
-    <ClInclude Include="$(ProjectDir)..\..\deps\spdlog\include\spdlog\details\log_msg_buffer-inl.h" />
-    <ClInclude Include="$(ProjectDir)..\..\deps\spdlog\include\spdlog\details\log_msg_buffer.h" />
-    <ClInclude Include="$(ProjectDir)..\..\deps\spdlog\include\spdlog\details\mpmc_blocking_q.h" />
-    <ClInclude Include="$(ProjectDir)..\..\deps\spdlog\include\spdlog\details\null_mutex.h" />
-    <ClInclude Include="$(ProjectDir)..\..\deps\spdlog\include\spdlog\details\os-inl.h" />
-    <ClInclude Include="$(ProjectDir)..\..\deps\spdlog\include\spdlog\details\os.h" />
-    <ClInclude Include="$(ProjectDir)..\..\deps\spdlog\include\spdlog\details\periodic_worker-inl.h" />
-    <ClInclude Include="$(ProjectDir)..\..\deps\spdlog\include\spdlog\details\periodic_worker.h" />
-    <ClInclude Include="$(ProjectDir)..\..\deps\spdlog\include\spdlog\details\registry-inl.h" />
-    <ClInclude Include="$(ProjectDir)..\..\deps\spdlog\include\spdlog\details\registry.h" />
-    <ClInclude Include="$(ProjectDir)..\..\deps\spdlog\include\spdlog\details\synchronous_factory.h" />
-    <ClInclude Include="$(ProjectDir)..\..\deps\spdlog\include\spdlog\details\tcp_client-windows.h" />
-    <ClInclude Include="$(ProjectDir)..\..\deps\spdlog\include\spdlog\details\tcp_client.h" />
-    <ClInclude Include="$(ProjectDir)..\..\deps\spdlog\include\spdlog\details\thread_pool-inl.h" />
-    <ClInclude Include="$(ProjectDir)..\..\deps\spdlog\include\spdlog\details\thread_pool.h" />
-    <ClInclude Include="$(ProjectDir)..\..\deps\spdlog\include\spdlog\details\windows_include.h" />
-    <ClInclude Include="$(ProjectDir)..\..\deps\spdlog\include\spdlog\sinks\android_sink.h" />
-    <ClInclude Include="$(ProjectDir)..\..\deps\spdlog\include\spdlog\sinks\ansicolor_sink-inl.h" />
-    <ClInclude Include="$(ProjectDir)..\..\deps\spdlog\include\spdlog\sinks\ansicolor_sink.h" />
-    <ClInclude Include="$(ProjectDir)..\..\deps\spdlog\include\spdlog\sinks\base_sink-inl.h" />
-    <ClInclude Include="$(ProjectDir)..\..\deps\spdlog\include\spdlog\sinks\base_sink.h" />
-    <ClInclude Include="$(ProjectDir)..\..\deps\spdlog\include\spdlog\sinks\basic_file_sink-inl.h" />
-    <ClInclude Include="$(ProjectDir)..\..\deps\spdlog\include\spdlog\sinks\basic_file_sink.h" />
-    <ClInclude Include="$(ProjectDir)..\..\deps\spdlog\include\spdlog\sinks\daily_file_sink.h" />
-    <ClInclude Include="$(ProjectDir)..\..\deps\spdlog\include\spdlog\sinks\dist_sink.h" />
-    <ClInclude Include="$(ProjectDir)..\..\deps\spdlog\include\spdlog\sinks\dup_filter_sink.h" />
-    <ClInclude Include="$(ProjectDir)..\..\deps\spdlog\include\spdlog\sinks\msvc_sink.h" />
-    <ClInclude Include="$(ProjectDir)..\..\deps\spdlog\include\spdlog\sinks\null_sink.h" />
-    <ClInclude Include="$(ProjectDir)..\..\deps\spdlog\include\spdlog\sinks\ostream_sink.h" />
-    <ClInclude Include="$(ProjectDir)..\..\deps\spdlog\include\spdlog\sinks\ringbuffer_sink.h" />
-    <ClInclude Include="$(ProjectDir)..\..\deps\spdlog\include\spdlog\sinks\rotating_file_sink-inl.h" />
-    <ClInclude Include="$(ProjectDir)..\..\deps\spdlog\include\spdlog\sinks\rotating_file_sink.h" />
-    <ClInclude Include="$(ProjectDir)..\..\deps\spdlog\include\spdlog\sinks\sink-inl.h" />
-    <ClInclude Include="$(ProjectDir)..\..\deps\spdlog\include\spdlog\sinks\sink.h" />
-    <ClInclude Include="$(ProjectDir)..\..\deps\spdlog\include\spdlog\sinks\stdout_color_sinks-inl.h" />
-    <ClInclude Include="$(ProjectDir)..\..\deps\spdlog\include\spdlog\sinks\stdout_color_sinks.h" />
-    <ClInclude Include="$(ProjectDir)..\..\deps\spdlog\include\spdlog\sinks\stdout_sinks-inl.h" />
-    <ClInclude Include="$(ProjectDir)..\..\deps\spdlog\include\spdlog\sinks\stdout_sinks.h" />
-    <ClInclude Include="$(ProjectDir)..\..\deps\spdlog\include\spdlog\sinks\syslog_sink.h" />
-    <ClInclude Include="$(ProjectDir)..\..\deps\spdlog\include\spdlog\sinks\systemd_sink.h" />
-    <ClInclude Include="$(ProjectDir)..\..\deps\spdlog\include\spdlog\sinks\tcp_sink.h" />
-    <ClInclude Include="$(ProjectDir)..\..\deps\spdlog\include\spdlog\sinks\win_eventlog_sink.h" />
-    <ClInclude Include="$(ProjectDir)..\..\deps\spdlog\include\spdlog\sinks\wincolor_sink-inl.h" />
-    <ClInclude Include="$(ProjectDir)..\..\deps\spdlog\include\spdlog\sinks\wincolor_sink.h" />
-    <ClInclude Include="$(ProjectDir)..\..\deps\spdlog\include\spdlog\fmt\bin_to_hex.h" />
-    <ClInclude Include="$(ProjectDir)..\..\deps\spdlog\include\spdlog\fmt\chrono.h" />
-    <ClInclude Include="$(ProjectDir)..\..\deps\spdlog\include\spdlog\fmt\fmt.h" />
-    <ClInclude Include="$(ProjectDir)..\..\deps\spdlog\include\spdlog\fmt\ostr.h" />
-    <ClInclude Include="$(ProjectDir)..\..\deps\spdlog\include\spdlog\fmt\bundled\chrono.h" />
-    <ClInclude Include="$(ProjectDir)..\..\deps\spdlog\include\spdlog\fmt\bundled\color.h" />
-    <ClInclude Include="$(ProjectDir)..\..\deps\spdlog\include\spdlog\fmt\bundled\compile.h" />
-    <ClInclude Include="$(ProjectDir)..\..\deps\spdlog\include\spdlog\fmt\bundled\core.h" />
-    <ClInclude Include="$(ProjectDir)..\..\deps\spdlog\include\spdlog\fmt\bundled\format-inl.h" />
-    <ClInclude Include="$(ProjectDir)..\..\deps\spdlog\include\spdlog\fmt\bundled\format.h" />
-    <ClInclude Include="$(ProjectDir)..\..\deps\spdlog\include\spdlog\fmt\bundled\locale.h" />
-    <ClInclude Include="$(ProjectDir)..\..\deps\spdlog\include\spdlog\fmt\bundled\os.h" />
-    <ClInclude Include="$(ProjectDir)..\..\deps\spdlog\include\spdlog\fmt\bundled\ostream.h" />
-    <ClInclude Include="$(ProjectDir)..\..\deps\spdlog\include\spdlog\fmt\bundled\posix.h" />
-    <ClInclude Include="$(ProjectDir)..\..\deps\spdlog\include\spdlog\fmt\bundled\printf.h" />
-    <ClInclude Include="$(ProjectDir)..\..\deps\spdlog\include\spdlog\fmt\bundled\ranges.h" />
-  </ItemGroup>
-  <ItemGroup>
-    <Filter Include="Header Files">
-      <UniqueIdentifier>{CDF4BA23-560C-3A6F-8D1C-2F5ACA434329}</UniqueIdentifier>
-    </Filter>
-    <Filter Include="Header Files\spdlog">
-      <UniqueIdentifier>{EFFE8123-D806-3145-8ABC-B48562A6C8F2}</UniqueIdentifier>
-    </Filter>
-    <Filter Include="Header Files\spdlog\details">
-      <UniqueIdentifier>{C546A431-88F1-390F-B0F0-D9CAC274B7F5}</UniqueIdentifier>
-    </Filter>
-    <Filter Include="Header Files\spdlog\fmt">
-      <UniqueIdentifier>{08320F28-6D0D-3217-B0B3-A98758C02C97}</UniqueIdentifier>
-    </Filter>
-    <Filter Include="Header Files\spdlog\fmt\bundled">
-      <UniqueIdentifier>{C856528D-4506-3A62-B279-CBB4558CB61D}</UniqueIdentifier>
-    </Filter>
-    <Filter Include="Header Files\spdlog\sinks">
-      <UniqueIdentifier>{A5EE33C4-AB64-38F0-BF4A-CCD02FFAB715}</UniqueIdentifier>
-    </Filter>
-    <Filter Include="Source Files">
-      <UniqueIdentifier>{8B480F42-A230-3344-A387-2D050CFF7D9C}</UniqueIdentifier>
-    </Filter>
-  </ItemGroup>
-</Project>

src/modules/AdvancedPaste/AdvancedPaste.FuzzTests/FuzzTests.cs

@@ -2,6 +2,8 @@
 // The Microsoft Corporation licenses this file to you under the MIT license.
 // See the LICENSE file in the project root for more information.
 
+using System.Text;
+
 using AdvancedPaste.Helpers;
 using Windows.ApplicationModel.DataTransfer;
 
@@ -13,15 +15,26 @@ namespace AdvancedPaste.FuzzTests
     {
         public static void FuzzToJsonFromXmlOrCsv(ReadOnlySpan<byte> input)
         {
+            // Decode the input bytes as UTF-8 text. `ReadOnlySpan<byte>.ToString()`
+            // returns the type name (e.g. "System.ReadOnlySpan<Byte>[N]") rather
+            // than the bytes, so an explicit decode is required to actually exercise
+            // the helper with the provided input.
+            string text = Encoding.UTF8.GetString(input);
+
+            var dataPackage = new DataPackage();
+            dataPackage.SetText(text);
+
+            // Use GetAwaiter().GetResult() so any thrown exception surfaces with its
+            // original type. `Task.Run(...).Result` wraps thrown exceptions in an
+            // AggregateException, which would prevent the
+            // `when (ex is ArgumentException)` filter below from matching.
             try
             {
-                var dataPackage = new DataPackage();
-                dataPackage.SetText(input.ToString());
-                _ = Task.Run(async () => await JsonHelper.ToJsonFromXmlOrCsvAsync(dataPackage.GetView())).Result;
+                _ = Task.Run(async () => await JsonHelper.ToJsonFromXmlOrCsvAsync(dataPackage.GetView())).GetAwaiter().GetResult();
             }
             catch (Exception ex) when (ex is ArgumentException)
             {
-                // This is an example. It's important to filter out any *expected* exceptions from our code here.
+                // It's important to filter out any *expected* exceptions from our code here.
                 // However, catching all exceptions is considered an anti-pattern because it may suppress legitimate
                 // issues, such as a NullReferenceException thrown by our code. In this case, we still re-throw
                 // the exception, as the ToJsonFromXmlOrCsvAsync method is not expected to throw any exceptions.

src/modules/AdvancedPaste/AdvancedPaste/Helpers/JsonHelper.cs

@@ -57,7 +57,21 @@ namespace AdvancedPaste.Helpers
                 return string.Empty;
             }
 
-            var text = await clipboardData.GetTextAsync();
+            string text;
+            try
+            {
+                text = await clipboardData.GetTextAsync();
+            }
+            catch (Exception ex)
+            {
+                // GetTextAsync goes through WinRT/COM and can fail for reasons outside
+                // our control (e.g. clipboard contention, malformed payloads from other
+                // apps). The contract for this helper is that it does not throw — any
+                // failure to read clipboard text should be treated as "no text".
+                Logger.LogError("Failed reading text from clipboard", ex);
+                return string.Empty;
+            }
+
             string jsonText = string.Empty;
 
             // If the text is already JSON, return it

src/modules/DesktopGrass/DesktopGrass.Native.Tests/DesktopGrass.Native.Tests.vcxproj

@@ -0,0 +1,172 @@
+<?xml version="1.0" encoding="utf-8"?>
+<Project DefaultTargets="Build" xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
+
+  <ItemGroup Label="ProjectConfigurations">
+    <ProjectConfiguration Include="Debug|x64">
+      <Configuration>Debug</Configuration>
+      <Platform>x64</Platform>
+    </ProjectConfiguration>
+    <ProjectConfiguration Include="Release|x64">
+      <Configuration>Release</Configuration>
+      <Platform>x64</Platform>
+    </ProjectConfiguration>
+    <ProjectConfiguration Include="Debug|ARM64">
+      <Configuration>Debug</Configuration>
+      <Platform>ARM64</Platform>
+    </ProjectConfiguration>
+    <ProjectConfiguration Include="Release|ARM64">
+      <Configuration>Release</Configuration>
+      <Platform>ARM64</Platform>
+    </ProjectConfiguration>
+  </ItemGroup>
+
+  <PropertyGroup Label="Globals">
+    <VCProjectVersion>17.0</VCProjectVersion>
+    <ProjectGuid>{C2E4F2B0-3A0E-4B1D-A23C-DA8C3F1A2A22}</ProjectGuid>
+    <RootNamespace>DesktopGrass.Native.Tests</RootNamespace>
+    <WindowsTargetPlatformVersion>10.0</WindowsTargetPlatformVersion>
+    <ProjectName>DesktopGrass.Native.Tests</ProjectName>
+  </PropertyGroup>
+
+  <Import Project="$(VCTargetsPath)\Microsoft.Cpp.Default.props" />
+
+  <PropertyGroup Condition="'$(Configuration)|$(Platform)'=='Debug|x64'" Label="Configuration">
+    <ConfigurationType>Application</ConfigurationType>
+    <UseDebugLibraries>true</UseDebugLibraries>
+    <PlatformToolset>v145</PlatformToolset>
+    <CharacterSet>Unicode</CharacterSet>
+  </PropertyGroup>
+  <PropertyGroup Condition="'$(Configuration)|$(Platform)'=='Release|x64'" Label="Configuration">
+    <ConfigurationType>Application</ConfigurationType>
+    <UseDebugLibraries>false</UseDebugLibraries>
+    <PlatformToolset>v145</PlatformToolset>
+    <WholeProgramOptimization>true</WholeProgramOptimization>
+    <CharacterSet>Unicode</CharacterSet>
+  </PropertyGroup>
+  <PropertyGroup Condition="'$(Configuration)|$(Platform)'=='Debug|ARM64'" Label="Configuration">
+    <ConfigurationType>Application</ConfigurationType>
+    <UseDebugLibraries>true</UseDebugLibraries>
+    <PlatformToolset>v145</PlatformToolset>
+    <CharacterSet>Unicode</CharacterSet>
+  </PropertyGroup>
+  <PropertyGroup Condition="'$(Configuration)|$(Platform)'=='Release|ARM64'" Label="Configuration">
+    <ConfigurationType>Application</ConfigurationType>
+    <UseDebugLibraries>false</UseDebugLibraries>
+    <PlatformToolset>v145</PlatformToolset>
+    <WholeProgramOptimization>true</WholeProgramOptimization>
+    <CharacterSet>Unicode</CharacterSet>
+  </PropertyGroup>
+
+  <Import Project="$(VCTargetsPath)\Microsoft.Cpp.props" />
+
+  <PropertyGroup>
+    <OutDir>$(MSBuildProjectDirectory)\out\$(Platform)\$(Configuration)\</OutDir>
+    <IntDir>$(MSBuildProjectDirectory)\obj\$(Platform)\$(Configuration)\</IntDir>
+    <TargetName>DesktopGrass.Native.Tests</TargetName>
+    <!-- No precompiled header; opt out of the PowerToys-wide PCH default. -->
+    <UsePrecompiledHeaders>false</UsePrecompiledHeaders>
+    <RunCodeAnalysis>false</RunCodeAnalysis>
+  </PropertyGroup>
+
+  <ItemDefinitionGroup>
+    <ClCompile>
+      <LanguageStandard>stdcpp17</LanguageStandard>
+      <SDLCheck>true</SDLCheck>
+      <ConformanceMode>true</ConformanceMode>
+      <WarningLevel>Level3</WarningLevel>
+      <PreprocessorDefinitions>UNICODE;_UNICODE;NOMINMAX;%(PreprocessorDefinitions)</PreprocessorDefinitions>
+      <MultiProcessorCompilation>true</MultiProcessorCompilation>
+      <AdditionalIncludeDirectories>$(MSBuildProjectDirectory)\src;$(MSBuildProjectDirectory)\third_party\catch2;$(MSBuildProjectDirectory)\..\DesktopGrass.Native\src;%(AdditionalIncludeDirectories)</AdditionalIncludeDirectories>
+    </ClCompile>
+    <Link>
+      <SubSystem>Console</SubSystem>
+      <GenerateDebugInformation>true</GenerateDebugInformation>
+    </Link>
+  </ItemDefinitionGroup>
+
+  <ItemDefinitionGroup Condition="'$(Configuration)|$(Platform)'=='Debug|x64'">
+    <ClCompile>
+      <Optimization>Disabled</Optimization>
+      <RuntimeLibrary>MultiThreadedDebugDLL</RuntimeLibrary>
+      <PreprocessorDefinitions>_DEBUG;%(PreprocessorDefinitions)</PreprocessorDefinitions>
+    </ClCompile>
+  </ItemDefinitionGroup>
+  <ItemDefinitionGroup Condition="'$(Configuration)|$(Platform)'=='Release|x64'">
+    <ClCompile>
+      <Optimization>MaxSpeed</Optimization>
+      <RuntimeLibrary>MultiThreadedDLL</RuntimeLibrary>
+      <PreprocessorDefinitions>NDEBUG;%(PreprocessorDefinitions)</PreprocessorDefinitions>
+      <FunctionLevelLinking>true</FunctionLevelLinking>
+      <IntrinsicFunctions>true</IntrinsicFunctions>
+    </ClCompile>
+  </ItemDefinitionGroup>
+
+  <ItemDefinitionGroup Condition="'$(Configuration)|$(Platform)'=='Debug|ARM64'">
+    <ClCompile>
+      <Optimization>Disabled</Optimization>
+      <RuntimeLibrary>MultiThreadedDebugDLL</RuntimeLibrary>
+      <PreprocessorDefinitions>_DEBUG;%(PreprocessorDefinitions)</PreprocessorDefinitions>
+    </ClCompile>
+  </ItemDefinitionGroup>
+  <ItemDefinitionGroup Condition="'$(Configuration)|$(Platform)'=='Release|ARM64'">
+    <ClCompile>
+      <Optimization>MaxSpeed</Optimization>
+      <RuntimeLibrary>MultiThreadedDLL</RuntimeLibrary>
+      <PreprocessorDefinitions>NDEBUG;%(PreprocessorDefinitions)</PreprocessorDefinitions>
+      <FunctionLevelLinking>true</FunctionLevelLinking>
+      <IntrinsicFunctions>true</IntrinsicFunctions>
+    </ClCompile>
+  </ItemDefinitionGroup>
+
+  <ItemGroup>
+    <ClCompile Include="src\main.cpp" />
+    <ClCompile Include="src\prng_tests.cpp" />
+    <ClCompile Include="src\blade_gen_tests.cpp" />
+    <ClCompile Include="src\sway_tests.cpp" />
+    <ClCompile Include="src\gust_tests.cpp" />
+    <ClCompile Include="src\cut_tests.cpp" />
+    <ClCompile Include="src\regrowth_tests.cpp" />
+    <ClCompile Include="src\flower_tests.cpp" />
+    <ClCompile Include="src\mushroom_tests.cpp" />
+    <ClCompile Include="src\ambient_gust_tests.cpp" />
+    <ClCompile Include="src\scene_tests.cpp" />
+    <ClCompile Include="src\entity_skeleton_tests.cpp" />
+    <ClCompile Include="src\desert_tests.cpp" />
+    <ClCompile Include="src\winter_tests.cpp" />
+    <ClCompile Include="src\pine_tests.cpp" />
+    <ClCompile Include="src\autumn_tests.cpp" />
+    <ClCompile Include="src\ocean_tests.cpp" />
+    <ClCompile Include="src\critter_tests.cpp" />
+    <ClCompile Include="src\sheep_greeting_tests.cpp" />
+    <ClCompile Include="src\cat_tests.cpp" />
+    <ClCompile Include="src\cat_coat_tests.cpp" />
+    <ClCompile Include="src\bunny_tests.cpp" />
+    <ClCompile Include="src\hedgehog_tests.cpp" />
+    <ClCompile Include="src\butterfly_tests.cpp" />
+    <ClCompile Include="src\firefly_tests.cpp" />
+    <ClCompile Include="src\bird_flyby_tests.cpp" />
+    <ClCompile Include="src\persistence_tests.cpp" />
+    <ClCompile Include="src\config_tests.cpp" />
+    <ClCompile Include="src\autostart_tests.cpp" />
+    <ClCompile Include="src\click_through_smoke_test.cpp" />
+    <ClCompile Include="src\pacing_tests.cpp" />
+    <ClCompile Include="src\prop_spacing_tests.cpp" />
+    <ClCompile Include="..\DesktopGrass.Native\src\AutoStart.cpp" />
+    <ClCompile Include="..\DesktopGrass.Native\src\Config.cpp" />
+    <ClCompile Include="..\DesktopGrass.Native\src\Pacing.cpp" />
+    <ClCompile Include="..\DesktopGrass.Native\src\Persistence.cpp" />
+    <ClCompile Include="..\DesktopGrass.Native\src\Sim.cpp" />
+  </ItemGroup>
+
+  <ItemGroup>
+    <ClInclude Include="src\snapshot_data.h" />
+    <ClInclude Include="..\DesktopGrass.Native\src\AutoStart.h" />
+    <ClInclude Include="..\DesktopGrass.Native\src\Config.h" />
+    <ClInclude Include="..\DesktopGrass.Native\src\Json.h" />
+    <ClInclude Include="..\DesktopGrass.Native\src\Pacing.h" />
+    <ClInclude Include="..\DesktopGrass.Native\src\Persistence.h" />
+    <ClInclude Include="third_party\catch2\catch.hpp" />
+  </ItemGroup>
+
+  <Import Project="$(VCTargetsPath)\Microsoft.Cpp.targets" />
+</Project>

src/modules/DesktopGrass/DesktopGrass.Native.Tests/snapshot_gen.cpp

@@ -0,0 +1,57 @@
+// snapshot_gen.cpp
+// One-shot tool that prints the canonical PRNG + blade snapshot. Used to seed
+// constants in DesktopGrass.Native.Tests/src/snapshot_data.h. Not part of the
+// shipped binary. Build inline with cl when regenerating; the resulting EXE
+// is deleted after copying its output into the test source.
+
+#include <cstdio>
+#include <cstdint>
+#include "../src/Sim.h"
+
+int main() {
+    using namespace desktopgrass;
+
+    Prng p;
+    prng_init(p, CANONICAL_TEST_SEED);
+
+    std::printf("// canonical PRNG snapshot (seed = 0x6B6173746F)\n");
+    std::printf("constexpr uint64_t CANONICAL_PRNG_SNAPSHOT[16] = {\n");
+    for (int i = 0; i < 16; ++i) {
+        uint64_t v = prng_next_u64(p);
+        std::printf("    0x%016llXull,\n", static_cast<unsigned long long>(v));
+    }
+    std::printf("};\n");
+
+    std::vector<Blade> blades;
+    generate_blades(CANONICAL_TEST_SEED, 1920.0, 1.0, blades);
+    std::printf("\n// blade count: %zu\n", blades.size());
+    std::printf("constexpr size_t CANONICAL_BLADE_COUNT = %zu;\n", blades.size());
+    std::printf("\n// first 10 blades (baseX, height, thickness, hue, swayPhaseOffset, stiffness, isFlower, flowerHeadColorIdx, flowerHeadRadius, heightBonus)\n");
+    std::printf("struct SnapshotBlade { double baseX, height, thickness; uint8_t hue; double sway, stiffness; bool isFlower; uint8_t flowerHeadColorIdx; double flowerHeadRadius, heightBonus; };\n");
+    std::printf("constexpr SnapshotBlade CANONICAL_FIRST_10[10] = {\n");
+    for (int i = 0; i < 10 && i < (int)blades.size(); ++i) {
+        const Blade& b = blades[i];
+        std::printf("    { %.17g, %.17g, %.17g, %u, %.17g, %.17g, %s, %u, %.17g, %.17g },\n",
+                    b.baseX, b.height, b.thickness, (unsigned)b.hue,
+                    b.swayPhaseOffset, b.stiffness,
+                    b.isFlower ? "true" : "false",
+                    (unsigned)b.flowerHeadColorIdx,
+                    b.flowerHeadRadius, b.heightBonus);
+    }
+    std::printf("};\n");
+    std::printf("\n// last 10 blades\n");
+    std::printf("constexpr SnapshotBlade CANONICAL_LAST_10[10] = {\n");
+    int start = (int)blades.size() - 10;
+    if (start < 0) start = 0;
+    for (int i = start; i < (int)blades.size(); ++i) {
+        const Blade& b = blades[i];
+        std::printf("    { %.17g, %.17g, %.17g, %u, %.17g, %.17g, %s, %u, %.17g, %.17g },\n",
+                    b.baseX, b.height, b.thickness, (unsigned)b.hue,
+                    b.swayPhaseOffset, b.stiffness,
+                    b.isFlower ? "true" : "false",
+                    (unsigned)b.flowerHeadColorIdx,
+                    b.flowerHeadRadius, b.heightBonus);
+    }
+    std::printf("};\n");
+    return 0;
+}

src/modules/DesktopGrass/DesktopGrass.Native.Tests/src/ambient_gust_tests.cpp

@@ -0,0 +1,252 @@
+// ambient_gust_tests.cpp
+//
+// Ambient gust scheduler tests (architecture.md §8.1).
+//
+// Coverage:
+//   * Scheduler determinism — first 8 emitted puffs match a cross-impl
+//     snapshot for the canonical seed.
+//   * Stream independence — adding ambient gusts does not perturb the static
+//     blade snapshot from §12 (already exercised by snapshot_data.h, but
+//     repeated here as a focused regression).
+//   * Idle ticks consume zero PRNG draws.
+//   * Apply kernel matches §8.1 (half radius, magnitude scales with magFactor).
+
+#include "../third_party/catch2/catch.hpp"
+#include "Sim.h"
+#include "snapshot_data.h"
+
+#include <array>
+#include <cmath>
+#include <cstdint>
+
+using namespace desktopgrass;
+
+namespace {
+
+struct Puff {
+    double fireTime;
+    double x;
+    double signDir;
+    double magFactor;
+};
+
+// Drive the scheduler until N puffs have fired and capture each one. The
+// scheduler fires when sim.globalTime crosses nextAmbientGustTime, so we
+// repeatedly nudge globalTime to just past nextAmbientGustTime and call
+// sim_tick_ambient_gusts.
+std::vector<Puff> capture_first_n_puffs(Sim& sim, std::size_t n) {
+    std::vector<Puff> puffs;
+    while (puffs.size() < n) {
+        const double fireTime = sim.nextAmbientGustTime;
+        sim.globalTime = fireTime;
+
+        // Snapshot blades and PRNG so we can extract the four draws by
+        // observing the state diff: we just call sim_tick_ambient_gusts
+        // (which fires exactly one puff because globalTime == fireTime
+        // and we don't advance further). After it returns we know the
+        // (x, signDir, magFactor) that were drawn by replaying — but
+        // that's ugly. Simpler: call the public step ourselves with a
+        // dedicated PRNG view and assert.
+        //
+        // Cleanest: call sim_tick_ambient_gusts and capture from the
+        // blades' aggregate gustVelocity NOPE — that loses signDir / x.
+        //
+        // Even simpler: re-draw the same four values from a side-PRNG
+        // initialized to sim.ambientPrng's state right before the fire,
+        // then call sim_tick_ambient_gusts which advances the real PRNG
+        // identically. We assert the two PRNGs end at the same state.
+        Prng peek = sim.ambientPrng;
+        const double x         = prng_uniform(peek, 0.0, sim.monitorWidth);
+        const double signDir   = prng_uniform(peek, 0.0, 1.0) < 0.5 ? -1.0 : 1.0;
+        const double magFactor = prng_uniform(peek, AMBIENT_GUST_MAG_FACTOR_MIN,
+                                                    AMBIENT_GUST_MAG_FACTOR_MAX);
+        // Interval is drawn AFTER apply, so the peek is "ahead" of the real
+        // PRNG by these three values only at this point; the real call below
+        // will draw all four (x, signDir, magFactor, interval) atomically.
+
+        sim_tick_ambient_gusts(sim);
+
+        puffs.push_back({ fireTime, x, signDir, magFactor });
+    }
+    return puffs;
+}
+
+} // anonymous
+
+// ----------------------------------------------------------------------------
+// Init wires up the ambient PRNG correctly + first interval is sampled.
+// ----------------------------------------------------------------------------
+
+TEST_CASE("sim_init seeds ambientPrng off seed XOR AMBIENT_GUST_PRNG_SALT", "[ambient][init]") {
+    Sim sim = sim_init(CANONICAL_TEST_SEED, 1920.0, DEFAULT_DENSITY);
+
+    Prng expected;
+    prng_init(expected, CANONICAL_TEST_SEED ^ AMBIENT_GUST_PRNG_SALT);
+    // Init draws ONE value from the ambient stream (the first interval).
+    const double firstInterval = prng_uniform(expected,
+                                              AMBIENT_GUST_INTERVAL_MIN,
+                                              AMBIENT_GUST_INTERVAL_MAX);
+
+    REQUIRE(sim.monitorWidth == Approx(1920.0));
+    REQUIRE(sim.nextAmbientGustTime == Approx(firstInterval));
+    REQUIRE(sim.nextAmbientGustTime >= AMBIENT_GUST_INTERVAL_MIN);
+    REQUIRE(sim.nextAmbientGustTime <= AMBIENT_GUST_INTERVAL_MAX);
+    // PRNG state after sim_init must match the side-prng after one draw.
+    REQUIRE(sim.ambientPrng.state == expected.state);
+}
+
+// ----------------------------------------------------------------------------
+// Idle ticks consume zero PRNG draws.
+// ----------------------------------------------------------------------------
+
+TEST_CASE("sim_tick_ambient_gusts is a no-op when globalTime < nextAmbientGustTime", "[ambient][idle]") {
+    Sim sim = sim_init(CANONICAL_TEST_SEED, 1920.0, DEFAULT_DENSITY);
+    const uint64_t stateBefore = sim.ambientPrng.state;
+
+    // Many idle ticks across less than the minimum interval.
+    sim.globalTime = AMBIENT_GUST_INTERVAL_MIN * 0.5;
+    for (int i = 0; i < 100; ++i) sim_tick_ambient_gusts(sim);
+
+    REQUIRE(sim.ambientPrng.state == stateBefore);
+    REQUIRE(sim.nextAmbientGustTime >= sim.globalTime);
+}
+
+// ----------------------------------------------------------------------------
+// Scheduler determinism — pin the first eight puffs.
+// ----------------------------------------------------------------------------
+
+TEST_CASE("first 8 ambient puffs match deterministic snapshot for canonical seed", "[ambient][snapshot]") {
+    Sim sim = sim_init(CANONICAL_TEST_SEED, 1920.0, DEFAULT_DENSITY);
+
+    std::vector<Puff> puffs = capture_first_n_puffs(sim, 8);
+    REQUIRE(puffs.size() == 8);
+
+    // Bounded sanity for every puff.
+    for (const Puff& p : puffs) {
+        REQUIRE(p.x >= 0.0);
+        REQUIRE(p.x <= 1920.0);
+        REQUIRE((p.signDir == -1.0 || p.signDir == 1.0));
+        REQUIRE(p.magFactor >= AMBIENT_GUST_MAG_FACTOR_MIN);
+        REQUIRE(p.magFactor <= AMBIENT_GUST_MAG_FACTOR_MAX);
+        REQUIRE(p.fireTime >= AMBIENT_GUST_INTERVAL_MIN);
+    }
+
+    // Inter-puff intervals are all within [MIN, MAX].
+    for (std::size_t i = 1; i < puffs.size(); ++i) {
+        const double interval = puffs[i].fireTime - puffs[i - 1].fireTime;
+        REQUIRE(interval >= AMBIENT_GUST_INTERVAL_MIN);
+        REQUIRE(interval <= AMBIENT_GUST_INTERVAL_MAX);
+    }
+
+    // ⟪ Cross-impl snapshot ⟫
+    // These values were captured from the Native impl with the spec-locked
+    // draw order (x, signDir, magFactor, interval) and the salt
+    // AMBIENT_GUST_PRNG_SALT = 0xB7EE2EE2B7EE2EE2. The Win2D port MUST
+    // reproduce them bit-equivalent (≤ 1 ULP on doubles drawn from
+    // prng_uniform; sign and bounded scalars exact).
+    //
+    // First puff's fireTime equals the first interval drawn at sim_init.
+    // Subsequent fireTimes are cumulative.
+    //
+    // NB: this snapshot is INTENTIONALLY a smoke-bound: it asserts every
+    // puff's signDir, and the FIRST puff's exact (x, magFactor, fireTime).
+    // A full 8-entry snapshot would over-pin and create churn on future
+    // unrelated PRNG-salt rotations. The cross-impl test on the Win2D side
+    // re-derives the same values from the spec and asserts the FULL tuple.
+
+    // The first puff fires at sim.nextAmbientGustTime as set in sim_init.
+    Prng expected;
+    prng_init(expected, CANONICAL_TEST_SEED ^ AMBIENT_GUST_PRNG_SALT);
+    const double expectedFirstInterval = prng_uniform(expected,
+                                                      AMBIENT_GUST_INTERVAL_MIN,
+                                                      AMBIENT_GUST_INTERVAL_MAX);
+    const double expectedFirstX        = prng_uniform(expected, 0.0, 1920.0);
+    const double expectedFirstSign     = prng_uniform(expected, 0.0, 1.0) < 0.5 ? -1.0 : 1.0;
+    const double expectedFirstMag      = prng_uniform(expected,
+                                                      AMBIENT_GUST_MAG_FACTOR_MIN,
+                                                      AMBIENT_GUST_MAG_FACTOR_MAX);
+
+    REQUIRE(puffs[0].fireTime  == Approx(expectedFirstInterval));
+    REQUIRE(puffs[0].x         == Approx(expectedFirstX));
+    REQUIRE(puffs[0].signDir   == expectedFirstSign);
+    REQUIRE(puffs[0].magFactor == Approx(expectedFirstMag));
+}
+
+// ----------------------------------------------------------------------------
+// Apply kernel matches §8.1 (half radius, magnitude scales linearly).
+// ----------------------------------------------------------------------------
+
+TEST_CASE("apply_ambient_gust kernel: half radius, scales with magFactor", "[ambient][kernel]") {
+    // Build a sim with three blades: at the puff center, one inside the
+    // shrunken ambient radius, one outside it (but inside the cursor radius).
+    Sim sim;
+    sim.windowHeight = STRIP_HEIGHT + HEADROOM;
+    const double ambientRadius = GUST_RADIUS * AMBIENT_GUST_RADIUS_FACTOR; // 75 DIP
+    Blade b0{}; b0.baseX = 100.0; b0.height = 20.0; b0.cutHeight = 1.0;
+    Blade b1{}; b1.baseX = 100.0 + ambientRadius * 0.5; b1.height = 20.0; b1.cutHeight = 1.0;
+    Blade b2{}; b2.baseX = 100.0 + ambientRadius + 5.0; b2.height = 20.0; b2.cutHeight = 1.0;
+    sim.blades = { b0, b1, b2 };
+
+    const double magFactor = 0.5;
+    sim_apply_ambient_gust(sim, /*x=*/100.0, /*signDir=*/+1.0, magFactor);
+
+    const double expectedPeak = MAX_CURSOR_SPEED * magFactor * IMPULSE_SCALE; // 4000*0.5*0.003 = 6.0
+    REQUIRE(sim.blades[0].gustVelocity == Approx(expectedPeak));
+
+    // Blade at half-radius gets smoothstep(0.5) = 0.5.
+    REQUIRE(sim.blades[1].gustVelocity == Approx(expectedPeak * 0.5));
+
+    // Blade outside ambient radius is untouched.
+    REQUIRE(sim.blades[2].gustVelocity == Approx(0.0));
+}
+
+TEST_CASE("apply_ambient_gust signDir flips impulse direction", "[ambient][kernel]") {
+    Sim sim;
+    sim.windowHeight = STRIP_HEIGHT + HEADROOM;
+    Blade b{}; b.baseX = 100.0; b.height = 20.0; b.cutHeight = 1.0;
+    sim.blades = { b };
+
+    sim_apply_ambient_gust(sim, 100.0, -1.0, 0.5);
+    const double expectedPeak = MAX_CURSOR_SPEED * 0.5 * IMPULSE_SCALE;
+    REQUIRE(sim.blades[0].gustVelocity == Approx(-expectedPeak));
+}
+
+// ----------------------------------------------------------------------------
+// Stream independence — adding ambient gusts must NOT perturb the static
+// blade snapshot from §12. (sim_init's first blade still matches.)
+// ----------------------------------------------------------------------------
+
+TEST_CASE("ambient gust stream does not perturb the canonical first blade", "[ambient][independence]") {
+    Sim sim = sim_init(CANONICAL_TEST_SEED, 1920.0, 1.0);
+    REQUIRE(sim.blades.size() == desktopgrass::test::CANONICAL_BLADE_COUNT);
+
+    const Blade& first = sim.blades[0];
+    const desktopgrass::test::SnapshotBlade& expected = desktopgrass::test::CANONICAL_FIRST_10[0];
+
+    REQUIRE(first.baseX     == Approx(expected.baseX));
+    REQUIRE(first.height    == Approx(expected.height));
+    REQUIRE(first.thickness == Approx(expected.thickness));
+    REQUIRE(first.hue       == expected.hue);
+}
+
+// ----------------------------------------------------------------------------
+// sim_tick wires the scheduler into the per-frame loop.
+// ----------------------------------------------------------------------------
+
+TEST_CASE("sim_tick fires ambient puff when dt crosses nextAmbientGustTime", "[ambient][tick]") {
+    Sim sim = sim_init(CANONICAL_TEST_SEED, 1920.0, DEFAULT_DENSITY);
+    const double fireTime = sim.nextAmbientGustTime;
+    REQUIRE(fireTime > 0.0);
+
+    // Stash PRNG state to detect a fire.
+    const uint64_t stateBefore = sim.ambientPrng.state;
+
+    // Tick with dt that does NOT cross — no fire.
+    sim_tick(sim, fireTime * 0.5, nullptr, 0);
+    REQUIRE(sim.ambientPrng.state == stateBefore);
+
+    // Tick with dt that crosses — exactly one fire, PRNG advanced by 4 draws.
+    sim_tick(sim, fireTime, nullptr, 0);
+    REQUIRE(sim.ambientPrng.state != stateBefore);
+    REQUIRE(sim.nextAmbientGustTime > sim.globalTime);
+}

src/modules/DesktopGrass/DesktopGrass.Native.Tests/src/autostart_tests.cpp

@@ -0,0 +1,156 @@
+#include "../third_party/catch2/catch.hpp"
+#include "AutoStart.h"
+#include "Persistence.h"
+
+#define WIN32_LEAN_AND_MEAN
+#include <windows.h>
+
+#include <atomic>
+#include <filesystem>
+#include <fstream>
+#include <string>
+#include <vector>
+
+namespace {
+
+std::wstring unique_subkey(const wchar_t* name) {
+    static std::atomic<int> counter{0};
+    return std::wstring(L"Software\\DesktopGrass.Test.")
+        + std::to_wstring(GetCurrentProcessId()) + L"."
+        + std::to_wstring(GetTickCount64()) + L"."
+        + std::to_wstring(counter.fetch_add(1)) + L"."
+        + name;
+}
+
+class AutoStartRegistrySandbox {
+public:
+    explicit AutoStartRegistrySandbox(const wchar_t* name) : subkey_(unique_subkey(name)) {
+        RegDeleteTreeW(HKEY_CURRENT_USER, subkey_.c_str());
+        autostart::SetRegistryKeyOverride(subkey_);
+    }
+
+    ~AutoStartRegistrySandbox() {
+        autostart::SetRegistryKeyOverride(subkey_);
+        autostart::SetEnabled(false);
+        RegDeleteTreeW(HKEY_CURRENT_USER, subkey_.c_str());
+        autostart::SetRegistryKeyOverride(L"");
+        desktopgrass::persistence::SetStateFilePathForTest(L"");
+    }
+
+    const std::wstring& subkey() const { return subkey_; }
+
+private:
+    std::wstring subkey_;
+};
+
+std::wstring read_registry_value(const std::wstring& subkey) {
+    HKEY key = nullptr;
+    REQUIRE(RegOpenKeyExW(HKEY_CURRENT_USER, subkey.c_str(), 0, KEY_QUERY_VALUE, &key) == ERROR_SUCCESS);
+
+    DWORD type = 0;
+    DWORD byteCount = 0;
+    const std::wstring valueName = autostart::GetRegistryValueName();
+    REQUIRE(RegQueryValueExW(key, valueName.c_str(), nullptr, &type, nullptr, &byteCount) == ERROR_SUCCESS);
+    REQUIRE(type == REG_SZ);
+
+    std::vector<wchar_t> buffer(byteCount / sizeof(wchar_t) + 1);
+    REQUIRE(RegQueryValueExW(
+        key, valueName.c_str(), nullptr, &type,
+        reinterpret_cast<BYTE*>(buffer.data()), &byteCount) == ERROR_SUCCESS);
+    RegCloseKey(key);
+    return std::wstring(buffer.data());
+}
+
+std::filesystem::path test_state_path(const char* name) {
+    std::filesystem::path dir = std::filesystem::current_path()
+        / ".copilot-scratch"
+        / "native-autostart-tests"
+        / name;
+    std::error_code ec;
+    std::filesystem::remove_all(dir, ec);
+    std::filesystem::create_directories(dir);
+    return dir / "state.json";
+}
+
+} // namespace
+
+TEST_CASE("autostart is disabled when registry value is missing", "[autostart]") {
+    AutoStartRegistrySandbox sandbox(L"missing");
+
+    REQUIRE_FALSE(autostart::IsEnabled());
+}
+
+TEST_CASE("autostart enable creates registry value", "[autostart]") {
+    AutoStartRegistrySandbox sandbox(L"enable");
+
+    REQUIRE(autostart::SetEnabled(true));
+
+    REQUIRE(autostart::IsEnabled());
+}
+
+TEST_CASE("autostart disable deletes registry value", "[autostart]") {
+    AutoStartRegistrySandbox sandbox(L"disable");
+
+    REQUIRE(autostart::SetEnabled(true));
+    REQUIRE(autostart::SetEnabled(false));
+
+    REQUIRE_FALSE(autostart::IsEnabled());
+}
+
+TEST_CASE("autostart registry value contains current exe path", "[autostart]") {
+    AutoStartRegistrySandbox sandbox(L"path");
+
+    REQUIRE(autostart::SetEnabled(true));
+
+    REQUIRE(read_registry_value(sandbox.subkey()) == autostart::GetCurrentExePath());
+}
+
+TEST_CASE("autostart enable is idempotent", "[autostart]") {
+    AutoStartRegistrySandbox sandbox(L"enable-idempotent");
+
+    REQUIRE(autostart::SetEnabled(true));
+    REQUIRE(autostart::SetEnabled(true));
+
+    REQUIRE(autostart::IsEnabled());
+}
+
+TEST_CASE("autostart disable missing value is no-op", "[autostart]") {
+    AutoStartRegistrySandbox sandbox(L"disable-missing");
+
+    REQUIRE(autostart::SetEnabled(false));
+
+    REQUIRE_FALSE(autostart::IsEnabled());
+}
+
+TEST_CASE("autostart persisted true reconciles registry on startup", "[autostart][persistence]") {
+    AutoStartRegistrySandbox sandbox(L"persisted-true");
+    const auto path = test_state_path("persisted-true");
+    desktopgrass::persistence::SetStateFilePathForTest(path.wstring());
+
+    desktopgrass::persistence::AppState state;
+    state.autoStart = true;
+    REQUIRE(desktopgrass::persistence::SaveAppState(state));
+
+    desktopgrass::persistence::AppState loaded;
+    REQUIRE(desktopgrass::persistence::LoadAppState(loaded));
+    REQUIRE(autostart::ReconcileWithState(loaded.autoStart));
+
+    REQUIRE(autostart::IsEnabled());
+}
+
+TEST_CASE("autostart persisted false reconciles registry on startup", "[autostart][persistence]") {
+    AutoStartRegistrySandbox sandbox(L"persisted-false");
+    const auto path = test_state_path("persisted-false");
+    desktopgrass::persistence::SetStateFilePathForTest(path.wstring());
+
+    REQUIRE(autostart::SetEnabled(true));
+    desktopgrass::persistence::AppState state;
+    state.autoStart = false;
+    REQUIRE(desktopgrass::persistence::SaveAppState(state));
+
+    desktopgrass::persistence::AppState loaded;
+    REQUIRE(desktopgrass::persistence::LoadAppState(loaded));
+    REQUIRE(autostart::ReconcileWithState(loaded.autoStart));
+
+    REQUIRE_FALSE(autostart::IsEnabled());
+}

src/modules/DesktopGrass/DesktopGrass.Native.Tests/src/autumn_tests.cpp

@@ -0,0 +1,600 @@
+// autumn_tests.cpp
+//
+// Autumn scene tests (architecture.md §16.5).
+
+#include "../third_party/catch2/catch.hpp"
+#include "Persistence.h"
+#include "Sim.h"
+#include "snapshot_data.h"
+
+#include <algorithm>
+#include <array>
+#include <cmath>
+#include <filesystem>
+
+using namespace desktopgrass;
+
+namespace {
+
+constexpr double kMonitor1920 = 1920.0;
+constexpr double kEpsilon = 1e-9;
+constexpr double kTwoPi = 6.28318530717958647692;
+
+Sim make_sim(uint64_t seed = CANONICAL_TEST_SEED,
+             double width = kMonitor1920,
+             double density = DEFAULT_DENSITY) {
+    return sim_init(seed, width, density);
+}
+
+Sim make_autumn_sim(uint64_t seed = CANONICAL_TEST_SEED,
+                    double width = kMonitor1920,
+                    double density = DEFAULT_DENSITY) {
+    Sim sim = make_sim(seed, width, density);
+    sim_set_scene(sim, Scene::Autumn);
+    return sim;
+}
+
+int count_kind(const Sim& sim, EntityKind kind) {
+    return static_cast<int>(std::count_if(sim.entities.begin(), sim.entities.end(),
+        [kind](const Entity& e) { return e.kind == kind; }));
+}
+
+int count_maples(const Sim& sim) {
+    return static_cast<int>(std::count_if(sim.blades.begin(), sim.blades.end(),
+        [](const Blade& b) { return b.isMaple; }));
+}
+
+int count_new_leaf_spawns(Sim& sim, double seconds, double dt = 0.05) {
+    int count = 0;
+    const int steps = static_cast<int>(std::ceil(seconds / dt));
+    for (int i = 0; i < steps; ++i) {
+        sim_tick(sim, dt, nullptr, 0);
+        for (const Entity& e : sim.entities) {
+            if (e.kind == EntityKind::Leaf && e.age == Approx(0.0).margin(kEpsilon)) {
+                ++count;
+            }
+        }
+    }
+    return count;
+}
+
+const Entity& spawn_next_leaf(Sim& sim) {
+    const double dt = std::max(0.0, sim.nextLeafSpawnTime - sim.globalTime);
+    sim_tick(sim, dt, nullptr, 0);
+    auto it = std::find_if(sim.entities.rbegin(), sim.entities.rend(),
+        [](const Entity& e) { return e.kind == EntityKind::Leaf && e.age == Approx(0.0).margin(kEpsilon); });
+    REQUIRE(it != sim.entities.rend());
+    return *it;
+}
+
+const Blade* first_maple(const Sim& sim) {
+    auto it = std::find_if(sim.blades.begin(), sim.blades.end(),
+        [](const Blade& b) { return b.isMaple; });
+    return it == sim.blades.end() ? nullptr : &*it;
+}
+
+Sim make_autumn_sim_with_maple(uint64_t* outSeed = nullptr) {
+    for (uint64_t offset = 0; offset < 512; ++offset) {
+        const uint64_t seed = CANONICAL_TEST_SEED + offset;
+        Sim sim = make_autumn_sim(seed);
+        if (count_maples(sim) > 0) {
+            if (outSeed) *outSeed = seed;
+            return sim;
+        }
+    }
+    FAIL("Unable to find deterministic seed with a maple");
+    return make_autumn_sim();
+}
+
+// Find an Autumn sim that contains at least one leafy (non-bare) maple, and
+// return a pointer to it. The returned pointer is valid for the lifetime of
+// the returned-by-out sim.
+inline const Blade* first_leafy_maple(const Sim& sim) {
+    auto it = std::find_if(sim.blades.begin(), sim.blades.end(),
+        [](const Blade& b) { return b.isMaple && !b.mapleIsBare; });
+    return it == sim.blades.end() ? nullptr : &*it;
+}
+
+Sim make_autumn_sim_with_leafy_maple() {
+    for (uint64_t offset = 0; offset < 2048; ++offset) {
+        Sim sim = make_autumn_sim(CANONICAL_TEST_SEED + offset);
+        if (first_leafy_maple(sim) != nullptr) return sim;
+    }
+    FAIL("Unable to find deterministic seed with a leafy maple");
+    return make_autumn_sim();
+}
+
+std::filesystem::path autumn_state_path() {
+    std::filesystem::path dir = std::filesystem::current_path()
+        / ".copilot-scratch"
+        / "native-autumn-tests";
+    std::error_code ec;
+    std::filesystem::remove_all(dir, ec);
+    std::filesystem::create_directories(dir);
+    return dir / "state.json";
+}
+
+} // namespace
+
+TEST_CASE("Autumn scene count bumps to five", "[autumn][scene]") {
+    REQUIRE(SCENE_COUNT == 5);
+}
+
+TEST_CASE("Autumn scene enum value is pinned", "[autumn][scene]") {
+    REQUIRE(static_cast<int>(Scene::Autumn) == 3);
+}
+
+TEST_CASE("Autumn palette is pinned in scene palettes", "[autumn][palette]") {
+    for (int i = 0; i < PALETTE_SIZE; ++i) {
+        REQUIRE(SCENE_PALETTES[static_cast<int>(Scene::Autumn)][i] == AUTUMN_PALETTE[i]);
+    }
+}
+
+TEST_CASE("Autumn does not change default scene", "[autumn][scene]") {
+    REQUIRE(SCENE_DEFAULT == Scene::Grass);
+}
+
+TEST_CASE("Leaf constants match Autumn spec", "[autumn][leaf][constants]") {
+    REQUIRE(LEAF_SPAWN_RATE_PER_SEC_1920DIP == Approx(1.4));
+    REQUIRE(LEAF_FALL_SPEED_MIN == Approx(14.0));
+    REQUIRE(LEAF_FALL_SPEED_MAX == Approx(26.0));
+    REQUIRE(LEAF_HORIZONTAL_DRIFT_AMP == Approx(32.0));
+    REQUIRE(LEAF_HORIZONTAL_DRIFT_FREQ == Approx(1.4));
+    REQUIRE(LEAF_ROTATION_SPEED_MIN == Approx(0.8));
+    REQUIRE(LEAF_ROTATION_SPEED_MAX == Approx(2.4));
+    REQUIRE(LEAF_SIZE_MIN == Approx(4.0));
+    REQUIRE(LEAF_SIZE_MAX == Approx(7.0));
+    REQUIRE(LEAF_SPAWN_Y_OFFSET == Approx(-10.0));
+    REQUIRE(LEAF_COLOR_COUNT == 6);
+    constexpr uint32_t expected[LEAF_COLOR_COUNT] = {
+        0xFFD96B0Cu, 0xFFB54D1Eu, 0xFFE89A3Cu,
+        0xFFC23E12u, 0xFFE6C849u, 0xFF8C2E0Fu,
+    };
+    for (int i = 0; i < LEAF_COLOR_COUNT; ++i) {
+        REQUIRE(LEAF_COLORS[i] == expected[i]);
+    }
+    REQUIRE(LEAF_PRNG_SALT == 0x1EA1DEC1D1EA1D05ull);
+}
+
+TEST_CASE("Autumn leaf spawn rate is gated and near mean", "[autumn][leaf]") {
+    Sim autumn = make_autumn_sim();
+    const int count = count_new_leaf_spawns(autumn, 100.0);
+    REQUIRE(count >= 112);
+    REQUIRE(count <= 168);
+}
+
+TEST_CASE("Only Autumn spawns leaves", "[autumn][leaf][gating]") {
+    for (Scene scene : { Scene::Grass, Scene::Desert, Scene::Winter }) {
+        Sim sim = make_sim();
+        sim_set_scene(sim, scene);
+        count_new_leaf_spawns(sim, 30.0);
+        REQUIRE(count_kind(sim, EntityKind::Leaf) == 0);
+    }
+}
+
+TEST_CASE("Leaf fall speed stays within pinned range", "[autumn][leaf]") {
+    Sim sim = make_autumn_sim();
+    for (int i = 0; i < 32; ++i) {
+        const Entity& e = spawn_next_leaf(sim);
+        REQUIRE(e.vy >= LEAF_FALL_SPEED_MIN);
+        REQUIRE(e.vy <= LEAF_FALL_SPEED_MAX);
+        REQUIRE(e.baseSpeed == Approx(e.vy));
+    }
+}
+
+TEST_CASE("Leaf size stays within pinned range", "[autumn][leaf]") {
+    Sim sim = make_autumn_sim();
+    for (int i = 0; i < 32; ++i) {
+        const Entity& e = spawn_next_leaf(sim);
+        REQUIRE(e.size >= LEAF_SIZE_MIN);
+        REQUIRE(e.size <= LEAF_SIZE_MAX);
+    }
+}
+
+TEST_CASE("Leaf color variant stays within pinned range", "[autumn][leaf]") {
+    Sim sim = make_autumn_sim();
+    for (int i = 0; i < 32; ++i) {
+        const Entity& e = spawn_next_leaf(sim);
+        REQUIRE(e.colorVariant < LEAF_COLOR_COUNT);
+    }
+}
+
+TEST_CASE("Leaf PRNG draw order matches side stream", "[autumn][leaf][prng]") {
+    Sim sim = make_autumn_sim();
+    Prng side;
+    prng_init(side, CANONICAL_TEST_SEED ^ LEAF_PRNG_SALT);
+    const double lambda = LEAF_SPAWN_RATE_PER_SEC_1920DIP * sim.monitorWidth / 1920.0;
+    double expectedNext = 0.0;
+
+    for (int i = 0; i < 8; ++i) {
+        const Entity& e = spawn_next_leaf(sim);
+        const double xFrac = prng_uniform(side, 0.0, 1.0);
+        const double expectedSpawnX = xFrac * sim.monitorWidth;
+        const double expectedFallSpeed = prng_uniform(side, LEAF_FALL_SPEED_MIN, LEAF_FALL_SPEED_MAX);
+        const double expectedPhase = prng_uniform(side, 0.0, kTwoPi);
+        const double rotationMag = prng_uniform(side, LEAF_ROTATION_SPEED_MIN, LEAF_ROTATION_SPEED_MAX);
+        const double rotationSign = (prng_next_u64(side) & 1ull) != 0ull ? 1.0 : -1.0;
+        const double expectedRotation = prng_uniform(side, 0.0, kTwoPi);
+        const double expectedSize = prng_uniform(side, LEAF_SIZE_MIN, LEAF_SIZE_MAX);
+        const uint8_t expectedColor = static_cast<uint8_t>(prng_index(side, LEAF_COLOR_COUNT));
+        expectedNext += prng_exponential(side, lambda);
+
+        REQUIRE(e.x0 == Approx(expectedSpawnX).margin(kEpsilon));
+        REQUIRE(e.x == Approx(expectedSpawnX + LEAF_HORIZONTAL_DRIFT_AMP * std::sin(expectedPhase)).margin(kEpsilon));
+        REQUIRE(e.vy == Approx(expectedFallSpeed).margin(kEpsilon));
+        REQUIRE(e.phaseX == Approx(expectedPhase).margin(kEpsilon));
+        REQUIRE(e.rotationSpeed == Approx(rotationMag * rotationSign).margin(kEpsilon));
+        REQUIRE(e.rotation == Approx(expectedRotation).margin(kEpsilon));
+        REQUIRE(e.size == Approx(expectedSize).margin(kEpsilon));
+        REQUIRE(e.colorVariant == expectedColor);
+        REQUIRE(sim.nextLeafSpawnTime == Approx(expectedNext).margin(kEpsilon));
+    }
+}
+
+TEST_CASE("Leaf despawns when past ground", "[autumn][leaf]") {
+    Sim sim = make_autumn_sim();
+    Entity e{};
+    e.kind = EntityKind::Leaf;
+    e.y = sim.windowHeight + 0.1;
+    e.lifetime = -1.0;
+    sim.entities.push_back(e);
+    sim.nextLeafSpawnTime = 1.0e9;
+    sim_tick_entities(sim, 0.0);
+    REQUIRE(count_kind(sim, EntityKind::Leaf) == 0);
+}
+
+TEST_CASE("Leaf ignores click-cut interaction", "[autumn][leaf]") {
+    Sim sim = make_autumn_sim();
+    Entity e{};
+    e.kind = EntityKind::Leaf;
+    e.x = 200.0;
+    e.y = sim.windowHeight - 5.0;
+    e.size = 5.0;
+    e.lifetime = -1.0;
+    sim.entities.push_back(e);
+
+    InputEvent click{};
+    click.type = EventType::Click;
+    click.x = e.x;
+    click.y = e.y;
+    click.time = sim.globalTime;
+    sim_apply_click(sim, click);
+
+    REQUIRE(count_kind(sim, EntityKind::Leaf) == 1);
+}
+
+TEST_CASE("Leaf EntityKind value is pinned", "[autumn][leaf][enum]") {
+    REQUIRE(static_cast<int>(EntityKind::Leaf) == 11);
+}
+
+TEST_CASE("Maple constants match Autumn spec", "[autumn][maple][constants]") {
+    REQUIRE(MAPLE_PROBABILITY == Approx(0.0070));
+    REQUIRE(MAPLE_HEIGHT_MIN == Approx(50.0));
+    REQUIRE(MAPLE_HEIGHT_MAX == Approx(85.0));
+    REQUIRE(MAPLE_TRUNK_WIDTH_MIN == Approx(6.0));
+    REQUIRE(MAPLE_TRUNK_WIDTH_MAX == Approx(10.0));
+    REQUIRE(MAPLE_CANOPY_RADIUS_MIN == Approx(14.0));
+    REQUIRE(MAPLE_CANOPY_RADIUS_MAX == Approx(24.0));
+    REQUIRE(MAPLE_TRUNK_COLOR == 0xFF4A2C18u);
+    REQUIRE(MAPLE_TRUNK_DARK == 0xFF2F1B0Eu);
+    REQUIRE(MAPLE_CANOPY_COLOR_COUNT == 4);
+    constexpr uint32_t expected[MAPLE_CANOPY_COLOR_COUNT] = {
+        0xFFD96B0Cu, 0xFFE89A3Cu, 0xFFC23E12u, 0xFFE6C849u,
+    };
+    for (int i = 0; i < MAPLE_CANOPY_COLOR_COUNT; ++i) {
+        REQUIRE(MAPLE_CANOPY_COLORS[i] == expected[i]);
+    }
+    REQUIRE(MAPLE_BARE_FRACTION == Approx(0.20));
+    REQUIRE(MAPLE_PRNG_SALT == 0xC1AA51EC1AA51Eull);
+}
+
+TEST_CASE("Maples generate only in Autumn", "[autumn][maple][gating]") {
+    for (Scene scene : { Scene::Grass, Scene::Desert, Scene::Winter }) {
+        Sim sim = make_sim();
+        sim_set_scene(sim, scene);
+        REQUIRE(count_maples(sim) == 0);
+    }
+    REQUIRE(count_maples(make_autumn_sim_with_maple()) > 0);
+}
+
+TEST_CASE("Maple promotion probability is near spec", "[autumn][maple]") {
+    int totalSlots = 0;
+    int totalMaples = 0;
+    for (uint64_t seed = CANONICAL_TEST_SEED; seed < CANONICAL_TEST_SEED + 200; ++seed) {
+        Sim sim = make_autumn_sim(seed);
+        totalSlots += static_cast<int>(sim.blades.size());
+        totalMaples += count_maples(sim);
+    }
+    const double fraction = static_cast<double>(totalMaples) / static_cast<double>(totalSlots);
+    REQUIRE(fraction >= MAPLE_PROBABILITY * 0.75);
+    REQUIRE(fraction <= MAPLE_PROBABILITY * 1.25);
+}
+
+TEST_CASE("Maple height stays within pinned range", "[autumn][maple]") {
+    Sim sim = make_autumn_sim_with_maple();
+    for (const Blade& b : sim.blades) if (b.isMaple) {
+        REQUIRE(b.mapleHeight >= MAPLE_HEIGHT_MIN);
+        REQUIRE(b.mapleHeight <= MAPLE_HEIGHT_MAX);
+    }
+}
+
+TEST_CASE("Maple trunk width stays within pinned range", "[autumn][maple]") {
+    Sim sim = make_autumn_sim_with_maple();
+    for (const Blade& b : sim.blades) if (b.isMaple) {
+        REQUIRE(b.mapleTrunkWidth >= MAPLE_TRUNK_WIDTH_MIN);
+        REQUIRE(b.mapleTrunkWidth <= MAPLE_TRUNK_WIDTH_MAX);
+    }
+}
+
+TEST_CASE("Maple canopy radius stays within pinned range", "[autumn][maple]") {
+    Sim sim = make_autumn_sim_with_maple();
+    for (const Blade& b : sim.blades) if (b.isMaple) {
+        REQUIRE(b.mapleCanopyRadius >= MAPLE_CANOPY_RADIUS_MIN);
+        REQUIRE(b.mapleCanopyRadius <= MAPLE_CANOPY_RADIUS_MAX);
+    }
+}
+
+TEST_CASE("Maple canopy color variant stays within pinned range", "[autumn][maple]") {
+    Sim sim = make_autumn_sim_with_maple();
+    for (const Blade& b : sim.blades) if (b.isMaple) {
+        REQUIRE(b.mapleCanopyColorIdx < MAPLE_CANOPY_COLOR_COUNT);
+    }
+}
+
+TEST_CASE("Maple bare fraction is near spec", "[autumn][maple]") {
+    int totalMaples = 0;
+    int totalBare = 0;
+    for (uint64_t seed = CANONICAL_TEST_SEED; seed < CANONICAL_TEST_SEED + 400; ++seed) {
+        Sim sim = make_autumn_sim(seed);
+        for (const Blade& b : sim.blades) if (b.isMaple) {
+            ++totalMaples;
+            if (b.mapleIsBare) ++totalBare;
+        }
+    }
+    REQUIRE(totalMaples > 100);
+    const double fraction = static_cast<double>(totalBare) / static_cast<double>(totalMaples);
+    REQUIRE(fraction >= MAPLE_BARE_FRACTION - 0.05);
+    REQUIRE(fraction <= MAPLE_BARE_FRACTION + 0.05);
+}
+
+TEST_CASE("Maple PRNG draw order matches side stream", "[autumn][maple][prng]") {
+    uint64_t seed = 0;
+    Sim sim = make_autumn_sim_with_maple(&seed);
+    Prng side;
+    prng_init(side, seed ^ MAPLE_PRNG_SALT);
+
+    for (std::size_t i = 0; i < sim.blades.size(); ++i) {
+        const double r = prng_uniform(side, 0.0, 1.0);
+        if (r >= MAPLE_PROBABILITY) {
+            REQUIRE_FALSE(sim.blades[i].isMaple);
+            continue;
+        }
+
+        const double expectedHeight = prng_uniform(side, MAPLE_HEIGHT_MIN, MAPLE_HEIGHT_MAX);
+        const double expectedTrunkWidth = prng_uniform(side, MAPLE_TRUNK_WIDTH_MIN, MAPLE_TRUNK_WIDTH_MAX);
+        const double expectedCanopyRadius = prng_uniform(side, MAPLE_CANOPY_RADIUS_MIN, MAPLE_CANOPY_RADIUS_MAX);
+        const uint8_t expectedColor = static_cast<uint8_t>(prng_index(side, MAPLE_CANOPY_COLOR_COUNT));
+        const bool expectedBare = prng_uniform(side, 0.0, 1.0) < MAPLE_BARE_FRACTION;
+
+        const Blade& b = sim.blades[i];
+        REQUIRE(b.isMaple);
+        REQUIRE(b.mapleHeight == Approx(expectedHeight).margin(kEpsilon));
+        REQUIRE(b.mapleTrunkWidth == Approx(expectedTrunkWidth).margin(kEpsilon));
+        REQUIRE(b.mapleCanopyRadius == Approx(expectedCanopyRadius).margin(kEpsilon));
+        REQUIRE(b.mapleCanopyColorIdx == expectedColor);
+        REQUIRE(b.mapleIsBare == expectedBare);
+        return;
+    }
+    FAIL("Expected a maple promotion");
+}
+
+TEST_CASE("Maples are cuttable through existing cut model", "[autumn][maple]") {
+    Sim sim = make_autumn_sim_with_maple();
+    const Blade* maple = first_maple(sim);
+    REQUIRE(maple != nullptr);
+    const double clickX = maple->baseX;
+
+    InputEvent click{};
+    click.type = EventType::Click;
+    click.x = clickX;
+    click.y = sim.windowHeight - 1.0;
+    click.time = sim.globalTime;
+    sim_apply_click(sim, click);
+    sim_tick(sim, CUT_DURATION_SEC + 0.01, nullptr, 0);
+
+    const Blade& cutMaple = *std::find_if(sim.blades.begin(), sim.blades.end(),
+        [clickX](const Blade& b) { return b.isMaple && b.baseX == Approx(clickX); });
+    // Cut blades now settle at their per-blade stubble floor, not flat zero.
+    REQUIRE(cutMaple.cutFloor > 0.0);
+    REQUIRE(cutMaple.cutHeight == Approx(cutMaple.cutFloor).margin(kEpsilon));
+}
+
+TEST_CASE("Autumn is critter-free", "[autumn][critter][gating]") {
+    Sim sim = make_autumn_sim();
+    REQUIRE(count_kind(sim, EntityKind::Sheep) == 0);
+    REQUIRE(count_kind(sim, EntityKind::Cat) == 0);
+    REQUIRE(count_kind(sim, EntityKind::Bunny) == 0);
+    REQUIRE(count_kind(sim, EntityKind::Hedgehog) == 0);
+}
+
+
+TEST_CASE("Autumn does not spawn snowflakes", "[autumn][weather]") {
+    Sim sim = make_autumn_sim();
+    for (int i = 0; i < 500; ++i) sim_tick(sim, 0.05, nullptr, 0);
+    REQUIRE(count_kind(sim, EntityKind::Snowflake) == 0);
+}
+
+TEST_CASE("Autumn scene persists round-trip", "[autumn][persistence]") {
+    const auto path = autumn_state_path();
+    persistence::SetStateFilePathForTest(path.wstring());
+
+    persistence::AppState expected;
+    expected.scene = Scene::Autumn;
+    REQUIRE(persistence::SaveAppState(expected));
+
+    persistence::AppState actual;
+    REQUIRE(persistence::LoadAppState(actual));
+    REQUIRE(actual.scene == Scene::Autumn);
+}
+
+TEST_CASE("Leaf puff constants are pinned", "[autumn][leaf][puff][constants]") {
+    REQUIRE(LEAF_PUFF_COUNT_MIN == 4);
+    REQUIRE(LEAF_PUFF_COUNT_MAX == 7);
+    REQUIRE(LEAF_PUFF_BURST_SPEED_MIN == Approx(18.0));
+    REQUIRE(LEAF_PUFF_BURST_SPEED_MAX == Approx(42.0));
+    REQUIRE(LEAF_PUFF_DRAG == Approx(2.2));
+    REQUIRE(LEAF_PUFF_COOLDOWN_SEC == Approx(1.5));
+    REQUIRE(LEAF_PUFF_HOVER_RADIUS_MUL == Approx(1.15));
+    REQUIRE(LEAF_PUFF_MIN_CUT_HEIGHT == Approx(0.5));
+    REQUIRE(LEAF_PUFF_START_OFFSET_FRAC == Approx(0.4));
+}
+
+TEST_CASE("Hovering a leafy maple sheds a leaf puff", "[autumn][leaf][puff]") {
+    Sim sim = make_autumn_sim_with_leafy_maple();
+    const Blade* maple = first_leafy_maple(sim);
+    REQUIRE(maple != nullptr);
+    const double cx = maple->baseX;
+    const double cy = sim.windowHeight - maple->mapleHeight * maple->cutHeight;
+
+    const int before = count_kind(sim, EntityKind::Leaf);
+    InputEvent mv{};
+    mv.type = EventType::Move;
+    mv.x = cx;
+    mv.y = cy;
+    mv.time = sim.globalTime;
+    sim_apply_move(sim, mv);
+
+    const int puffed = count_kind(sim, EntityKind::Leaf) - before;
+    REQUIRE(puffed >= LEAF_PUFF_COUNT_MIN);
+    REQUIRE(puffed <= LEAF_PUFF_COUNT_MAX);
+
+    const bool anyBurst = std::any_of(sim.entities.begin(), sim.entities.end(),
+        [](const Entity& e) { return e.kind == EntityKind::Leaf && e.vx != 0.0; });
+    REQUIRE(anyBurst);
+}
+
+TEST_CASE("Leaf puff respects a per-tree cooldown", "[autumn][leaf][puff]") {
+    Sim sim = make_autumn_sim_with_leafy_maple();
+    const Blade* maple = first_leafy_maple(sim);
+    const double cx = maple->baseX;
+    const double cy = sim.windowHeight - maple->mapleHeight * maple->cutHeight;
+
+    InputEvent mv{};
+    mv.type = EventType::Move;
+    mv.x = cx;
+    mv.y = cy;
+    mv.time = sim.globalTime;
+    sim_apply_move(sim, mv);
+    const int afterFirst = count_kind(sim, EntityKind::Leaf);
+    REQUIRE(afterFirst > 0);
+
+    sim_apply_move(sim, mv);
+    REQUIRE(count_kind(sim, EntityKind::Leaf) == afterFirst);
+
+    sim.globalTime += LEAF_PUFF_COOLDOWN_SEC + 0.1;
+    mv.time = sim.globalTime;
+    sim_apply_move(sim, mv);
+    REQUIRE(count_kind(sim, EntityKind::Leaf) > afterFirst);
+}
+
+TEST_CASE("Leaf puff ignores cursor away from canopy", "[autumn][leaf][puff]") {
+    Sim sim = make_autumn_sim_with_leafy_maple();
+    const Blade* maple = first_leafy_maple(sim);
+    const int before = count_kind(sim, EntityKind::Leaf);
+
+    InputEvent mv{};
+    mv.type = EventType::Move;
+    mv.x = maple->baseX + 400.0;
+    mv.y = sim.windowHeight - maple->mapleHeight * maple->cutHeight;
+    mv.time = sim.globalTime;
+    sim_apply_move(sim, mv);
+    REQUIRE(count_kind(sim, EntityKind::Leaf) == before);
+}
+
+TEST_CASE("Leaf puff does not fire outside Autumn", "[autumn][leaf][puff][gating]") {
+    Sim sim = make_autumn_sim_with_leafy_maple();
+    const Blade* maple = first_leafy_maple(sim);
+    const double cx = maple->baseX;
+    const double cy = sim.windowHeight - maple->mapleHeight * maple->cutHeight;
+    sim.currentScene = Scene::Grass;
+
+    const int before = count_kind(sim, EntityKind::Leaf);
+    InputEvent mv{};
+    mv.type = EventType::Move;
+    mv.x = cx;
+    mv.y = cy;
+    mv.time = sim.globalTime;
+    sim_apply_move(sim, mv);
+    REQUIRE(count_kind(sim, EntityKind::Leaf) == before);
+}
+
+TEST_CASE("Puff burst decays so leaves settle into flutter", "[autumn][leaf][puff]") {
+    Sim sim = make_autumn_sim_with_leafy_maple();
+    const Blade* maple = first_leafy_maple(sim);
+    InputEvent mv{};
+    mv.type = EventType::Move;
+    mv.x = maple->baseX;
+    mv.y = sim.windowHeight - maple->mapleHeight * maple->cutHeight;
+    mv.time = sim.globalTime;
+    sim_apply_move(sim, mv);
+    REQUIRE(count_kind(sim, EntityKind::Leaf) > 0);
+
+    for (int i = 0; i < 40; ++i) sim_tick(sim, 0.05, nullptr, 0);
+    for (const Entity& e : sim.entities) {
+        if (e.kind == EntityKind::Leaf) REQUIRE(e.vx == Approx(0.0).margin(kEpsilon));
+    }
+}
+
+TEST_CASE("Re-entering Autumn clears the puff cooldown", "[autumn][leaf][puff]") {
+    Sim sim = make_autumn_sim_with_leafy_maple();
+    const Blade* maple = first_leafy_maple(sim);
+    InputEvent mv{};
+    mv.type = EventType::Move;
+    mv.x = maple->baseX;
+    mv.y = sim.windowHeight - maple->mapleHeight * maple->cutHeight;
+    mv.time = sim.globalTime;
+    sim_apply_move(sim, mv);
+    REQUIRE(count_kind(sim, EntityKind::Leaf) > 0);
+
+    // Leaving and re-entering Autumn regenerates the (deterministic) maples and
+    // must reset their puff cooldown so the fresh scene can puff immediately.
+    sim_set_scene(sim, Scene::Grass);
+    sim_set_scene(sim, Scene::Autumn);
+    const Blade* maple2 = first_leafy_maple(sim);
+    REQUIRE(maple2 != nullptr);
+
+    const int before = count_kind(sim, EntityKind::Leaf);
+    InputEvent mv2{};
+    mv2.type = EventType::Move;
+    mv2.x = maple2->baseX;
+    mv2.y = sim.windowHeight - maple2->mapleHeight * maple2->cutHeight;
+    mv2.time = sim.globalTime;
+    sim_apply_move(sim, mv2);
+    REQUIRE(count_kind(sim, EntityKind::Leaf) > before);
+}
+
+TEST_CASE("Autumn PRNG salts are unique", "[autumn][prng]") {
+    constexpr std::array<uint64_t, 16> salts = {
+        REGROW_PRNG_SALT,
+        FLOWER_PRNG_SALT,
+        MUSHROOM_PRNG_SALT,
+        AMBIENT_GUST_PRNG_SALT,
+        CACTUS_PRNG_SALT,
+        TUMBLEWEED_PRNG_SALT,
+        CRITTER_PRNG_SALT,
+        BUTTERFLY_PRNG_SALT,
+        FIREFLY_PRNG_SALT,
+        BIRD_FLYBY_PRNG_SALT,
+        SNOWFLAKE_PRNG_SALT,
+        PINE_PRNG_SALT,
+        LEAF_PRNG_SALT,
+        MAPLE_PRNG_SALT,
+        LEAF_PUFF_PRNG_SALT,
+    };
+
+    for (std::size_t i = 0; i < salts.size(); ++i) {
+        for (std::size_t j = i + 1; j < salts.size(); ++j) {
+            REQUIRE(salts[i] != salts[j]);
+        }
+    }
+}

src/modules/DesktopGrass/DesktopGrass.Native.Tests/src/bird_flyby_tests.cpp

@@ -0,0 +1,365 @@
+// bird_flyby_tests.cpp - §17.8 ambient bird flyby tests.
+
+#include "../third_party/catch2/catch.hpp"
+#include "Sim.h"
+
+#include <algorithm>
+#include <cmath>
+#include <vector>
+
+using namespace desktopgrass;
+
+namespace {
+constexpr double Monitor1920 = 1920.0;
+constexpr double TwoPi = 6.28318530717958647692;
+
+Sim build_sim(uint64_t seed = CANONICAL_TEST_SEED) {
+    Sim sim = sim_init(seed, Monitor1920, DEFAULT_DENSITY);
+    sim.currentScene = Scene::Grass;
+    sim.entities.clear();
+    return sim;
+}
+
+int count_birds(const Sim& sim) {
+    return static_cast<int>(std::count_if(sim.entities.begin(), sim.entities.end(),
+        [](const Entity& e) { return e.kind == EntityKind::Bird; }));
+}
+
+std::vector<Entity> birds(const Sim& sim) {
+    std::vector<Entity> out;
+    for (const Entity& e : sim.entities) {
+        if (e.kind == EntityKind::Bird) out.push_back(e);
+    }
+    return out;
+}
+
+int prng_count(Prng& side, int minCount, int maxCount) {
+    const double draw = prng_uniform(side, static_cast<double>(minCount), static_cast<double>(maxCount + 1));
+    int count = static_cast<int>(std::floor(draw));
+    if (count < minCount) count = minCount;
+    if (count > maxCount) count = maxCount;
+    return count;
+}
+
+void reset_bird_stream_fresh(Sim& sim, uint64_t seed) {
+    prng_init(sim.birdFlybyPrng, seed ^ BIRD_FLYBY_PRNG_SALT);
+    sim.nextBirdFlybyAtTime = sim.globalTime;
+}
+
+void reset_bird_schedule(Sim& sim, uint64_t seed) {
+    prng_init(sim.birdFlybyPrng, seed ^ BIRD_FLYBY_PRNG_SALT);
+    sim.nextBirdFlybyAtTime = sim.globalTime + bird_flyby_sample_interval(sim.birdFlybyPrng);
+}
+
+uint64_t find_seed_for_flock_size(int size) {
+    for (uint64_t i = 1; i < 10000; ++i) {
+        Sim sim = build_sim(CANONICAL_TEST_SEED + i);
+        reset_bird_stream_fresh(sim, CANONICAL_TEST_SEED + i);
+        sim_spawn_bird_flyby(sim);
+        if (count_birds(sim) == size) return CANONICAL_TEST_SEED + i;
+    }
+    return CANONICAL_TEST_SEED;
+}
+
+uint64_t find_v_seed(int minSize) {
+    for (uint64_t i = 1; i < 10000; ++i) {
+        Sim sim = build_sim(CANONICAL_TEST_SEED + i);
+        reset_bird_stream_fresh(sim, CANONICAL_TEST_SEED + i);
+        sim_spawn_bird_flyby(sim);
+        auto flock = birds(sim);
+        if (static_cast<int>(flock.size()) >= minSize && flock[0].colorVariant == 0) {
+            return CANONICAL_TEST_SEED + i;
+        }
+    }
+    return CANONICAL_TEST_SEED;
+}
+} // namespace
+
+TEST_CASE("Bird flyby constants are pinned to spec values", "[bird][constants]") {
+    REQUIRE(BIRD_FLYBY_SPAWN_RATE_PER_HOUR == Approx(15.0));
+    REQUIRE(BIRD_FLOCK_SIZE_MIN == 3);
+    REQUIRE(BIRD_FLOCK_SIZE_MAX == 7);
+    REQUIRE(BIRD_FLOCK_FORMATION_SPACING == Approx(9.0));
+    REQUIRE(BIRD_FLOCK_V_ANGLE_DEG == Approx(22.0));
+    REQUIRE(BIRD_SPEED_MIN == Approx(65.0));
+    REQUIRE(BIRD_SPEED_MAX == Approx(95.0));
+    REQUIRE(BIRD_ALTITUDE_MIN == Approx(78.0));
+    REQUIRE(BIRD_ALTITUDE_MAX == Approx(96.0));
+    REQUIRE(BIRD_BODY_LENGTH == Approx(3.6));
+    REQUIRE(BIRD_WING_SPAN == Approx(5.0));
+    REQUIRE(BIRD_WING_FLAP_FREQ == Approx(7.0));
+    REQUIRE(BIRD_WING_FLAP_PHASE_JITTER == Approx(0.6));
+    REQUIRE(BIRD_BODY_COLOR == 0xFF1A1610u);
+    REQUIRE(BIRD_WING_OPEN_RATIO == Approx(1.0));
+    REQUIRE(BIRD_WING_FOLD_RATIO == Approx(0.30));
+    REQUIRE(BIRD_FADE_IN_FRAC == Approx(0.08));
+    REQUIRE(BIRD_FADE_OUT_FRAC == Approx(0.08));
+    REQUIRE(BIRD_DRIFT_AMP_Y == Approx(3.0));
+    REQUIRE(BIRD_DRIFT_FREQ_Y == Approx(0.8));
+    REQUIRE(BIRD_FLYBY_PRNG_SALT == 0xB12D1F1A1B12D1Aull);
+}
+
+TEST_CASE("Bird flyby PRNG salt is unique", "[bird][constants]") {
+    const uint64_t salts[] = {
+        REGROW_PRNG_SALT, FLOWER_PRNG_SALT, MUSHROOM_PRNG_SALT,
+        AMBIENT_GUST_PRNG_SALT, CACTUS_PRNG_SALT, TUMBLEWEED_PRNG_SALT,
+        CRITTER_PRNG_SALT, BUTTERFLY_PRNG_SALT, FIREFLY_PRNG_SALT,
+        SNOWFLAKE_PRNG_SALT, PINE_PRNG_SALT,
+    };
+    for (uint64_t salt : salts) {
+        REQUIRE(BIRD_FLYBY_PRNG_SALT != salt);
+    }
+}
+
+TEST_CASE("Bird flyby flock size stays in range over seeds", "[bird][spawn]") {
+    for (uint64_t i = 0; i < 256; ++i) {
+        const uint64_t seed = CANONICAL_TEST_SEED + i * 0x9E3779B97F4A7C15ull;
+        Sim sim = build_sim(seed);
+        reset_bird_stream_fresh(sim, seed);
+        sim_spawn_bird_flyby(sim);
+        REQUIRE(count_birds(sim) >= BIRD_FLOCK_SIZE_MIN);
+        REQUIRE(count_birds(sim) <= BIRD_FLOCK_SIZE_MAX);
+    }
+}
+
+TEST_CASE("Bird flyby leader altitude stays in range", "[bird][spawn]") {
+    for (uint64_t i = 0; i < 128; ++i) {
+        const uint64_t seed = CANONICAL_TEST_SEED + i;
+        Sim sim = build_sim(seed);
+        reset_bird_stream_fresh(sim, seed);
+        sim_spawn_bird_flyby(sim);
+        auto flock = birds(sim);
+        REQUIRE(!flock.empty());
+        REQUIRE(flock[0].altitudeAnchor >= BIRD_ALTITUDE_MIN);
+        REQUIRE(flock[0].altitudeAnchor <  BIRD_ALTITUDE_MAX);
+    }
+}
+
+TEST_CASE("Bird flyby leader speed stays in range", "[bird][spawn]") {
+    for (uint64_t i = 0; i < 128; ++i) {
+        const uint64_t seed = CANONICAL_TEST_SEED + i;
+        Sim sim = build_sim(seed);
+        reset_bird_stream_fresh(sim, seed);
+        sim_spawn_bird_flyby(sim);
+        auto flock = birds(sim);
+        REQUIRE(!flock.empty());
+        REQUIRE(flock[0].baseSpeed >= BIRD_SPEED_MIN);
+        REQUIRE(flock[0].baseSpeed <  BIRD_SPEED_MAX);
+        REQUIRE(std::abs(flock[0].vx) == Approx(flock[0].baseSpeed));
+    }
+}
+
+TEST_CASE("Bird flyby PRNG draw order matches side stream", "[bird][prng]") {
+    const uint64_t seed = 0xB17D5EED1234ull;
+    Sim sim = build_sim(seed);
+    reset_bird_stream_fresh(sim, seed);
+    Prng side;
+    prng_init(side, seed ^ BIRD_FLYBY_PRNG_SALT);
+
+    sim_spawn_bird_flyby(sim);
+    const int expectedCount = prng_count(side, BIRD_FLOCK_SIZE_MIN, BIRD_FLOCK_SIZE_MAX);
+    const uint64_t directionBit = prng_next_u64(side) & 1ull;
+    const double direction = directionBit != 0ull ? 1.0 : -1.0;
+    const double leaderAltitude = prng_uniform(side, BIRD_ALTITUDE_MIN, BIRD_ALTITUDE_MAX);
+    const double leaderSpeed = prng_uniform(side, BIRD_SPEED_MIN, BIRD_SPEED_MAX);
+    const uint64_t formationStyle = prng_next_u64(side) & 1ull;
+
+    std::vector<double> wingPhases;
+    std::vector<double> driftPhases;
+    for (int i = 0; i < expectedCount; ++i) {
+        wingPhases.push_back(prng_uniform(side, -BIRD_WING_FLAP_PHASE_JITTER, BIRD_WING_FLAP_PHASE_JITTER));
+        driftPhases.push_back(prng_uniform(side, 0.0, TwoPi));
+    }
+
+    auto flock = birds(sim);
+    REQUIRE(static_cast<int>(flock.size()) == expectedCount);
+    REQUIRE(sim.birdFlybyPrng.state == side.state);
+
+    const double spawnX = direction > 0.0 ? -50.0 : Monitor1920 + 50.0;
+    const double sinAngle = std::sin(BIRD_FLOCK_V_ANGLE_DEG * 3.14159265358979323846 / 180.0);
+    for (int i = 0; i < expectedCount; ++i) {
+        const double along = -static_cast<double>(i) * BIRD_FLOCK_FORMATION_SPACING;
+        double perpendicular = 0.0;
+        if (formationStyle == 0ull) {
+            const int armIndex = (i + 1) / 2;
+            const double sideSign = (i % 2) == 0 ? 1.0 : -1.0;
+            perpendicular = sideSign * static_cast<double>(armIndex) * BIRD_FLOCK_FORMATION_SPACING * sinAngle;
+        } else {
+            perpendicular = static_cast<double>(i) * BIRD_FLOCK_FORMATION_SPACING * sinAngle;
+        }
+
+        const Entity& e = flock[static_cast<std::size_t>(i)];
+        REQUIRE(e.x0 == Approx(spawnX + direction * along));
+        REQUIRE(e.x == Approx(e.x0));
+        REQUIRE(e.vx == Approx(direction * leaderSpeed));
+        REQUIRE(e.baseSpeed == Approx(leaderSpeed));
+        REQUIRE(e.altitudeAnchor == Approx(leaderAltitude - perpendicular));
+        REQUIRE(e.phaseX == Approx(wingPhases[static_cast<std::size_t>(i)]));
+        REQUIRE(e.phaseY == Approx(driftPhases[static_cast<std::size_t>(i)]));
+        REQUIRE(e.formationOffsetAlongFlight == Approx(along));
+        REQUIRE(e.formationOffsetPerpendicular == Approx(perpendicular));
+        REQUIRE(e.colorVariant == static_cast<uint8_t>(formationStyle));
+        REQUIRE(e.spawnTime == Approx(sim.globalTime));
+    }
+}
+
+TEST_CASE("Bird flybys are Grass scene only", "[bird][scene]") {
+    for (Scene scene : { Scene::Desert, Scene::Winter }) {
+        Sim sim = build_sim();
+        sim_set_scene(sim, scene);
+        sim.entities.clear();
+        reset_bird_schedule(sim, CANONICAL_TEST_SEED);
+        for (int i = 0; i < 8 * 3600; ++i) {
+            sim.globalTime += 1.0;
+            sim_tick_bird_flybys(sim);
+        }
+        REQUIRE(count_birds(sim) == 0);
+    }
+}
+
+TEST_CASE("Bird flyby Poisson spawns when schedule elapses", "[bird][time]") {
+    Sim sim = build_sim(0xDAD1B17Dull);
+    reset_bird_schedule(sim, 0xDAD1B17Dull);
+    int flybys = 0;
+    for (int i = 0; i < 10 * 3600; ++i) {
+        sim.globalTime += 1.0;
+        const int before = count_birds(sim);
+        sim_tick_bird_flybys(sim);
+        if (count_birds(sim) > before) {
+            ++flybys;
+            sim.entities.clear();
+        }
+    }
+
+    const double observedPerHour = static_cast<double>(flybys) / 10.0;
+    REQUIRE(observedPerHour == Approx(BIRD_FLYBY_SPAWN_RATE_PER_HOUR).epsilon(0.15));
+}
+
+TEST_CASE("Bird V formation geometry is locked", "[bird][formation]") {
+    const uint64_t seed = find_v_seed(5);
+    Sim sim = build_sim(seed);
+    reset_bird_stream_fresh(sim, seed);
+    sim_spawn_bird_flyby(sim);
+    auto flock = birds(sim);
+    REQUIRE(flock.size() >= 5);
+    REQUIRE(flock[0].colorVariant == 0);
+    REQUIRE(flock[0].formationOffsetAlongFlight == Approx(0.0));
+
+    for (std::size_t i = 1; i < flock.size(); ++i) {
+        REQUIRE(std::fabs(flock[0].formationOffsetAlongFlight)
+            < std::fabs(flock[i].formationOffsetAlongFlight));
+        REQUIRE(flock[i - 1].formationOffsetAlongFlight - flock[i].formationOffsetAlongFlight
+            == Approx(BIRD_FLOCK_FORMATION_SPACING));
+        const double expectedSign = (i % 2 == 0) ? 1.0 : -1.0;
+        REQUIRE((flock[i].formationOffsetPerpendicular > 0.0 ? 1.0 : -1.0) == expectedSign);
+    }
+}
+
+TEST_CASE("Bird wing flap scale stays in range", "[bird][wing]") {
+    for (int i = 0; i < 200; ++i) {
+        const double t = i * 0.137;
+        const double phase = -BIRD_WING_FLAP_PHASE_JITTER
+            + (2.0 * BIRD_WING_FLAP_PHASE_JITTER) * (static_cast<double>(i) / 199.0);
+        const double scale = bird_wing_scale(t, phase);
+        REQUIRE(scale >= BIRD_WING_FOLD_RATIO);
+        REQUIRE(scale <= BIRD_WING_OPEN_RATIO);
+    }
+}
+
+TEST_CASE("Bird wing phases decorrelate within a flock", "[bird][wing]") {
+    for (uint64_t i = 1; i < 10000; ++i) {
+        const uint64_t seed = CANONICAL_TEST_SEED + i;
+        Sim sim = build_sim(seed);
+        reset_bird_stream_fresh(sim, seed);
+        sim_spawn_bird_flyby(sim);
+        auto flock = birds(sim);
+        if (flock.size() != 5) continue;
+
+        std::vector<double> distinct;
+        for (const Entity& e : flock) {
+            const double scale = bird_wing_scale(1.234, e.phaseX);
+            bool seen = false;
+            for (double existing : distinct) {
+                if (std::fabs(existing - scale) < 1e-6) { seen = true; break; }
+            }
+            if (!seen) distinct.push_back(scale);
+        }
+        if (distinct.size() >= 3) {
+            REQUIRE(distinct.size() >= 3);
+            return;
+        }
+    }
+    FAIL("no decorrelated 5-bird flock found");
+}
+
+TEST_CASE("Birds despawn past opposite boundary", "[bird][despawn]") {
+    Sim sim = build_sim();
+    sim.currentScene = Scene::Desert;
+    sim.entities.clear();
+    Entity bird{};
+    bird.kind = EntityKind::Bird;
+    bird.x = Monitor1920 + 49.0;
+    bird.y = 10.0;
+    bird.vx = 20.0;
+    bird.altitudeAnchor = BIRD_ALTITUDE_MIN;
+    bird.lifetime = -1.0;
+    sim.entities.push_back(bird);
+
+    sim_tick_entities(sim, 0.2);
+
+    REQUIRE(count_birds(sim) == 0);
+}
+
+TEST_CASE("Birds do not interact with cuts or critters", "[bird][interaction]") {
+    Sim sim = build_sim();
+    sim.entities.clear();
+    Entity bird{};
+    bird.kind = EntityKind::Bird;
+    bird.x = 500.0;
+    bird.y = sim.windowHeight - STRIP_HEIGHT - 10.0;
+    bird.vx = BIRD_SPEED_MIN;
+    bird.baseSpeed = BIRD_SPEED_MIN;
+    bird.altitudeAnchor = BIRD_ALTITUDE_MIN;
+    bird.lifetime = -1.0;
+    sim.entities.push_back(bird);
+
+    Entity sheep{};
+    sheep.kind = EntityKind::Sheep;
+    sheep.x = bird.x;
+    sheep.y = sim.windowHeight - SHEEP_BODY_HEIGHT - SHEEP_LEG_LENGTH;
+    sheep.vx = SHEEP_WALK_SPEED_MIN;
+    sheep.state = SHEEP_STATE_WALKING;
+    sheep.stateTimer = 10.0;
+    sim.entities.push_back(sheep);
+
+    InputEvent ev{};
+    ev.type = EventType::Click;
+    ev.x = bird.x;
+    ev.y = bird.y;
+    sim_apply_click(sim, ev);
+
+    REQUIRE(sim.entities[0].kind == EntityKind::Bird);
+    REQUIRE(sim.entities[0].baseSpeed == Approx(BIRD_SPEED_MIN));
+    REQUIRE(sim.entities[1].state == SHEEP_STATE_WALKING);
+    for (const Blade& b : sim.blades) REQUIRE(b.cutAnimStart < 0.0);
+}
+
+TEST_CASE("Bird flyby Poisson inter-arrivals keep expected mean", "[bird][poisson]") {
+    const uint64_t seed = 0x510B17D00ull;
+    Sim sim = build_sim(seed);
+    reset_bird_schedule(sim, seed);
+
+    double prev = sim.globalTime;
+    double totalInterval = 0.0;
+    constexpr int Events = 100;
+    for (int i = 0; i < Events; ++i) {
+        sim.globalTime = sim.nextBirdFlybyAtTime;
+        totalInterval += sim.globalTime - prev;
+        prev = sim.globalTime;
+        sim_tick_bird_flybys(sim);
+        sim.entities.clear();
+    }
+
+    const double expectedMean = 3600.0 / BIRD_FLYBY_SPAWN_RATE_PER_HOUR;
+    REQUIRE((totalInterval / Events) == Approx(expectedMean).epsilon(0.20));
+}

src/modules/DesktopGrass/DesktopGrass.Native.Tests/src/blade_gen_tests.cpp

@@ -0,0 +1,153 @@
+// blade_gen_tests.cpp
+//
+// Snapshot + invariant tests for procedural blade generation (architecture.md §5).
+
+#include "../third_party/catch2/catch.hpp"
+#include "Sim.h"
+#include "snapshot_data.h"
+
+#include <cmath>
+#include <vector>
+
+using namespace desktopgrass;
+using namespace desktopgrass::test;
+
+namespace {
+
+void requireBladeEquals(const Blade& actual, const SnapshotBlade& expected, std::size_t index) {
+    INFO("blade index = " << index);
+    REQUIRE(actual.baseX           == Approx(expected.baseX          ).margin(1e-12));
+    REQUIRE(actual.height          == Approx(expected.height         ).margin(1e-12));
+    REQUIRE(actual.thickness       == Approx(expected.thickness      ).margin(1e-12));
+    REQUIRE(actual.hue             == expected.hue);
+    REQUIRE(actual.swayPhaseOffset == Approx(expected.sway          ).margin(1e-12));
+    REQUIRE(actual.stiffness       == Approx(expected.stiffness     ).margin(1e-12));
+    REQUIRE(actual.isFlower             == expected.isFlower);
+    REQUIRE(actual.flowerHeadColorIdx   == expected.flowerHeadColorIdx);
+    REQUIRE(actual.flowerHeadRadius     == Approx(expected.flowerHeadRadius).margin(1e-12));
+    REQUIRE(actual.heightBonus          == Approx(expected.heightBonus    ).margin(1e-12));
+}
+
+} // anonymous
+
+TEST_CASE("blade generation matches the canonical snapshot", "[blade-gen][snapshot]") {
+    std::vector<Blade> blades;
+    generate_blades(CANONICAL_TEST_SEED, 1920.0, 1.0, blades);
+
+    REQUIRE(blades.size() == CANONICAL_BLADE_COUNT);
+
+    SECTION("first 10 blades match") {
+        for (std::size_t i = 0; i < 10; ++i) {
+            requireBladeEquals(blades[i], CANONICAL_FIRST_10[i], i);
+        }
+    }
+
+    SECTION("last 10 blades match") {
+        const std::size_t start = blades.size() - 10;
+        for (std::size_t i = 0; i < 10; ++i) {
+            requireBladeEquals(blades[start + i], CANONICAL_LAST_10[i], start + i);
+        }
+    }
+}
+
+TEST_CASE("blade fields stay within spec ranges", "[blade-gen]") {
+    std::vector<Blade> blades;
+    generate_blades(CANONICAL_TEST_SEED, 1920.0, 1.0, blades);
+
+    constexpr double TWO_PI = 6.283185307179586;
+    for (std::size_t i = 0; i < blades.size(); ++i) {
+        const Blade& b = blades[i];
+        INFO("blade index = " << i);
+        REQUIRE(b.baseX           >= 0.0);
+        REQUIRE(b.baseX           <  1920.0);
+        REQUIRE(b.height          >= BLADE_HEIGHT_MIN);
+        REQUIRE(b.height          <  BLADE_HEIGHT_MAX);
+        REQUIRE(b.thickness       >= BLADE_THICKNESS_MIN);
+        REQUIRE(b.thickness       <  BLADE_THICKNESS_MAX);
+        REQUIRE(b.hue             <  PALETTE_SIZE);
+        REQUIRE(b.swayPhaseOffset >= 0.0);
+        REQUIRE(b.swayPhaseOffset <  TWO_PI);
+        REQUIRE(b.stiffness       >= STIFFNESS_MIN);
+        REQUIRE(b.stiffness       <  STIFFNESS_MAX);
+        REQUIRE(b.cutHeight        == Approx(1.0));
+        REQUIRE(b.gustVelocity     == Approx(0.0));
+        REQUIRE(b.cutAnimStart     == Approx(-1.0));
+        REQUIRE(b.cutInitialHeight == Approx(1.0));
+        if (b.isFlower) {
+            REQUIRE(b.flowerHeadColorIdx < FLOWER_PALETTE_SIZE);
+            REQUIRE(b.flowerHeadRadius >= FLOWER_HEAD_RADIUS_MIN);
+            REQUIRE(b.flowerHeadRadius <  FLOWER_HEAD_RADIUS_MAX);
+            REQUIRE(b.heightBonus      >= FLOWER_HEIGHT_BONUS_MIN);
+            REQUIRE(b.heightBonus      <  FLOWER_HEIGHT_BONUS_MAX);
+        } else {
+            REQUIRE(b.flowerHeadColorIdx == 0);
+            REQUIRE(b.flowerHeadRadius   == Approx(0.0));
+            REQUIRE(b.heightBonus        == Approx(1.0));
+        }
+    }
+}
+
+TEST_CASE("flower count is near configured probability and ordinary blades use defaults", "[blade-gen][flowers]") {
+    std::vector<Blade> blades;
+    generate_blades(CANONICAL_TEST_SEED, 1920.0, 1.0, blades);
+    REQUIRE(blades.size() > 100);
+
+    std::size_t flowerCount = 0;
+    for (const Blade& b : blades) {
+        if (b.isFlower) {
+            ++flowerCount;
+        } else {
+            REQUIRE(b.flowerHeadColorIdx == 0);
+            REQUIRE(b.flowerHeadRadius   == Approx(0.0));
+            REQUIRE(b.heightBonus        == Approx(1.0));
+        }
+    }
+
+    const double n  = static_cast<double>(blades.size());
+    const double p  = FLOWER_PROBABILITY;
+    const double mu = n * p;
+    const double sd = std::sqrt(n * p * (1.0 - p));
+    REQUIRE(flowerCount >= static_cast<std::size_t>(std::floor(mu - 3.0 * sd)));
+    REQUIRE(flowerCount <= static_cast<std::size_t>(std::ceil(mu + 3.0 * sd)));
+}
+
+TEST_CASE("blade baseX is strictly increasing", "[blade-gen]") {
+    std::vector<Blade> blades;
+    generate_blades(CANONICAL_TEST_SEED, 1920.0, 1.0, blades);
+    REQUIRE(blades.size() > 0);
+    for (std::size_t i = 1; i < blades.size(); ++i) {
+        INFO("between " << (i-1) << " and " << i);
+        REQUIRE(blades[i].baseX > blades[i-1].baseX);
+    }
+}
+
+TEST_CASE("blade generation is deterministic across repeat runs", "[blade-gen]") {
+    std::vector<Blade> a, b;
+    generate_blades(CANONICAL_TEST_SEED, 1920.0, 1.0, a);
+    generate_blades(CANONICAL_TEST_SEED, 1920.0, 1.0, b);
+    REQUIRE(a.size() == b.size());
+    for (std::size_t i = 0; i < a.size(); ++i) {
+        REQUIRE(a[i].baseX           == b[i].baseX);
+        REQUIRE(a[i].height          == b[i].height);
+        REQUIRE(a[i].thickness       == b[i].thickness);
+        REQUIRE(a[i].hue             == b[i].hue);
+        REQUIRE(a[i].swayPhaseOffset == b[i].swayPhaseOffset);
+        REQUIRE(a[i].stiffness       == b[i].stiffness);
+    }
+}
+
+TEST_CASE("density scales blade count roughly linearly", "[blade-gen]") {
+    std::vector<Blade> low, high;
+    generate_blades(CANONICAL_TEST_SEED, 1920.0, 0.5, low);
+    generate_blades(CANONICAL_TEST_SEED, 1920.0, 2.0, high);
+    REQUIRE(low.size()  > 0);
+    REQUIRE(high.size() > low.size() * 3);  // 4x density ≈ 4x blades, allow slack
+}
+
+TEST_CASE("blade count near plan default at density 1.25", "[blade-gen]") {
+    std::vector<Blade> blades;
+    generate_blades(CANONICAL_TEST_SEED, 1920.0, 1.25, blades);
+    // Plan target: ~400 blades per 1920 px at the v1 default density of 1.25.
+    REQUIRE(blades.size() >= 350);
+    REQUIRE(blades.size() <= 450);
+}

src/modules/DesktopGrass/DesktopGrass.Native.Tests/src/bunny_tests.cpp

@@ -0,0 +1,311 @@
+// bunny_tests.cpp
+//
+// §18 Bunny critter tests. Mirrors Win2D BunnyTests.cs.
+
+#include "../third_party/catch2/catch.hpp"
+#include "Sim.h"
+
+#include <algorithm>
+#include <cmath>
+#include <cwchar>
+
+using namespace desktopgrass;
+
+namespace {
+
+constexpr double Monitor1920 = 1920.0;
+
+int count_kind(const Sim& sim, EntityKind kind) {
+    return static_cast<int>(std::count_if(sim.entities.begin(), sim.entities.end(),
+        [kind](const Entity& e) { return e.kind == kind; }));
+}
+
+Sim build_grass_sim(uint64_t seed = CANONICAL_TEST_SEED) {
+    Sim sim = sim_init(seed, Monitor1920, DEFAULT_DENSITY);
+    sim_set_scene(sim, Scene::Grass);
+    sim_set_critter(sim, CritterKind::Bunny);
+    return sim;
+}
+
+Entity bunny_entity(double x = 500.0, double vx = BUNNY_HOP_SPEED_MIN) {
+    Entity e{};
+    e.kind = EntityKind::Bunny;
+    e.size = BUNNY_BODY_RADIUS;
+    e.x = x;
+    e.y = STRIP_HEIGHT + HEADROOM - BUNNY_BODY_HEIGHT - BUNNY_LEG_LENGTH;
+    e.vx = vx;
+    e.rotationSpeed = std::abs(vx);
+    e.lifetime = -1.0;
+    e.state = BUNNY_STATE_HOPPING;
+    e.stateTimer = BUNNY_HOP_DURATION;
+    return e;
+}
+
+InputEvent click_event(double x, double y) {
+    InputEvent ev{};
+    ev.type = EventType::Click;
+    ev.x = x;
+    ev.y = y;
+    ev.time = 0.0;
+    return ev;
+}
+
+int prng_count(Prng& side, int minCount, int maxCount) {
+    const double draw = prng_uniform(side, static_cast<double>(minCount), static_cast<double>(maxCount + 1));
+    int count = static_cast<int>(std::floor(draw));
+    if (count < minCount) count = minCount;
+    if (count > maxCount) count = maxCount;
+    return count;
+}
+
+void advance_sheep(Prng& side, int count) {
+    for (int i = 0; i < count; ++i) {
+        const double margin = SHEEP_BODY_RADIUS + 8.0;
+        (void)prng_uniform(side, margin, Monitor1920 - margin);
+        (void)prng_uniform(side, SHEEP_WALK_SPEED_MIN, SHEEP_WALK_SPEED_MAX);
+        (void)prng_uniform(side, 0.0, 1.0);
+        (void)prng_next_u32(side);
+        (void)prng_uniform(side, SHEEP_WALK_DURATION_MIN, SHEEP_WALK_DURATION_MAX);
+        (void)prng_index(side, static_cast<uint32_t>(sizeof(SHEEP_NAME_POOL) / sizeof(SHEEP_NAME_POOL[0])));
+    }
+}
+
+void advance_cats(Prng& side, int count) {
+    for (int i = 0; i < count; ++i) {
+        const double margin = CAT_BODY_RADIUS + 8.0;
+        (void)prng_uniform(side, margin, Monitor1920 - margin);
+        (void)prng_uniform(side, CAT_WALK_SPEED_MIN, CAT_WALK_SPEED_MAX);
+        (void)prng_uniform(side, 0.0, 1.0);
+        (void)prng_next_u32(side);
+        (void)prng_uniform(side, CAT_WALK_DURATION_MIN, CAT_WALK_DURATION_MAX);
+        (void)prng_index(side, static_cast<uint32_t>(sizeof(CAT_NAME_POOL) / sizeof(CAT_NAME_POOL[0])));
+        (void)prng_index(side, static_cast<uint32_t>(CAT_COAT_VARIANT_COUNT));
+    }
+}
+
+bool bunny_name_in_pool(const Entity& e) {
+    if (e.nameIndex >= sizeof(BUNNY_NAME_POOL) / sizeof(BUNNY_NAME_POOL[0])) return false;
+    const wchar_t* name = BUNNY_NAME_POOL[e.nameIndex];
+    for (const wchar_t* candidate : BUNNY_NAME_POOL) {
+        if (std::wcscmp(name, candidate) == 0) return true;
+    }
+    return false;
+}
+
+} // namespace
+
+TEST_CASE("Bunny constants are pinned to spec values", "[bunny][constants]") {
+    REQUIRE(BUNNY_COUNT_MIN == 1);
+    REQUIRE(BUNNY_COUNT_MAX == 2);
+    REQUIRE(BUNNY_HOP_SPEED_MIN == Approx(22.0));
+    REQUIRE(BUNNY_HOP_SPEED_MAX == Approx(38.0));
+    REQUIRE(BUNNY_BODY_RADIUS == Approx(8.0));
+    REQUIRE(BUNNY_BODY_HEIGHT == Approx(6.5));
+    REQUIRE(BUNNY_HEAD_RADIUS == Approx(4.2));
+    REQUIRE(BUNNY_EAR_HEIGHT == Approx(9.0));
+    REQUIRE(BUNNY_EAR_WIDTH == Approx(2.2));
+    REQUIRE(BUNNY_EAR_SPACING == Approx(3.0));
+    REQUIRE(BUNNY_LEG_LENGTH == Approx(4.0));
+    REQUIRE(BUNNY_TAIL_RADIUS == Approx(2.4));
+    REQUIRE(BUNNY_BODY_COLOR == 0xFF8A6A4Au);
+    REQUIRE(BUNNY_BELLY_COLOR == 0xFFC4A98Du);
+    REQUIRE(BUNNY_EAR_COLOR == 0xFF8A6A4Au);
+    REQUIRE(BUNNY_EAR_INNER_COLOR == 0xFFD9A0A0u);
+    REQUIRE(BUNNY_TAIL_COLOR == 0xFFF7F4EBu);
+    REQUIRE(BUNNY_EYE_COLOR == 0xFF1A1208u);
+    REQUIRE(BUNNY_NOSE_COLOR == 0xFF8A4040u);
+    REQUIRE(BUNNY_STATE_HOPPING == 0);
+    REQUIRE(BUNNY_STATE_GRAZING == 1);
+    REQUIRE(BUNNY_STATE_IDLE == 2);
+    REQUIRE(BUNNY_STATE_SLEEPING == 3);
+    REQUIRE(BUNNY_STATE_STARTLED == 4);
+    REQUIRE(BUNNY_HOP_DURATION == Approx(0.40));
+    REQUIRE(BUNNY_HOP_HEIGHT == Approx(8.0));
+    REQUIRE(BUNNY_HOP_GAP_MIN == Approx(0.05));
+    REQUIRE(BUNNY_HOP_GAP_MAX == Approx(0.20));
+    REQUIRE(BUNNY_GRAZE_DURATION_MIN == Approx(2.5));
+    REQUIRE(BUNNY_GRAZE_DURATION_MAX == Approx(4.5));
+    REQUIRE(BUNNY_IDLE_DURATION_MIN == Approx(2.0));
+    REQUIRE(BUNNY_IDLE_DURATION_MAX == Approx(4.0));
+    REQUIRE(BUNNY_SLEEP_DURATION_MIN == Approx(6.0));
+    REQUIRE(BUNNY_SLEEP_DURATION_MAX == Approx(12.0));
+    REQUIRE(BUNNY_GRAZE_PROBABILITY == Approx(0.55));
+    REQUIRE(BUNNY_IDLE_PROBABILITY == Approx(0.30));
+    REQUIRE(BUNNY_SLEEP_PROB == Approx(0.05));
+    REQUIRE(BUNNY_STARTLE_RADIUS == Approx(90.0));
+    REQUIRE(BUNNY_STARTLE_BOOST == Approx(2.0));
+    REQUIRE(BUNNY_STARTLE_HOP_HEIGHT == Approx(14.0));
+    REQUIRE(BUNNY_STARTLE_DURATION == Approx(3.0));
+    REQUIRE(BUNNY_NOSE_TWITCH_FREQ == Approx(6.0));
+    REQUIRE(BUNNY_NOSE_TWITCH_AMP == Approx(0.5));
+    REQUIRE(BUNNY_EAR_WIGGLE_FREQ == Approx(1.2));
+    REQUIRE(BUNNY_EAR_WIGGLE_AMP == Approx(0.20));
+    REQUIRE(BUNNY_ZZZ_CYCLE_SEC == Approx(SHEEP_ZZZ_CYCLE_SEC));
+    REQUIRE(BUNNY_ZZZ_RISE == Approx(SHEEP_ZZZ_RISE * 0.7));
+    REQUIRE(BUNNY_ZZZ_SIZE_START == Approx(SHEEP_ZZZ_SIZE_START * 0.7));
+    REQUIRE(BUNNY_ZZZ_SIZE_END == Approx(SHEEP_ZZZ_SIZE_END * 0.7));
+    REQUIRE(sizeof(BUNNY_NAME_POOL) / sizeof(BUNNY_NAME_POOL[0]) == 12);
+    REQUIRE(std::wcscmp(BUNNY_NAME_POOL[0], L"Clover") == 0);
+    REQUIRE(std::wcscmp(BUNNY_NAME_POOL[11], L"Snowdrop") == 0);
+}
+
+TEST_CASE("Grass generation produces bunny count in range", "[bunny][gen]") {
+    for (uint64_t i = 0; i < 128; ++i) {
+        const uint64_t seed = CANONICAL_TEST_SEED + i * 0x9E3779B97F4A7C15ull;
+        Sim sim = build_grass_sim(seed);
+        const int bunnies = count_kind(sim, EntityKind::Bunny);
+        REQUIRE(bunnies >= BUNNY_COUNT_MIN);
+        REQUIRE(bunnies <= BUNNY_COUNT_MAX);
+    }
+}
+
+TEST_CASE("Bunnies are Grass scene only", "[bunny][scene]") {
+    Sim sim = sim_init(CANONICAL_TEST_SEED, Monitor1920, DEFAULT_DENSITY);
+    sim_set_scene(sim, Scene::Desert);
+    REQUIRE(count_kind(sim, EntityKind::Bunny) == 0);
+    sim_set_scene(sim, Scene::Winter);
+    REQUIRE(count_kind(sim, EntityKind::Bunny) == 0);
+    sim_set_critter(sim, CritterKind::Bunny);
+    REQUIRE(count_kind(sim, EntityKind::Bunny) == 0);
+}
+
+TEST_CASE("Generated bunnies have speed range", "[bunny][gen]") {
+    Sim sim = build_grass_sim();
+    for (const Entity& e : sim.entities) {
+        if (e.kind != EntityKind::Bunny) continue;
+        REQUIRE(std::abs(e.vx) >= BUNNY_HOP_SPEED_MIN);
+        REQUIRE(std::abs(e.vx) < BUNNY_HOP_SPEED_MAX);
+        REQUIRE(e.rotationSpeed == Approx(std::abs(e.vx)));
+    }
+}
+
+TEST_CASE("Generated bunnies have names in pool", "[bunny][gen]") {
+    Sim sim = build_grass_sim();
+    for (const Entity& e : sim.entities) {
+        if (e.kind != EntityKind::Bunny) continue;
+        REQUIRE(bunny_name_in_pool(e));
+    }
+}
+
+TEST_CASE("Bunny PRNG draw order follows sheep and cats", "[bunny][prng]") {
+    Prng side;
+    prng_init(side, CANONICAL_TEST_SEED ^ CRITTER_PRNG_SALT);
+
+    Sim sim = build_grass_sim();
+
+    const int sheepCount = prng_count(side, SHEEP_COUNT_MIN, SHEEP_COUNT_MAX);
+    advance_sheep(side, sheepCount);
+    const int catCount = prng_count(side, CAT_COUNT_MIN, CAT_COUNT_MAX);
+    advance_cats(side, catCount);
+    const int bunnyCount = prng_count(side, BUNNY_COUNT_MIN, BUNNY_COUNT_MAX);
+    REQUIRE(count_kind(sim, EntityKind::Bunny) == bunnyCount);
+
+    int seen = 0;
+    for (const Entity& e : sim.entities) {
+        if (e.kind != EntityKind::Bunny) continue;
+        const double margin = BUNNY_BODY_RADIUS + 8.0;
+        const double xFrac = prng_uniform(side, 0.0, 1.0);
+        const double expectedX = margin + xFrac * (Monitor1920 - 2.0 * margin);
+        const uint64_t vxSign = prng_next_u64(side) & 1ull;
+        const double expectedDir = vxSign != 0ull ? 1.0 : -1.0;
+        const double expectedSpeed = prng_uniform(side, BUNNY_HOP_SPEED_MIN, BUNNY_HOP_SPEED_MAX);
+        const uint8_t expectedName = static_cast<uint8_t>(prng_index(side,
+            static_cast<uint32_t>(sizeof(BUNNY_NAME_POOL) / sizeof(BUNNY_NAME_POOL[0]))));
+        REQUIRE(e.x == Approx(expectedX));
+        REQUIRE(e.vx == Approx(expectedDir * expectedSpeed));
+        REQUIRE(e.nameIndex == expectedName);
+        ++seen;
+    }
+    REQUIRE(seen == bunnyCount);
+}
+
+TEST_CASE("Bunny edge bounce flips direction", "[bunny][motion]") {
+    Sim sim = sim_init(CANONICAL_TEST_SEED, Monitor1920, DEFAULT_DENSITY);
+    sim.currentScene = Scene::Desert;
+    sim.entities.clear();
+    Entity e = bunny_entity(Monitor1920 - (BUNNY_BODY_RADIUS + 2.0) + 0.1, BUNNY_HOP_SPEED_MIN);
+    e.stateTimer = 10.0;
+    sim.entities.push_back(e);
+
+    sim_tick_entities(sim, 0.016);
+
+    REQUIRE(sim.entities.front().vx < 0.0);
+}
+
+TEST_CASE("Bunny startle radius hops away and outside click does nothing", "[bunny][click]") {
+    Sim sim = sim_init(CANONICAL_TEST_SEED, Monitor1920, DEFAULT_DENSITY);
+    sim.entities.clear();
+    Entity e = bunny_entity(500.0, -BUNNY_HOP_SPEED_MIN);
+    e.state = BUNNY_STATE_IDLE;
+    e.stateTimer = 3.0;
+    sim.entities.push_back(e);
+
+    sim_apply_click(sim, click_event(500.0 - 20.0, e.y));
+    REQUIRE(sim.entities.front().state == BUNNY_STATE_STARTLED);
+    REQUIRE(sim.entities.front().vx > 0.0);
+    REQUIRE(sim.entities.front().stateTimer == Approx(BUNNY_STARTLE_DURATION));
+
+    Entity after = sim.entities.front();
+    const double vxBefore = after.vx;
+    const uint8_t stateBefore = after.state;
+    sim_apply_click(sim, click_event(after.x + BUNNY_STARTLE_RADIUS + 10.0, after.y));
+    REQUIRE(sim.entities.front().state == stateBefore);
+    REQUIRE(sim.entities.front().vx == Approx(vxBefore));
+}
+
+TEST_CASE("Bunny wakes from sleep on startle", "[bunny][click]") {
+    Sim sim = sim_init(CANONICAL_TEST_SEED, Monitor1920, DEFAULT_DENSITY);
+    sim.entities.clear();
+    Entity e = bunny_entity(500.0, BUNNY_HOP_SPEED_MIN);
+    e.state = BUNNY_STATE_SLEEPING;
+    e.stateTimer = 10.0;
+    sim.entities.push_back(e);
+
+    sim_apply_click(sim, click_event(e.x + 10.0, e.y));
+
+    REQUIRE(sim.entities.front().state == BUNNY_STATE_STARTLED);
+    REQUIRE(sim.entities.front().state != BUNNY_STATE_SLEEPING);
+    REQUIRE(sim.entities.front().vx < 0.0);
+}
+
+TEST_CASE("Bunny hop arc is bounded", "[bunny][motion]") {
+    REQUIRE(bunny_hop_y_offset(0.0, false) == Approx(0.0));
+    REQUIRE(bunny_hop_y_offset(BUNNY_HOP_DURATION, false) == Approx(0.0).margin(1e-12));
+    const double peak = bunny_hop_y_offset(BUNNY_HOP_DURATION * 0.5, false);
+    REQUIRE(peak > 0.0);
+    REQUIRE(peak <= BUNNY_HOP_HEIGHT);
+}
+
+TEST_CASE("Bunny state transition probabilities are stable", "[bunny][state]") {
+    Prng p;
+    prng_init(p, CANONICAL_TEST_SEED ^ CRITTER_PRNG_SALT);
+    constexpr int N = 10000;
+    int graze = 0;
+    int idle = 0;
+    int sleep = 0;
+    for (int i = 0; i < N; ++i) {
+        const uint8_t state = bunny_choose_rest_state(p);
+        if (state == BUNNY_STATE_GRAZING) ++graze;
+        else if (state == BUNNY_STATE_IDLE) ++idle;
+        else if (state == BUNNY_STATE_SLEEPING) ++sleep;
+    }
+
+    const double sleepProb = BUNNY_SLEEP_PROB;
+    const double activeWeight = BUNNY_GRAZE_PROBABILITY + BUNNY_IDLE_PROBABILITY;
+    const double expectedGraze = (1.0 - sleepProb) * BUNNY_GRAZE_PROBABILITY / activeWeight;
+    const double expectedIdle = (1.0 - sleepProb) * BUNNY_IDLE_PROBABILITY / activeWeight;
+    REQUIRE(static_cast<double>(sleep) / N == Approx(sleepProb).margin(0.02));
+    REQUIRE(static_cast<double>(graze) / N == Approx(expectedGraze).margin(0.02));
+    REQUIRE(static_cast<double>(idle) / N == Approx(expectedIdle).margin(0.02));
+}
+
+TEST_CASE("Bunny sleep probability is stable", "[bunny][state]") {
+    constexpr int N = 20000;
+    Prng p;
+    prng_init(p, CANONICAL_TEST_SEED ^ 0x1234ull);
+    int sleep = 0;
+    for (int i = 0; i < N; ++i) {
+        if (bunny_choose_rest_state(p) == BUNNY_STATE_SLEEPING) ++sleep;
+    }
+    REQUIRE(static_cast<double>(sleep) / N == Approx(BUNNY_SLEEP_PROB).margin(0.02));
+}

src/modules/DesktopGrass/DesktopGrass.Native.Tests/src/butterfly_tests.cpp

@@ -0,0 +1,180 @@
+// butterfly_tests.cpp - §17.6 ambient Butterfly tests.
+
+#include "../third_party/catch2/catch.hpp"
+#include "Sim.h"
+
+#include <algorithm>
+#include <cmath>
+
+using namespace desktopgrass;
+
+namespace {
+constexpr double Monitor1920 = 1920.0;
+
+int count_kind(const Sim& sim, EntityKind kind) {
+    return static_cast<int>(std::count_if(sim.entities.begin(), sim.entities.end(),
+        [kind](const Entity& e) { return e.kind == kind; }));
+}
+
+Sim build_grass_sim(uint64_t seed = CANONICAL_TEST_SEED) {
+    Sim sim = sim_init(seed, Monitor1920, DEFAULT_DENSITY);
+    sim_set_scene(sim, Scene::Grass);
+    return sim;
+}
+
+int prng_count(Prng& side, int minCount, int maxCount) {
+    const double draw = prng_uniform(side, static_cast<double>(minCount), static_cast<double>(maxCount + 1));
+    int count = static_cast<int>(std::floor(draw));
+    if (count < minCount) count = minCount;
+    if (count > maxCount) count = maxCount;
+    return count;
+}
+
+const Entity* first_butterfly(const Sim& sim) {
+    for (const Entity& e : sim.entities) if (e.kind == EntityKind::Butterfly) return &e;
+    return nullptr;
+}
+} // namespace
+
+TEST_CASE("Butterfly constants are pinned to spec values", "[butterfly][constants]") {
+    REQUIRE(BUTTERFLY_COUNT_MIN == 2);
+    REQUIRE(BUTTERFLY_COUNT_MAX == 4);
+    REQUIRE(BUTTERFLY_SPEED_MIN == Approx(18.0));
+    REQUIRE(BUTTERFLY_SPEED_MAX == Approx(32.0));
+    REQUIRE(BUTTERFLY_BODY_LENGTH == Approx(2.4));
+    REQUIRE(BUTTERFLY_WING_RADIUS == Approx(3.5));
+    REQUIRE(BUTTERFLY_WING_OFFSET == Approx(2.2));
+    REQUIRE(BUTTERFLY_FLUTTER_FREQ == Approx(16.0));
+    REQUIRE(BUTTERFLY_FLUTTER_MIN_SCALE == Approx(0.20));
+    REQUIRE(BUTTERFLY_MEANDER_FREQ_Y == Approx(0.8));
+    REQUIRE(BUTTERFLY_MEANDER_AMP_Y == Approx(16.0));
+    REQUIRE(BUTTERFLY_MEANDER_FREQ_X == Approx(0.5));
+    REQUIRE(BUTTERFLY_MEANDER_AMP_X == Approx(0.4));
+    REQUIRE(BUTTERFLY_ALTITUDE_MIN == Approx(18.0));
+    REQUIRE(BUTTERFLY_ALTITUDE_MAX == Approx(70.0));
+    REQUIRE(BUTTERFLY_BODY_COLOR == 0xFF2A2018u);
+    REQUIRE(BUTTERFLY_COLOR_COUNT == 5);
+    REQUIRE(BUTTERFLY_PRNG_SALT == 0xB07DEF1E0001ull);
+}
+
+TEST_CASE("Grass generation produces butterfly count in range", "[butterfly][gen]") {
+    for (uint64_t i = 0; i < 128; ++i) {
+        const uint64_t seed = CANONICAL_TEST_SEED + i * 0x9E3779B97F4A7C15ull;
+        Sim sim = build_grass_sim(seed);
+        REQUIRE(count_kind(sim, EntityKind::Butterfly) >= BUTTERFLY_COUNT_MIN);
+        REQUIRE(count_kind(sim, EntityKind::Butterfly) <= BUTTERFLY_COUNT_MAX);
+    }
+}
+
+TEST_CASE("Butterflies are Grass scene only", "[butterfly][scene]") {
+    Sim sim = sim_init(CANONICAL_TEST_SEED, Monitor1920, DEFAULT_DENSITY);
+    sim_set_scene(sim, Scene::Desert);
+    REQUIRE(count_kind(sim, EntityKind::Butterfly) == 0);
+    sim_set_scene(sim, Scene::Winter);
+    REQUIRE(count_kind(sim, EntityKind::Butterfly) == 0);
+}
+
+TEST_CASE("Generated butterflies have speed altitude and color ranges", "[butterfly][gen]") {
+    Sim sim = build_grass_sim();
+    for (const Entity& e : sim.entities) {
+        if (e.kind != EntityKind::Butterfly) continue;
+        REQUIRE(e.baseSpeed >= BUTTERFLY_SPEED_MIN);
+        REQUIRE(e.baseSpeed <  BUTTERFLY_SPEED_MAX);
+        REQUIRE(e.altitudeAnchor >= BUTTERFLY_ALTITUDE_MIN);
+        REQUIRE(e.altitudeAnchor <  BUTTERFLY_ALTITUDE_MAX);
+        REQUIRE(e.colorVariant < BUTTERFLY_COLOR_COUNT);
+    }
+}
+
+TEST_CASE("Butterfly PRNG draw order matches side stream", "[butterfly][prng]") {
+    Prng side;
+    prng_init(side, CANONICAL_TEST_SEED ^ BUTTERFLY_PRNG_SALT);
+    Sim sim = build_grass_sim();
+
+    const int expectedCount = prng_count(side, BUTTERFLY_COUNT_MIN, BUTTERFLY_COUNT_MAX);
+    REQUIRE(count_kind(sim, EntityKind::Butterfly) == expectedCount);
+
+    int seen = 0;
+    for (const Entity& e : sim.entities) {
+        if (e.kind != EntityKind::Butterfly) continue;
+        const double xFrac = prng_uniform(side, 0.0, 1.0);
+        const double yFrac = prng_uniform(side, 0.0, 1.0);
+        const uint64_t vxSign = prng_next_u64(side) & 1ull;
+        const double expectedDir = vxSign != 0ull ? 1.0 : -1.0;
+        const double expectedSpeed = prng_uniform(side, BUTTERFLY_SPEED_MIN, BUTTERFLY_SPEED_MAX);
+        const uint8_t expectedColor = static_cast<uint8_t>(prng_index(side, static_cast<uint32_t>(BUTTERFLY_COLOR_COUNT)));
+        const double expectedPhaseY = prng_uniform(side, 0.0, 2.0 * 3.14159265358979323846);
+        const double expectedPhaseX = prng_uniform(side, 0.0, 2.0 * 3.14159265358979323846);
+        const double expectedAltitude = BUTTERFLY_ALTITUDE_MIN + yFrac * (BUTTERFLY_ALTITUDE_MAX - BUTTERFLY_ALTITUDE_MIN);
+        const double expectedVx = expectedDir * expectedSpeed * (1.0 + BUTTERFLY_MEANDER_AMP_X * std::sin(expectedPhaseX));
+
+        REQUIRE(e.x == Approx(xFrac * Monitor1920));
+        REQUIRE(e.altitudeAnchor == Approx(expectedAltitude));
+        REQUIRE(e.baseSpeed == Approx(expectedSpeed));
+        REQUIRE(e.vx == Approx(expectedVx));
+        REQUIRE(e.colorVariant == expectedColor);
+        REQUIRE(e.phaseY == Approx(expectedPhaseY));
+        REQUIRE(e.phaseX == Approx(expectedPhaseX));
+        ++seen;
+    }
+    REQUIRE(seen == expectedCount);
+}
+
+TEST_CASE("Butterfly edge wrap preserves altitude anchor", "[butterfly][motion]") {
+    Sim sim = build_grass_sim();
+    auto it = std::find_if(sim.entities.begin(), sim.entities.end(), [](const Entity& e) { return e.kind == EntityKind::Butterfly; });
+    REQUIRE(it != sim.entities.end());
+    const double margin = BUTTERFLY_WING_OFFSET + BUTTERFLY_WING_RADIUS;
+    it->x = Monitor1920 + margin + 1.0;
+    it->vx = std::abs(it->vx);
+    const double altitude = it->altitudeAnchor;
+    sim.currentScene = Scene::Desert;
+
+    sim_tick_entities(sim, 0.016);
+
+    REQUIRE(it->x == Approx(-margin));
+    REQUIRE(it->altitudeAnchor == Approx(altitude));
+}
+
+TEST_CASE("Butterflies do not interact with cuts or pets", "[butterfly][interaction]") {
+    Sim sim = sim_init(CANONICAL_TEST_SEED, Monitor1920, DEFAULT_DENSITY);
+    sim.entities.clear();
+    Entity butterfly{};
+    butterfly.kind = EntityKind::Butterfly;
+    butterfly.x = 500.0;
+    butterfly.y = sim.windowHeight - STRIP_HEIGHT - 5.0;
+    butterfly.vx = BUTTERFLY_SPEED_MIN;
+    butterfly.baseSpeed = BUTTERFLY_SPEED_MIN;
+    butterfly.altitudeAnchor = BUTTERFLY_ALTITUDE_MIN;
+    butterfly.lifetime = -1.0;
+    sim.entities.push_back(butterfly);
+    Entity sheep{};
+    sheep.kind = EntityKind::Sheep;
+    sheep.x = butterfly.x;
+    sheep.y = sim.windowHeight - SHEEP_BODY_HEIGHT - SHEEP_LEG_LENGTH;
+    sheep.vx = SHEEP_WALK_SPEED_MIN;
+    sheep.state = SHEEP_STATE_WALKING;
+    sheep.stateTimer = 10.0;
+    sim.entities.push_back(sheep);
+
+    InputEvent ev{};
+    ev.type = EventType::Click;
+    ev.x = butterfly.x;
+    ev.y = butterfly.y;
+    sim_apply_click(sim, ev);
+
+    REQUIRE(sim.entities[0].kind == EntityKind::Butterfly);
+    REQUIRE(sim.entities[0].baseSpeed == Approx(BUTTERFLY_SPEED_MIN));
+    REQUIRE(sim.entities[1].state == SHEEP_STATE_WALKING);
+    for (const Blade& b : sim.blades) REQUIRE(b.cutAnimStart < 0.0);
+}
+
+TEST_CASE("Butterfly wing scale stays within flutter bounds", "[butterfly][render]") {
+    for (int i = 0; i < 200; ++i) {
+        const double t = i * 0.05;
+        const double scale = butterfly_wing_scale(t, 1.3);
+        REQUIRE(scale >= BUTTERFLY_FLUTTER_MIN_SCALE);
+        REQUIRE(scale <= 1.0);
+    }
+}
+

src/modules/DesktopGrass/DesktopGrass.Native.Tests/src/cat_coat_tests.cpp

@@ -0,0 +1,158 @@
+// cat_coat_tests.cpp
+//
+// §17 Cat coat palette and deterministic coat variant tests. Mirrors Win2D CatCoatTests.cs.
+
+#include "../third_party/catch2/catch.hpp"
+#include "Sim.h"
+
+#include <cmath>
+#include <cstdint>
+
+using namespace desktopgrass;
+
+namespace {
+
+int count_kind(const Sim& sim, EntityKind kind) {
+    int n = 0;
+    for (const Entity& e : sim.entities) if (e.kind == kind) ++n;
+    return n;
+}
+
+constexpr CatCoatPalette EXPECTED_CAT_COATS[CAT_COAT_VARIANT_COUNT] = {
+    { 0xFF6B6259u, 0xFF3D3733u, 0xFF6B6259u, 0xFF3D3733u, 0xFF1A1614u },
+    { 0xFFD89A6Fu, 0xFFA56B40u, 0xFFD89A6Fu, 0xFFA56B40u, 0xFF2B1A0Eu },
+    { 0xFF2A2522u, 0xFF140F0Cu, 0xFF2A2522u, 0xFF140F0Cu, 0xFFD9B85Bu },
+    { 0xFFEDE9E1u, 0xFFBDB7ABu, 0xFFEDE9E1u, 0xFFBDB7ABu, 0xFF1F1817u },
+    { 0xFF7A5F3Cu, 0xFF4E3F26u, 0xFF7A5F3Cu, 0xFF4E3F26u, 0xFF1A1108u },
+    { 0xFFC9B898u, 0xFF8E7F6Bu, 0xFFC9B898u, 0xFF8E7F6Bu, 0xFF2E251Du },
+};
+
+uint8_t next_cat_coat_after_prefix(Prng& side) {
+    (void)prng_uniform(side, CAT_BODY_RADIUS + 8.0, 1920.0 - (CAT_BODY_RADIUS + 8.0));
+    (void)prng_uniform(side, CAT_WALK_SPEED_MIN, CAT_WALK_SPEED_MAX);
+    (void)prng_uniform(side, 0.0, 1.0);
+    (void)prng_next_u32(side);
+    (void)prng_uniform(side, CAT_WALK_DURATION_MIN, CAT_WALK_DURATION_MAX);
+    (void)prng_index(side, static_cast<uint32_t>(sizeof(CAT_NAME_POOL) / sizeof(CAT_NAME_POOL[0])));
+    return static_cast<uint8_t>(prng_index(side, static_cast<uint32_t>(CAT_COAT_VARIANT_COUNT)));
+}
+
+} // namespace
+
+TEST_CASE("Cat coat variant count is pinned", "[cat][coat][constants]") {
+    REQUIRE(CAT_COAT_VARIANT_COUNT == 6);
+}
+
+TEST_CASE("Cat coat palette zero matches backward-compatible aliases", "[cat][coat][constants]") {
+    REQUIRE(CAT_COAT_PALETTES[0].body == CAT_BODY_COLOR);
+    REQUIRE(CAT_COAT_PALETTES[0].leg  == CAT_LEG_COLOR);
+    REQUIRE(CAT_COAT_PALETTES[0].face == CAT_FACE_COLOR);
+    REQUIRE(CAT_COAT_PALETTES[0].ear  == CAT_EAR_COLOR);
+    REQUIRE(CAT_COAT_PALETTES[0].ink  == CAT_INK_COLOR);
+}
+
+TEST_CASE("All cat coat palettes are pinned", "[cat][coat][constants]") {
+    for (int i = 0; i < CAT_COAT_VARIANT_COUNT; ++i) {
+        CAPTURE(i);
+        REQUIRE(CAT_COAT_PALETTES[i].body == EXPECTED_CAT_COATS[i].body);
+        REQUIRE(CAT_COAT_PALETTES[i].leg  == EXPECTED_CAT_COATS[i].leg);
+        REQUIRE(CAT_COAT_PALETTES[i].face == EXPECTED_CAT_COATS[i].face);
+        REQUIRE(CAT_COAT_PALETTES[i].ear  == EXPECTED_CAT_COATS[i].ear);
+        REQUIRE(CAT_COAT_PALETTES[i].ink  == EXPECTED_CAT_COATS[i].ink);
+    }
+}
+
+TEST_CASE("Cat coat body colors are distinct", "[cat][coat][constants]") {
+    for (int i = 0; i < CAT_COAT_VARIANT_COUNT; ++i) {
+        for (int j = i + 1; j < CAT_COAT_VARIANT_COUNT; ++j) {
+            CAPTURE(i);
+            CAPTURE(j);
+            REQUIRE(CAT_COAT_PALETTES[i].body != CAT_COAT_PALETTES[j].body);
+        }
+    }
+}
+
+TEST_CASE("Canonical cat flock pins deterministic coat variants", "[cat][coat][gen]") {
+    Sim sim = sim_init(CANONICAL_TEST_SEED, 1920.0, DEFAULT_DENSITY);
+    sim_set_critter(sim, CritterKind::Cat);
+
+    const uint8_t expectedCoats[] = { 1 };
+    int seen = 0;
+    for (const Entity& e : sim.entities) {
+        if (e.kind != EntityKind::Cat) continue;
+        REQUIRE(seen < static_cast<int>(sizeof(expectedCoats) / sizeof(expectedCoats[0])));
+        REQUIRE(e.coatVariantIndex == expectedCoats[seen]);
+        ++seen;
+    }
+    REQUIRE(seen == static_cast<int>(sizeof(expectedCoats) / sizeof(expectedCoats[0])));
+}
+
+TEST_CASE("Cat coat PRNG draw follows nameIndex", "[cat][coat][prng]") {
+    Prng side;
+    prng_init(side, CANONICAL_TEST_SEED ^ CRITTER_PRNG_SALT);
+
+    Sim sim = sim_init(CANONICAL_TEST_SEED, 1920.0, DEFAULT_DENSITY);
+    sim_set_critter(sim, CritterKind::Cat);
+
+    const double countDraw = prng_uniform(side, CAT_COUNT_MIN, CAT_COUNT_MAX + 1);
+    int expectedCount = static_cast<int>(std::floor(countDraw));
+    if (expectedCount < CAT_COUNT_MIN) expectedCount = CAT_COUNT_MIN;
+    if (expectedCount > CAT_COUNT_MAX) expectedCount = CAT_COUNT_MAX;
+    REQUIRE(count_kind(sim, EntityKind::Cat) == expectedCount);
+
+    int seen = 0;
+    for (const Entity& e : sim.entities) {
+        if (e.kind != EntityKind::Cat) continue;
+        const uint8_t expectedCoat = next_cat_coat_after_prefix(side);
+        REQUIRE(e.coatVariantIndex == expectedCoat);
+        ++seen;
+    }
+    REQUIRE(seen == expectedCount);
+}
+
+TEST_CASE("Generated cat coats always stay within palette range", "[cat][coat][gen]") {
+    for (uint64_t i = 0; i < 128; ++i) {
+        const uint64_t seed = CANONICAL_TEST_SEED + i * 0x9E3779B97F4A7C15ull;
+        Sim sim = sim_init(seed, 1920.0, DEFAULT_DENSITY);
+        sim_set_critter(sim, CritterKind::Cat);
+
+        int seen = 0;
+        for (const Entity& e : sim.entities) {
+            if (e.kind != EntityKind::Cat) continue;
+            REQUIRE(e.coatVariantIndex < CAT_COAT_VARIANT_COUNT);
+            ++seen;
+        }
+        REQUIRE(seen >= CAT_COUNT_MIN);
+        REQUIRE(seen <= CAT_COUNT_MAX);
+    }
+}
+
+TEST_CASE("Sheep keep default coat variant zero", "[cat][coat][sheep]") {
+    Sim sim = sim_init(CANONICAL_TEST_SEED, 1920.0, DEFAULT_DENSITY);
+    sim_set_critter(sim, CritterKind::Sheep);
+
+    REQUIRE(count_kind(sim, EntityKind::Sheep) >= SHEEP_COUNT_MIN);
+    for (const Entity& e : sim.entities) {
+        if (e.kind != EntityKind::Sheep) continue;
+        REQUIRE(e.coatVariantIndex == 0);
+    }
+}
+
+TEST_CASE("Fixed cat count coat PRNG skips only the count draw", "[cat][coat][count][prng]") {
+    Sim sim = sim_init(CANONICAL_TEST_SEED, 1920.0, DEFAULT_DENSITY);
+    sim_set_critter(sim, CritterKind::Cat);
+    sim_set_critter_count(sim, 3);
+    REQUIRE(count_kind(sim, EntityKind::Cat) == 3);
+
+    Prng side;
+    prng_init(side, CANONICAL_TEST_SEED ^ CRITTER_PRNG_SALT);
+
+    int seen = 0;
+    for (const Entity& e : sim.entities) {
+        if (e.kind != EntityKind::Cat) continue;
+        const uint8_t expectedCoat = next_cat_coat_after_prefix(side);
+        REQUIRE(e.coatVariantIndex == expectedCoat);
+        ++seen;
+    }
+    REQUIRE(seen == 3);
+}

src/modules/DesktopGrass/DesktopGrass.Native.Tests/src/cat_tests.cpp

@@ -0,0 +1,332 @@
+// cat_tests.cpp
+//
+// §17 Cat critter tests. Mirrors Win2D CatTests.cs.
+
+#include "../third_party/catch2/catch.hpp"
+#include "Sim.h"
+
+#include <algorithm>
+#include <cmath>
+
+using namespace desktopgrass;
+
+namespace {
+
+int count_kind(const Sim& sim, EntityKind kind) {
+    return static_cast<int>(std::count_if(sim.entities.begin(), sim.entities.end(),
+        [kind](const Entity& e) { return e.kind == kind; }));
+}
+
+Entity* first_kind(Sim& sim, EntityKind kind) {
+    for (Entity& e : sim.entities) if (e.kind == kind) return &e;
+    return nullptr;
+}
+
+const Entity* first_kind(const Sim& sim, EntityKind kind) {
+    for (const Entity& e : sim.entities) if (e.kind == kind) return &e;
+    return nullptr;
+}
+
+void keep_first_cat_only(Sim& sim) {
+    Entity* cat = first_kind(sim, EntityKind::Cat);
+    REQUIRE(cat != nullptr);
+    const Entity copy = *cat;
+    sim.entities.clear();
+    sim.entities.push_back(copy);
+}
+
+InputEvent click_event(double x, double y) {
+    InputEvent ev{};
+    ev.type = EventType::Click;
+    ev.x = x;
+    ev.y = y;
+    ev.time = 0.0;
+    return ev;
+}
+
+} // namespace
+
+TEST_CASE("CritterKind::Cat and CRITTER_COUNT are pinned", "[cat][enum]") {
+    REQUIRE(static_cast<int>(CritterKind::None)  == 0);
+    REQUIRE(static_cast<int>(CritterKind::Sheep) == 1);
+    REQUIRE(static_cast<int>(CritterKind::Cat)   == 2);
+    REQUIRE(static_cast<int>(CritterKind::Bunny) == 3);
+    REQUIRE(CRITTER_COUNT == 4);
+    REQUIRE(CRITTER_DEFAULT == CritterKind::None);
+}
+
+TEST_CASE("EntityKind::Cat is pinned", "[cat][enum]") {
+    REQUIRE(static_cast<int>(EntityKind::None)       == 0);
+    REQUIRE(static_cast<int>(EntityKind::Tumbleweed) == 1);
+    REQUIRE(static_cast<int>(EntityKind::Snowflake)  == 2);
+    REQUIRE(static_cast<int>(EntityKind::Sheep)      == 3);
+    REQUIRE(static_cast<int>(EntityKind::Cat)        == 4);
+}
+
+TEST_CASE("Cat constants are pinned to spec values", "[cat][constants]") {
+    REQUIRE(CAT_COUNT_MIN == 1);
+    REQUIRE(CAT_COUNT_MAX == 2);
+    REQUIRE(CAT_WALK_SPEED_MIN == Approx(10.0));
+    REQUIRE(CAT_WALK_SPEED_MAX == Approx(22.0));
+    REQUIRE(CAT_POUNCE_SPEED   == Approx(60.0));
+
+    REQUIRE(CAT_BODY_RADIUS    == Approx(11.0));
+    REQUIRE(CAT_BODY_HEIGHT    == Approx(7.0));
+    REQUIRE(CAT_HEAD_RADIUS    == Approx(4.5));
+    REQUIRE(CAT_LEG_LENGTH     == Approx(5.0));
+    REQUIRE(CAT_TAIL_LENGTH    == Approx(13.0));
+    REQUIRE(CAT_TAIL_THICKNESS == Approx(1.6));
+    REQUIRE(CAT_EAR_HEIGHT     == Approx(4.5));
+
+    REQUIRE(CAT_BODY_COLOR == 0xFF6B6259u);
+    REQUIRE(CAT_LEG_COLOR  == 0xFF3D3733u);
+    REQUIRE(CAT_FACE_COLOR == 0xFF6B6259u);
+    REQUIRE(CAT_EAR_COLOR  == 0xFF3D3733u);
+    REQUIRE(CAT_INK_COLOR  == 0xFF1A1614u);
+
+    REQUIRE(CAT_WALK_PERIOD    == Approx(0.50));
+    REQUIRE(CAT_LEG_CYCLE_AMP  == Approx(1.6));
+    REQUIRE(CAT_HEAD_BOB_AMP   == Approx(0.4));
+    REQUIRE(CAT_TAIL_SWAY_FREQ == Approx(1.2));
+    REQUIRE(CAT_TAIL_SWAY_AMP  == Approx(0.35));
+
+    REQUIRE(CAT_STATE_WALKING  == SHEEP_STATE_WALKING);
+    REQUIRE(CAT_STATE_IDLE     == SHEEP_STATE_IDLE);
+    REQUIRE(CAT_STATE_SLEEPING == SHEEP_STATE_SLEEPING);
+    REQUIRE(CAT_STATE_POUNCING == SHEEP_STATE_HOPPING);
+
+    REQUIRE(CAT_WALK_DURATION_MIN  == Approx(6.0));
+    REQUIRE(CAT_WALK_DURATION_MAX  == Approx(10.0));
+    REQUIRE(CAT_IDLE_DURATION_MIN  == Approx(4.0));
+    REQUIRE(CAT_IDLE_DURATION_MAX  == Approx(8.0));
+    REQUIRE(CAT_SLEEP_DURATION_MIN == Approx(20.0));
+    REQUIRE(CAT_SLEEP_DURATION_MAX == Approx(40.0));
+    REQUIRE(CAT_POUNCE_DURATION    == Approx(0.45));
+
+    REQUIRE(CAT_IDLE_PROBABILITY == Approx(0.65));
+    REQUIRE(CAT_SLEEP_PROBABILITY == Approx(0.30));
+    REQUIRE(CAT_SLEEP_FROM_IDLE_PROB == Approx(0.50));
+
+    REQUIRE(CAT_POUNCE_RADIUS == Approx(80.0));
+    REQUIRE(CAT_POUNCE_HEIGHT == Approx(9.0));
+    REQUIRE(CAT_CURIOUS_RADIUS == Approx(100.0));
+    REQUIRE(CAT_CURIOUS_HEAD_TURN_MAX == Approx(0.7));
+}
+
+TEST_CASE("sim_init defaults to None and does not generate cats until selected", "[cat][init]") {
+    Sim sim = sim_init(CANONICAL_TEST_SEED, 1920.0, DEFAULT_DENSITY);
+    REQUIRE(sim.currentCritter == CritterKind::None);
+    REQUIRE(count_kind(sim, EntityKind::Cat) == 0);
+
+    sim_set_critter(sim, CritterKind::Cat);
+    REQUIRE(count_kind(sim, EntityKind::Cat) >= CAT_COUNT_MIN);
+}
+
+TEST_CASE("sim_set_critter(Cat) produces deterministic cats", "[cat][gen]") {
+    Sim sim = sim_init(CANONICAL_TEST_SEED, 1920.0, DEFAULT_DENSITY);
+    sim_set_critter(sim, CritterKind::Cat);
+
+    REQUIRE(sim.currentCritter == CritterKind::Cat);
+    const int k = count_kind(sim, EntityKind::Cat);
+    REQUIRE(k >= CAT_COUNT_MIN);
+    REQUIRE(k <= CAT_COUNT_MAX);
+
+    for (const Entity& e : sim.entities) {
+        if (e.kind != EntityKind::Cat) continue;
+        REQUIRE(e.state == CAT_STATE_WALKING);
+        REQUIRE(e.stateTimer >= CAT_WALK_DURATION_MIN);
+        REQUIRE(e.stateTimer <  CAT_WALK_DURATION_MAX);
+        REQUIRE(std::fabs(e.vx) >= CAT_WALK_SPEED_MIN);
+        REQUIRE(std::fabs(e.vx) <  CAT_WALK_SPEED_MAX);
+        const double margin = e.size + 8.0;
+        REQUIRE(e.x >= margin);
+        REQUIRE(e.x <= sim.monitorWidth - margin);
+        REQUIRE(e.y == Approx(sim.windowHeight - CAT_BODY_HEIGHT - CAT_LEG_LENGTH));
+        REQUIRE(e.size == Approx(CAT_BODY_RADIUS));
+        REQUIRE(e.lifetime < 0.0);
+        REQUIRE(e.nameIndex < sizeof(CAT_NAME_POOL) / sizeof(CAT_NAME_POOL[0]));
+        REQUIRE(e.coatVariantIndex < CAT_COAT_VARIANT_COUNT);
+    }
+}
+
+TEST_CASE("Cat PRNG draw order matches a side stream", "[cat][prng]") {
+    // count, then per-cat: x, speed, dir-coin, seed, stateTimer, nameIndex, coatVariantIndex
+    Prng side;
+    prng_init(side, CANONICAL_TEST_SEED ^ CRITTER_PRNG_SALT);
+
+    Sim sim = sim_init(CANONICAL_TEST_SEED, 1920.0, DEFAULT_DENSITY);
+    sim_set_critter(sim, CritterKind::Cat);
+
+    const double countDraw = prng_uniform(side, CAT_COUNT_MIN, CAT_COUNT_MAX + 1);
+    int expectedCount = static_cast<int>(std::floor(countDraw));
+    if (expectedCount < CAT_COUNT_MIN) expectedCount = CAT_COUNT_MIN;
+    if (expectedCount > CAT_COUNT_MAX) expectedCount = CAT_COUNT_MAX;
+    REQUIRE(count_kind(sim, EntityKind::Cat) == expectedCount);
+
+    int seen = 0;
+    for (const Entity& e : sim.entities) {
+        if (e.kind != EntityKind::Cat) continue;
+        const double margin = CAT_BODY_RADIUS + 8.0;
+        const double expectedX = prng_uniform(side, margin, 1920.0 - margin);
+        const double expectedSpeed = prng_uniform(side, CAT_WALK_SPEED_MIN, CAT_WALK_SPEED_MAX);
+        const double dirCoin = prng_uniform(side, 0.0, 1.0);
+        const double expectedDir = (dirCoin < 0.5) ? -1.0 : 1.0;
+        const uint32_t expectedSeed = prng_next_u32(side);
+        const double expectedTimer = prng_uniform(side, CAT_WALK_DURATION_MIN, CAT_WALK_DURATION_MAX);
+        const uint8_t expectedNameIndex = static_cast<uint8_t>(prng_index(side,
+            static_cast<uint32_t>(sizeof(CAT_NAME_POOL) / sizeof(CAT_NAME_POOL[0]))));
+        const uint8_t expectedCoatVariantIndex = static_cast<uint8_t>(prng_index(side,
+            static_cast<uint32_t>(CAT_COAT_VARIANT_COUNT)));
+
+        REQUIRE(e.x == Approx(expectedX));
+        REQUIRE(e.vx == Approx(expectedSpeed * expectedDir));
+        REQUIRE(e.seed == expectedSeed);
+        REQUIRE(e.stateTimer == Approx(expectedTimer));
+        REQUIRE(e.nameIndex == expectedNameIndex);
+        REQUIRE(e.coatVariantIndex == expectedCoatVariantIndex);
+        ++seen;
+    }
+    REQUIRE(seen == expectedCount);
+}
+
+TEST_CASE("sim_set_critter(None) clears ambient cats", "[cat][toggle]") {
+    Sim sim = sim_init(CANONICAL_TEST_SEED, 1920.0, DEFAULT_DENSITY);
+    sim_set_critter(sim, CritterKind::Cat);
+    REQUIRE(count_kind(sim, EntityKind::Cat) >= CAT_COUNT_MIN);
+
+    sim_set_critter(sim, CritterKind::None);
+    REQUIRE(sim.currentCritter == CritterKind::None);
+    REQUIRE(count_kind(sim, EntityKind::Cat) == 0);
+    REQUIRE(count_kind(sim, EntityKind::Bunny) == 0);
+}
+
+TEST_CASE("Switching between critter species replaces the previous species", "[cat][toggle]") {
+    Sim sim = sim_init(CANONICAL_TEST_SEED, 1920.0, DEFAULT_DENSITY);
+    sim_set_critter(sim, CritterKind::Cat);
+    REQUIRE(count_kind(sim, EntityKind::Cat) >= CAT_COUNT_MIN);
+    REQUIRE(count_kind(sim, EntityKind::Sheep) == 0);
+
+    sim_set_critter(sim, CritterKind::Sheep);
+    REQUIRE(count_kind(sim, EntityKind::Cat) == 0);
+    REQUIRE(count_kind(sim, EntityKind::Sheep) >= SHEEP_COUNT_MIN);
+
+    sim_set_critter(sim, CritterKind::Cat);
+    REQUIRE(count_kind(sim, EntityKind::Sheep) == 0);
+    REQUIRE(count_kind(sim, EntityKind::Cat) >= CAT_COUNT_MIN);
+}
+
+TEST_CASE("sim_set_scene gates active Cat to Grass", "[cat][scene]") {
+    Sim sim = sim_init(CANONICAL_TEST_SEED, 1920.0, DEFAULT_DENSITY);
+    sim_set_critter(sim, CritterKind::Cat);
+    const int catsGrass = count_kind(sim, EntityKind::Cat);
+    REQUIRE(catsGrass >= CAT_COUNT_MIN);
+
+    sim_set_scene(sim, Scene::Desert);
+    REQUIRE(sim.currentCritter == CritterKind::Cat);
+    REQUIRE(count_kind(sim, EntityKind::Cat) == 0);
+
+    sim_set_scene(sim, Scene::Winter);
+    REQUIRE(sim.currentCritter == CritterKind::Cat);
+    REQUIRE(count_kind(sim, EntityKind::Cat) == 0);
+
+    sim_set_scene(sim, Scene::Grass);
+    REQUIRE(count_kind(sim, EntityKind::Cat) == catsGrass);
+}
+
+TEST_CASE("Click within CAT_POUNCE_RADIUS pounces toward the click", "[cat][click]") {
+    Sim sim = sim_init(CANONICAL_TEST_SEED, 1920.0, DEFAULT_DENSITY);
+    sim_set_critter(sim, CritterKind::Cat);
+    keep_first_cat_only(sim);
+
+    Entity& cat = sim.entities.front();
+    cat.x = 500.0;
+    cat.vx = -CAT_WALK_SPEED_MIN;
+    cat.age = 5.0;
+
+    sim_apply_click(sim, click_event(cat.x + 16.0, sim.windowHeight - 20.0));
+
+    const Entity& after = sim.entities.front();
+    REQUIRE(after.state == CAT_STATE_POUNCING);
+    REQUIRE(after.stateTimer == Approx(CAT_POUNCE_DURATION));
+    REQUIRE(after.age == Approx(0.0));
+    REQUIRE(after.vx == Approx(CAT_POUNCE_SPEED));
+}
+
+TEST_CASE("Click outside CAT_POUNCE_RADIUS leaves cat alone", "[cat][click]") {
+    Sim sim = sim_init(CANONICAL_TEST_SEED, 1920.0, DEFAULT_DENSITY);
+    sim_set_critter(sim, CritterKind::Cat);
+    keep_first_cat_only(sim);
+
+    Entity& cat = sim.entities.front();
+    cat.x = 500.0;
+    cat.vx = -CAT_WALK_SPEED_MIN;
+    const uint8_t stateBefore = cat.state;
+    const double vxBefore = cat.vx;
+
+    sim_apply_click(sim, click_event(cat.x + CAT_POUNCE_RADIUS + 5.0, sim.windowHeight - 20.0));
+
+    const Entity& after = sim.entities.front();
+    REQUIRE(after.state == stateBefore);
+    REQUIRE(after.vx == Approx(vxBefore));
+}
+
+TEST_CASE("Cats do not greet other cats", "[cat][greeting]") {
+    Sim sim = sim_init(CANONICAL_TEST_SEED, 1920.0, DEFAULT_DENSITY);
+    sim_set_critter(sim, CritterKind::Cat);
+    keep_first_cat_only(sim);
+
+    Entity first = sim.entities.front();
+    first.x = 400.0;
+    first.vx = CAT_WALK_SPEED_MIN;
+    first.state = CAT_STATE_WALKING;
+    first.stateTimer = 10.0;
+    first.age = SHEEP_GREET_MIN_AGE + 1.0;
+    Entity second = first;
+    second.x = first.x + 20.0;
+    second.vx = -CAT_WALK_SPEED_MIN;
+    sim.entities.clear();
+    sim.entities.push_back(first);
+    sim.entities.push_back(second);
+
+    sim_tick_entities(sim, 0.016);
+
+    REQUIRE(count_kind(sim, EntityKind::Cat) == 2);
+    for (const Entity& e : sim.entities) {
+        if (e.kind == EntityKind::Cat) REQUIRE(e.state != SHEEP_STATE_GREETING);
+    }
+}
+
+TEST_CASE("Cats do not greet sheep", "[cat][greeting]") {
+    Sim sim = sim_init(CANONICAL_TEST_SEED, 1920.0, DEFAULT_DENSITY);
+    sim_set_critter(sim, CritterKind::Cat);
+    keep_first_cat_only(sim);
+
+    Entity cat = sim.entities.front();
+    cat.x = 400.0;
+    cat.vx = CAT_WALK_SPEED_MIN;
+    cat.state = CAT_STATE_WALKING;
+    cat.stateTimer = 10.0;
+    cat.age = SHEEP_GREET_MIN_AGE + 1.0;
+
+    Entity sheep{};
+    sheep.kind = EntityKind::Sheep;
+    sheep.size = SHEEP_BODY_RADIUS;
+    sheep.x = cat.x + 20.0;
+    sheep.y = sim.windowHeight - SHEEP_BODY_HEIGHT - SHEEP_LEG_LENGTH;
+    sheep.vx = -SHEEP_WALK_SPEED_MIN;
+    sheep.age = SHEEP_GREET_MIN_AGE + 1.0;
+    sheep.lifetime = -1.0;
+    sheep.state = SHEEP_STATE_WALKING;
+    sheep.stateTimer = 10.0;
+
+    sim.entities.clear();
+    sim.entities.push_back(cat);
+    sim.entities.push_back(sheep);
+
+    sim_tick_entities(sim, 0.016);
+
+    REQUIRE(count_kind(sim, EntityKind::Cat) == 1);
+    REQUIRE(count_kind(sim, EntityKind::Sheep) == 1);
+    for (const Entity& e : sim.entities) REQUIRE(e.state != SHEEP_STATE_GREETING);
+}
+

src/modules/DesktopGrass/DesktopGrass.Native.Tests/src/click_through_smoke_test.cpp

@@ -0,0 +1,176 @@
+#include "../third_party/catch2/catch.hpp"
+
+#define WIN32_LEAN_AND_MEAN
+#include <windows.h>
+
+#include <atomic>
+#include <chrono>
+#include <string>
+#include <thread>
+
+namespace {
+
+std::atomic<bool> g_probeReceivedLeftDown{false};
+
+enum class ClickThroughResult {
+    Passed,
+    Skipped,
+    Failed,
+};
+
+std::wstring unique_class_name(const wchar_t* suffix) {
+    return std::wstring(L"DesktopGrass.Native.ClickThrough.")
+        + std::to_wstring(GetCurrentProcessId()) + L"."
+        + std::to_wstring(GetTickCount64()) + L"."
+        + suffix;
+}
+
+LRESULT CALLBACK ProbeWndProc(HWND hwnd, UINT msg, WPARAM wp, LPARAM lp) {
+    if (msg == WM_LBUTTONDOWN) {
+        g_probeReceivedLeftDown.store(true, std::memory_order_release);
+    }
+    return DefWindowProcW(hwnd, msg, wp, lp);
+}
+
+LRESULT CALLBACK OverlayWndProc(HWND hwnd, UINT msg, WPARAM wp, LPARAM lp) {
+    return DefWindowProcW(hwnd, msg, wp, lp);
+}
+
+void pump_messages_for(std::chrono::milliseconds duration) {
+    const auto deadline = std::chrono::steady_clock::now() + duration;
+    MSG msg{};
+    do {
+        while (PeekMessageW(&msg, nullptr, 0, 0, PM_REMOVE)) {
+            TranslateMessage(&msg);
+            DispatchMessageW(&msg);
+        }
+        if (g_probeReceivedLeftDown.load(std::memory_order_acquire)) {
+            return;
+        }
+        std::this_thread::sleep_for(std::chrono::milliseconds(5));
+    } while (std::chrono::steady_clock::now() < deadline);
+}
+
+bool has_interactive_desktop() {
+    if (GetConsoleWindow() == nullptr) {
+        return false;
+    }
+
+    HDESK inputDesktop = OpenInputDesktop(0, FALSE, DESKTOP_SWITCHDESKTOP);
+    if (inputDesktop == nullptr) {
+        return false;
+    }
+    CloseDesktop(inputDesktop);
+    return true;
+}
+
+ClickThroughResult spawn_probe_window_and_click_through_overlay() {
+    if (!has_interactive_desktop()) {
+        return ClickThroughResult::Skipped;
+    }
+
+    g_probeReceivedLeftDown.store(false, std::memory_order_release);
+
+    const HINSTANCE instance = GetModuleHandleW(nullptr);
+    const std::wstring probeClass = unique_class_name(L"Probe");
+    const std::wstring overlayClass = unique_class_name(L"Overlay");
+
+    WNDCLASSEXW probeWc{};
+    probeWc.cbSize = sizeof(probeWc);
+    probeWc.lpfnWndProc = ProbeWndProc;
+    probeWc.hInstance = instance;
+    probeWc.lpszClassName = probeClass.c_str();
+
+    WNDCLASSEXW overlayWc{};
+    overlayWc.cbSize = sizeof(overlayWc);
+    overlayWc.lpfnWndProc = OverlayWndProc;
+    overlayWc.hInstance = instance;
+    overlayWc.lpszClassName = overlayClass.c_str();
+
+    if (!RegisterClassExW(&probeWc)) {
+        return ClickThroughResult::Failed;
+    }
+    if (!RegisterClassExW(&overlayWc)) {
+        UnregisterClassW(probeClass.c_str(), instance);
+        return ClickThroughResult::Failed;
+    }
+
+    const int x = GetSystemMetrics(SM_XVIRTUALSCREEN) + 96;
+    const int y = GetSystemMetrics(SM_YVIRTUALSCREEN) + 96;
+    constexpr int kWidth = 96;
+    constexpr int kHeight = 64;
+    const int clickX = x + 24;
+    const int clickY = y + 24;
+
+    HWND probe = CreateWindowExW(
+        WS_EX_TOOLWINDOW | WS_EX_TOPMOST,
+        probeClass.c_str(), L"DesktopGrass click-through probe",
+        WS_POPUP | WS_VISIBLE,
+        x, y, kWidth, kHeight,
+        nullptr, nullptr, instance, nullptr);
+
+    HWND overlay = nullptr;
+    bool ok = probe != nullptr;
+    if (ok) {
+        SetWindowPos(probe, HWND_TOPMOST, x, y, kWidth, kHeight, SWP_SHOWWINDOW);
+
+        overlay = CreateWindowExW(
+            WS_EX_LAYERED | WS_EX_TRANSPARENT | WS_EX_TOPMOST |
+                WS_EX_TOOLWINDOW | WS_EX_NOACTIVATE,
+            overlayClass.c_str(), L"DesktopGrass click-through overlay",
+            WS_POPUP,
+            x, y, kWidth, kHeight,
+            nullptr, nullptr, instance, nullptr);
+        ok = overlay != nullptr;
+    }
+
+    if (ok) {
+        SetLayeredWindowAttributes(overlay, 0, 1, LWA_ALPHA);
+        ShowWindow(overlay, SW_SHOWNOACTIVATE);
+        SetWindowPos(overlay, HWND_TOPMOST, x, y, kWidth, kHeight,
+                     SWP_SHOWWINDOW | SWP_NOACTIVATE);
+        pump_messages_for(std::chrono::milliseconds(50));
+
+        if (!SetCursorPos(clickX, clickY)) {
+            ok = false;
+        }
+    }
+
+    ClickThroughResult result = ClickThroughResult::Failed;
+    if (ok) {
+        INPUT inputs[2]{};
+        inputs[0].type = INPUT_MOUSE;
+        inputs[0].mi.dwFlags = MOUSEEVENTF_LEFTDOWN;
+        inputs[1].type = INPUT_MOUSE;
+        inputs[1].mi.dwFlags = MOUSEEVENTF_LEFTUP;
+
+        const UINT sent = SendInput(2, inputs, sizeof(INPUT));
+        if (sent != 2) {
+            result = ClickThroughResult::Skipped;
+        } else {
+            pump_messages_for(std::chrono::milliseconds(200));
+            result = g_probeReceivedLeftDown.load(std::memory_order_acquire)
+                ? ClickThroughResult::Passed
+                : ClickThroughResult::Failed;
+        }
+    }
+
+    if (overlay) DestroyWindow(overlay);
+    if (probe) DestroyWindow(probe);
+    UnregisterClassW(overlayClass.c_str(), instance);
+    UnregisterClassW(probeClass.c_str(), instance);
+    return result;
+}
+
+} // namespace
+
+TEST_CASE("Overlay click-through allows input to reach windows beneath", "[smoke][input]") {
+    const ClickThroughResult result = spawn_probe_window_and_click_through_overlay();
+    if (result == ClickThroughResult::Skipped) {
+        WARN("Skipping click-through smoke test: requires an interactive desktop and SendInput.");
+        SUCCEED("Requires interactive session");
+        return;
+    }
+
+    REQUIRE(result == ClickThroughResult::Passed);
+}

src/modules/DesktopGrass/DesktopGrass.Native.Tests/src/config_tests.cpp

@@ -0,0 +1,154 @@
+#include "../third_party/catch2/catch.hpp"
+#include "Config.h"
+
+#include <filesystem>
+#include <fstream>
+#include <sstream>
+#include <string>
+
+using namespace desktopgrass;
+
+namespace {
+
+std::filesystem::path test_config_path(const char* name) {
+    std::filesystem::path dir = std::filesystem::current_path()
+        / ".copilot-scratch"
+        / "native-config-tests"
+        / name;
+    std::error_code ec;
+    std::filesystem::remove_all(dir, ec);
+    std::filesystem::create_directories(dir);
+    return dir / "config.json";
+}
+
+void write_text(const std::filesystem::path& path, const std::string& text) {
+    std::filesystem::create_directories(path.parent_path());
+    std::ofstream file(path, std::ios::binary | std::ios::trunc);
+    file << text;
+}
+
+std::string read_text(const std::filesystem::path& path) {
+    std::ifstream file(path, std::ios::binary);
+    std::ostringstream buffer;
+    buffer << file.rdbuf();
+    return buffer.str();
+}
+
+} // namespace
+
+TEST_CASE("Config: missing file yields defaults and writes a template", "[config]") {
+    const std::filesystem::path path = test_config_path("missing");
+    REQUIRE_FALSE(std::filesystem::exists(path));
+
+    const config::Config cfg = config::LoadConfig(path.wstring());
+
+    CHECK(cfg.targetFps == config::kTargetFpsDefault);
+    CHECK(cfg.bladeDensity == Approx(config::kBladeDensityDefault));
+
+    // A default file should have been created and be re-readable (it is JSONC).
+    REQUIRE(std::filesystem::exists(path));
+    const config::Config reread = config::LoadConfig(path.wstring());
+    CHECK(reread.targetFps == config::kTargetFpsDefault);
+    CHECK(reread.bladeDensity == Approx(config::kBladeDensityDefault));
+}
+
+TEST_CASE("Config: valid values are parsed", "[config]") {
+    const std::filesystem::path path = test_config_path("valid");
+    write_text(path, "{ \"version\": 1, \"targetFps\": 60, \"bladeDensity\": 1.5 }");
+
+    const config::Config cfg = config::LoadConfig(path.wstring());
+    CHECK(cfg.targetFps == 60);
+    CHECK(cfg.bladeDensity == Approx(1.5));
+}
+
+TEST_CASE("Config: out-of-range values are clamped", "[config]") {
+    const std::filesystem::path path = test_config_path("clamp");
+    write_text(path, "{ \"targetFps\": 1000, \"bladeDensity\": 99.0 }");
+
+    config::Config cfg = config::LoadConfig(path.wstring());
+    CHECK(cfg.targetFps == config::kTargetFpsMax);
+    CHECK(cfg.bladeDensity == Approx(config::kBladeDensityMax));
+
+    write_text(path, "{ \"targetFps\": 0, \"bladeDensity\": 0.0 }");
+    cfg = config::LoadConfig(path.wstring());
+    CHECK(cfg.targetFps == config::kTargetFpsMin);
+    CHECK(cfg.bladeDensity == Approx(config::kBladeDensityMin));
+}
+
+TEST_CASE("Config: JSONC comments and trailing commas are tolerated", "[config]") {
+    const std::filesystem::path path = test_config_path("jsonc");
+    write_text(path,
+        "{\n"
+        "  // a comment\n"
+        "  \"targetFps\": 24, /* inline */\n"
+        "  \"bladeDensity\": 2.0,\n"  // trailing comma below
+        "}\n");
+
+    const config::Config cfg = config::LoadConfig(path.wstring());
+    CHECK(cfg.targetFps == 24);
+    CHECK(cfg.bladeDensity == Approx(2.0));
+}
+
+TEST_CASE("Config: malformed file falls back to defaults and is preserved", "[config]") {
+    const std::filesystem::path path = test_config_path("malformed");
+    write_text(path, "{ not valid json ");
+
+    const config::Config cfg = config::LoadConfig(path.wstring());
+    CHECK(cfg.targetFps == config::kTargetFpsDefault);
+    CHECK(cfg.bladeDensity == Approx(config::kBladeDensityDefault));
+
+    // The user's (broken) file must be left untouched for them to fix.
+    CHECK(read_text(path) == "{ not valid json ");
+}
+
+TEST_CASE("Config: missing keys fall back to per-key defaults", "[config]") {
+    const std::filesystem::path path = test_config_path("partial");
+    write_text(path, "{ \"targetFps\": 45 }");
+
+    const config::Config cfg = config::LoadConfig(path.wstring());
+    CHECK(cfg.targetFps == 45);
+    CHECK(cfg.bladeDensity == Approx(config::kBladeDensityDefault));
+    CHECK(cfg.swaySpeed == Approx(config::kSwaySpeedDefault));
+    CHECK(cfg.swayAmplitude == Approx(config::kSwayAmplitudeDefault));
+}
+
+TEST_CASE("Config: keys are matched case-insensitively", "[config]") {
+    const std::filesystem::path path = test_config_path("case-insensitive");
+    write_text(path,
+        "{ \"TargetFps\": 60, \"BLADEDENSITY\": 1.5, "
+        "\"SwaySpeed\": 0.5, \"swayamplitude\": 2.0 }");
+
+    const config::Config cfg = config::LoadConfig(path.wstring());
+    CHECK(cfg.targetFps == 60);
+    CHECK(cfg.bladeDensity == Approx(1.5));
+    CHECK(cfg.swaySpeed == Approx(0.5));
+    CHECK(cfg.swayAmplitude == Approx(2.0));
+}
+
+TEST_CASE("Config: sway knobs parse, clamp, and reject non-finite", "[config]") {
+    const std::filesystem::path path = test_config_path("sway");
+
+    // Defaults when absent.
+    write_text(path, "{ }");
+    config::Config cfg = config::LoadConfig(path.wstring());
+    CHECK(cfg.swaySpeed == Approx(config::kSwaySpeedDefault));
+    CHECK(cfg.swayAmplitude == Approx(config::kSwayAmplitudeDefault));
+
+    // Valid values parsed.
+    write_text(path, "{ \"swaySpeed\": 0.5, \"swayAmplitude\": 2.0 }");
+    cfg = config::LoadConfig(path.wstring());
+    CHECK(cfg.swaySpeed == Approx(0.5));
+    CHECK(cfg.swayAmplitude == Approx(2.0));
+
+    // Out-of-range clamped to bounds.
+    write_text(path, "{ \"swaySpeed\": 99.0, \"swayAmplitude\": -5.0 }");
+    cfg = config::LoadConfig(path.wstring());
+    CHECK(cfg.swaySpeed == Approx(config::kSwaySpeedMax));
+    CHECK(cfg.swayAmplitude == Approx(config::kSwayAmplitudeMin));
+
+    // Non-finite (inf from overflow) falls back to default, never poisons the sim.
+    write_text(path, "{ \"swaySpeed\": 1e999, \"swayAmplitude\": 1e999 }");
+    cfg = config::LoadConfig(path.wstring());
+    CHECK(cfg.swaySpeed == Approx(config::kSwaySpeedDefault));
+    CHECK(cfg.swayAmplitude == Approx(config::kSwayAmplitudeDefault));
+}

src/modules/DesktopGrass/DesktopGrass.Native.Tests/src/critter_tests.cpp

@@ -0,0 +1,379 @@
+// critter_tests.cpp
+//
+// Critter subsystem tests (architecture.md §13.3 / §16). Orthogonal to Scene.
+//
+// Coverage:
+//   * CritterKind discriminants are spec-locked ({None=0, Sheep=1}).
+//   * EntityKind::Sheep == 3 (added after the original {None, Tumbleweed,
+//     Snowflake} enum).
+//   * SHEEP_* and CRITTER_* constants are pinned to spec values.
+//   * sim_init defaults sim.currentCritter to None (no sheep until the user
+//     opts in via tray).
+//   * sim_set_critter(Sheep) on CANONICAL_TEST_SEED + 1920 produces
+//     deterministic count K ∈ [SHEEP_COUNT_MIN, SHEEP_COUNT_MAX], with
+//     every sheep entity well-formed: kind=Sheep, state=Walking, stateTimer
+//     in [WALK_DURATION_MIN, MAX], speed in [WALK_SPEED_MIN, MAX], x within
+//     monitor margins.
+//   * sim_set_critter(None) erases all sheep but preserves scene entities
+//     (snowflakes/tumbleweeds aren't touched).
+//   * sim_set_scene preserves the active critter — flipping Grass→Desert
+//     re-spawns sheep on the new scene.
+//   * Sheep PRNG draw order is bit-identical to a side-stream Prng for the
+//     locked sequence (count, then per-sheep: x, speed, dir-coin, seed,
+//     stateTimer, nameIndex).
+//   * Click within SHEEP_STARTLE_RADIUS pushes a sheep into Hopping, flips
+//     vx away from the cursor, and resets age.
+//   * Click outside SHEEP_STARTLE_RADIUS leaves sheep state untouched.
+
+#include "../third_party/catch2/catch.hpp"
+#include "Sim.h"
+
+#include <algorithm>
+#include <cmath>
+#include <cwchar>
+
+using namespace desktopgrass;
+
+namespace {
+
+int count_kind(const Sim& sim, EntityKind kind) {
+    int n = 0;
+    for (const Entity& e : sim.entities) if (e.kind == kind) ++n;
+    return n;
+}
+
+int count_sheep(const Sim& sim) {
+    return count_kind(sim, EntityKind::Sheep);
+}
+
+const Entity* first_sheep(const Sim& sim) {
+    for (const Entity& e : sim.entities) if (e.kind == EntityKind::Sheep) return &e;
+    return nullptr;
+}
+
+} // namespace
+
+TEST_CASE("CritterKind has spec-locked discriminants", "[critter][enum]") {
+    REQUIRE(static_cast<int>(CritterKind::None)  == 0);
+    REQUIRE(static_cast<int>(CritterKind::Sheep) == 1);
+    REQUIRE(static_cast<int>(CritterKind::Cat)   == 2);
+    REQUIRE(static_cast<int>(CritterKind::Bunny) == 3);
+    REQUIRE(static_cast<int>(EntityKind::Sheep)  == 3);
+    REQUIRE(static_cast<int>(EntityKind::Bunny)  == 6);
+    REQUIRE(static_cast<int>(EntityKind::Butterfly) == 7);
+    REQUIRE(static_cast<int>(EntityKind::Firefly) == 8);
+    REQUIRE(CRITTER_DEFAULT == CritterKind::None);
+}
+
+TEST_CASE("Sheep constants are pinned to spec values", "[critter][constants]") {
+    REQUIRE(SHEEP_COUNT_MIN      == 2);
+    REQUIRE(SHEEP_COUNT_MAX      == 3);
+    REQUIRE(sizeof(PET_COUNT_OPTIONS) / sizeof(PET_COUNT_OPTIONS[0]) == 6);
+    for (int i = 0; i < 6; ++i) REQUIRE(PET_COUNT_OPTIONS[i] == i + 1);
+    REQUIRE(PET_COUNT_DEFAULT_SHEEP == SHEEP_COUNT_MIN);
+    REQUIRE(PET_COUNT_DEFAULT_CAT == CAT_COUNT_MIN);
+    REQUIRE(PET_COUNT_MAX_PER_MONITOR == 6);
+    REQUIRE(sizeof(SHEEP_NAME_POOL) / sizeof(SHEEP_NAME_POOL[0]) == 8);
+    REQUIRE(sizeof(CAT_NAME_POOL) / sizeof(CAT_NAME_POOL[0]) == 8);
+    REQUIRE(std::wcscmp(SHEEP_NAME_POOL[0], L"Bessie") == 0);
+    REQUIRE(std::wcscmp(SHEEP_NAME_POOL[7], L"Hazel") == 0);
+    REQUIRE(std::wcscmp(CAT_NAME_POOL[0], L"Mittens") == 0);
+    REQUIRE(std::wcscmp(CAT_NAME_POOL[7], L"Juno") == 0);
+    REQUIRE(PET_NAME_HOVER_RADIUS == Approx(50.0));
+    REQUIRE(PET_NAME_FADE_DURATION == Approx(1.5));
+    REQUIRE(PET_NAME_FONT_SIZE == Approx(11.0));
+    REQUIRE(PET_NAME_OFFSET_Y == Approx(-8.0));
+    REQUIRE(PET_NAME_COLOR == 0xFFFFFFFFu);
+    REQUIRE(PET_NAME_SHADOW_COLOR == 0xC0000000u);
+    REQUIRE(SHEEP_WALK_SPEED_MIN == Approx(14.0));
+    REQUIRE(SHEEP_WALK_SPEED_MAX == Approx(26.0));
+    REQUIRE(SHEEP_BODY_RADIUS    == Approx(12.0));
+    REQUIRE(SHEEP_HEAD_RADIUS    == Approx(5.0));
+    REQUIRE(SHEEP_LEG_LENGTH     == Approx(5.5));
+
+    REQUIRE(SHEEP_STATE_WALKING  == 0);
+    REQUIRE(SHEEP_STATE_GRAZING  == 1);
+    REQUIRE(SHEEP_STATE_IDLE     == 2);
+    REQUIRE(SHEEP_STATE_SLEEPING == 3);
+    REQUIRE(SHEEP_STATE_HOPPING  == 4);
+
+    REQUIRE(SHEEP_HOP_DURATION   == Approx(0.55));
+    REQUIRE(SHEEP_HOP_HEIGHT     == Approx(11.0));
+    REQUIRE(SHEEP_STARTLE_RADIUS == Approx(64.0));
+    REQUIRE(SHEEP_STARTLE_BOOST  == Approx(1.6));
+
+    REQUIRE(SHEEP_GRAZE_PROBABILITY     == Approx(0.60));
+    REQUIRE(SHEEP_IDLE_PROBABILITY      == Approx(0.25));
+    REQUIRE(SHEEP_SLEEP_FROM_IDLE_PROB  == Approx(0.30));
+}
+
+TEST_CASE("sim_init defaults critter to None", "[critter][init]") {
+    Sim sim = sim_init(CANONICAL_TEST_SEED, 1920.0, DEFAULT_DENSITY);
+    REQUIRE(sim.currentCritter == CritterKind::None);
+    REQUIRE(count_sheep(sim) == 0);
+}
+
+TEST_CASE("sim_set_critter(Sheep) produces deterministic flock", "[critter][gen]") {
+    Sim sim = sim_init(CANONICAL_TEST_SEED, 1920.0, DEFAULT_DENSITY);
+    sim_set_critter(sim, CritterKind::Sheep);
+
+    REQUIRE(sim.currentCritter == CritterKind::Sheep);
+    const int k = count_sheep(sim);
+    REQUIRE(k >= SHEEP_COUNT_MIN);
+    REQUIRE(k <= SHEEP_COUNT_MAX);
+
+    const double groundY = sim.windowHeight;
+    for (const Entity& e : sim.entities) {
+        if (e.kind != EntityKind::Sheep) continue;
+        REQUIRE(e.state == SHEEP_STATE_WALKING);
+        REQUIRE(e.stateTimer >= SHEEP_WALK_DURATION_MIN);
+        REQUIRE(e.stateTimer <  SHEEP_WALK_DURATION_MAX);
+        REQUIRE(std::fabs(e.vx) >= SHEEP_WALK_SPEED_MIN);
+        REQUIRE(std::fabs(e.vx) <  SHEEP_WALK_SPEED_MAX);
+        const double margin = e.size + 8.0;
+        REQUIRE(e.x >= margin);
+        REQUIRE(e.x <= sim.monitorWidth - margin);
+        REQUIRE(e.y == Approx(groundY - SHEEP_BODY_HEIGHT - SHEEP_LEG_LENGTH));
+        REQUIRE(e.lifetime < 0.0); // infinite — sheep don't expire
+        REQUIRE(e.nameIndex < sizeof(SHEEP_NAME_POOL) / sizeof(SHEEP_NAME_POOL[0]));
+    }
+}
+
+TEST_CASE("Sheep PRNG draw order matches a side stream", "[critter][prng]") {
+    // Independent side stream that walks the documented sequence:
+    //   count
+    //   per-sheep: x, speed, dir-coin, seed, stateTimer, nameIndex
+    Prng side;
+    prng_init(side, CANONICAL_TEST_SEED ^ CRITTER_PRNG_SALT);
+
+    Sim sim = sim_init(CANONICAL_TEST_SEED, 1920.0, DEFAULT_DENSITY);
+    sim_set_critter(sim, CritterKind::Sheep);
+
+    const double countDraw = prng_uniform(side, SHEEP_COUNT_MIN, SHEEP_COUNT_MAX + 1);
+    int expectedCount = static_cast<int>(std::floor(countDraw));
+    if (expectedCount < SHEEP_COUNT_MIN) expectedCount = SHEEP_COUNT_MIN;
+    if (expectedCount > SHEEP_COUNT_MAX) expectedCount = SHEEP_COUNT_MAX;
+    REQUIRE(count_sheep(sim) == expectedCount);
+
+    int seen = 0;
+    for (const Entity& e : sim.entities) {
+        if (e.kind != EntityKind::Sheep) continue;
+        const double margin = SHEEP_BODY_RADIUS + 8.0;
+        const double expectedX = prng_uniform(side, margin, 1920.0 - margin);
+        const double expectedSpeed = prng_uniform(side, SHEEP_WALK_SPEED_MIN, SHEEP_WALK_SPEED_MAX);
+        const double dirCoin = prng_uniform(side, 0.0, 1.0);
+        const double expectedDir = (dirCoin < 0.5) ? -1.0 : 1.0;
+        const uint32_t expectedSeed = prng_next_u32(side);
+        const double expectedTimer = prng_uniform(side, SHEEP_WALK_DURATION_MIN, SHEEP_WALK_DURATION_MAX);
+        const uint8_t expectedNameIndex = static_cast<uint8_t>(prng_index(side,
+            static_cast<uint32_t>(sizeof(SHEEP_NAME_POOL) / sizeof(SHEEP_NAME_POOL[0]))));
+
+        REQUIRE(e.x == Approx(expectedX));
+        REQUIRE(e.vx == Approx(expectedSpeed * expectedDir));
+        REQUIRE(e.seed == expectedSeed);
+        REQUIRE(e.stateTimer == Approx(expectedTimer));
+        REQUIRE(e.nameIndex == expectedNameIndex);
+        ++seen;
+    }
+    REQUIRE(seen == expectedCount);
+}
+
+TEST_CASE("canonical critter name indices are stable and species-local", "[critter][names]") {
+    Sim sim = sim_init(CANONICAL_TEST_SEED, 1920.0, DEFAULT_DENSITY);
+    sim_set_critter(sim, CritterKind::Sheep);
+    const uint8_t expectedSheepNames[] = { 4, 7 };
+    int sheepSeen = 0;
+    for (const Entity& e : sim.entities) {
+        if (e.kind != EntityKind::Sheep) continue;
+        REQUIRE(sheepSeen < static_cast<int>(sizeof(expectedSheepNames) / sizeof(expectedSheepNames[0])));
+        REQUIRE(e.nameIndex == expectedSheepNames[sheepSeen]);
+        REQUIRE(std::wcscmp(SHEEP_NAME_POOL[e.nameIndex], sheepSeen == 0 ? L"Pippin" : L"Hazel") == 0);
+        ++sheepSeen;
+    }
+    REQUIRE(sheepSeen == 2);
+
+    sim_set_critter(sim, CritterKind::Cat);
+    const uint8_t expectedCatNames[] = { 4 };
+    int catSeen = 0;
+    for (const Entity& e : sim.entities) {
+        if (e.kind != EntityKind::Cat) continue;
+        REQUIRE(catSeen < static_cast<int>(sizeof(expectedCatNames) / sizeof(expectedCatNames[0])));
+        REQUIRE(e.nameIndex == expectedCatNames[catSeen]);
+        REQUIRE(e.nameIndex < sizeof(CAT_NAME_POOL) / sizeof(CAT_NAME_POOL[0]));
+        REQUIRE(std::wcscmp(CAT_NAME_POOL[e.nameIndex], L"Smokey") == 0);
+        ++catSeen;
+    }
+    REQUIRE(catSeen == 1);
+}
+
+TEST_CASE("sim_set_critter_count(0) preserves random sheep count draw", "[critter][count]") {
+    bool sawMin = false;
+    bool sawMax = false;
+    for (uint64_t i = 0; i < 64; ++i) {
+        const uint64_t seed = CANONICAL_TEST_SEED + i * 0x9E3779B97F4A7C15ull;
+        Sim sim = sim_init(seed, 1920.0, DEFAULT_DENSITY);
+        sim_set_critter_count(sim, 3);
+        sim_set_critter_count(sim, 0);
+        sim_set_critter(sim, CritterKind::Sheep);
+
+        Prng side;
+        prng_init(side, seed ^ CRITTER_PRNG_SALT);
+        const double countDraw = prng_uniform(side, SHEEP_COUNT_MIN, SHEEP_COUNT_MAX + 1);
+        int expectedCount = static_cast<int>(std::floor(countDraw));
+        if (expectedCount < SHEEP_COUNT_MIN) expectedCount = SHEEP_COUNT_MIN;
+        if (expectedCount > SHEEP_COUNT_MAX) expectedCount = SHEEP_COUNT_MAX;
+
+        REQUIRE(count_sheep(sim) == expectedCount);
+        sawMin = sawMin || expectedCount == SHEEP_COUNT_MIN;
+        sawMax = sawMax || expectedCount == SHEEP_COUNT_MAX;
+    }
+    REQUIRE(sawMin);
+    REQUIRE(sawMax);
+}
+
+TEST_CASE("fixed sheep count override skips the count PRNG draw", "[critter][count][prng]") {
+    Sim sim = sim_init(CANONICAL_TEST_SEED, 1920.0, DEFAULT_DENSITY);
+    sim_set_critter(sim, CritterKind::Sheep);
+    sim_set_critter_count(sim, 3);
+
+    REQUIRE(sim.critterCountOverride == 3);
+    REQUIRE(count_sheep(sim) == 3);
+
+    Prng side;
+    prng_init(side, CANONICAL_TEST_SEED ^ CRITTER_PRNG_SALT);
+    int seen = 0;
+    for (const Entity& e : sim.entities) {
+        if (e.kind != EntityKind::Sheep) continue;
+        const double margin = SHEEP_BODY_RADIUS + 8.0;
+        const double expectedX = prng_uniform(side, margin, 1920.0 - margin);
+        const double expectedSpeed = prng_uniform(side, SHEEP_WALK_SPEED_MIN, SHEEP_WALK_SPEED_MAX);
+        const double dirCoin = prng_uniform(side, 0.0, 1.0);
+        const double expectedDir = (dirCoin < 0.5) ? -1.0 : 1.0;
+        const uint32_t expectedSeed = prng_next_u32(side);
+        const double expectedTimer = prng_uniform(side, SHEEP_WALK_DURATION_MIN, SHEEP_WALK_DURATION_MAX);
+        const uint8_t expectedNameIndex = static_cast<uint8_t>(prng_index(side,
+            static_cast<uint32_t>(sizeof(SHEEP_NAME_POOL) / sizeof(SHEEP_NAME_POOL[0]))));
+
+        REQUIRE(e.x == Approx(expectedX));
+        REQUIRE(e.vx == Approx(expectedSpeed * expectedDir));
+        REQUIRE(e.seed == expectedSeed);
+        REQUIRE(e.stateTimer == Approx(expectedTimer));
+        REQUIRE(e.nameIndex == expectedNameIndex);
+        ++seen;
+    }
+    REQUIRE(seen == 3);
+}
+
+TEST_CASE("fixed critter count override supports tray range and clamps", "[critter][count]") {
+    Sim sim = sim_init(CANONICAL_TEST_SEED, 1920.0, DEFAULT_DENSITY);
+    sim_set_critter(sim, CritterKind::Sheep);
+
+    sim_set_critter_count(sim, 6);
+    REQUIRE(count_sheep(sim) == 6);
+
+    sim_set_critter_count(sim, 8);
+    REQUIRE(count_sheep(sim) == PET_COUNT_MAX_PER_MONITOR);
+
+    sim_set_critter(sim, CritterKind::Cat);
+    sim_set_critter_count(sim, 2);
+    REQUIRE(count_kind(sim, EntityKind::Cat) == 2);
+    REQUIRE(count_sheep(sim) == 0);
+}
+
+TEST_CASE("sim_set_critter(None) clears all ground critters",
+          "[critter][toggle]") {
+    Sim sim = sim_init(CANONICAL_TEST_SEED, 1920.0, DEFAULT_DENSITY);
+    sim_set_critter(sim, CritterKind::Sheep);
+    REQUIRE(count_sheep(sim) >= SHEEP_COUNT_MIN);
+    REQUIRE(count_kind(sim, EntityKind::Cat) == 0);
+
+    sim_set_critter(sim, CritterKind::None);
+    REQUIRE(count_sheep(sim) == 0);
+    REQUIRE(count_kind(sim, EntityKind::Cat) == 0);
+    REQUIRE(count_kind(sim, EntityKind::Bunny) == 0);
+    REQUIRE(count_kind(sim, EntityKind::Hedgehog) == 0);
+}
+
+TEST_CASE("sim_set_scene gates active sheep to Grass", "[critter][scene]") {
+    Sim sim = sim_init(CANONICAL_TEST_SEED, 1920.0, DEFAULT_DENSITY);
+    sim_set_critter(sim, CritterKind::Sheep);
+    const int sheepCountGrass = count_sheep(sim);
+    REQUIRE(sheepCountGrass >= SHEEP_COUNT_MIN);
+
+    sim_set_scene(sim, Scene::Desert);
+    REQUIRE(count_sheep(sim) == 0);
+    REQUIRE(sim.currentCritter == CritterKind::Sheep);
+
+    sim_set_scene(sim, Scene::Winter);
+    REQUIRE(count_sheep(sim) == 0);
+    REQUIRE(sim.currentCritter == CritterKind::Sheep);
+
+    sim_set_scene(sim, Scene::Grass);
+    REQUIRE(count_sheep(sim) == sheepCountGrass);
+}
+
+TEST_CASE("Click within SHEEP_STARTLE_RADIUS triggers hop away", "[critter][click]") {
+    Sim sim = sim_init(CANONICAL_TEST_SEED, 1920.0, DEFAULT_DENSITY);
+    sim_set_critter(sim, CritterKind::Sheep);
+
+    Entity* target = nullptr;
+    for (Entity& e : sim.entities) {
+        if (e.kind == EntityKind::Sheep) { target = &e; break; }
+    }
+    REQUIRE(target != nullptr);
+
+    // Click 16 DIP to the left of the sheep — well within startle radius,
+    // inside the cut band (so the early y-gate doesn't reject).
+    const double clickX = target->x - 16.0;
+    const double clickY = sim.windowHeight - 20.0;
+    target->age = 5.0; // pre-set age to verify reset
+
+    InputEvent ev{};
+    ev.type = EventType::Click;
+    ev.x = clickX;
+    ev.y = clickY;
+    ev.time = 0.0;
+    sim_apply_click(sim, ev);
+
+    Entity* after = nullptr;
+    for (Entity& e : sim.entities) {
+        if (e.kind == EntityKind::Sheep) { after = &e; break; }
+    }
+    REQUIRE(after != nullptr);
+    REQUIRE(after->state == SHEEP_STATE_HOPPING);
+    REQUIRE(after->stateTimer == Approx(SHEEP_HOP_DURATION));
+    REQUIRE(after->age == Approx(0.0));
+    REQUIRE(after->vx > 0.0); // sheep was right of click → vx flipped to +
+    REQUIRE(std::fabs(after->vx) <= SHEEP_WALK_SPEED_MAX * SHEEP_STARTLE_BOOST);
+}
+
+TEST_CASE("Click outside SHEEP_STARTLE_RADIUS leaves sheep alone", "[critter][click]") {
+    Sim sim = sim_init(CANONICAL_TEST_SEED, 1920.0, DEFAULT_DENSITY);
+    sim_set_critter(sim, CritterKind::Sheep);
+
+    Entity* target = nullptr;
+    for (Entity& e : sim.entities) {
+        if (e.kind == EntityKind::Sheep) { target = &e; break; }
+    }
+    REQUIRE(target != nullptr);
+    const uint8_t stateBefore = target->state;
+    const double  vxBefore    = target->vx;
+
+    // Click far away (300 DIP) but still in the cut band.
+    const double clickX = target->x + SHEEP_STARTLE_RADIUS + 200.0;
+    const double clickY = sim.windowHeight - 20.0;
+    InputEvent ev{};
+    ev.type = EventType::Click;
+    ev.x = clickX;
+    ev.y = clickY;
+    ev.time = 0.0;
+    sim_apply_click(sim, ev);
+
+    Entity* after = nullptr;
+    for (Entity& e : sim.entities) {
+        if (e.kind == EntityKind::Sheep) { after = &e; break; }
+    }
+    REQUIRE(after != nullptr);
+    REQUIRE(after->state == stateBefore);
+    REQUIRE(after->vx == Approx(vxBefore));
+}

src/modules/DesktopGrass/DesktopGrass.Native.Tests/src/cut_tests.cpp

@@ -0,0 +1,259 @@
+// cut_tests.cpp
+//
+// Cut state animation tests (architecture.md §9).
+
+#include "../third_party/catch2/catch.hpp"
+#include "Sim.h"
+#include "snapshot_data.h"
+
+#include <cmath>
+#include <vector>
+
+using namespace desktopgrass;
+using namespace desktopgrass::test;
+
+namespace {
+
+Sim make_sim_with_blades(std::initializer_list<double> baseXs) {
+    Sim sim;
+    sim.windowHeight = STRIP_HEIGHT + HEADROOM;
+    for (double x : baseXs) {
+        Blade b{};
+        b.baseX            = x;
+        b.height           = 20.0;
+        b.thickness        = 1.5;
+        b.swayPhaseOffset  = 0.0;
+        b.stiffness        = 1.0;
+        b.cutHeight        = 1.0;
+        b.cutInitialHeight = 1.0;
+        b.cutAnimStart     = -1.0;
+        sim.blades.push_back(b);
+    }
+    return sim;
+}
+
+InputEvent click(double x, double y, double t) {
+    return InputEvent{ EventType::Click, x, y, t };
+}
+
+} // anonymous
+
+TEST_CASE("click inside cut band animates blades within radius to 0", "[cut]") {
+    Sim sim = make_sim_with_blades({100.0, 110.0, 200.0});
+    const double y_in_band = sim.windowHeight - 40.0; // inside strip
+
+    InputEvent ev = click(100.0, y_in_band, 0.0);
+    sim_tick(sim, 0.0, &ev, 1);
+
+    // Apply 5 ticks of 50 ms (total = 250 ms > CUT_DURATION_SEC).
+    for (int i = 0; i < 5; ++i) {
+        sim_tick(sim, 0.05, nullptr, 0);
+    }
+
+    REQUIRE(sim.blades[0].cutHeight == Approx(0.0));
+    REQUIRE(sim.blades[0].cutAnimStart == Approx(-1.0));
+    REQUIRE(sim.blades[1].cutHeight == Approx(0.0));
+    // Blade at 200 is outside CUT_RADIUS = 30.
+    REQUIRE(sim.blades[2].cutHeight == Approx(1.0));
+    REQUIRE(sim.blades[2].cutAnimStart == Approx(-1.0));
+}
+
+TEST_CASE("cut animation is linear over CUT_DURATION_SEC", "[cut]") {
+    Sim sim = make_sim_with_blades({100.0});
+    const double y = sim.windowHeight - 40.0;
+
+    InputEvent ev = click(100.0, y, 0.0);
+    sim_tick(sim, 0.0, &ev, 1);
+    // After tick(0.0) globalTime = 0 still; cutAnimStart = 0.
+
+    // 50 ms in → cutHeight ≈ 0.75.
+    sim_tick(sim, 0.05, nullptr, 0);
+    REQUIRE(sim.blades[0].cutHeight == Approx(0.75).margin(1e-9));
+
+    // 100 ms in → 0.5.
+    sim_tick(sim, 0.05, nullptr, 0);
+    REQUIRE(sim.blades[0].cutHeight == Approx(0.5).margin(1e-9));
+
+    // 150 ms in → 0.25.
+    sim_tick(sim, 0.05, nullptr, 0);
+    REQUIRE(sim.blades[0].cutHeight == Approx(0.25).margin(1e-9));
+
+    // 200 ms in → 0.0 and idle.
+    sim_tick(sim, 0.05, nullptr, 0);
+    REQUIRE(sim.blades[0].cutHeight == Approx(0.0).margin(1e-9));
+    REQUIRE(sim.blades[0].cutAnimStart < 0.0);
+}
+
+TEST_CASE("click outside cut band is ignored", "[cut]") {
+    Sim sim = make_sim_with_blades({100.0});
+    const double y_above = sim.windowHeight - STRIP_HEIGHT - 5.0;
+
+    InputEvent ev = click(100.0, y_above, 0.0);
+    sim_tick(sim, 0.0, &ev, 1);
+
+    REQUIRE(sim.blades[0].cutHeight == Approx(1.0));
+    REQUIRE(sim.blades[0].cutAnimStart < 0.0);
+}
+
+TEST_CASE("repeat click on in-flight blade is idempotent", "[cut]") {
+    Sim sim = make_sim_with_blades({100.0});
+    const double y = sim.windowHeight - 40.0;
+
+    InputEvent first = click(100.0, y, 0.0);
+    sim_tick(sim, 0.0, &first, 1);
+
+    // Mid-animation second click → should not reset cutAnimStart.
+    sim_tick(sim, 0.05, nullptr, 0);  // 0.05 elapsed; cutHeight = 0.75
+    const double startSnapshot = sim.blades[0].cutAnimStart;
+    const double heightSnapshot = sim.blades[0].cutHeight;
+
+    InputEvent second = click(100.0, y, 0.05);
+    sim_tick(sim, 0.0, &second, 1);
+
+    REQUIRE(sim.blades[0].cutAnimStart    == Approx(startSnapshot));
+    REQUIRE(sim.blades[0].cutInitialHeight == Approx(1.0));
+    REQUIRE(sim.blades[0].cutHeight == Approx(heightSnapshot));
+}
+
+TEST_CASE("click on already-cut blade is a no-op", "[cut]") {
+    Sim sim = make_sim_with_blades({100.0});
+    sim.blades[0].cutHeight        = 0.0;
+    sim.blades[0].cutInitialHeight = 0.0;
+    sim.blades[0].cutAnimStart     = -1.0;
+
+    const double y = sim.windowHeight - 40.0;
+    InputEvent ev = click(100.0, y, 0.0);
+    sim_tick(sim, 0.0, &ev, 1);
+
+    REQUIRE(sim.blades[0].cutHeight    == Approx(0.0));
+    REQUIRE(sim.blades[0].cutAnimStart  < 0.0);
+}
+
+TEST_CASE("blades outside cut radius are untouched", "[cut]") {
+    Sim sim = make_sim_with_blades({100.0, 131.0, 200.0});
+    const double y = sim.windowHeight - 40.0;
+
+    InputEvent ev = click(100.0, y, 0.0);
+    sim_tick(sim, 0.0, &ev, 1);
+
+    REQUIRE(sim.blades[0].cutAnimStart >= 0.0);
+    REQUIRE(sim.blades[1].cutAnimStart  < 0.0);
+    REQUIRE(sim.blades[2].cutAnimStart  < 0.0);
+}
+
+TEST_CASE("compute_blade_stroke degenerates to a stump under threshold", "[cut][geometry]") {
+    Blade b{};
+    b.baseX            = 100.0;
+    b.height           = 20.0;
+    b.thickness        = 1.5;
+    b.hue              = 2;
+    b.cutHeight        = 0.04;       // below CUT_STUMP_THRESHOLD = 0.05
+    b.effectiveLean    = 5.0;
+    b.cutInitialHeight = 1.0;
+    b.cutAnimStart     = 0.0;
+
+    Stroke s = compute_blade_stroke(b, 110.0, Scene::Grass);
+    REQUIRE(s.tip.x == Approx(100.0));
+    REQUIRE(s.tip.y == Approx(110.0 - STUMP_HEIGHT));
+    REQUIRE(s.argb  == PALETTE[2]);
+}
+
+TEST_CASE("compute_blade_stroke produces vertical line when lean is zero", "[cut][geometry]") {
+    Blade b{};
+    b.baseX         = 100.0;
+    b.height        = 20.0;
+    b.thickness     = 1.5;
+    b.hue           = 1;
+    b.cutHeight     = 1.0;
+    b.effectiveLean = 0.0;
+
+    Stroke s = compute_blade_stroke(b, 110.0, Scene::Grass);
+    REQUIRE(s.base.x    == Approx(100.0));
+    REQUIRE(s.base.y    == Approx(110.0));
+    REQUIRE(s.tip.x     == Approx(100.0));
+    REQUIRE(s.tip.y     == Approx(90.0));
+    REQUIRE(s.control.x == Approx(100.0));
+}
+
+// ---------------------------------------------------------------------------
+// Cut-floor (stubble) variation
+// ---------------------------------------------------------------------------
+
+TEST_CASE("generated blades get a per-blade cut floor within spec range", "[cut][floor]") {
+    std::vector<Blade> blades;
+    generate_blades(CANONICAL_TEST_SEED, 1920.0, 1.0, blades);
+    REQUIRE(blades.size() > 50);
+
+    for (const Blade& b : blades) {
+        REQUIRE(b.cutFloor >= CUT_FLOOR_MIN);
+        REQUIRE(b.cutFloor <  CUT_FLOOR_MAX);
+        // Stubble must render as a short blade, never a degenerate stump.
+        REQUIRE(b.cutFloor >= CUT_STUMP_THRESHOLD);
+    }
+
+    // The whole point is variation: not every blade settles at the same height.
+    bool varies = false;
+    for (std::size_t i = 1; i < blades.size(); ++i) {
+        if (blades[i].cutFloor != blades[0].cutFloor) { varies = true; break; }
+    }
+    REQUIRE(varies);
+}
+
+TEST_CASE("cut settles at the per-blade stubble floor, not flat zero", "[cut][floor]") {
+    Blade b{};
+    b.height           = 20.0;
+    b.thickness        = 1.5;
+    b.cutHeight        = 1.0;
+    b.cutInitialHeight = 1.0;
+    b.cutFloor         = 0.12;
+    b.cutAnimStart     = 0.0;
+
+    // Advance past the full cut duration.
+    advance_cut(b, CUT_DURATION_SEC + 0.01);
+
+    REQUIRE(b.cutHeight    == Approx(0.12));
+    REQUIRE(b.cutAnimStart == Approx(-1.0));
+}
+
+TEST_CASE("cut-down animation lerps toward the floor", "[cut][floor]") {
+    Blade b{};
+    b.height           = 20.0;
+    b.cutHeight        = 1.0;
+    b.cutInitialHeight = 1.0;
+    b.cutFloor         = 0.10;
+    b.cutAnimStart     = 0.0;
+
+    // Half-way through the cut: lerp(1.0 -> 0.10) at t=0.5 = 0.10 + 0.90*0.5.
+    advance_cut(b, CUT_DURATION_SEC * 0.5);
+    REQUIRE(b.cutHeight == Approx(0.10 + 0.90 * 0.5).margin(1e-9));
+}
+
+TEST_CASE("regrowth grows back from the floor to full height", "[cut][floor][regrowth]") {
+    Blade b{};
+    b.height         = 20.0;
+    b.cutFloor       = 0.10;
+    b.cutHeight      = 0.10;
+    b.cutAnimStart   = -1.0;
+    b.regrowDuration = 0.4;
+    b.regrowStart    = 0.0;
+
+    // Half-way through regrowth: lerp(0.10 -> 1.0) at t=0.5.
+    advance_cut(b, 0.2);
+    REQUIRE(b.cutHeight == Approx(0.10 + 0.90 * 0.5).margin(1e-9));
+
+    // Fully regrown.
+    advance_cut(b, 0.4);
+    REQUIRE(b.cutHeight == Approx(1.0).margin(1e-9));
+}
+
+TEST_CASE("zero-floor blades still collapse fully (back-compat)", "[cut][floor]") {
+    Blade b{};
+    b.height           = 20.0;
+    b.cutHeight        = 1.0;
+    b.cutInitialHeight = 1.0;
+    b.cutFloor         = 0.0;
+    b.cutAnimStart     = 0.0;
+
+    advance_cut(b, CUT_DURATION_SEC + 0.01);
+    REQUIRE(b.cutHeight == Approx(0.0));
+}

src/modules/DesktopGrass/DesktopGrass.Native.Tests/src/desert_tests.cpp

@@ -0,0 +1,220 @@
+// desert_tests.cpp - §14 Desert scene cacti + tumbleweeds.
+
+#include "../third_party/catch2/catch.hpp"
+#include "Sim.h"
+#include "snapshot_data.h"
+
+#include <cmath>
+#include <cstddef>
+#include <vector>
+
+using namespace desktopgrass;
+
+namespace {
+
+constexpr double kMonitor1920 = 1920.0;
+
+struct ExpectedCactus {
+    std::size_t slotIndex = 0;
+    uint8_t type = 0;
+    double height = 0.0;
+    double width = 0.0;
+    int8_t armSide = +1;
+};
+
+ExpectedCactus first_expected_cactus(std::size_t bladeCount) {
+    Prng p;
+    prng_init(p, CANONICAL_TEST_SEED ^ CACTUS_PRNG_SALT);
+
+    for (std::size_t i = 0; i < bladeCount; ++i) {
+        const double r = prng_uniform(p, 0.0, 1.0);
+        if (r >= CACTUS_PROBABILITY) continue;
+
+        ExpectedCactus expected{};
+        expected.slotIndex = i;
+        expected.height = prng_uniform(p, CACTUS_HEIGHT_MIN, CACTUS_HEIGHT_MAX);
+        expected.width = prng_uniform(p, CACTUS_WIDTH_MIN, CACTUS_WIDTH_MAX);
+
+        const double armDraw = prng_uniform(p, 0.0, 1.0);
+        const double noArmThreshold = 1.0 - CACTUS_ARM_PROBABILITY;
+        const double twoArmThreshold = noArmThreshold + CACTUS_TWO_ARM_PROBABILITY * CACTUS_ARM_PROBABILITY;
+        if (armDraw < noArmThreshold) {
+            expected.type = 0;
+        } else if (armDraw < twoArmThreshold) {
+            expected.type = 2;
+        } else {
+            expected.type = 1;
+            expected.armSide = prng_uniform(p, 0.0, 1.0) < 0.5
+                ? static_cast<int8_t>(-1)
+                : static_cast<int8_t>(+1);
+        }
+        if (expected.height < CACTUS_ARM_MIN_HEIGHT) {
+            expected.type = 0;
+            expected.armSide = +1;
+        }
+        return expected;
+    }
+
+    FAIL("canonical seed produced no cactus slot");
+    return {};
+}
+
+int expected_tumbleweed_count(double monitorWidth) {
+    if (monitorWidth < 480.0) return 0;
+    int count = static_cast<int>(std::floor(monitorWidth / 1920.0 * static_cast<double>(TUMBLEWEED_COUNT_PER_1920DIP)));
+    return count < 1 ? 1 : count;
+}
+
+} // anonymous
+
+TEST_CASE("Desert constants are pinned", "[desert][constants]") {
+    REQUIRE(CACTUS_PROBABILITY == Approx(0.005));
+    REQUIRE(CACTUS_HEIGHT_MIN == Approx(30.0));
+    REQUIRE(CACTUS_HEIGHT_MAX == Approx(70.0));
+    REQUIRE(CACTUS_COLOR == 0xFF2D7A2Du);
+    REQUIRE(TUMBLEWEED_COUNT_PER_1920DIP == 4);
+    REQUIRE(TUMBLEWEED_SPEED_MAX == Approx(72.0));
+    REQUIRE(TUMBLEWEED_PRNG_SALT == 0x7B0117CA7B0117CAull);
+}
+
+TEST_CASE("sim_set_scene Desert clears entities and generates cacti", "[desert][scene]") {
+    Sim sim = sim_init(CANONICAL_TEST_SEED, kMonitor1920, DEFAULT_DENSITY);
+    Entity fake{};
+    fake.kind = EntityKind::Snowflake;
+    sim.entities.push_back(fake);
+
+    sim_set_scene(sim, Scene::Desert);
+
+    REQUIRE(sim.currentScene == Scene::Desert);
+    REQUIRE(sim.entities.size() == static_cast<std::size_t>(expected_tumbleweed_count(kMonitor1920)));
+    for (const Entity& e : sim.entities) REQUIRE(e.kind == EntityKind::Tumbleweed);
+
+    std::size_t cactusCount = 0;
+    for (const Blade& b : sim.blades) if (b.isCactus) ++cactusCount;
+    REQUIRE(cactusCount >= 1);
+    REQUIRE(cactusCount <= 10);
+}
+
+TEST_CASE("First cactus matches the spec-derived PRNG snapshot", "[desert][cactus]") {
+    Sim sim = sim_init(CANONICAL_TEST_SEED, kMonitor1920, DEFAULT_DENSITY);
+    const ExpectedCactus expected = first_expected_cactus(sim.blades.size());
+
+    sim_set_scene(sim, Scene::Desert);
+
+    REQUIRE(expected.slotIndex < sim.blades.size());
+    const Blade& b = sim.blades[expected.slotIndex];
+    REQUIRE(b.isCactus);
+    REQUIRE(b.cactusType == expected.type);
+    REQUIRE(b.cactusHeight == Approx(expected.height).margin(1e-12));
+    REQUIRE(b.cactusWidth == Approx(expected.width).margin(1e-12));
+    if (expected.type == 1) REQUIRE(b.cactusArmSide == expected.armSide);
+}
+
+TEST_CASE("Grass scene restores original flower and mushroom slot variants", "[desert][restore]") {
+    Sim sim = sim_init(CANONICAL_TEST_SEED, kMonitor1920, DEFAULT_DENSITY);
+    const ExpectedCactus expected = first_expected_cactus(sim.blades.size());
+    REQUIRE(expected.slotIndex < sim.blades.size());
+
+    Blade& target = sim.blades[expected.slotIndex];
+    target.isFlower = true;
+    target.isMushroom = true;
+    target.originalIsFlower = true;
+    target.originalIsMushroom = true;
+
+    sim_set_scene(sim, Scene::Desert);
+    REQUIRE(sim.blades[expected.slotIndex].isCactus);
+    REQUIRE_FALSE(sim.blades[expected.slotIndex].isFlower);
+    REQUIRE_FALSE(sim.blades[expected.slotIndex].isMushroom);
+
+    sim_set_scene(sim, Scene::Grass);
+    REQUIRE_FALSE(sim.blades[expected.slotIndex].isCactus);
+    REQUIRE(sim.blades[expected.slotIndex].isFlower);
+    REQUIRE(sim.blades[expected.slotIndex].isMushroom);
+}
+
+TEST_CASE("Desert generates the expected tumbleweed count", "[desert][tumbleweed]") {
+    Sim sim = sim_init(CANONICAL_TEST_SEED, kMonitor1920, DEFAULT_DENSITY);
+    sim_set_scene(sim, Scene::Desert);
+
+    const int expected = expected_tumbleweed_count(kMonitor1920);
+    REQUIRE(expected >= 1);
+    REQUIRE(sim.entities.size() == static_cast<std::size_t>(expected));
+}
+
+TEST_CASE("First tumbleweed matches the spec-derived PRNG snapshot", "[desert][tumbleweed]") {
+    Sim sim = sim_init(CANONICAL_TEST_SEED, kMonitor1920, DEFAULT_DENSITY);
+    sim_set_scene(sim, Scene::Desert);
+    REQUIRE_FALSE(sim.entities.empty());
+
+    Prng p;
+    prng_init(p, CANONICAL_TEST_SEED ^ TUMBLEWEED_PRNG_SALT);
+    const double expectedSize = prng_uniform(p, TUMBLEWEED_SIZE_MIN, TUMBLEWEED_SIZE_MAX);
+    const double expectedX = prng_uniform(p, 0.0, kMonitor1920);
+    const double expectedY = sim.windowHeight - prng_uniform(p, TUMBLEWEED_Y_OFFSET_MIN, TUMBLEWEED_Y_OFFSET_MAX);
+    const double speed = prng_uniform(p, TUMBLEWEED_SPEED_MIN, TUMBLEWEED_SPEED_MAX);
+    const double direction = prng_uniform(p, 0.0, 1.0) < 0.5 ? -1.0 : 1.0;
+    const double expectedVx = direction * speed;
+    const double expectedRotation = prng_uniform(p, 0.0, 6.28318530717958647692);
+
+    const Entity& e = sim.entities[0];
+    REQUIRE(e.kind == EntityKind::Tumbleweed);
+    REQUIRE(e.size == Approx(expectedSize).margin(1e-12));
+    REQUIRE(e.x == Approx(expectedX).margin(1e-12));
+    REQUIRE(e.y == Approx(expectedY).margin(1e-12));
+    REQUIRE(e.vx == Approx(expectedVx).margin(1e-12));
+    REQUIRE(e.rotation == Approx(expectedRotation).margin(1e-12));
+    REQUIRE(e.rotationSpeed == Approx(expectedVx / expectedSize).margin(1e-12));
+}
+
+TEST_CASE("Tumbleweed respawns at the opposite edge when off-screen", "[desert][tumbleweed]") {
+    Sim sim = sim_init(CANONICAL_TEST_SEED, kMonitor1920, DEFAULT_DENSITY);
+    sim_set_scene(sim, Scene::Desert);
+    REQUIRE_FALSE(sim.entities.empty());
+
+    sim.entities[0].x = sim.monitorWidth + 100.0;
+    sim_tick_entities(sim, 0.0);
+
+    const Entity& e = sim.entities[0];
+    REQUIRE(e.kind == EntityKind::Tumbleweed);
+    REQUIRE(e.x == Approx(-e.size).margin(1e-12));
+    REQUIRE(e.vx > 0.0);
+}
+
+TEST_CASE("Tumbleweed hops above its baseline then settles", "[desert][tumbleweed]") {
+    Sim sim = sim_init(CANONICAL_TEST_SEED, kMonitor1920, DEFAULT_DENSITY);
+    sim_set_scene(sim, Scene::Desert);
+    REQUIRE_FALSE(sim.entities.empty());
+
+    double yBase = sim.entities[0].altitudeAnchor;
+    REQUIRE(sim.entities[0].y == Approx(yBase).margin(1e-9)); // starts grounded
+
+    double minY = sim.entities[0].y;
+    for (int i = 0; i < 900; ++i) {
+        sim_tick_entities(sim, 1.0 / 60.0);
+        Entity& t = sim.entities[0];
+        // Pin x on-screen so it doesn't roll off and respawn mid-test.
+        if (t.x < 50.0) t.x = 50.0;
+        if (t.x > sim.monitorWidth - 50.0) t.x = sim.monitorWidth - 50.0;
+        yBase = t.altitudeAnchor;
+        minY = std::min(minY, t.y);
+        REQUIRE(t.y <= yBase + 1e-6); // never sinks below the baseline
+    }
+
+    REQUIRE(minY < yBase - 1.0); // it left the ground at least once
+}
+
+TEST_CASE("Desert scene leaves the canonical first blade geometry bit-identical", "[desert][snapshot]") {
+    Sim sim = sim_init(CANONICAL_TEST_SEED, kMonitor1920, 1.0);
+    REQUIRE(sim.blades.size() == desktopgrass::test::CANONICAL_BLADE_COUNT);
+
+    sim_set_scene(sim, Scene::Desert);
+
+    const Blade& first = sim.blades[0];
+    const auto& expected = desktopgrass::test::CANONICAL_FIRST_10[0];
+    REQUIRE(first.baseX == Approx(expected.baseX).margin(1e-12));
+    REQUIRE(first.height == Approx(expected.height).margin(1e-12));
+    REQUIRE(first.thickness == Approx(expected.thickness).margin(1e-12));
+    REQUIRE(first.hue == expected.hue);
+    REQUIRE(first.swayPhaseOffset == Approx(expected.sway).margin(1e-12));
+    REQUIRE(first.stiffness == Approx(expected.stiffness).margin(1e-12));
+}

src/modules/DesktopGrass/DesktopGrass.Native.Tests/src/entity_skeleton_tests.cpp

@@ -0,0 +1,113 @@
+// entity_skeleton_tests.cpp
+//
+// Entity subsystem skeleton tests (architecture.md §13.2).
+//
+// Coverage:
+//   * EntityKind discriminants match the spec ({None=0, Tumbleweed=1,
+//     Snowflake=2}).
+//   * MAX_ENTITIES_PER_MONITOR is the locked cap (= 64).
+//   * sim_init defaults sim.entities to empty, capacity >= cap.
+//   * sim_set_scene clears entities (currently a no-op since the Grass
+//     scene generates none; §14/§15 add per-scene generators).
+//   * sim_tick_entities is safe on empty (no exceptions, no growth).
+//   * Tick on empty entities does not perturb other sim state (blades
+//     untouched, ambient PRNG untouched).
+
+#include "../third_party/catch2/catch.hpp"
+#include "Sim.h"
+
+using namespace desktopgrass;
+
+TEST_CASE("EntityKind has spec-locked discriminants", "[entities][enum]") {
+    REQUIRE(static_cast<int>(EntityKind::None)       == 0);
+    REQUIRE(static_cast<int>(EntityKind::Tumbleweed) == 1);
+    REQUIRE(static_cast<int>(EntityKind::Snowflake)  == 2);
+    REQUIRE(static_cast<int>(EntityKind::Sheep)      == 3);
+    REQUIRE(static_cast<int>(EntityKind::Cat)        == 4);
+    REQUIRE(static_cast<int>(EntityKind::Bunny)      == 6);
+    REQUIRE(static_cast<int>(EntityKind::Butterfly)  == 7);
+    REQUIRE(static_cast<int>(EntityKind::Firefly)    == 8);
+    REQUIRE(static_cast<int>(EntityKind::Bird)       == 9);
+    REQUIRE(MAX_ENTITIES_PER_MONITOR == 64);
+}
+
+TEST_CASE("sim_init reserves entities capacity", "[entities][init]") {
+    Sim sim = sim_init(CANONICAL_TEST_SEED, 1920.0, DEFAULT_DENSITY);
+    REQUIRE(sim.entities.empty());
+    REQUIRE(sim.entities.capacity() >= static_cast<std::size_t>(MAX_ENTITIES_PER_MONITOR));
+    REQUIRE(sim.entitySeed == CANONICAL_TEST_SEED);
+}
+
+TEST_CASE("sim_set_scene clears entities", "[entities][scene]") {
+    Sim sim = sim_init(CANONICAL_TEST_SEED, 1920.0, 1.0);
+    // Push a fake entity directly to verify scene-transition removal runs.
+    Entity fake{};
+    fake.kind = EntityKind::Tumbleweed;
+    fake.x = 100.0;
+    sim.entities.push_back(fake);
+    REQUIRE(sim.entities.size() == 1);
+
+    sim_set_scene(sim, Scene::Winter);
+    REQUIRE(sim.entities.empty());
+    REQUIRE(sim.entities.capacity() >= static_cast<std::size_t>(MAX_ENTITIES_PER_MONITOR));
+}
+
+TEST_CASE("sim_tick_entities is a no-op on empty outside Grass", "[entities][tick]") {
+    Sim sim = sim_init(CANONICAL_TEST_SEED, 1920.0, 1.0);
+    sim.currentScene = Scene::Desert;
+    const auto bladesBefore = sim.blades.size();
+    const auto prngBefore   = sim.ambientPrng.state;
+
+    sim_tick_entities(sim, 0.016);
+    sim_tick_entities(sim, 0.5);
+
+    REQUIRE(sim.entities.empty());
+    REQUIRE(sim.blades.size() == bladesBefore);
+    REQUIRE(sim.ambientPrng.state == prngBefore);
+}
+
+TEST_CASE("sim_tick_entities advances a populated entity", "[entities][tick]") {
+    Sim sim = sim_init(CANONICAL_TEST_SEED, 1920.0, 1.0);
+    sim.currentScene = Scene::Desert;
+    Entity e{};
+    e.kind          = EntityKind::Tumbleweed;
+    e.x             = 100.0;
+    e.y             = 50.0;
+    e.vx            = 50.0;    // DIP/sec
+    e.vy            = 0.0;
+    e.size          = 10.0;
+    e.rotation      = 0.5;
+    e.rotationSpeed = 1.0;     // rad/sec
+    e.age           = 0.0;
+    e.lifetime      = -1.0;    // infinite
+    e.seed          = 0xDEADBEEF;
+    sim.entities.push_back(e);
+
+    const double dt = 0.5;
+    sim_tick_entities(sim, dt);
+
+    REQUIRE(sim.entities.size() == 1);
+    const Entity& after = sim.entities[0];
+    REQUIRE(after.x == Approx(100.0 + 50.0 * dt));
+    REQUIRE(after.y == Approx(50.0));
+    REQUIRE(after.rotation == Approx(0.5 + 1.0 * dt));
+    REQUIRE(after.age == Approx(0.0 + dt));
+    REQUIRE(after.kind == EntityKind::Tumbleweed);
+}
+
+TEST_CASE("sim_tick calls sim_tick_entities (wiring check)", "[entities][tick]") {
+    Sim sim = sim_init(CANONICAL_TEST_SEED, 1920.0, 1.0);
+    sim.currentScene = Scene::Desert;
+    Entity e{};
+    e.kind = EntityKind::Snowflake;
+    e.x = 0.0; e.y = 0.0;
+    e.vx = 10.0; e.vy = 20.0;
+    e.size = 2.0;
+    e.age = 0.0; e.lifetime = 100.0;
+    sim.entities.push_back(e);
+
+    sim_tick(sim, 0.1, nullptr, 0);
+    REQUIRE(sim.entities.size() == 1);
+    REQUIRE(sim.entities[0].x == Approx(1.0));   // 10 * 0.1
+    REQUIRE(sim.entities[0].y == Approx(2.0));   // 20 * 0.1
+}

src/modules/DesktopGrass/DesktopGrass.Native.Tests/src/firefly_tests.cpp

@@ -0,0 +1,195 @@
+// firefly_tests.cpp - §17.7 ambient Firefly tests.
+
+#include "../third_party/catch2/catch.hpp"
+#include "Sim.h"
+
+#include <algorithm>
+#include <cmath>
+#include <vector>
+
+using namespace desktopgrass;
+
+namespace {
+constexpr double Monitor1920 = 1920.0;
+
+int count_kind(const Sim& sim, EntityKind kind) {
+    return static_cast<int>(std::count_if(sim.entities.begin(), sim.entities.end(),
+        [kind](const Entity& e) { return e.kind == kind; }));
+}
+
+Sim build_grass_sim(uint64_t seed = CANONICAL_TEST_SEED) {
+    Sim sim = sim_init(seed, Monitor1920, DEFAULT_DENSITY);
+    sim_set_scene(sim, Scene::Grass);
+    return sim;
+}
+
+int prng_count(Prng& side, int minCount, int maxCount) {
+    const double draw = prng_uniform(side, static_cast<double>(minCount), static_cast<double>(maxCount + 1));
+    int count = static_cast<int>(std::floor(draw));
+    if (count < minCount) count = minCount;
+    if (count > maxCount) count = maxCount;
+    return count;
+}
+} // namespace
+
+TEST_CASE("Firefly constants are pinned to spec values", "[firefly][constants]") {
+    REQUIRE(FIREFLY_COUNT_MIN == 3);
+    REQUIRE(FIREFLY_COUNT_MAX == 6);
+    REQUIRE(FIREFLY_DRIFT_SPEED_MIN == Approx(4.0));
+    REQUIRE(FIREFLY_DRIFT_SPEED_MAX == Approx(10.0));
+    REQUIRE(FIREFLY_BODY_RADIUS == Approx(1.2));
+    REQUIRE(FIREFLY_GLOW_RADIUS == Approx(5.0));
+    REQUIRE(FIREFLY_BLINK_PERIOD_MIN == Approx(1.4));
+    REQUIRE(FIREFLY_BLINK_PERIOD_MAX == Approx(2.6));
+    REQUIRE(FIREFLY_BLINK_DUTY == Approx(0.55));
+    REQUIRE(FIREFLY_BLINK_FADE == Approx(0.30));
+    REQUIRE(FIREFLY_DRIFT_FREQ_X == Approx(0.4));
+    REQUIRE(FIREFLY_DRIFT_FREQ_Y == Approx(0.6));
+    REQUIRE(FIREFLY_DRIFT_AMP_X == Approx(0.6));
+    REQUIRE(FIREFLY_DRIFT_AMP_Y == Approx(8.0));
+    REQUIRE(FIREFLY_ALTITUDE_MIN == Approx(8.0));
+    REQUIRE(FIREFLY_ALTITUDE_MAX == Approx(55.0));
+    REQUIRE(FIREFLY_BODY_COLOR == 0xFFFFEE88u);
+    REQUIRE(FIREFLY_GLOW_COLOR_RGB == 0xEEDD66u);
+    REQUIRE(FIREFLY_GLOW_ALPHA_MAX == 110);
+    REQUIRE(FIREFLY_BODY_ALPHA_MAX == 255);
+    REQUIRE(FIREFLY_PRNG_SALT == 0xF13EF1E7777ull);
+}
+
+TEST_CASE("Grass generation produces firefly count in range", "[firefly][gen]") {
+    for (uint64_t i = 0; i < 128; ++i) {
+        const uint64_t seed = CANONICAL_TEST_SEED + i * 0x9E3779B97F4A7C15ull;
+        Sim sim = build_grass_sim(seed);
+        REQUIRE(count_kind(sim, EntityKind::Firefly) >= FIREFLY_COUNT_MIN);
+        REQUIRE(count_kind(sim, EntityKind::Firefly) <= FIREFLY_COUNT_MAX);
+    }
+}
+
+TEST_CASE("Fireflies are Grass scene only", "[firefly][scene]") {
+    Sim sim = sim_init(CANONICAL_TEST_SEED, Monitor1920, DEFAULT_DENSITY);
+    sim_set_scene(sim, Scene::Desert);
+    REQUIRE(count_kind(sim, EntityKind::Firefly) == 0);
+    sim_set_scene(sim, Scene::Winter);
+    REQUIRE(count_kind(sim, EntityKind::Firefly) == 0);
+}
+
+TEST_CASE("Generated fireflies have speed altitude and blink period ranges", "[firefly][gen]") {
+    Sim sim = build_grass_sim();
+    for (const Entity& e : sim.entities) {
+        if (e.kind != EntityKind::Firefly) continue;
+        REQUIRE(e.baseSpeed >= FIREFLY_DRIFT_SPEED_MIN);
+        REQUIRE(e.baseSpeed <  FIREFLY_DRIFT_SPEED_MAX);
+        REQUIRE(e.altitudeAnchor >= FIREFLY_ALTITUDE_MIN);
+        REQUIRE(e.altitudeAnchor <  FIREFLY_ALTITUDE_MAX);
+        REQUIRE(e.blinkPeriod >= FIREFLY_BLINK_PERIOD_MIN);
+        REQUIRE(e.blinkPeriod <  FIREFLY_BLINK_PERIOD_MAX);
+    }
+}
+
+TEST_CASE("Firefly PRNG draw order matches side stream", "[firefly][prng]") {
+    Prng side;
+    prng_init(side, CANONICAL_TEST_SEED ^ FIREFLY_PRNG_SALT);
+    Sim sim = build_grass_sim();
+
+    const int expectedCount = prng_count(side, FIREFLY_COUNT_MIN, FIREFLY_COUNT_MAX);
+    REQUIRE(count_kind(sim, EntityKind::Firefly) == expectedCount);
+
+    int seen = 0;
+    for (const Entity& e : sim.entities) {
+        if (e.kind != EntityKind::Firefly) continue;
+        const double xFrac = prng_uniform(side, 0.0, 1.0);
+        const double yFrac = prng_uniform(side, 0.0, 1.0);
+        const uint64_t vxSign = prng_next_u64(side) & 1ull;
+        const double expectedDir = vxSign != 0ull ? 1.0 : -1.0;
+        const double expectedSpeed = prng_uniform(side, FIREFLY_DRIFT_SPEED_MIN, FIREFLY_DRIFT_SPEED_MAX);
+        const double expectedBlinkPeriod = prng_uniform(side, FIREFLY_BLINK_PERIOD_MIN, FIREFLY_BLINK_PERIOD_MAX);
+        const double expectedBlinkPhase = prng_uniform(side, 0.0, 1.0);
+        const double expectedPhaseY = prng_uniform(side, 0.0, 2.0 * 3.14159265358979323846);
+        const double expectedPhaseX = prng_uniform(side, 0.0, 2.0 * 3.14159265358979323846);
+        const double expectedAltitude = FIREFLY_ALTITUDE_MIN + yFrac * (FIREFLY_ALTITUDE_MAX - FIREFLY_ALTITUDE_MIN);
+        const double expectedVx = expectedDir * expectedSpeed * (1.0 + FIREFLY_DRIFT_AMP_X * std::sin(expectedPhaseX));
+
+        REQUIRE(e.x == Approx(xFrac * Monitor1920));
+        REQUIRE(e.altitudeAnchor == Approx(expectedAltitude));
+        REQUIRE(e.baseSpeed == Approx(expectedSpeed));
+        REQUIRE(e.blinkPeriod == Approx(expectedBlinkPeriod));
+        REQUIRE(e.blinkPhase == Approx(expectedBlinkPhase));
+        REQUIRE(e.vx == Approx(expectedVx));
+        REQUIRE(e.phaseY == Approx(expectedPhaseY));
+        REQUIRE(e.phaseX == Approx(expectedPhaseX));
+        ++seen;
+    }
+    REQUIRE(seen == expectedCount);
+}
+
+TEST_CASE("Firefly edge wrap preserves altitude anchor", "[firefly][motion]") {
+    Sim sim = build_grass_sim();
+    auto it = std::find_if(sim.entities.begin(), sim.entities.end(), [](const Entity& e) { return e.kind == EntityKind::Firefly; });
+    REQUIRE(it != sim.entities.end());
+    const double margin = FIREFLY_GLOW_RADIUS;
+    it->x = Monitor1920 + margin + 1.0;
+    it->vx = std::abs(it->vx);
+    const double altitude = it->altitudeAnchor;
+    sim.currentScene = Scene::Desert;
+
+    sim_tick_entities(sim, 0.016);
+
+    REQUIRE(it->x == Approx(-margin));
+    REQUIRE(it->altitudeAnchor == Approx(altitude));
+}
+
+TEST_CASE("Fireflies do not interact with cuts or pets", "[firefly][interaction]") {
+    Sim sim = sim_init(CANONICAL_TEST_SEED, Monitor1920, DEFAULT_DENSITY);
+    sim.entities.clear();
+    Entity firefly{};
+    firefly.kind = EntityKind::Firefly;
+    firefly.x = 500.0;
+    firefly.y = sim.windowHeight - STRIP_HEIGHT - 5.0;
+    firefly.vx = FIREFLY_DRIFT_SPEED_MIN;
+    firefly.baseSpeed = FIREFLY_DRIFT_SPEED_MIN;
+    firefly.altitudeAnchor = FIREFLY_ALTITUDE_MIN;
+    firefly.blinkPeriod = FIREFLY_BLINK_PERIOD_MIN;
+    firefly.lifetime = -1.0;
+    sim.entities.push_back(firefly);
+    Entity sheep{};
+    sheep.kind = EntityKind::Sheep;
+    sheep.x = firefly.x;
+    sheep.y = sim.windowHeight - SHEEP_BODY_HEIGHT - SHEEP_LEG_LENGTH;
+    sheep.vx = SHEEP_WALK_SPEED_MIN;
+    sheep.state = SHEEP_STATE_WALKING;
+    sheep.stateTimer = 10.0;
+    sim.entities.push_back(sheep);
+
+    InputEvent ev{};
+    ev.type = EventType::Click;
+    ev.x = firefly.x;
+    ev.y = firefly.y;
+    sim_apply_click(sim, ev);
+
+    REQUIRE(sim.entities[0].kind == EntityKind::Firefly);
+    REQUIRE(sim.entities[0].baseSpeed == Approx(FIREFLY_DRIFT_SPEED_MIN));
+    REQUIRE(sim.entities[1].state == SHEEP_STATE_WALKING);
+    for (const Blade& b : sim.blades) REQUIRE(b.cutAnimStart < 0.0);
+}
+
+TEST_CASE("Firefly blink brightness has on and off phases", "[firefly][blink]") {
+    const double period = 2.0;
+    REQUIRE(firefly_blink_brightness(period * 0.25, period, 0.0) == Approx(1.0));
+    REQUIRE(firefly_blink_brightness(period * 0.80, period, 0.0) == Approx(0.0));
+}
+
+TEST_CASE("Firefly phases decorrelate visible brightness", "[firefly][blink]") {
+    const double period = 2.0;
+    const double phases[] = { 0.0, 0.0375, 0.075, 0.1125, 0.25, 0.80 };
+    std::vector<double> distinct;
+    for (double phase : phases) {
+        const double b = firefly_blink_brightness(0.0, period, phase);
+        bool seen = false;
+        for (double existing : distinct) {
+            if (std::fabs(existing - b) < 1e-6) { seen = true; break; }
+        }
+        if (!seen) distinct.push_back(b);
+    }
+    REQUIRE(distinct.size() >= 4);
+}
+

src/modules/DesktopGrass/DesktopGrass.Native.Tests/src/flower_tests.cpp

@@ -0,0 +1,54 @@
+// flower_tests.cpp
+//
+// Tests for §5 flower stream + §7 head-render contract.
+
+#include "../third_party/catch2/catch.hpp"
+#include "Sim.h"
+
+#include <cmath>
+#include <vector>
+
+using namespace desktopgrass;
+
+TEST_CASE("flower stream is deterministic for a given seed", "[flowers]") {
+    std::vector<Blade> a, b;
+    generate_blades(CANONICAL_TEST_SEED, 1920.0, 1.0, a);
+    generate_blades(CANONICAL_TEST_SEED, 1920.0, 1.0, b);
+    REQUIRE(a.size() == b.size());
+    for (std::size_t i = 0; i < a.size(); ++i) {
+        REQUIRE(a[i].isFlower           == b[i].isFlower);
+        REQUIRE(a[i].flowerHeadColorIdx == b[i].flowerHeadColorIdx);
+        REQUIRE(a[i].flowerHeadRadius   == b[i].flowerHeadRadius);
+        REQUIRE(a[i].heightBonus        == b[i].heightBonus);
+    }
+}
+
+TEST_CASE("flower count is within 3-sigma of FLOWER_PROBABILITY", "[flowers]") {
+    std::vector<Blade> blades;
+    generate_blades(CANONICAL_TEST_SEED, 1920.0, 1.0, blades);
+    REQUIRE(blades.size() > 100);
+
+    std::size_t flowerCount = 0;
+    for (const Blade& b : blades) if (b.isFlower) ++flowerCount;
+
+    const double n   = static_cast<double>(blades.size());
+    const double p   = FLOWER_PROBABILITY;
+    const double mu  = n * p;
+    const double sd  = std::sqrt(n * p * (1.0 - p));
+    // 3-sigma tolerance keeps this test stable across spec-conformant
+    // PRNG sequences. For seed=0x6B6173746F, n=321 we expect ~12.84 with
+    // sd≈3.51, so [2,24] is the acceptable range.
+    REQUIRE(flowerCount >= static_cast<std::size_t>(std::floor(mu - 3.0 * sd)));
+    REQUIRE(flowerCount <= static_cast<std::size_t>(std::ceil(mu + 3.0 * sd)));
+}
+
+TEST_CASE("flower stream does not perturb the main stream", "[flowers][conformance]") {
+    // Regenerate blades and assert the main-stream fields match the
+    // canonical snapshot. This is implicitly covered by blade_gen_tests
+    // (the first/last 10 still match), but pin it here for clarity.
+    std::vector<Blade> blades;
+    generate_blades(CANONICAL_TEST_SEED, 1920.0, 1.0, blades);
+    REQUIRE(blades.size() > 0);
+    REQUIRE(blades[0].baseX == Approx(4.941073726820111).margin(1e-12));
+    REQUIRE(blades[0].height == Approx(24.469991818248864).margin(1e-12));
+}

src/modules/DesktopGrass/DesktopGrass.Native.Tests/src/gust_tests.cpp

@@ -0,0 +1,164 @@
+// gust_tests.cpp
+//
+// Gust impulse model tests (architecture.md §8).
+
+#include "../third_party/catch2/catch.hpp"
+#include "Sim.h"
+
+#include <cmath>
+
+using namespace desktopgrass;
+
+namespace {
+
+Sim make_sim_with_blades(std::initializer_list<double> baseXs) {
+    Sim sim;
+    sim.windowHeight = STRIP_HEIGHT + HEADROOM;
+    for (double x : baseXs) {
+        Blade b{};
+        b.baseX            = x;
+        b.height           = 20.0;
+        b.thickness        = 1.5;
+        b.swayPhaseOffset  = 0.0;
+        b.stiffness        = 1.0;
+        b.cutHeight        = 1.0;
+        b.cutInitialHeight = 1.0;
+        b.cutAnimStart     = -1.0;
+        sim.blades.push_back(b);
+    }
+    return sim;
+}
+
+InputEvent move(double x, double y, double t) {
+    return InputEvent{ EventType::Move, x, y, t };
+}
+
+} // anonymous
+
+TEST_CASE("first move event is a baseline; no impulse", "[gust]") {
+    Sim sim = make_sim_with_blades({100.0});
+    const double groundY = sim.windowHeight;
+    const double bandY   = groundY - 10.0; // in band
+
+    sim_apply_move(sim, move(100.0, bandY, 0.0));
+    REQUIRE(sim.blades[0].gustVelocity == Approx(0.0));
+    REQUIRE(sim.prevCursorTime == Approx(0.0));
+}
+
+TEST_CASE("a second move inside the band emits an impulse", "[gust]") {
+    Sim sim = make_sim_with_blades({100.0, 200.0, 400.0});
+    const double bandY = sim.windowHeight - 10.0;
+
+    sim_apply_move(sim, move(  0.0, bandY, 0.0));
+    sim_apply_move(sim, move(100.0, bandY, 0.05));  // velocity = 2000 DIP/sec
+
+    // Blade at 100 is right under the cursor → max impulse.
+    // Expected magnitude:
+    //   capped = 2000 (≤ 4000 cap)
+    //   impulseMagnitude = 2000 * 0.003 = 6.0
+    //   smoothstep at distance 0 = 1.0
+    //   smoothstep at distance 100/150 (blade @ 200) = (1-2/3)² * (3 - 2*(1-2/3))
+    REQUIRE(sim.blades[0].gustVelocity == Approx(6.0).margin(1e-9));
+    // Blade outside radius (400, dist=300 > 150) → no impulse.
+    REQUIRE(sim.blades[2].gustVelocity == Approx(0.0));
+    REQUIRE(sim.blades[1].gustVelocity > 0.0);
+    REQUIRE(sim.blades[1].gustVelocity < 6.0);
+}
+
+TEST_CASE("impulse is signed by motion direction", "[gust]") {
+    Sim left  = make_sim_with_blades({100.0});
+    Sim right = make_sim_with_blades({100.0});
+
+    const double y = left.windowHeight - 10.0;
+    sim_apply_move(left,  move(200.0, y, 0.0));
+    sim_apply_move(left,  move(100.0, y, 0.05)); // moving left
+
+    sim_apply_move(right, move(  0.0, y, 0.0));
+    sim_apply_move(right, move(100.0, y, 0.05)); // moving right
+
+    REQUIRE(left.blades[0].gustVelocity  < 0.0);
+    REQUIRE(right.blades[0].gustVelocity > 0.0);
+    REQUIRE(std::fabs(left.blades[0].gustVelocity) ==
+            Approx(std::fabs(right.blades[0].gustVelocity)).margin(1e-9));
+}
+
+TEST_CASE("cursor speed is capped at MAX_CURSOR_SPEED", "[gust]") {
+    Sim sim = make_sim_with_blades({100.0});
+    const double y = sim.windowHeight - 10.0;
+
+    sim_apply_move(sim, move(0.0,      y, 0.0));
+    sim_apply_move(sim, move(100000.0, y, 0.05)); // velocity ≈ 2e6 DIP/sec
+
+    // capped magnitude = MAX_CURSOR_SPEED * IMPULSE_SCALE = 4000 * 0.003 = 12
+    // but the blade is at distance ~100k from cursor: outside radius → no impulse
+    REQUIRE(sim.blades[0].gustVelocity == Approx(0.0));
+}
+
+TEST_CASE("max impulse at the cursor equals capped magnitude", "[gust]") {
+    Sim sim = make_sim_with_blades({1000.0});
+    const double y = sim.windowHeight - 10.0;
+
+    sim_apply_move(sim, move(0.0,    y, 0.0));
+    sim_apply_move(sim, move(1000.0, y, 0.0001)); // velocity huge → saturates
+
+    // Saturated: cursor lands at x=1000 (blade), distance=0, smoothstep=1.0
+    REQUIRE(sim.blades[0].gustVelocity ==
+            Approx(MAX_CURSOR_SPEED * IMPULSE_SCALE).margin(1e-9));
+}
+
+TEST_CASE("moves outside the gust band don't emit impulses", "[gust]") {
+    Sim sim = make_sim_with_blades({100.0});
+    const double y_above_band = sim.windowHeight - STRIP_HEIGHT - HEADROOM - 20.0;
+
+    sim_apply_move(sim, move(  0.0, y_above_band, 0.0));
+    sim_apply_move(sim, move(100.0, y_above_band, 0.05));
+    REQUIRE(sim.blades[0].gustVelocity == Approx(0.0));
+}
+
+TEST_CASE("out-of-band move updates baseline; re-entry parity", "[gust]") {
+    Sim sim = make_sim_with_blades({700.0});
+    const double inBandY    = sim.windowHeight - 10.0;
+    const double outOfBandY = sim.windowHeight - STRIP_HEIGHT - HEADROOM - 20.0;
+
+    // t0 in-band: primes baseline (first event, no impulse).
+    sim_apply_move(sim, move(500.0, inBandY, 0.0));
+    // t1 out-of-band: updates baseline but emits no impulse.
+    sim_apply_move(sim, move(520.0, outOfBandY, 0.05));
+    REQUIRE(sim.prevCursorX    == Approx(520.0));
+    REQUIRE(sim.prevCursorTime == Approx(0.05));
+    REQUIRE(sim.blades[0].gustVelocity == Approx(0.0));
+
+    // t2 re-enter in-band: emits impulse off the out-of-band baseline.
+    sim_apply_move(sim, move(700.0, inBandY, 0.10));
+
+    const double dtEv  = std::max(0.10 - 0.05, 1.0 / 1000.0);
+    const double velX  = (700.0 - 520.0) / dtEv;
+    const double capped = std::max(-MAX_CURSOR_SPEED, std::min(velX, MAX_CURSOR_SPEED));
+    const double expected = capped * IMPULSE_SCALE; // distance 0 → smoothstep = 1
+    REQUIRE(sim.blades[0].gustVelocity == Approx(expected).margin(1e-9));
+}
+
+TEST_CASE("large time gap resets cursor baseline", "[gust]") {
+    Sim sim = make_sim_with_blades({100.0});
+    const double y = sim.windowHeight - 10.0;
+
+    sim_apply_move(sim, move(  0.0, y, 0.0));
+    sim_apply_move(sim, move(500.0, y, 0.5));   // > CURSOR_REINIT_GAP_SEC (0.25)
+    REQUIRE(sim.blades[0].gustVelocity == Approx(0.0));
+}
+
+TEST_CASE("impulse falls off smoothly with distance", "[gust]") {
+    Sim sim = make_sim_with_blades({100.0, 130.0, 175.0, 200.0, 249.0, 251.0});
+    const double y = sim.windowHeight - 10.0;
+
+    sim_apply_move(sim, move(  0.0, y, 0.0));
+    sim_apply_move(sim, move(100.0, y, 0.05));
+
+    // Monotonic falloff: cursor at 100.
+    REQUIRE(sim.blades[0].gustVelocity > sim.blades[1].gustVelocity);
+    REQUIRE(sim.blades[1].gustVelocity > sim.blades[2].gustVelocity);
+    REQUIRE(sim.blades[2].gustVelocity > sim.blades[3].gustVelocity);
+    REQUIRE(sim.blades[3].gustVelocity > sim.blades[4].gustVelocity);
+    // Just outside radius (251 → distance 151 > 150) → zero.
+    REQUIRE(sim.blades[5].gustVelocity == Approx(0.0));
+}

src/modules/DesktopGrass/DesktopGrass.Native.Tests/src/hedgehog_tests.cpp

@@ -0,0 +1,371 @@
+// hedgehog_tests.cpp
+//
+// §17.9 Hedgehog critter tests. Mirrors Win2D HedgehogTests.cs.
+
+#include "../third_party/catch2/catch.hpp"
+#include "Sim.h"
+
+#include <algorithm>
+#include <cmath>
+#include <cwchar>
+
+using namespace desktopgrass;
+
+namespace {
+
+constexpr double Monitor1920 = 1920.0;
+
+int count_kind(const Sim& sim, EntityKind kind) {
+    return static_cast<int>(std::count_if(sim.entities.begin(), sim.entities.end(),
+        [kind](const Entity& e) { return e.kind == kind; }));
+}
+
+Sim build_sim(uint64_t seed = CANONICAL_TEST_SEED) {
+    return sim_init(seed, Monitor1920, DEFAULT_DENSITY);
+}
+
+Sim build_grass_sim(uint64_t seed = CANONICAL_TEST_SEED) {
+    Sim sim = build_sim(seed);
+    sim_set_scene(sim, Scene::Grass);
+    sim_set_critter(sim, CritterKind::Bunny);
+    return sim;
+}
+
+Entity hedgehog_entity(double x = 500.0, double vx = HEDGEHOG_WALK_SPEED_MIN) {
+    Entity e{};
+    e.kind = EntityKind::Hedgehog;
+    e.size = HEDGEHOG_BODY_RADIUS;
+    e.x = x;
+    e.y = STRIP_HEIGHT + HEADROOM - HEDGEHOG_BODY_HEIGHT - HEDGEHOG_LEG_LENGTH;
+    e.vx = vx;
+    e.vy = 0.0;
+    e.rotationSpeed = std::abs(vx);
+    e.lifetime = -1.0;
+    e.state = HEDGEHOG_STATE_WALKING;
+    e.stateTimer = HEDGEHOG_WALK_DURATION_MIN;
+    e.previousState = HEDGEHOG_STATE_WALKING;
+    return e;
+}
+
+InputEvent click_event(double x, double y) {
+    InputEvent ev{};
+    ev.type = EventType::Click;
+    ev.x = x;
+    ev.y = y;
+    ev.time = 0.0;
+    return ev;
+}
+
+int prng_count(Prng& side, int minCount, int maxCount) {
+    const double draw = prng_uniform(side, static_cast<double>(minCount), static_cast<double>(maxCount + 1));
+    int count = static_cast<int>(std::floor(draw));
+    if (count < minCount) count = minCount;
+    if (count > maxCount) count = maxCount;
+    return count;
+}
+
+void advance_sheep(Prng& side, int count) {
+    for (int i = 0; i < count; ++i) {
+        const double margin = SHEEP_BODY_RADIUS + 8.0;
+        (void)prng_uniform(side, margin, Monitor1920 - margin);
+        (void)prng_uniform(side, SHEEP_WALK_SPEED_MIN, SHEEP_WALK_SPEED_MAX);
+        (void)prng_uniform(side, 0.0, 1.0);
+        (void)prng_next_u32(side);
+        (void)prng_uniform(side, SHEEP_WALK_DURATION_MIN, SHEEP_WALK_DURATION_MAX);
+        (void)prng_index(side, static_cast<uint32_t>(sizeof(SHEEP_NAME_POOL) / sizeof(SHEEP_NAME_POOL[0])));
+    }
+}
+
+void advance_cats(Prng& side, int count) {
+    for (int i = 0; i < count; ++i) {
+        const double margin = CAT_BODY_RADIUS + 8.0;
+        (void)prng_uniform(side, margin, Monitor1920 - margin);
+        (void)prng_uniform(side, CAT_WALK_SPEED_MIN, CAT_WALK_SPEED_MAX);
+        (void)prng_uniform(side, 0.0, 1.0);
+        (void)prng_next_u32(side);
+        (void)prng_uniform(side, CAT_WALK_DURATION_MIN, CAT_WALK_DURATION_MAX);
+        (void)prng_index(side, static_cast<uint32_t>(sizeof(CAT_NAME_POOL) / sizeof(CAT_NAME_POOL[0])));
+        (void)prng_index(side, static_cast<uint32_t>(CAT_COAT_VARIANT_COUNT));
+    }
+}
+
+void advance_bunnies(Prng& side, int count) {
+    for (int i = 0; i < count; ++i) {
+        (void)prng_uniform(side, 0.0, 1.0);
+        (void)prng_next_u64(side);
+        (void)prng_uniform(side, BUNNY_HOP_SPEED_MIN, BUNNY_HOP_SPEED_MAX);
+        (void)prng_index(side, static_cast<uint32_t>(sizeof(BUNNY_NAME_POOL) / sizeof(BUNNY_NAME_POOL[0])));
+    }
+}
+
+bool hedgehog_name_in_pool(const Entity& e) {
+    if (e.nameIndex >= sizeof(HEDGEHOG_NAME_POOL) / sizeof(HEDGEHOG_NAME_POOL[0])) return false;
+    const wchar_t* name = HEDGEHOG_NAME_POOL[e.nameIndex];
+    for (const wchar_t* candidate : HEDGEHOG_NAME_POOL) {
+        if (std::wcscmp(name, candidate) == 0) return true;
+    }
+    return false;
+}
+
+} // namespace
+
+TEST_CASE("Hedgehog constants are pinned to spec values", "[hedgehog][constants]") {
+    REQUIRE(HEDGEHOG_COUNT_MIN == 0);
+    REQUIRE(HEDGEHOG_COUNT_MAX == 1);
+    REQUIRE(HEDGEHOG_COUNT_PROBABILITY == Approx(0.55));
+    REQUIRE(HEDGEHOG_WALK_SPEED_MIN == Approx(4.0));
+    REQUIRE(HEDGEHOG_WALK_SPEED_MAX == Approx(8.0));
+    REQUIRE(HEDGEHOG_BODY_RADIUS == Approx(9.0));
+    REQUIRE(HEDGEHOG_BODY_HEIGHT == Approx(5.5));
+    REQUIRE(HEDGEHOG_HEAD_RADIUS == Approx(3.6));
+    REQUIRE(HEDGEHOG_NOSE_RADIUS == Approx(0.8));
+    REQUIRE(HEDGEHOG_LEG_LENGTH == Approx(2.5));
+    REQUIRE(HEDGEHOG_SPIKE_COUNT == 14);
+    REQUIRE(HEDGEHOG_SPIKE_LENGTH == Approx(3.0));
+    REQUIRE(HEDGEHOG_SPIKE_WIDTH == Approx(1.4));
+    REQUIRE(HEDGEHOG_SPIKE_ARC_START_DEG == Approx(-20.0));
+    REQUIRE(HEDGEHOG_SPIKE_ARC_END_DEG == Approx(200.0));
+    REQUIRE(HEDGEHOG_BODY_COLOR == 0xFF5C4633u);
+    REQUIRE(HEDGEHOG_SPIKE_COLOR == 0xFF3A2A1Fu);
+    REQUIRE(HEDGEHOG_SPIKE_TIP_COLOR == 0xFF1E150Eu);
+    REQUIRE(HEDGEHOG_NOSE_COLOR == 0xFF1A1208u);
+    REQUIRE(HEDGEHOG_EYE_COLOR == 0xFF1A1208u);
+    REQUIRE(HEDGEHOG_STATE_WALKING == 0);
+    REQUIRE(HEDGEHOG_STATE_SNUFFLING == 1);
+    REQUIRE(HEDGEHOG_STATE_IDLE == 2);
+    REQUIRE(HEDGEHOG_STATE_SLEEPING == 3);
+    REQUIRE(HEDGEHOG_STATE_CURLED == 4);
+    REQUIRE(HEDGEHOG_WALK_DURATION_MIN == Approx(6.0));
+    REQUIRE(HEDGEHOG_WALK_DURATION_MAX == Approx(12.0));
+    REQUIRE(HEDGEHOG_SNUFFLE_DURATION_MIN == Approx(3.0));
+    REQUIRE(HEDGEHOG_SNUFFLE_DURATION_MAX == Approx(6.0));
+    REQUIRE(HEDGEHOG_IDLE_DURATION_MIN == Approx(1.5));
+    REQUIRE(HEDGEHOG_IDLE_DURATION_MAX == Approx(3.0));
+    REQUIRE(HEDGEHOG_SLEEP_DURATION_MIN == Approx(10.0));
+    REQUIRE(HEDGEHOG_SLEEP_DURATION_MAX == Approx(25.0));
+    REQUIRE(HEDGEHOG_CURL_DURATION_MIN == Approx(3.0));
+    REQUIRE(HEDGEHOG_CURL_DURATION_MAX == Approx(5.5));
+    REQUIRE(HEDGEHOG_SNUFFLE_PROBABILITY == Approx(0.55));
+    REQUIRE(HEDGEHOG_IDLE_PROBABILITY == Approx(0.30));
+    REQUIRE(HEDGEHOG_SLEEP_PROB == Approx(0.50));
+    REQUIRE(HEDGEHOG_STARTLE_RADIUS == Approx(70.0));
+    REQUIRE(HEDGEHOG_SNUFFLE_HEAD_FREQ == Approx(5.0));
+    REQUIRE(HEDGEHOG_SNUFFLE_HEAD_AMP == Approx(0.7));
+    REQUIRE(HEDGEHOG_WADDLE_FREQ == Approx(4.0));
+    REQUIRE(HEDGEHOG_WADDLE_AMP == Approx(0.8));
+    REQUIRE(HEDGEHOG_ZZZ_CYCLE_SEC == Approx(SHEEP_ZZZ_CYCLE_SEC));
+    REQUIRE(HEDGEHOG_ZZZ_RISE == Approx(SHEEP_ZZZ_RISE * 0.5));
+    REQUIRE(HEDGEHOG_ZZZ_SIZE_START == Approx(SHEEP_ZZZ_SIZE_START * 0.6));
+    REQUIRE(HEDGEHOG_ZZZ_SIZE_END == Approx(SHEEP_ZZZ_SIZE_END * 0.6));
+    REQUIRE(sizeof(HEDGEHOG_NAME_POOL) / sizeof(HEDGEHOG_NAME_POOL[0]) == 12);
+    REQUIRE(std::wcscmp(HEDGEHOG_NAME_POOL[0], L"Bristle") == 0);
+    REQUIRE(std::wcscmp(HEDGEHOG_NAME_POOL[11], L"Burdock") == 0);
+}
+
+TEST_CASE("Hedgehog count distribution is probabilistic rare sighting", "[hedgehog][gen]") {
+    constexpr int N = 1000;
+    int present = 0;
+    for (uint64_t i = 0; i < N; ++i) {
+        const uint64_t seed = CANONICAL_TEST_SEED + i * 0x9E3779B97F4A7C15ull;
+        Sim sim = build_grass_sim(seed);
+        const int count = count_kind(sim, EntityKind::Hedgehog);
+        REQUIRE(count >= HEDGEHOG_COUNT_MIN);
+        REQUIRE(count <= HEDGEHOG_COUNT_MAX);
+        present += count;
+    }
+    REQUIRE(static_cast<double>(present) / N == Approx(HEDGEHOG_COUNT_PROBABILITY).margin(0.05));
+}
+
+TEST_CASE("Hedgehogs are Grass scene only", "[hedgehog][scene]") {
+    Sim sim = build_sim();
+    sim_set_scene(sim, Scene::Desert);
+    REQUIRE(count_kind(sim, EntityKind::Hedgehog) == 0);
+    sim_set_scene(sim, Scene::Winter);
+    REQUIRE(count_kind(sim, EntityKind::Hedgehog) == 0);
+}
+
+TEST_CASE("Generated hedgehogs have speed range", "[hedgehog][gen]") {
+    bool sawHedgehog = false;
+    for (uint64_t i = 0; i < 128; ++i) {
+        Sim sim = build_grass_sim(CANONICAL_TEST_SEED + i * 0xD1B54A32D192ED03ull);
+        for (const Entity& e : sim.entities) {
+            if (e.kind != EntityKind::Hedgehog) continue;
+            sawHedgehog = true;
+            REQUIRE(std::abs(e.vx) >= HEDGEHOG_WALK_SPEED_MIN);
+            REQUIRE(std::abs(e.vx) <= HEDGEHOG_WALK_SPEED_MAX);
+            REQUIRE(e.rotationSpeed == Approx(std::abs(e.vx)));
+        }
+    }
+    REQUIRE(sawHedgehog);
+}
+
+TEST_CASE("Generated hedgehogs have names in pool", "[hedgehog][gen]") {
+    bool sawHedgehog = false;
+    for (uint64_t i = 0; i < 128; ++i) {
+        Sim sim = build_grass_sim(CANONICAL_TEST_SEED + i * 0x94D049BB133111EBull);
+        for (const Entity& e : sim.entities) {
+            if (e.kind != EntityKind::Hedgehog) continue;
+            sawHedgehog = true;
+            REQUIRE(hedgehog_name_in_pool(e));
+        }
+    }
+    REQUIRE(sawHedgehog);
+}
+
+TEST_CASE("Hedgehog PRNG draw order follows sheep cats and bunnies", "[hedgehog][prng]") {
+    Prng side;
+    prng_init(side, CANONICAL_TEST_SEED ^ CRITTER_PRNG_SALT);
+    Sim sim = build_grass_sim();
+
+    const int sheepCount = prng_count(side, SHEEP_COUNT_MIN, SHEEP_COUNT_MAX);
+    advance_sheep(side, sheepCount);
+    const int catCount = prng_count(side, CAT_COUNT_MIN, CAT_COUNT_MAX);
+    advance_cats(side, catCount);
+    const int bunnyCount = prng_count(side, BUNNY_COUNT_MIN, BUNNY_COUNT_MAX);
+    advance_bunnies(side, bunnyCount);
+
+    const double hasDraw = prng_uniform(side, 0.0, 1.0);
+    const int hedgehogCount = hasDraw < HEDGEHOG_COUNT_PROBABILITY ? 1 : 0;
+    REQUIRE(count_kind(sim, EntityKind::Hedgehog) == hedgehogCount);
+
+    int seen = 0;
+    for (const Entity& e : sim.entities) {
+        if (e.kind != EntityKind::Hedgehog) continue;
+        const double margin = HEDGEHOG_BODY_RADIUS + 8.0;
+        const double xFrac = prng_uniform(side, 0.0, 1.0);
+        const double expectedX = margin + xFrac * (Monitor1920 - 2.0 * margin);
+        const uint64_t vxSign = prng_next_u64(side) & 1ull;
+        const double expectedDir = vxSign != 0ull ? 1.0 : -1.0;
+        const double expectedSpeed = prng_uniform(side, HEDGEHOG_WALK_SPEED_MIN, HEDGEHOG_WALK_SPEED_MAX);
+        const uint8_t expectedName = static_cast<uint8_t>(prng_index(side,
+            static_cast<uint32_t>(sizeof(HEDGEHOG_NAME_POOL) / sizeof(HEDGEHOG_NAME_POOL[0]))));
+        REQUIRE(e.x == Approx(expectedX));
+        REQUIRE(e.vx == Approx(expectedDir * expectedSpeed));
+        REQUIRE(e.nameIndex == expectedName);
+        ++seen;
+    }
+    REQUIRE(seen == hedgehogCount);
+}
+
+TEST_CASE("Hedgehog edge bounce flips direction", "[hedgehog][motion]") {
+    Sim sim = build_sim();
+    sim.currentScene = Scene::Desert;
+    sim.entities.clear();
+    Entity e = hedgehog_entity(Monitor1920 - (HEDGEHOG_BODY_RADIUS + 2.0) + 0.1, HEDGEHOG_WALK_SPEED_MIN);
+    e.stateTimer = 10.0;
+    sim.entities.push_back(e);
+
+    sim_tick_entities(sim, 0.016);
+
+    REQUIRE(sim.entities.front().vx < 0.0);
+}
+
+TEST_CASE("Hedgehog startle radius curls without flipping vx", "[hedgehog][click]") {
+    Sim sim = build_sim();
+    sim.entities.clear();
+    Entity e = hedgehog_entity(500.0, -HEDGEHOG_WALK_SPEED_MIN);
+    e.state = HEDGEHOG_STATE_WALKING;
+    e.stateTimer = 10.0;
+    sim.entities.push_back(e);
+
+    sim_apply_click(sim, click_event(e.x + 10.0, e.y));
+    REQUIRE(sim.entities.front().state == HEDGEHOG_STATE_CURLED);
+    REQUIRE(sim.entities.front().vx == Approx(-HEDGEHOG_WALK_SPEED_MIN));
+    REQUIRE(sim.entities.front().stateTimer >= HEDGEHOG_CURL_DURATION_MIN);
+    REQUIRE(sim.entities.front().stateTimer <= HEDGEHOG_CURL_DURATION_MAX);
+
+    Sim outside = build_sim();
+    outside.entities.clear();
+    Entity far = hedgehog_entity(500.0, HEDGEHOG_WALK_SPEED_MIN);
+    outside.entities.push_back(far);
+    sim_apply_click(outside, click_event(far.x + HEDGEHOG_STARTLE_RADIUS + 10.0, far.y));
+    REQUIRE(outside.entities.front().state == HEDGEHOG_STATE_WALKING);
+    REQUIRE(outside.entities.front().vx == Approx(HEDGEHOG_WALK_SPEED_MIN));
+}
+
+TEST_CASE("Hedgehog curl auto uncurls to previous state", "[hedgehog][state]") {
+    Sim sim = build_sim();
+    sim.entities.clear();
+    Entity e = hedgehog_entity(500.0, HEDGEHOG_WALK_SPEED_MIN);
+    e.state = HEDGEHOG_STATE_IDLE;
+    e.stateTimer = 2.5;
+    sim.entities.push_back(e);
+
+    sim_apply_click(sim, click_event(e.x, e.y));
+    REQUIRE(sim.entities.front().state == HEDGEHOG_STATE_CURLED);
+    sim_tick_entities(sim, HEDGEHOG_CURL_DURATION_MAX + 0.1);
+
+    REQUIRE(sim.entities.front().state == HEDGEHOG_STATE_IDLE);
+    REQUIRE(sim.entities.front().vx == Approx(HEDGEHOG_WALK_SPEED_MIN));
+}
+
+TEST_CASE("Hedgehog wakes from sleep on startle and does not resume sleep", "[hedgehog][click]") {
+    Sim sim = build_sim();
+    sim.entities.clear();
+    Entity e = hedgehog_entity(500.0, HEDGEHOG_WALK_SPEED_MIN);
+    e.state = HEDGEHOG_STATE_SLEEPING;
+    e.stateTimer = 10.0;
+    sim.entities.push_back(e);
+
+    sim_apply_click(sim, click_event(e.x + 10.0, e.y));
+    REQUIRE(sim.entities.front().state == HEDGEHOG_STATE_CURLED);
+    REQUIRE(sim.entities.front().state != HEDGEHOG_STATE_SLEEPING);
+    sim_tick_entities(sim, HEDGEHOG_CURL_DURATION_MAX + 0.1);
+
+    REQUIRE(sim.entities.front().state == HEDGEHOG_STATE_WALKING);
+    REQUIRE(sim.entities.front().state != HEDGEHOG_STATE_SLEEPING);
+}
+
+TEST_CASE("Hedgehog state transition probabilities are stable", "[hedgehog][state]") {
+    Prng p;
+    prng_init(p, CANONICAL_TEST_SEED ^ CRITTER_PRNG_SALT);
+    constexpr int N = 10000;
+    int snuffle = 0;
+    int idle = 0;
+    int sleep = 0;
+    for (int i = 0; i < N; ++i) {
+        const uint8_t state = hedgehog_choose_rest_state(p);
+        if (state == HEDGEHOG_STATE_SNUFFLING) ++snuffle;
+        else if (state == HEDGEHOG_STATE_IDLE) ++idle;
+        else if (state == HEDGEHOG_STATE_SLEEPING) ++sleep;
+    }
+
+    const double sleepProb = HEDGEHOG_SLEEP_PROB;
+    const double activeWeight = HEDGEHOG_SNUFFLE_PROBABILITY + HEDGEHOG_IDLE_PROBABILITY;
+    const double expectedSnuffle = (1.0 - sleepProb) * HEDGEHOG_SNUFFLE_PROBABILITY / activeWeight;
+    const double expectedIdle = (1.0 - sleepProb) * HEDGEHOG_IDLE_PROBABILITY / activeWeight;
+    REQUIRE(static_cast<double>(sleep) / N == Approx(sleepProb).margin(0.02));
+    REQUIRE(static_cast<double>(snuffle) / N == Approx(expectedSnuffle).margin(0.02));
+    REQUIRE(static_cast<double>(idle) / N == Approx(expectedIdle).margin(0.02));
+}
+
+TEST_CASE("Hedgehog sleep probability is stable", "[hedgehog][state]") {
+    constexpr int N = 20000;
+    Prng p;
+    prng_init(p, CANONICAL_TEST_SEED ^ 0x1234ull);
+    int sleep = 0;
+    for (int i = 0; i < N; ++i) {
+        if (hedgehog_choose_rest_state(p) == HEDGEHOG_STATE_SLEEPING) ++sleep;
+    }
+    REQUIRE(static_cast<double>(sleep) / N == Approx(HEDGEHOG_SLEEP_PROB).margin(0.02));
+}
+
+TEST_CASE("Hedgehog has no active interaction states", "[hedgehog][state]") {
+    Prng p;
+    prng_init(p, CANONICAL_TEST_SEED ^ 0xCAFEull);
+    for (int i = 0; i < 1000; ++i) {
+        const uint8_t state = hedgehog_choose_rest_state(p);
+        REQUIRE((state == HEDGEHOG_STATE_SNUFFLING
+              || state == HEDGEHOG_STATE_IDLE
+              || state == HEDGEHOG_STATE_SLEEPING));
+    }
+
+    Sim sim = build_sim();
+    sim.entities.clear();
+    Entity e = hedgehog_entity(500.0, HEDGEHOG_WALK_SPEED_MIN);
+    e.stateTimer = 10.0;
+    sim.entities.push_back(e);
+    sim_tick_entities(sim, 0.016);
+    REQUIRE(sim.entities.front().state == HEDGEHOG_STATE_WALKING);
+    REQUIRE(std::abs(sim.entities.front().vx) == Approx(HEDGEHOG_WALK_SPEED_MIN));
+}

src/modules/DesktopGrass/DesktopGrass.Native.Tests/src/main.cpp

@@ -0,0 +1,7 @@
+// main.cpp
+//
+// Catch2 entry point. The Sim.cpp translation unit is also linked in via the
+// vcxproj's source list so we can test it directly.
+
+#define CATCH_CONFIG_MAIN
+#include "../third_party/catch2/catch.hpp"

src/modules/DesktopGrass/DesktopGrass.Native.Tests/src/mushroom_tests.cpp

@@ -0,0 +1,89 @@
+// mushroom_tests.cpp
+//
+// Tests for §5 mushroom stream + §7 mushroom-render contract.
+
+#include "../third_party/catch2/catch.hpp"
+#include "Sim.h"
+
+#include <algorithm>
+#include <cmath>
+#include <vector>
+
+using namespace desktopgrass;
+
+TEST_CASE("mushroom stream is deterministic for a given seed", "[mushrooms]") {
+    std::vector<Blade> a, b;
+    generate_blades(CANONICAL_TEST_SEED, 1920.0, 1.0, a);
+    generate_blades(CANONICAL_TEST_SEED, 1920.0, 1.0, b);
+    REQUIRE(a.size() == b.size());
+    for (std::size_t i = 0; i < a.size(); ++i) {
+        REQUIRE(a[i].isMushroom            == b[i].isMushroom);
+        REQUIRE(a[i].mushroomCapColorIdx   == b[i].mushroomCapColorIdx);
+        REQUIRE(a[i].mushroomCapWidth      == b[i].mushroomCapWidth);
+        REQUIRE(a[i].mushroomCapHeight     == b[i].mushroomCapHeight);
+        REQUIRE(a[i].mushroomStemHeight    == b[i].mushroomStemHeight);
+        REQUIRE(a[i].mushroomStemThickness == b[i].mushroomStemThickness);
+    }
+}
+
+TEST_CASE("mushroom count is within 3-sigma of MUSHROOM_PROBABILITY", "[mushrooms]") {
+    std::vector<Blade> blades;
+    generate_blades(CANONICAL_TEST_SEED, 1920.0, 1.0, blades);
+    REQUIRE(blades.size() > 100);
+
+    std::size_t mushroomCount = 0;
+    for (const Blade& b : blades) if (b.isMushroom) ++mushroomCount;
+
+    const double n   = static_cast<double>(blades.size());
+    const double p   = MUSHROOM_PROBABILITY;
+    const double mu  = n * p;
+    const double sd  = std::sqrt(n * p * (1.0 - p));
+    // 3-sigma tolerance keeps this test stable across spec-conformant
+    // PRNG sequences. For seed=0x6B6173746F, n=321 we expect ~8.03 with
+    // sd≈2.80, so the inclusive 3-sigma range is roughly [0, 17].
+    const double lo  = std::max(0.0, std::floor(mu - 3.0 * sd));
+    REQUIRE(mushroomCount >= static_cast<std::size_t>(lo));
+    REQUIRE(mushroomCount <= static_cast<std::size_t>(std::ceil(mu + 3.0 * sd)));
+}
+
+TEST_CASE("mushroom stream does not perturb the main stream", "[mushrooms][conformance]") {
+    // The mushroom stream is independent (seed ^ MUSHROOM_PRNG_SALT) so
+    // the main-stream first-blade values must still match the canonical.
+    std::vector<Blade> blades;
+    generate_blades(CANONICAL_TEST_SEED, 1920.0, 1.0, blades);
+    REQUIRE(blades.size() > 0);
+    REQUIRE(blades[0].baseX == Approx(4.941073726820111).margin(1e-12));
+    REQUIRE(blades[0].height == Approx(24.469991818248864).margin(1e-12));
+}
+
+TEST_CASE("non-mushroom blades have zero mushroom fields", "[mushrooms]") {
+    std::vector<Blade> blades;
+    generate_blades(CANONICAL_TEST_SEED, 1920.0, 1.0, blades);
+    for (const Blade& b : blades) {
+        if (!b.isMushroom) {
+            REQUIRE(b.mushroomCapColorIdx   == 0);
+            REQUIRE(b.mushroomCapWidth      == 0.0);
+            REQUIRE(b.mushroomCapHeight     == 0.0);
+            REQUIRE(b.mushroomStemHeight    == 0.0);
+            REQUIRE(b.mushroomStemThickness == 0.0);
+        }
+    }
+}
+
+TEST_CASE("mushroom field ranges respect spec", "[mushrooms]") {
+    std::vector<Blade> blades;
+    generate_blades(CANONICAL_TEST_SEED, 1920.0, 1.0, blades);
+    for (const Blade& b : blades) {
+        if (b.isMushroom) {
+            REQUIRE(b.mushroomCapColorIdx < MUSHROOM_PALETTE_SIZE);
+            REQUIRE(b.mushroomCapWidth      >= MUSHROOM_CAP_WIDTH_MIN);
+            REQUIRE(b.mushroomCapWidth      <  MUSHROOM_CAP_WIDTH_MAX);
+            REQUIRE(b.mushroomCapHeight     >= MUSHROOM_CAP_HEIGHT_MIN);
+            REQUIRE(b.mushroomCapHeight     <  MUSHROOM_CAP_HEIGHT_MAX);
+            REQUIRE(b.mushroomStemHeight    >= MUSHROOM_STEM_HEIGHT_MIN);
+            REQUIRE(b.mushroomStemHeight    <  MUSHROOM_STEM_HEIGHT_MAX);
+            REQUIRE(b.mushroomStemThickness >= MUSHROOM_STEM_THICKNESS_MIN);
+            REQUIRE(b.mushroomStemThickness <  MUSHROOM_STEM_THICKNESS_MAX);
+        }
+    }
+}

src/modules/DesktopGrass/DesktopGrass.Native.Tests/src/ocean_tests.cpp

@@ -0,0 +1,114 @@
+// ocean_tests.cpp
+//
+// Ocean scene tests (architecture.md §17). Mirror of the Win2D OceanTests so
+// the coral blade variant, bubble emitter, and fish swimmers stay in lockstep
+// across impls.
+
+#include "../third_party/catch2/catch.hpp"
+#include "Sim.h"
+
+#include <algorithm>
+
+using namespace desktopgrass;
+
+namespace {
+
+constexpr double kMonitor1920 = 1920.0;
+
+Sim make_ocean_sim(uint64_t seed = CANONICAL_TEST_SEED,
+                   double width = kMonitor1920,
+                   double density = DEFAULT_DENSITY) {
+    Sim sim = sim_init(seed, width, density);
+    sim_set_scene(sim, Scene::Ocean);
+    return sim;
+}
+
+int count_kind(const Sim& sim, EntityKind kind) {
+    return static_cast<int>(std::count_if(sim.entities.begin(), sim.entities.end(),
+        [kind](const Entity& e) { return e.kind == kind; }));
+}
+
+} // namespace
+
+TEST_CASE("Ocean scene generates at least one coral and keeps values in range",
+          "[ocean][coral]") {
+    Sim sim = make_ocean_sim();
+
+    int coralCount = 0;
+    for (const Blade& b : sim.blades) {
+        if (!b.isCoral) continue;
+        ++coralCount;
+        REQUIRE_FALSE(b.isPine);
+        REQUIRE_FALSE(b.isCactus);
+        REQUIRE_FALSE(b.isMaple);
+        REQUIRE_FALSE(b.isFlower);
+        REQUIRE_FALSE(b.isMushroom);
+        REQUIRE(b.coralHeight >= CORAL_HEIGHT_MIN);
+        REQUIRE(b.coralHeight <= CORAL_HEIGHT_MAX);
+        REQUIRE(b.coralWidth  >= CORAL_WIDTH_MIN);
+        REQUIRE(b.coralWidth  <= CORAL_WIDTH_MAX);
+        REQUIRE(static_cast<int>(b.coralType)     >= 0);
+        REQUIRE(static_cast<int>(b.coralType)     <= CORAL_TYPE_COUNT  - 1);
+        REQUIRE(static_cast<int>(b.coralColorIdx) >= 0);
+        REQUIRE(static_cast<int>(b.coralColorIdx) <= CORAL_COLOR_COUNT - 1);
+    }
+    REQUIRE(coralCount > 0);
+}
+
+TEST_CASE("Ocean scene spawns initial fish at or above the target minimum",
+          "[ocean][fish]") {
+    Sim sim = make_ocean_sim();
+
+    const int fishCount = count_kind(sim, EntityKind::Fish);
+    REQUIRE(fishCount >= FISH_COUNT_MIN);
+    REQUIRE(fishCount <= FISH_COUNT_MAX);
+}
+
+TEST_CASE("Ocean fish count rounds half-to-even deterministically",
+          "[ocean][fish]") {
+    // scaled = 2.5 * width / 1920. Widths chosen so scaled lands exactly on a
+    // .5 tie; round-half-to-even must pick the even neighbor (NOT half-up),
+    // matching C# Math.Round and independent of the FPU rounding mode.
+    Sim tie25 = make_ocean_sim(CANONICAL_TEST_SEED, 1920.0); // scaled 2.5 -> 2
+    REQUIRE(count_kind(tie25, EntityKind::Fish) == 2);
+
+    Sim tie45 = make_ocean_sim(CANONICAL_TEST_SEED, 3456.0); // scaled 4.5 -> 4
+    REQUIRE(count_kind(tie45, EntityKind::Fish) == 4);
+}
+
+TEST_CASE("Ocean tick emits bubbles over time", "[ocean][bubble]") {
+    Sim sim = make_ocean_sim();
+
+    const double dt = 1.0 / 60.0;
+    for (int i = 0; i < 600; ++i) {
+        sim.globalTime += dt;
+        sim_tick_entities(sim, dt);
+    }
+
+    REQUIRE(count_kind(sim, EntityKind::Bubble) > 0);
+}
+
+TEST_CASE("Switching from Ocean to Grass wipes bubbles and fish",
+          "[ocean][scene]") {
+    Sim sim = make_ocean_sim();
+
+    const double dt = 1.0 / 60.0;
+    for (int i = 0; i < 120; ++i) {
+        sim.globalTime += dt;
+        sim_tick_entities(sim, dt);
+    }
+    REQUIRE(count_kind(sim, EntityKind::Fish) > 0);
+
+    sim_set_scene(sim, Scene::Grass);
+
+    REQUIRE(count_kind(sim, EntityKind::Bubble) == 0);
+    REQUIRE(count_kind(sim, EntityKind::Fish) == 0);
+    REQUIRE(std::none_of(sim.blades.begin(), sim.blades.end(),
+        [](const Blade& b) { return b.isCoral; }));
+}
+
+TEST_CASE("Ocean palette is pinned in scene palettes", "[ocean][palette]") {
+    for (int i = 0; i < PALETTE_SIZE; ++i) {
+        REQUIRE(SCENE_PALETTES[static_cast<int>(Scene::Ocean)][i] == OCEAN_PALETTE[i]);
+    }
+}

src/modules/DesktopGrass/DesktopGrass.Native.Tests/src/pacing_tests.cpp

@@ -0,0 +1,80 @@
+// pacing_tests.cpp
+//
+// FramePacer behaviour tests.
+//
+// Goal: lock in the contract that on supported Windows (10 1803+) the pacer
+// honours sub-15.6 ms waits via the high-resolution waitable timer, not the
+// default system timer resolution. A regression that drops the high-res flag
+// would silently re-introduce the ~48 ms dt_p95 pacing bug; the timing-bound
+// assertion below catches that without needing benchmark numbers.
+//
+// The timing assertions are deliberately generous (we measure absolute upper
+// bounds, not exact wait times) so CI runners with momentary scheduling
+// hiccups don't flake. Even at the loosest bound the test still distinguishes
+// high-res (~sub-ms) from default-resolution (~15.6 ms minimum tick) behaviour.
+
+#include "../third_party/catch2/catch.hpp"
+#include "Pacing.h"
+
+#define WIN32_LEAN_AND_MEAN
+#include <windows.h>
+
+using namespace desktopgrass;
+
+namespace {
+
+double qpc_now_sec() {
+    LARGE_INTEGER c{}, f{};
+    QueryPerformanceCounter(&c);
+    QueryPerformanceFrequency(&f);
+    return static_cast<double>(c.QuadPart) / static_cast<double>(f.QuadPart);
+}
+
+} // namespace
+
+TEST_CASE("FramePacer: creates a high-resolution waitable timer on supported Windows",
+          "[pacing]") {
+    FramePacer pacer;
+    // DesktopGrass requires Windows 10 1809+, which is well past the
+    // CREATE_WAITABLE_TIMER_HIGH_RESOLUTION minimum (Win 10 1803). Build/CI
+    // environments below that floor are not supported.
+    REQUIRE(pacer.IsHighResolution());
+}
+
+TEST_CASE("FramePacer: zero or negative wait returns essentially immediately",
+          "[pacing]") {
+    FramePacer pacer;
+    const double t0 = qpc_now_sec();
+    pacer.WaitUntilNextFrame(0.0);
+    pacer.WaitUntilNextFrame(-1.0);
+    const double dt = qpc_now_sec() - t0;
+    // Two no-op calls should complete in well under a millisecond, but allow
+    // 5 ms of slop for loaded CI machines.
+    REQUIRE(dt < 0.005);
+}
+
+TEST_CASE("FramePacer: honours sub-15.6 ms waits via the high-resolution timer",
+          "[pacing]") {
+    FramePacer pacer;
+    REQUIRE(pacer.IsHighResolution());
+
+    // Five 1 ms waits. With the high-resolution timer the cumulative time
+    // should sit well below 30 ms. Without it (legacy ~15.6 ms tick) each
+    // wait would round up to ~15.6 ms for a total of ~78 ms, so 30 ms is a
+    // wide safety margin that still catches regressions cleanly.
+    constexpr int    kIterations = 5;
+    constexpr double kWaitSec    = 0.001;
+
+    const double t0 = qpc_now_sec();
+    for (int i = 0; i < kIterations; ++i) {
+        pacer.WaitUntilNextFrame(kWaitSec);
+    }
+    const double total = qpc_now_sec() - t0;
+
+    // Lower bound: we asked for 5 ms total — actual wait must be at least
+    // a small fraction of that, otherwise we are not waiting at all.
+    REQUIRE(total >= 0.0005);
+    // Upper bound: must beat the default ~15.6 ms tick by a comfortable
+    // margin. 30 ms catches the regression (78 ms) without flaking on CI.
+    REQUIRE(total < 0.030);
+}

src/modules/DesktopGrass/DesktopGrass.Native.Tests/src/persistence_tests.cpp

@@ -0,0 +1,285 @@
+#include "../third_party/catch2/catch.hpp"
+#include "Persistence.h"
+#include "Sim.h"
+
+#include <algorithm>
+#include <filesystem>
+#include <fstream>
+#include <sstream>
+#include <string>
+
+using namespace desktopgrass;
+
+namespace {
+
+std::filesystem::path test_state_path(const char* name) {
+    std::filesystem::path dir = std::filesystem::current_path()
+        / ".copilot-scratch"
+        / "native-persistence-tests"
+        / name;
+    std::error_code ec;
+    std::filesystem::remove_all(dir, ec);
+    std::filesystem::create_directories(dir);
+    return dir / "state.json";
+}
+
+void use_state_path(const std::filesystem::path& path) {
+    persistence::SetStateFilePathForTest(path.wstring());
+}
+
+void write_text(const std::filesystem::path& path, const std::string& text) {
+    std::filesystem::create_directories(path.parent_path());
+    std::ofstream file(path, std::ios::binary | std::ios::trunc);
+    file << text;
+}
+
+std::string read_text(const std::filesystem::path& path) {
+    std::ifstream file(path, std::ios::binary);
+    std::ostringstream buffer;
+    buffer << file.rdbuf();
+    return buffer.str();
+}
+
+persistence::AppState make_state_with_cuts() {
+    persistence::AppState state;
+    state.scene = Scene::Winter;
+    state.critter = CritterKind::Cat;
+    state.critterCountOverride = 4;
+    state.autoStart = true;
+
+    for (int i = 0; i < 3; ++i) {
+        persistence::MonitorState monitor;
+        monitor.width = 1920 + i * 320;
+        monitor.height = 1080 + i * 120;
+        monitor.left = i * 1920;
+        monitor.top = i == 2 ? -120 : 0;
+        const int cutCount = 2 + i;
+        for (int j = 0; j < cutCount; ++j) {
+            monitor.cuts.push_back(persistence::CutRecord{ i * 100 + j, -5.0 - i - j * 0.5 });
+        }
+        state.monitors.push_back(monitor);
+    }
+
+    return state;
+}
+
+void assert_state_equal(const persistence::AppState& expected, const persistence::AppState& actual) {
+    REQUIRE(actual.version == 2);
+    REQUIRE(actual.scene == expected.scene);
+    REQUIRE(actual.critter == expected.critter);
+    REQUIRE(actual.critterCountOverride == expected.critterCountOverride);
+    REQUIRE(actual.autoStart == expected.autoStart);
+    REQUIRE(actual.monitors.size() == expected.monitors.size());
+
+    for (std::size_t i = 0; i < expected.monitors.size(); ++i) {
+        const auto& e = expected.monitors[i];
+        const auto& a = actual.monitors[i];
+        REQUIRE(a.width == e.width);
+        REQUIRE(a.height == e.height);
+        REQUIRE(a.left == e.left);
+        REQUIRE(a.top == e.top);
+        REQUIRE(a.cuts.size() == e.cuts.size());
+        for (std::size_t j = 0; j < e.cuts.size(); ++j) {
+            REQUIRE(a.cuts[j].bladeIndex == e.cuts[j].bladeIndex);
+            REQUIRE(a.cuts[j].cutTime == Approx(e.cuts[j].cutTime).margin(1e-9));
+        }
+    }
+}
+
+Blade make_blade(double regrowDelay, double regrowDuration) {
+    Blade b{};
+    b.baseX = 100.0;
+    b.height = 20.0;
+    b.thickness = 1.0;
+    b.cutHeight = 1.0;
+    b.cutAnimStart = -1.0;
+    b.cutInitialHeight = 1.0;
+    b.regrowDelay = regrowDelay;
+    b.regrowDuration = regrowDuration;
+    b.regrowStart = -1.0;
+    return b;
+}
+
+} // namespace
+
+TEST_CASE("persistence round-trips empty state", "[persistence]") {
+    const auto path = test_state_path("round-trip-empty");
+    use_state_path(path);
+
+    persistence::AppState expected;
+    REQUIRE(persistence::SaveAppState(expected));
+
+    persistence::AppState actual;
+    REQUIRE(persistence::LoadAppState(actual));
+    assert_state_equal(expected, actual);
+}
+
+TEST_CASE("persistence round-trips state with cuts", "[persistence]") {
+    const auto path = test_state_path("round-trip-cuts");
+    use_state_path(path);
+
+    const persistence::AppState expected = make_state_with_cuts();
+    REQUIRE(persistence::SaveAppState(expected));
+
+    persistence::AppState actual;
+    REQUIRE(persistence::LoadAppState(actual));
+    assert_state_equal(expected, actual);
+}
+
+TEST_CASE("persistence round-trips every scene", "[persistence]") {
+    const Scene scenes[] = {
+        Scene::Grass, Scene::Desert, Scene::Winter, Scene::Autumn, Scene::Ocean
+    };
+    for (Scene scene : scenes) {
+        const auto path = test_state_path("round-trip-scene");
+        use_state_path(path);
+
+        persistence::AppState expected;
+        expected.scene = scene;
+        REQUIRE(persistence::SaveAppState(expected));
+
+        persistence::AppState actual;
+        REQUIRE(persistence::LoadAppState(actual));
+        REQUIRE(actual.scene == scene);
+    }
+}
+
+TEST_CASE("persistence version mismatch returns false", "[persistence]") {
+    const auto path = test_state_path("version-mismatch");
+    use_state_path(path);
+    write_text(path, "{ \"version\": 999, \"monitors\": {} }");
+
+    persistence::AppState actual;
+    REQUIRE_FALSE(persistence::LoadAppState(actual));
+}
+
+TEST_CASE("persistence missing file returns false", "[persistence]") {
+    const auto path = test_state_path("missing-file");
+    use_state_path(path);
+
+    persistence::AppState actual;
+    REQUIRE_FALSE(persistence::LoadAppState(actual));
+}
+
+TEST_CASE("persistence malformed json returns false", "[persistence]") {
+    const auto path = test_state_path("malformed-json");
+    use_state_path(path);
+    write_text(path, "not-json");
+
+    persistence::AppState actual;
+    REQUIRE_FALSE(persistence::LoadAppState(actual));
+}
+
+TEST_CASE("persistence atomic write leaves final file and removes tmp", "[persistence]") {
+    const auto path = test_state_path("atomic-write");
+    use_state_path(path);
+
+    persistence::AppState state;
+    REQUIRE(persistence::SaveAppState(state));
+
+    REQUIRE(std::filesystem::exists(path));
+    REQUIRE_FALSE(std::filesystem::exists(std::filesystem::path(path.wstring() + L".tmp")));
+}
+
+TEST_CASE("persistence monitor key format round-trips", "[persistence]") {
+    const auto path = test_state_path("monitor-key");
+    use_state_path(path);
+
+    persistence::AppState state;
+    persistence::MonitorState monitor;
+    monitor.width = 1920;
+    monitor.height = 1080;
+    monitor.left = 0;
+    monitor.top = 0;
+    state.monitors.push_back(monitor);
+
+    REQUIRE(persistence::SaveAppState(state));
+    REQUIRE(read_text(path).find("\"1920x1080@0,0\"") != std::string::npos);
+
+    persistence::AppState loaded;
+    REQUIRE(persistence::LoadAppState(loaded));
+    REQUIRE(loaded.monitors.size() == 1);
+    REQUIRE(persistence::MonitorKey(loaded.monitors[0]) == "1920x1080@0,0");
+}
+
+TEST_CASE("persistence cut timestamps shift for fresh sim load", "[persistence]") {
+    const auto path = test_state_path("time-shift");
+    use_state_path(path);
+
+    Sim running;
+    running.globalTime = 100.0;
+    running.blades.push_back(make_blade(30.0, 10.0));
+    running.blades[0].cutHeight = 0.0;
+    running.blades[0].regrowStart = 80.0 + CUT_DURATION_SEC + running.blades[0].regrowDelay;
+
+    auto cuts = sim_get_cuts(running);
+    REQUIRE(cuts.size() == 1);
+    REQUIRE(cuts[0].cutTime == Approx(-20.0).margin(1e-9));
+
+    persistence::AppState state;
+    persistence::MonitorState monitor;
+    monitor.width = 1920;
+    monitor.height = 1080;
+    monitor.left = 0;
+    monitor.top = 0;
+    monitor.cuts = cuts;
+    state.monitors.push_back(monitor);
+    REQUIRE(persistence::SaveAppState(state));
+
+    persistence::AppState loaded;
+    REQUIRE(persistence::LoadAppState(loaded));
+    REQUIRE(loaded.monitors[0].cuts[0].cutTime < 0.0);
+
+    Sim fresh;
+    fresh.globalTime = 0.0;
+    fresh.blades.push_back(make_blade(30.0, 10.0));
+    sim_apply_cuts(fresh, loaded.monitors[0].cuts);
+    REQUIRE(fresh.blades[0].cutHeight == Approx(0.0).margin(1e-9));
+    REQUIRE(fresh.blades[0].regrowStart == Approx(10.0 + CUT_DURATION_SEC).margin(1e-9));
+}
+
+TEST_CASE("persistence unmatched monitor cuts are skipped", "[persistence]") {
+    const auto path = test_state_path("unmatched-monitor");
+    use_state_path(path);
+
+    persistence::AppState state;
+    persistence::MonitorState unmatched;
+    unmatched.width = 9999;
+    unmatched.height = 9999;
+    unmatched.left = 99;
+    unmatched.top = 99;
+    unmatched.cuts.push_back(persistence::CutRecord{ 0, -20.0 });
+    state.monitors.push_back(unmatched);
+    REQUIRE(persistence::SaveAppState(state));
+
+    persistence::AppState loaded;
+    REQUIRE(persistence::LoadAppState(loaded));
+
+    Sim sim;
+    sim.blades.push_back(make_blade(30.0, 10.0));
+    const int width = 1920;
+    const int height = 1080;
+    const int left = 0;
+    const int top = 0;
+    const auto match = std::find_if(loaded.monitors.begin(), loaded.monitors.end(),
+        [&](const persistence::MonitorState& monitor) {
+            return monitor.width == width && monitor.height == height
+                && monitor.left == left && monitor.top == top;
+        });
+    if (match != loaded.monitors.end()) {
+        sim_apply_cuts(sim, match->cuts);
+    }
+
+    REQUIRE(sim_get_cuts(sim).empty());
+}
+
+TEST_CASE("persistence json is human readable", "[persistence]") {
+    const auto path = test_state_path("human-readable");
+    use_state_path(path);
+
+    REQUIRE(persistence::SaveAppState(make_state_with_cuts()));
+    const std::string text = read_text(path);
+    REQUIRE(text.find('\n') != std::string::npos);
+    REQUIRE(text.find("  \"version\"") != std::string::npos);
+    REQUIRE(text.find("    \"") != std::string::npos);
+}

src/modules/DesktopGrass/DesktopGrass.Native.Tests/src/pine_tests.cpp

@@ -0,0 +1,255 @@
+// pine_tests.cpp - §15.1 Winter pine trees (slot-bound, mirrors §14 cacti).
+
+#include "../third_party/catch2/catch.hpp"
+#include "Sim.h"
+#include "snapshot_data.h"
+
+#include <cmath>
+#include <cstddef>
+#include <vector>
+
+using namespace desktopgrass;
+
+namespace {
+
+constexpr double kMonitor1920 = 1920.0;
+
+struct ExpectedTree {
+    std::size_t slotIndex = 0;
+    uint8_t variant = 0;
+    double height = 0.0;
+    double width = 0.0;
+    int tierCount = 0;
+};
+
+ExpectedTree first_expected_tree(std::size_t bladeCount) {
+    Prng p;
+    prng_init(p, CANONICAL_TEST_SEED ^ PINE_PRNG_SALT);
+
+    for (std::size_t i = 0; i < bladeCount; ++i) {
+        const double r = prng_uniform(p, 0.0, 1.0);
+        if (r >= PINE_PROBABILITY) continue;
+
+        ExpectedTree expected{};
+        expected.slotIndex = i;
+        const double variantDraw = prng_uniform(p, 0.0, 1.0);
+        expected.variant = variantDraw < BIRCH_VARIANT_PROBABILITY ? 1 : 0;
+        expected.height = prng_uniform(p, PINE_HEIGHT_MIN, PINE_HEIGHT_MAX);
+        if (expected.variant == 1) {
+            expected.width = prng_uniform(p, BIRCH_TRUNK_WIDTH_MIN, BIRCH_TRUNK_WIDTH_MAX);
+        } else {
+            expected.width = prng_uniform(p, PINE_WIDTH_MIN, PINE_WIDTH_MAX);
+        }
+        const double tierDraw = prng_uniform(p,
+            static_cast<double>(PINE_TIER_COUNT_MIN),
+            static_cast<double>(PINE_TIER_COUNT_MAX + 1));
+        int tiers = static_cast<int>(std::floor(tierDraw));
+        if (tiers < PINE_TIER_COUNT_MIN) tiers = PINE_TIER_COUNT_MIN;
+        if (tiers > PINE_TIER_COUNT_MAX) tiers = PINE_TIER_COUNT_MAX;
+        expected.tierCount = tiers;
+        return expected;
+    }
+
+    FAIL("canonical seed produced no tree slot");
+    return {};
+}
+
+} // anonymous
+
+TEST_CASE("Pine constants are pinned", "[pine][constants]") {
+    REQUIRE(PINE_PROBABILITY == Approx(0.0075));
+    REQUIRE(PINE_HEIGHT_MIN == Approx(45.0));
+    REQUIRE(PINE_HEIGHT_MAX == Approx(90.0));
+    REQUIRE(PINE_WIDTH_MIN  == Approx(28.0));
+    REQUIRE(PINE_WIDTH_MAX  == Approx(48.0));
+    REQUIRE(PINE_TIER_COUNT_MIN == 2);
+    REQUIRE(PINE_TIER_COUNT_MAX == 4);
+    REQUIRE(PINE_TIP_TAPER == Approx(0.25));
+    REQUIRE(PINE_TIER_OVERLAP == Approx(0.15));
+    REQUIRE(PINE_SNOW_CAP_FRACTION == Approx(0.30));
+    REQUIRE(PINE_COLOR == 0xFF1B5E20u);
+    REQUIRE(PINE_PRNG_SALT == 0x50494E4550494E45ull);
+}
+
+TEST_CASE("Birch constants are pinned", "[pine][birch][constants]") {
+    REQUIRE(BIRCH_VARIANT_PROBABILITY == Approx(0.30));
+    REQUIRE(BIRCH_TRUNK_WIDTH_MIN == Approx(4.0));
+    REQUIRE(BIRCH_TRUNK_WIDTH_MAX == Approx(7.0));
+    REQUIRE(BIRCH_BARK_MARK_COUNT == 5);
+    REQUIRE(BIRCH_BARK_MARK_LENGTH_FRAC == Approx(0.50));
+    REQUIRE(BIRCH_BRANCH_COUNT == 6);
+    REQUIRE(BIRCH_SNOW_CAP_FRACTION == Approx(0.18));
+    REQUIRE(BIRCH_BARK_COLOR == 0xFFEFEFE6u);
+    REQUIRE(BIRCH_MARK_COLOR == 0xFF2A2A28u);
+}
+
+TEST_CASE("sim_set_scene Winter promotes some slots to trees", "[pine][scene]") {
+    Sim sim = sim_init(CANONICAL_TEST_SEED, kMonitor1920, DEFAULT_DENSITY);
+    sim_set_scene(sim, Scene::Winter);
+
+    REQUIRE(sim.currentScene == Scene::Winter);
+    std::size_t treeCount = 0;
+    for (const Blade& b : sim.blades) {
+        if (b.isPine) {
+            ++treeCount;
+            REQUIRE(b.pineTierCount >= PINE_TIER_COUNT_MIN);
+            REQUIRE(b.pineTierCount <= PINE_TIER_COUNT_MAX);
+            REQUIRE(b.pineHeight >= PINE_HEIGHT_MIN);
+            REQUIRE(b.pineHeight <= PINE_HEIGHT_MAX);
+            const double widthMin = (b.treeVariant == 1) ? BIRCH_TRUNK_WIDTH_MIN : PINE_WIDTH_MIN;
+            const double widthMax = (b.treeVariant == 1) ? BIRCH_TRUNK_WIDTH_MAX : PINE_WIDTH_MAX;
+            REQUIRE(b.pineWidth >= widthMin);
+            REQUIRE(b.pineWidth <= widthMax);
+        }
+    }
+    REQUIRE(treeCount >= 1);
+    REQUIRE(treeCount <= 25);
+}
+
+TEST_CASE("First tree matches the spec-derived PRNG snapshot", "[pine][snapshot]") {
+    Sim sim = sim_init(CANONICAL_TEST_SEED, kMonitor1920, DEFAULT_DENSITY);
+    const ExpectedTree expected = first_expected_tree(sim.blades.size());
+
+    sim_set_scene(sim, Scene::Winter);
+
+    REQUIRE(expected.slotIndex < sim.blades.size());
+    const Blade& b = sim.blades[expected.slotIndex];
+    REQUIRE(b.isPine);
+    REQUIRE(b.treeVariant == expected.variant);
+    REQUIRE(b.pineHeight == Approx(expected.height).margin(1e-12));
+    REQUIRE(b.pineWidth  == Approx(expected.width).margin(1e-12));
+    REQUIRE(b.pineTierCount == expected.tierCount);
+}
+
+TEST_CASE("Grass scene restores tree slots to vanilla variants", "[pine][restore]") {
+    Sim sim = sim_init(CANONICAL_TEST_SEED, kMonitor1920, DEFAULT_DENSITY);
+    const ExpectedTree expected = first_expected_tree(sim.blades.size());
+    REQUIRE(expected.slotIndex < sim.blades.size());
+
+    Blade& target = sim.blades[expected.slotIndex];
+    target.isFlower = true;
+    target.isMushroom = true;
+    target.originalIsFlower = true;
+    target.originalIsMushroom = true;
+
+    sim_set_scene(sim, Scene::Winter);
+    REQUIRE(sim.blades[expected.slotIndex].isPine);
+    REQUIRE_FALSE(sim.blades[expected.slotIndex].isFlower);
+    REQUIRE_FALSE(sim.blades[expected.slotIndex].isMushroom);
+
+    sim_set_scene(sim, Scene::Grass);
+    REQUIRE_FALSE(sim.blades[expected.slotIndex].isPine);
+    REQUIRE(sim.blades[expected.slotIndex].treeVariant == 0);
+    REQUIRE(sim.blades[expected.slotIndex].isFlower);
+    REQUIRE(sim.blades[expected.slotIndex].isMushroom);
+}
+
+TEST_CASE("Winter produces both pine and birch variants over canonical seed", "[pine][birch]") {
+    Sim sim = sim_init(CANONICAL_TEST_SEED, kMonitor1920, DEFAULT_DENSITY);
+    sim_set_scene(sim, Scene::Winter);
+
+    std::size_t pineCount = 0;
+    std::size_t birchCount = 0;
+    for (const Blade& b : sim.blades) {
+        if (!b.isPine) continue;
+        if (b.treeVariant == 0) {
+            ++pineCount;
+            REQUIRE(b.pineWidth >= PINE_WIDTH_MIN);
+            REQUIRE(b.pineWidth <= PINE_WIDTH_MAX);
+        } else {
+            REQUIRE(b.treeVariant == 1);
+            ++birchCount;
+            REQUIRE(b.pineWidth >= BIRCH_TRUNK_WIDTH_MIN);
+            REQUIRE(b.pineWidth <= BIRCH_TRUNK_WIDTH_MAX);
+        }
+    }
+    REQUIRE(pineCount >= 1);
+    REQUIRE(birchCount >= 1);
+}
+
+TEST_CASE("Winter scene suppresses mushrooms on every slot", "[pine][winter][mushroom]") {
+    Sim sim = sim_init(CANONICAL_TEST_SEED, kMonitor1920, DEFAULT_DENSITY);
+    // Pre-mark a handful of slots as mushrooms; Winter must clear them all.
+    for (std::size_t i = 0; i < sim.blades.size(); i += 17) {
+        sim.blades[i].isMushroom = true;
+        sim.blades[i].originalIsMushroom = true;
+    }
+
+    sim_set_scene(sim, Scene::Winter);
+
+    for (const Blade& b : sim.blades) REQUIRE_FALSE(b.isMushroom);
+
+    // Switching back to Grass must restore the original mushroom flags.
+    sim_set_scene(sim, Scene::Grass);
+    REQUIRE(sim.blades[0].isMushroom == sim.blades[0].originalIsMushroom);
+}
+
+TEST_CASE("Winter grass height scale is pinned", "[pine][winter][scale]") {
+    REQUIRE(WINTER_GRASS_HEIGHT_SCALE == Approx(0.5));
+}
+
+TEST_CASE("Tree depth constants are pinned", "[pine][depth][constants]") {
+    REQUIRE(TREE_BACKGROUND_PROBABILITY == Approx(0.45));
+    REQUIRE(TREE_BG_SCALE == Approx(0.62));
+    REQUIRE(TREE_BG_OPACITY == Approx(0.78f));
+}
+
+TEST_CASE("Winter mixes foreground and background trees", "[pine][depth]") {
+    Sim sim = sim_init(CANONICAL_TEST_SEED, kMonitor1920, DEFAULT_DENSITY);
+    sim_set_scene(sim, Scene::Winter);
+
+    std::size_t fg = 0;
+    std::size_t bg = 0;
+    for (const Blade& b : sim.blades) {
+        if (!b.isPine) continue;
+        if (b.treeBackground) ++bg; else ++fg;
+    }
+    REQUIRE(fg >= 1);
+    REQUIRE(bg >= 1);
+}
+
+TEST_CASE("Tree depth assignment is deterministic across re-entry", "[pine][depth]") {
+    Sim sim = sim_init(CANONICAL_TEST_SEED, kMonitor1920, DEFAULT_DENSITY);
+    sim_set_scene(sim, Scene::Winter);
+
+    std::vector<bool> firstPass;
+    for (const Blade& b : sim.blades) {
+        if (b.isPine) firstPass.push_back(b.treeBackground);
+    }
+
+    // Leaving and re-entering Winter must reproduce the same depth layout.
+    sim_set_scene(sim, Scene::Grass);
+    sim_set_scene(sim, Scene::Winter);
+
+    std::size_t idx = 0;
+    for (const Blade& b : sim.blades) {
+        if (!b.isPine) continue;
+        REQUIRE(idx < firstPass.size());
+        REQUIRE(b.treeBackground == firstPass[idx]);
+        ++idx;
+    }
+    REQUIRE(idx == firstPass.size());
+}
+
+TEST_CASE("Non-winter scenes clear the tree background flag", "[pine][depth][restore]") {
+    Sim sim = sim_init(CANONICAL_TEST_SEED, kMonitor1920, DEFAULT_DENSITY);
+    sim_set_scene(sim, Scene::Winter);
+    sim_set_scene(sim, Scene::Grass);
+    for (const Blade& b : sim.blades) REQUIRE_FALSE(b.treeBackground);
+}
+
+TEST_CASE("Winter scene leaves the canonical first blade geometry bit-identical", "[pine][snapshot]") {
+    Sim sim = sim_init(CANONICAL_TEST_SEED, kMonitor1920, 1.0);
+    REQUIRE(sim.blades.size() == desktopgrass::test::CANONICAL_BLADE_COUNT);
+
+    sim_set_scene(sim, Scene::Winter);
+
+    const Blade& first = sim.blades[0];
+    const auto& expected = desktopgrass::test::CANONICAL_FIRST_10[0];
+    REQUIRE(first.baseX == Approx(expected.baseX).margin(1e-12));
+    REQUIRE(first.height == Approx(expected.height).margin(1e-12));
+    REQUIRE(first.thickness == Approx(expected.thickness).margin(1e-12));
+    REQUIRE(first.hue == expected.hue);
+    REQUIRE(first.swayPhaseOffset == Approx(expected.sway).margin(1e-12));
+    REQUIRE(first.stiffness == Approx(expected.stiffness).margin(1e-12));
+}

src/modules/DesktopGrass/DesktopGrass.Native.Tests/src/prng_tests.cpp

@@ -0,0 +1,78 @@
+// prng_tests.cpp
+//
+// Conformance + snapshot tests for the PRNG (architecture.md §3).
+
+#include "../third_party/catch2/catch.hpp"
+#include "Sim.h"
+#include "snapshot_data.h"
+
+using namespace desktopgrass;
+using namespace desktopgrass::test;
+
+TEST_CASE("PRNG matches the canonical 16-output snapshot", "[prng][snapshot]") {
+    Prng p;
+    prng_init(p, CANONICAL_TEST_SEED);
+
+    for (std::size_t i = 0; i < 16; ++i) {
+        uint64_t v = prng_next_u64(p);
+        INFO("index = " << i);
+        REQUIRE(v == CANONICAL_PRNG_SNAPSHOT[i]);
+    }
+}
+
+TEST_CASE("PRNG is deterministic for a given seed", "[prng]") {
+    Prng a, b;
+    prng_init(a, CANONICAL_TEST_SEED);
+    prng_init(b, CANONICAL_TEST_SEED);
+    for (int i = 0; i < 1000; ++i) {
+        REQUIRE(prng_next_u64(a) == prng_next_u64(b));
+    }
+}
+
+TEST_CASE("PRNG decorrelates seed=0 via splitmix64", "[prng]") {
+    // seed == 0 must not produce a stuck-at-zero PRNG.
+    Prng p;
+    prng_init(p, 0);
+    REQUIRE(p.state != 0);
+    uint64_t a = prng_next_u64(p);
+    uint64_t b = prng_next_u64(p);
+    REQUIRE(a != 0);
+    REQUIRE(b != 0);
+    REQUIRE(a != b);
+}
+
+TEST_CASE("prng_next_unit is in [0, 1)", "[prng]") {
+    Prng p;
+    prng_init(p, CANONICAL_TEST_SEED);
+    for (int i = 0; i < 10000; ++i) {
+        double u = prng_next_unit(p);
+        REQUIRE(u >= 0.0);
+        REQUIRE(u <  1.0);
+    }
+}
+
+TEST_CASE("prng_uniform stays within [lo, hi)", "[prng]") {
+    Prng p;
+    prng_init(p, 12345);
+    for (int i = 0; i < 10000; ++i) {
+        double v = prng_uniform(p, 8.0, 40.0);
+        REQUIRE(v >= 8.0);
+        REQUIRE(v <  40.0);
+    }
+}
+
+TEST_CASE("prng_index is in [0, n)", "[prng]") {
+    Prng p;
+    prng_init(p, 42);
+    bool sawZero = false;
+    bool sawFive = false;
+    for (int i = 0; i < 10000; ++i) {
+        uint32_t v = prng_index(p, PALETTE_SIZE);
+        REQUIRE(v < PALETTE_SIZE);
+        if (v == 0) sawZero = true;
+        if (v == 5) sawFive = true;
+    }
+    // Distribution sanity. Not strict — just confirms we cover both extremes.
+    REQUIRE(sawZero);
+    REQUIRE(sawFive);
+}

src/modules/DesktopGrass/DesktopGrass.Native.Tests/src/prop_spacing_tests.cpp

@@ -0,0 +1,136 @@
+#include "catch.hpp"
+
+#include "Sim.h"
+#include "Constants.h"
+
+#include <vector>
+
+using namespace desktopgrass;
+
+namespace {
+
+constexpr double kMonitor1920 = 1920.0;
+constexpr double kDensity     = 1.0;
+constexpr uint64_t kSeed      = 0xDE5C70F6A55ED511ull;
+
+struct Prop {
+    double leftEdge;
+    double rightEdge;
+};
+
+double cactus_half_width(const Blade& b) {
+    return (b.cactusType != 0) ? b.cactusWidth * 1.55 : b.cactusWidth * 0.5;
+}
+
+double pine_half_width(const Blade& b) {
+    double hw = (b.treeVariant == 1) ? b.pineWidth * 4.0 : b.pineWidth * 0.5;
+    if (b.treeBackground) hw *= TREE_BG_SCALE;
+    return hw;
+}
+
+// Walk the prop list left-to-right and verify that every adjacent pair has
+// at least PROP_MIN_GAP_DIP between the right edge of one and the left edge
+// of the next. The generators emit props in baseX order so a single linear
+// pass is sufficient.
+void require_spacing(const std::vector<Prop>& props, double minGap, const char* label) {
+    INFO(label << ": " << props.size() << " props placed");
+    REQUIRE(props.size() >= 1);
+    for (std::size_t i = 1; i < props.size(); ++i) {
+        const double gap = props[i].leftEdge - props[i - 1].rightEdge;
+        INFO("pair " << (i - 1) << "→" << i
+             << " right=" << props[i - 1].rightEdge
+             << " left=" << props[i].leftEdge
+             << " gap=" << gap);
+        REQUIRE(gap >= minGap);
+    }
+}
+
+}  // namespace
+
+TEST_CASE("Desert cacti keep at least PROP_MIN_GAP_DIP between neighbours",
+          "[spacing][desert][cactus]") {
+    Sim sim = sim_init(kSeed, kMonitor1920, kDensity);
+    sim_set_scene(sim, Scene::Desert);
+
+    std::vector<Prop> cacti;
+    for (const Blade& b : sim.blades) {
+        if (!b.isCactus) continue;
+        const double hw = cactus_half_width(b);
+        cacti.push_back({b.baseX - hw, b.baseX + hw});
+    }
+    require_spacing(cacti, PROP_MIN_GAP_DIP, "cacti");
+}
+
+TEST_CASE("Winter pines keep at least PROP_MIN_GAP_DIP between same-layer neighbours",
+          "[spacing][winter][pine]") {
+    Sim sim = sim_init(kSeed, kMonitor1920, kDensity);
+    sim_set_scene(sim, Scene::Winter);
+
+    std::vector<Prop> fgPines;
+    std::vector<Prop> bgPines;
+    for (const Blade& b : sim.blades) {
+        if (!b.isPine) continue;
+        const double hw = pine_half_width(b);
+        Prop p{b.baseX - hw, b.baseX + hw};
+        if (b.treeBackground) bgPines.push_back(p);
+        else                  fgPines.push_back(p);
+    }
+    require_spacing(fgPines, PROP_MIN_GAP_DIP, "foreground pines");
+    require_spacing(bgPines, PROP_MIN_GAP_DIP, "background pines");
+}
+
+TEST_CASE("Autumn maples keep at least PROP_MIN_GAP_DIP between neighbours",
+          "[spacing][autumn][maple]") {
+    Sim sim = sim_init(kSeed, kMonitor1920, kDensity);
+    sim_set_scene(sim, Scene::Autumn);
+
+    std::vector<Prop> maples;
+    for (const Blade& b : sim.blades) {
+        if (!b.isMaple) continue;
+        const double hw = b.mapleCanopyRadius;
+        maples.push_back({b.baseX - hw, b.baseX + hw});
+    }
+    require_spacing(maples, PROP_MIN_GAP_DIP, "maples");
+}
+
+TEST_CASE("Ocean coral keep at least PROP_MIN_GAP_DIP between neighbours",
+          "[spacing][ocean][coral]") {
+    Sim sim = sim_init(kSeed, kMonitor1920, kDensity);
+    sim_set_scene(sim, Scene::Ocean);
+
+    std::vector<Prop> coral;
+    for (const Blade& b : sim.blades) {
+        if (!b.isCoral) continue;
+        const double hw = b.coralWidth * 0.5;
+        coral.push_back({b.baseX - hw, b.baseX + hw});
+    }
+    require_spacing(coral, PROP_MIN_GAP_DIP, "coral");
+}
+
+TEST_CASE("Prop spacing rule reduces but doesn't decimate the population",
+          "[spacing][population]") {
+    // Sanity check that gap rejection isn't aggressive enough to break the
+    // existing "near-spec probability" tests — each scene should still place
+    // at least a handful of props on a 1920-DIP window with canonical seed.
+    Sim sim = sim_init(kSeed, kMonitor1920, kDensity);
+
+    sim_set_scene(sim, Scene::Desert);
+    int cactusCount = 0;
+    for (const Blade& b : sim.blades) if (b.isCactus) ++cactusCount;
+    REQUIRE(cactusCount >= 1);
+
+    sim_set_scene(sim, Scene::Winter);
+    int pineCount = 0;
+    for (const Blade& b : sim.blades) if (b.isPine) ++pineCount;
+    REQUIRE(pineCount >= 3);
+
+    sim_set_scene(sim, Scene::Autumn);
+    int mapleCount = 0;
+    for (const Blade& b : sim.blades) if (b.isMaple) ++mapleCount;
+    REQUIRE(mapleCount >= 1);
+
+    sim_set_scene(sim, Scene::Ocean);
+    int coralCount = 0;
+    for (const Blade& b : sim.blades) if (b.isCoral) ++coralCount;
+    REQUIRE(coralCount >= 5);
+}

src/modules/DesktopGrass/DesktopGrass.Native.Tests/src/regrowth_tests.cpp

@@ -0,0 +1,196 @@
+// regrowth_tests.cpp
+//
+// Regrowth lifecycle tests (architecture.md §9 "Regrowth").
+//
+// Lifecycle: alive (cutHeight=1) -> cut anim (0.2s) -> stump (cutHeight=0,
+// regrowStart scheduled) -> wait regrowDelay -> regrow (linear over
+// regrowDuration) -> alive again.
+
+#include "../third_party/catch2/catch.hpp"
+#include "Sim.h"
+
+#include <cmath>
+
+using namespace desktopgrass;
+
+namespace {
+
+// A test blade that opts in to regrowth — sets delay and duration to small,
+// known values so we can deterministically tick through the lifecycle.
+Blade make_regrowing_blade(double baseX, double regrowDelay, double regrowDuration) {
+    Blade b{};
+    b.baseX            = baseX;
+    b.height           = 20.0;
+    b.thickness        = 1.5;
+    b.swayPhaseOffset  = 0.0;
+    b.stiffness        = 1.0;
+    b.cutHeight        = 1.0;
+    b.cutInitialHeight = 1.0;
+    b.cutAnimStart     = -1.0;
+    b.regrowDelay      = regrowDelay;
+    b.regrowDuration   = regrowDuration;
+    b.regrowStart      = -1.0;
+    return b;
+}
+
+Sim make_sim_with(Blade b) {
+    Sim sim;
+    sim.windowHeight = STRIP_HEIGHT + HEADROOM;
+    sim.blades.push_back(b);
+    return sim;
+}
+
+InputEvent click(double x, double y, double t) {
+    return InputEvent{ EventType::Click, x, y, t };
+}
+
+} // anonymous
+
+TEST_CASE("cut completion schedules regrowth", "[regrowth]") {
+    Sim sim = make_sim_with(make_regrowing_blade(100.0, /*delay=*/1.0, /*dur=*/0.5));
+    const double y = sim.windowHeight - 40.0;
+
+    InputEvent ev = click(100.0, y, 0.0);
+    sim_tick(sim, 0.0, &ev, 1);
+
+    // Run the cut animation to completion (200 ms).
+    for (int i = 0; i < 4; ++i) sim_tick(sim, 0.05, nullptr, 0);
+
+    REQUIRE(sim.blades[0].cutHeight    == Approx(0.0));
+    REQUIRE(sim.blades[0].cutAnimStart  < 0.0);
+    // regrowStart is scheduled at globalTime + regrowDelay = 0.2 + 1.0 = 1.2.
+    REQUIRE(sim.blades[0].regrowStart  == Approx(1.2).margin(1e-9));
+}
+
+TEST_CASE("regrowth is linear over regrowDuration", "[regrowth]") {
+    Sim sim = make_sim_with(make_regrowing_blade(100.0, /*delay=*/0.5, /*dur=*/0.4));
+    const double y = sim.windowHeight - 40.0;
+
+    InputEvent ev = click(100.0, y, 0.0);
+    sim_tick(sim, 0.0, &ev, 1);
+
+    // Cut animation: 4 x 50 ms -> globalTime=0.20, cutHeight=0, regrowStart=0.70.
+    for (int i = 0; i < 4; ++i) sim_tick(sim, 0.05, nullptr, 0);
+    REQUIRE(sim.blades[0].regrowStart == Approx(0.70).margin(1e-9));
+
+    // Tick through the regrow delay (0.5s = 10 frames). Blade stays cut.
+    for (int i = 0; i < 10; ++i) {
+        sim_tick(sim, 0.05, nullptr, 0);
+        REQUIRE(sim.blades[0].cutHeight == Approx(0.0).margin(1e-9));
+    }
+    // globalTime = 0.70 now (start of regrowth).
+
+    // Quarter of the way through regrowth (dur=0.4 -> 0.10 elapsed): cutHeight = 0.25.
+    sim_tick(sim, 0.10, nullptr, 0);
+    REQUIRE(sim.blades[0].cutHeight == Approx(0.25).margin(1e-9));
+
+    // Half way: cutHeight = 0.5.
+    sim_tick(sim, 0.10, nullptr, 0);
+    REQUIRE(sim.blades[0].cutHeight == Approx(0.5).margin(1e-9));
+
+    // Three quarters: cutHeight = 0.75.
+    sim_tick(sim, 0.10, nullptr, 0);
+    REQUIRE(sim.blades[0].cutHeight == Approx(0.75).margin(1e-9));
+
+    // Full: cutHeight = 1.0, regrowStart idle.
+    sim_tick(sim, 0.10, nullptr, 0);
+    REQUIRE(sim.blades[0].cutHeight  == Approx(1.0).margin(1e-9));
+    REQUIRE(sim.blades[0].regrowStart  < 0.0);
+
+    // After regrowth, further ticks don't change cutHeight.
+    sim_tick(sim, 1.0, nullptr, 0);
+    REQUIRE(sim.blades[0].cutHeight  == Approx(1.0).margin(1e-9));
+}
+
+TEST_CASE("re-click during regrowth restarts the cut from current height", "[regrowth]") {
+    Sim sim = make_sim_with(make_regrowing_blade(100.0, /*delay=*/0.1, /*dur=*/0.4));
+    const double y = sim.windowHeight - 40.0;
+
+    InputEvent ev1 = click(100.0, y, 0.0);
+    sim_tick(sim, 0.0, &ev1, 1);
+
+    // Drive the cut to completion + delay + halfway through regrowth.
+    // 4 ticks of 50 ms = 200 ms (cut done), globalTime=0.20, regrowStart=0.30.
+    for (int i = 0; i < 4; ++i) sim_tick(sim, 0.05, nullptr, 0);
+    // 2 ticks of 50 ms = 100 ms further -> globalTime=0.30 (regrowth starts).
+    for (int i = 0; i < 2; ++i) sim_tick(sim, 0.05, nullptr, 0);
+    // 4 ticks of 50 ms = 200 ms into the 0.4s regrowth -> cutHeight should be 0.5.
+    for (int i = 0; i < 4; ++i) sim_tick(sim, 0.05, nullptr, 0);
+    REQUIRE(sim.blades[0].cutHeight == Approx(0.5).margin(1e-9));
+    REQUIRE(sim.blades[0].regrowStart > 0.0);
+
+    // Click again mid-regrowth.
+    InputEvent ev2 = click(100.0, y, 0.5);
+    sim_tick(sim, 0.0, &ev2, 1);
+
+    // Cut should restart: cutAnimStart valid, cutInitialHeight = 0.5,
+    // regrowStart cleared.
+    REQUIRE(sim.blades[0].cutAnimStart    >= 0.0);
+    REQUIRE(sim.blades[0].cutInitialHeight == Approx(0.5).margin(1e-9));
+    REQUIRE(sim.blades[0].regrowStart      < 0.0);
+
+    // Animate cut for 200 ms -> cutHeight returns to 0 and regrowth re-schedules.
+    for (int i = 0; i < 4; ++i) sim_tick(sim, 0.05, nullptr, 0);
+    REQUIRE(sim.blades[0].cutHeight    == Approx(0.0).margin(1e-9));
+    REQUIRE(sim.blades[0].cutAnimStart  < 0.0);
+    REQUIRE(sim.blades[0].regrowStart   > 0.0);
+}
+
+TEST_CASE("click on stump (cut, waiting to regrow) is a no-op", "[regrowth]") {
+    // cutHeight=0 and regrowStart scheduled but not yet started.
+    Sim sim = make_sim_with(make_regrowing_blade(100.0, /*delay=*/10.0, /*dur=*/1.0));
+    sim.blades[0].cutHeight    = 0.0;
+    sim.blades[0].cutAnimStart = -1.0;
+    sim.blades[0].regrowStart  = 5.0;  // scheduled
+
+    const double y = sim.windowHeight - 40.0;
+    InputEvent ev = click(100.0, y, 0.0);
+    sim_tick(sim, 0.0, &ev, 1);
+
+    REQUIRE(sim.blades[0].cutHeight    == Approx(0.0));
+    REQUIRE(sim.blades[0].cutAnimStart  < 0.0);
+    REQUIRE(sim.blades[0].regrowStart  == Approx(5.0));
+}
+
+TEST_CASE("regrowth jitter is deterministic for a given seed", "[regrowth][snapshot]") {
+    std::vector<Blade> a;
+    std::vector<Blade> b;
+    generate_blades(CANONICAL_TEST_SEED, 1920.0, 1.0, a);
+    generate_blades(CANONICAL_TEST_SEED, 1920.0, 1.0, b);
+
+    REQUIRE(a.size() == b.size());
+    for (std::size_t i = 0; i < a.size(); ++i) {
+        REQUIRE(a[i].regrowDelay    == Approx(b[i].regrowDelay   ).margin(1e-12));
+        REQUIRE(a[i].regrowDuration == Approx(b[i].regrowDuration).margin(1e-12));
+    }
+}
+
+TEST_CASE("regrowth jitter falls within configured min/max", "[regrowth][snapshot]") {
+    std::vector<Blade> blades;
+    generate_blades(CANONICAL_TEST_SEED, 1920.0, 1.0, blades);
+
+    REQUIRE(blades.size() > 50);
+    for (const Blade& b : blades) {
+        REQUIRE(b.regrowDelay    >= REGROW_DELAY_MIN);
+        REQUIRE(b.regrowDelay    <  REGROW_DELAY_MAX);
+        REQUIRE(b.regrowDuration >= REGROW_DURATION_MIN);
+        REQUIRE(b.regrowDuration <  REGROW_DURATION_MAX);
+        REQUIRE(b.regrowStart    == Approx(-1.0));
+    }
+}
+
+TEST_CASE("regrowth jitter does not perturb static-field generation", "[regrowth][snapshot]") {
+    // Whole point of the salted second-stream design: snapshot tests for
+    // baseX/height/etc are unaffected by adding regrowth. Cross-check by
+    // generating with and without regrowth jitter via two seeds that share
+    // the main stream but differ in regrow stream (i.e. same seed produces
+    // identical static fields).
+    std::vector<Blade> a;
+    generate_blades(CANONICAL_TEST_SEED, 1920.0, 1.0, a);
+
+    // Spec gates the static-field count + per-blade values; this is here
+    // as a tripwire if anyone slips an extra prng_next_* call into the
+    // main stream during generation.
+    REQUIRE(a.size() > 0);
+    REQUIRE(a[0].baseX    == Approx(a[0].baseX));   // tautology — placeholder
+}

src/modules/DesktopGrass/DesktopGrass.Native.Tests/src/scene_tests.cpp

@@ -0,0 +1,105 @@
+// scene_tests.cpp
+//
+// Scene infrastructure tests (architecture.md §13).
+//
+// Coverage:
+//   * Scene enum discriminants match the spec ({Grass=0, Desert=1, Winter=2, Autumn=3}).
+//   * sim_init defaults currentScene to SCENE_DEFAULT (= Grass).
+//   * sim_set_scene does not perturb blade positions/dimensions/hues or
+//     any non-scene PRNG stream.
+//   * Per-scene palette tables are 6 entries each with full-alpha ARGB.
+//   * SCENE_PALETTES[Grass] is bit-identical to the original §4 PALETTE.
+
+#include "../third_party/catch2/catch.hpp"
+#include "Sim.h"
+#include "snapshot_data.h"
+
+#include <cstdint>
+
+using namespace desktopgrass;
+
+TEST_CASE("Scene enum has spec-locked discriminants", "[scene][enum]") {
+    REQUIRE(static_cast<int>(Scene::Grass)  == 0);
+    REQUIRE(static_cast<int>(Scene::Desert) == 1);
+    REQUIRE(static_cast<int>(Scene::Winter) == 2);
+    REQUIRE(static_cast<int>(Scene::Autumn) == 3);
+    REQUIRE(static_cast<int>(Scene::Ocean)  == 4);
+    REQUIRE(SCENE_COUNT == 5);
+    REQUIRE(static_cast<int>(SCENE_DEFAULT) == 0);
+}
+
+TEST_CASE("sim_init defaults currentScene to Grass", "[scene][init]") {
+    Sim sim = sim_init(CANONICAL_TEST_SEED, 1920.0, DEFAULT_DENSITY);
+    REQUIRE(sim.currentScene == Scene::Grass);
+}
+
+TEST_CASE("sim_set_scene does not perturb blade geometry or hues", "[scene][independence]") {
+    Sim a = sim_init(CANONICAL_TEST_SEED, 1920.0, 1.0);
+    Sim b = sim_init(CANONICAL_TEST_SEED, 1920.0, 1.0);
+
+    // Same seed → same blades initially.
+    REQUIRE(a.blades.size() == b.blades.size());
+    REQUIRE(a.blades.size() == desktopgrass::test::CANONICAL_BLADE_COUNT);
+
+    sim_set_scene(b, Scene::Desert);
+
+    REQUIRE(b.currentScene == Scene::Desert);
+    REQUIRE(a.currentScene == Scene::Grass);
+    REQUIRE(a.blades.size() == b.blades.size());
+    for (size_t i = 0; i < a.blades.size(); ++i) {
+        REQUIRE(a.blades[i].baseX     == Approx(b.blades[i].baseX));
+        REQUIRE(a.blades[i].height    == Approx(b.blades[i].height));
+        REQUIRE(a.blades[i].thickness == Approx(b.blades[i].thickness));
+        REQUIRE(a.blades[i].hue       == b.blades[i].hue);
+    }
+    // Desert cacti may mutate variant tags, but geometry and ambient PRNG stay untouched.
+    REQUIRE(a.ambientPrng.state == b.ambientPrng.state);
+    REQUIRE(a.nextAmbientGustTime == Approx(b.nextAmbientGustTime));
+}
+
+TEST_CASE("sim_set_scene round-trips through all values", "[scene][api]") {
+    Sim sim = sim_init(CANONICAL_TEST_SEED, 1920.0, DEFAULT_DENSITY);
+    sim_set_scene(sim, Scene::Desert);  REQUIRE(sim.currentScene == Scene::Desert);
+    sim_set_scene(sim, Scene::Winter);  REQUIRE(sim.currentScene == Scene::Winter);
+    sim_set_scene(sim, Scene::Autumn);  REQUIRE(sim.currentScene == Scene::Autumn);
+    sim_set_scene(sim, Scene::Ocean);   REQUIRE(sim.currentScene == Scene::Ocean);
+    sim_set_scene(sim, Scene::Grass);   REQUIRE(sim.currentScene == Scene::Grass);
+}
+
+TEST_CASE("Per-scene palette tables are 6 ARGB entries with full alpha", "[scene][palette]") {
+    for (int s = 0; s < SCENE_COUNT; ++s) {
+        for (int i = 0; i < PALETTE_SIZE; ++i) {
+            const uint32_t argb = SCENE_PALETTES[s][i];
+            const uint8_t alpha = static_cast<uint8_t>((argb >> 24) & 0xFFu);
+            REQUIRE(alpha == 0xFFu);
+        }
+    }
+}
+
+TEST_CASE("Grass scene palette is bit-identical to the original §4 PALETTE", "[scene][palette]") {
+    for (int i = 0; i < PALETTE_SIZE; ++i) {
+        REQUIRE(SCENE_PALETTES[static_cast<int>(Scene::Grass)][i] == PALETTE[i]);
+    }
+}
+
+TEST_CASE("Desert palette values match spec §13", "[scene][palette]") {
+    constexpr uint32_t expected[PALETTE_SIZE] = {
+        0xFFC9A26Bu, 0xFFB48A56u, 0xFFD9B57Au,
+        0xFF8F6E3Fu, 0xFFE6C896u, 0xFFA67843u,
+    };
+    for (int i = 0; i < PALETTE_SIZE; ++i) {
+        REQUIRE(SCENE_PALETTES[static_cast<int>(Scene::Desert)][i] == expected[i]);
+        REQUIRE(DESERT_PALETTE[i] == expected[i]);
+    }
+}
+
+TEST_CASE("Winter palette values match spec §13", "[scene][palette]") {
+    constexpr uint32_t expected[PALETTE_SIZE] = {
+        0xFFE8EEF5u, 0xFFB7C4D2u, 0xFFCBD8E5u,
+        0xFFD7E2EEu, 0xFFA8B7C6u, 0xFFEEF3F8u,
+    };
+    for (int i = 0; i < PALETTE_SIZE; ++i) {
+        REQUIRE(SCENE_PALETTES[static_cast<int>(Scene::Winter)][i] == expected[i]);
+        REQUIRE(WINTER_PALETTE[i] == expected[i]);
+    }
+}

src/modules/DesktopGrass/DesktopGrass.Native.Tests/src/sheep_greeting_tests.cpp

@@ -0,0 +1,228 @@
+// sheep_greeting_tests.cpp
+//
+// §16 sheep proximity-greeting tests. Mirrors Win2D SheepGreetingTests.cs.
+
+#include "../third_party/catch2/catch.hpp"
+#include "Sim.h"
+
+#include <algorithm>
+#include <cmath>
+#include <cstddef>
+#include <vector>
+
+using namespace desktopgrass;
+
+namespace {
+
+constexpr double Monitor1920 = 1920.0;
+constexpr double EligibleAge = 2.0;
+constexpr double LongTimer = 10.0;
+
+Sim build_sheep_sim() {
+    Sim sim = sim_init(CANONICAL_TEST_SEED, Monitor1920, DEFAULT_DENSITY);
+    sim_set_critter(sim, CritterKind::Sheep);
+    return sim;
+}
+
+std::vector<std::size_t> sheep_indices(const Sim& sim) {
+    std::vector<std::size_t> indices;
+    for (std::size_t i = 0; i < sim.entities.size(); ++i) {
+        if (sim.entities[i].kind == EntityKind::Sheep) indices.push_back(i);
+    }
+    return indices;
+}
+
+void set_sheep(Sim& sim, std::size_t index, double x, double vx,
+               uint8_t state = SHEEP_STATE_WALKING,
+               double age = EligibleAge,
+               double stateTimer = LongTimer) {
+    Entity& e = sim.entities[index];
+    e.x = x;
+    e.vx = vx;
+    e.state = state;
+    e.age = age;
+    e.stateTimer = stateTimer;
+}
+
+std::vector<std::size_t> prepare_two_sheep(Sim& sim, double gap = 40.0,
+                                           double ageA = EligibleAge,
+                                           double ageB = EligibleAge) {
+    std::vector<std::size_t> indices = sheep_indices(sim);
+    REQUIRE(indices.size() >= 2);
+
+    set_sheep(sim, indices[0], 500.0, -20.0, SHEEP_STATE_WALKING, ageA);
+    set_sheep(sim, indices[1], 500.0 + gap, 18.0, SHEEP_STATE_WALKING, ageB);
+    for (std::size_t n = 2; n < indices.size(); ++n) {
+        set_sheep(sim, indices[n], 1000.0 + 150.0 * static_cast<double>(n), 16.0);
+    }
+    return indices;
+}
+
+int advance_side_past_sheep_generation(Prng& side) {
+    const double countDraw = prng_uniform(side, SHEEP_COUNT_MIN, SHEEP_COUNT_MAX + 1);
+    int expectedCount = static_cast<int>(std::floor(countDraw));
+    if (expectedCount < SHEEP_COUNT_MIN) expectedCount = SHEEP_COUNT_MIN;
+    if (expectedCount > SHEEP_COUNT_MAX) expectedCount = SHEEP_COUNT_MAX;
+
+    for (int i = 0; i < expectedCount; ++i) {
+        const double margin = SHEEP_BODY_RADIUS + 8.0;
+        (void)prng_uniform(side, margin, Monitor1920 - margin);
+        (void)prng_uniform(side, SHEEP_WALK_SPEED_MIN, SHEEP_WALK_SPEED_MAX);
+        (void)prng_uniform(side, 0.0, 1.0);
+        (void)prng_next_u32(side);
+        (void)prng_uniform(side, SHEEP_WALK_DURATION_MIN, SHEEP_WALK_DURATION_MAX);
+        (void)prng_index(side, static_cast<uint32_t>(sizeof(SHEEP_NAME_POOL) / sizeof(SHEEP_NAME_POOL[0])));
+    }
+    return expectedCount;
+}
+
+int count_sheep_in_state(const Sim& sim, uint8_t state) {
+    return static_cast<int>(std::count_if(sim.entities.begin(), sim.entities.end(),
+        [state](const Entity& e) {
+            return e.kind == EntityKind::Sheep && e.state == state;
+        }));
+}
+
+} // namespace
+
+TEST_CASE("Sheep greeting constants are pinned to spec values", "[sheep][greeting][constants]") {
+    REQUIRE(SHEEP_STATE_GREETING       == 5);
+    REQUIRE(SHEEP_GREET_RADIUS         == Approx(50.0));
+    REQUIRE(SHEEP_GREET_DURATION_MIN   == Approx(1.6));
+    REQUIRE(SHEEP_GREET_DURATION_MAX   == Approx(2.8));
+    REQUIRE(SHEEP_GREET_MIN_AGE        == Approx(1.5));
+    REQUIRE(SHEEP_GREET_HEAD_BOB_FREQ  == Approx(4.5));
+    REQUIRE(SHEEP_GREET_HEAD_BOB_AMP   == Approx(0.7));
+}
+
+TEST_CASE("Sheep curious constants are pinned to spec values", "[sheep][curious][constants]") {
+    REQUIRE(SHEEP_CURIOUS_RADIUS        == Approx(80.0));
+    REQUIRE(SHEEP_CURIOUS_HEAD_TURN_MAX == Approx(0.55));
+}
+
+
+TEST_CASE("Eligible nearby sheep enter Greeting facing each other", "[sheep][greeting]") {
+    Sim sim = build_sheep_sim();
+    const std::vector<std::size_t> indices = prepare_two_sheep(sim);
+
+    sim_tick_entities(sim, 0.016);
+
+    const Entity& a = sim.entities[indices[0]];
+    const Entity& b = sim.entities[indices[1]];
+    REQUIRE(a.state == SHEEP_STATE_GREETING);
+    REQUIRE(b.state == SHEEP_STATE_GREETING);
+    REQUIRE(a.stateTimer >= SHEEP_GREET_DURATION_MIN);
+    REQUIRE(a.stateTimer <= SHEEP_GREET_DURATION_MAX);
+    REQUIRE(a.stateTimer == Approx(b.stateTimer));
+    REQUIRE(a.vx > 0.0);
+    REQUIRE(b.vx < 0.0);
+}
+
+TEST_CASE("Far apart eligible sheep do not greet", "[sheep][greeting]") {
+    Sim sim = build_sheep_sim();
+    const std::vector<std::size_t> indices = prepare_two_sheep(sim, 200.0);
+
+    for (int i = 0; i < 3; ++i) sim_tick_entities(sim, 0.016);
+
+    REQUIRE(sim.entities[indices[0]].state == SHEEP_STATE_WALKING);
+    REQUIRE(sim.entities[indices[1]].state == SHEEP_STATE_WALKING);
+}
+
+TEST_CASE("Sheep under greeting minimum age do not greet", "[sheep][greeting]") {
+    Sim sim = build_sheep_sim();
+    const std::vector<std::size_t> indices = prepare_two_sheep(sim, 40.0, 0.5, EligibleAge);
+
+    sim_tick_entities(sim, 0.016);
+
+    REQUIRE(sim.entities[indices[0]].state == SHEEP_STATE_WALKING);
+    REQUIRE(sim.entities[indices[1]].state == SHEEP_STATE_WALKING);
+}
+
+TEST_CASE("Sleeping hopping and greeting sheep are not greeting-eligible", "[sheep][greeting]") {
+    const uint8_t blockedStates[] = {
+        SHEEP_STATE_SLEEPING,
+        SHEEP_STATE_HOPPING,
+        SHEEP_STATE_GREETING,
+    };
+
+    for (uint8_t blockedState : blockedStates) {
+        Sim sim = build_sheep_sim();
+        const std::vector<std::size_t> indices = prepare_two_sheep(sim);
+        set_sheep(sim, indices[0], 500.0, -20.0, blockedState, EligibleAge);
+
+        sim_tick_entities(sim, 0.016);
+
+        REQUIRE(sim.entities[indices[0]].state == blockedState);
+        REQUIRE(sim.entities[indices[1]].state == SHEEP_STATE_WALKING);
+    }
+}
+
+TEST_CASE("Greeting expiry returns sheep to Walking with vx flipped", "[sheep][greeting]") {
+    Sim sim = build_sheep_sim();
+    const std::vector<std::size_t> indices = prepare_two_sheep(sim);
+
+    sim_tick_entities(sim, 0.016);
+    const double duration = sim.entities[indices[0]].stateTimer;
+    const double aGreetingVx = sim.entities[indices[0]].vx;
+    const double bGreetingVx = sim.entities[indices[1]].vx;
+
+    sim_tick_entities(sim, duration + 0.01);
+
+    REQUIRE(sim.entities[indices[0]].state == SHEEP_STATE_WALKING);
+    REQUIRE(sim.entities[indices[1]].state == SHEEP_STATE_WALKING);
+    REQUIRE(sim.entities[indices[0]].vx == Approx(-aGreetingVx));
+    REQUIRE(sim.entities[indices[1]].vx == Approx(-bGreetingVx));
+}
+
+TEST_CASE("Greeting trigger consumes one PRNG draw per pair", "[sheep][greeting][prng]") {
+    Prng side;
+    prng_init(side, CANONICAL_TEST_SEED ^ CRITTER_PRNG_SALT);
+
+    Sim sim = build_sheep_sim();
+    const int expectedCount = advance_side_past_sheep_generation(side);
+    REQUIRE(static_cast<int>(sheep_indices(sim).size()) == expectedCount);
+    const std::vector<std::size_t> indices = prepare_two_sheep(sim);
+
+    const double expectedDuration = prng_uniform(side,
+                                                 SHEEP_GREET_DURATION_MIN,
+                                                 SHEEP_GREET_DURATION_MAX);
+    sim_tick_entities(sim, 0.016);
+
+    REQUIRE(sim.entities[indices[0]].stateTimer == Approx(expectedDuration));
+    REQUIRE(sim.entities[indices[1]].stateTimer == Approx(expectedDuration));
+}
+
+TEST_CASE("Single sheep cannot enter Greeting", "[sheep][greeting]") {
+    Sim sim = build_sheep_sim();
+    sim.currentScene = Scene::Desert;
+    REQUIRE(sim.entities.size() >= 1);
+    sim.entities.erase(sim.entities.begin() + 1, sim.entities.end());
+    set_sheep(sim, 0, 500.0, 20.0);
+
+    sim_tick_entities(sim, 0.016);
+
+    REQUIRE(sim.entities.size() == 1);
+    REQUIRE(sim.entities[0].state == SHEEP_STATE_WALKING);
+}
+
+TEST_CASE("Three sheep cluster greets only the first encountered pair", "[sheep][greeting]") {
+    Sim sim = build_sheep_sim();
+    std::vector<std::size_t> indices = sheep_indices(sim);
+    REQUIRE(indices.size() >= 2);
+    if (indices.size() < 3) {
+        sim.entities.push_back(sim.entities[indices[1]]);
+        indices = sheep_indices(sim);
+    }
+    REQUIRE(indices.size() >= 3);
+
+    set_sheep(sim, indices[0], 500.0, -20.0);
+    set_sheep(sim, indices[1], 540.0, 18.0);
+    set_sheep(sim, indices[2], 580.0, 16.0);
+
+    sim_tick_entities(sim, 0.016);
+
+    REQUIRE(sim.entities[indices[0]].state == SHEEP_STATE_GREETING);
+    REQUIRE(sim.entities[indices[1]].state == SHEEP_STATE_GREETING);
+    REQUIRE(sim.entities[indices[2]].state == SHEEP_STATE_WALKING);
+    REQUIRE(count_sheep_in_state(sim, SHEEP_STATE_GREETING) == 2);
+}

src/modules/DesktopGrass/DesktopGrass.Native.Tests/src/snapshot_data.h

@@ -0,0 +1,73 @@
+// snapshot_data.h
+//
+// Canonical snapshot values for conformance tests. Generated by
+// snapshot_gen.cpp against the Native implementation; the Win2D test
+// project shares these exact same values to prove cross-impl parity.
+//
+// To regenerate after changing the spec:
+//   cd tests/DesktopGrass.Native.Tests
+//   cl /nologo /std:c++17 /EHsc /O2 /I../../src/DesktopGrass.Native/src \
+//      /Fe:snapshot_gen.exe snapshot_gen.cpp ../../src/DesktopGrass.Native/src/Sim.cpp
+//   ./snapshot_gen.exe > snapshot_data_generated.h
+// Then copy the contents of snapshot_data_generated.h into this file.
+
+#pragma once
+
+#include <cstdint>
+#include <cstddef>
+
+namespace desktopgrass::test {
+
+// canonical PRNG snapshot (seed = 0x6B6173746F)
+constexpr uint64_t CANONICAL_PRNG_SNAPSHOT[16] = {
+    0x3C3A8D4BF44D4757ull,
+    0xC5036418082CE819ull,
+    0x637C39DC81179789ull,
+    0xA8D438AF7ACD7AE6ull,
+    0x872C242C0B1C9993ull,
+    0xEFA4F8384FDEA460ull,
+    0x1C028EE81E340128ull,
+    0x292DB46E8579232Aull,
+    0xD68F60B495865BECull,
+    0xB92C6D6C0EF02C5Bull,
+    0xEA3E31B01AEBBAC3ull,
+    0x69414C59CD84BD76ull,
+    0x824EF03EDB86298Cull,
+    0x2EC0BC0D0F34C6DFull,
+    0x06931E51B1E4F892ull,
+    0x51E8736B5F6D55E3ull,
+};
+
+// blade count: 321
+constexpr size_t CANONICAL_BLADE_COUNT = 321;
+
+// first 10 blades (baseX, height, thickness, hue, swayPhaseOffset, stiffness, isFlower, flowerHeadColorIdx, flowerHeadRadius, heightBonus)
+struct SnapshotBlade { double baseX, height, thickness; uint8_t hue; double sway, stiffness; bool isFlower; uint8_t flowerHeadColorIdx; double flowerHeadRadius, heightBonus; };
+constexpr SnapshotBlade CANONICAL_FIRST_10[10] = {
+    { 4.941073726820111, 24.469991818248864, 1.5829214329729786, 3, 3.3176304956845826, 0.97444439458772458, false, 0, 0, 1 },
+    { 9.3787298687475591, 9.8604876018392638, 2.2571879063910156, 4, 5.7491868538687054, 0.76446104886036426, false, 0, 0, 1 },
+    { 15.414797889934666, 10.383081509132303, 1.0385235237289103, 1, 3.002564694512488, 0.80184457223353733, true, 5, 1.9856510266114094, 1.2028967677469276 },
+    { 19.593121666328006, 27.357762722959727, 1.0339384653459984, 3, 1.6105552667895404, 0.81282211516340619, false, 0, 0, 1 },
+    { 24.583549065022112, 10.405811371734785, 1.3631340217308754, 3, 6.0791471337675995, 0.85778838989075124, false, 0, 0, 1 },
+    { 30.469280325562636, 14.64969214497285, 2.1029229162066789, 4, 1.369186973739968, 0.64921394446231895, false, 0, 0, 1 },
+    { 36.151633528778135, 24.905416507570557, 1.681128965493375, 5, 1.0984313545668589, 0.61705905497643643, false, 0, 0, 1 },
+    { 41.240173248804979, 21.090216438210287, 2.4112504781311586, 1, 2.5650668705987827, 0.80856258993385732, false, 0, 0, 1 },
+    { 45.909481179288093, 25.779836864342794, 1.9217430631389112, 3, 4.5760223476063198, 0.6897456846181147, false, 0, 0, 1 },
+    { 51.704527631340518, 7.0226866871355051, 2.0844748317130479, 5, 0.35993160065393376, 0.95409362721021629, false, 0, 0, 1 },
+};
+
+// last 10 blades
+constexpr SnapshotBlade CANONICAL_LAST_10[10] = {
+    { 1862.1862973905477, 12.711608036449295, 1.012073444534392, 3, 2.3651694770128948, 0.87280041193860214, false, 0, 0, 1 },
+    { 1869.0137044788548, 29.295061932038202, 1.8599729032248227, 5, 0.93125378903474243, 0.77711311572472863, false, 0, 0, 1 },
+    { 1876.3989600185221, 16.412749219937503, 2.3707904389430361, 4, 6.2236497795954646, 0.69830242079702853, false, 0, 0, 1 },
+    { 1883.2648022027838, 27.079136980574535, 1.3818519218724266, 1, 5.6607957368262252, 0.64471754349581489, false, 0, 0, 1 },
+    { 1889.9657219661015, 6.5120673117922729, 1.3927977522226092, 0, 1.0400004070684932, 0.65011504476310344, false, 0, 0, 1 },
+    { 1897.0421995171516, 22.778199667770664, 1.6103911154185315, 3, 5.4418514925265704, 0.6792514093313039, false, 0, 0, 1 },
+    { 1902.4342767348269, 14.612095947624056, 2.4718071777795467, 4, 5.8520526497642198, 0.91196804564197653, false, 0, 0, 1 },
+    { 1907.2058102690753, 11.469067214809311, 1.0067274803347863, 1, 3.1644688274678971, 0.97325380897540192, false, 0, 0, 1 },
+    { 1911.3865054893965, 26.080515240165873, 2.0193479120917956, 2, 3.350989422282157, 0.72097617434818306, false, 0, 0, 1 },
+    { 1915.6595838732392, 8.7174302729300273, 1.7257363895237519, 3, 2.9693994932808887, 0.74923939092464364, false, 0, 0, 1 },
+};
+
+} // namespace desktopgrass::test

src/modules/DesktopGrass/DesktopGrass.Native.Tests/src/sway_tests.cpp

@@ -0,0 +1,139 @@
+// sway_tests.cpp
+//
+// Sway physics tests (architecture.md §6).
+
+#include "../third_party/catch2/catch.hpp"
+#include "Sim.h"
+
+#include <cmath>
+
+using namespace desktopgrass;
+
+namespace {
+
+constexpr double kPi = 3.14159265358979323846;
+
+Blade make_blade(double phase, double stiffness) {
+    Blade b{};
+    b.baseX            = 0.0;
+    b.height           = 20.0;
+    b.thickness        = 1.5;
+    b.hue              = 0;
+    b.swayPhaseOffset  = phase;
+    b.stiffness        = stiffness;
+    b.cutHeight        = 1.0;
+    b.gustVelocity     = 0.0;
+    b.cutAnimStart     = -1.0;
+    b.cutInitialHeight = 1.0;
+    return b;
+}
+
+} // anonymous
+
+TEST_CASE("sway phase advances linearly with globalTime", "[sway]") {
+    Blade b = make_blade(0.0, 1.0);
+    update_blade_dynamics(b, 0.0, 0.016);
+    const double leanT0 = b.effectiveLean;
+
+    // After one full BASE_SWAY_SPEED period (6 sec) the lean returns to ~same.
+    update_blade_dynamics(b, (2.0 * kPi) / BASE_SWAY_SPEED, 0.016);
+    REQUIRE(b.effectiveLean == Approx(leanT0).margin(1e-9));
+}
+
+TEST_CASE("sway lean stays bounded by BASE_AMPLITUDE * stiffness", "[sway]") {
+    Blade b = make_blade(0.0, 1.0);
+    double maxAbs = 0.0;
+    // Sample one full period at fine granularity.
+    for (double t = 0.0; t < (2.0 * kPi) / BASE_SWAY_SPEED; t += 0.001) {
+        update_blade_dynamics(b, t, 0.001);
+        maxAbs = std::max(maxAbs, std::fabs(b.effectiveLean));
+    }
+    REQUIRE(maxAbs <= BASE_AMPLITUDE + 1e-9);
+    REQUIRE(maxAbs >= BASE_AMPLITUDE * 0.99);
+}
+
+TEST_CASE("stiffness scales sway amplitude", "[sway]") {
+    Blade soft = make_blade(0.0, 0.6);
+    Blade hard = make_blade(0.0, 1.0);
+
+    double softMax = 0.0, hardMax = 0.0;
+    for (double t = 0.0; t < (2.0 * kPi) / BASE_SWAY_SPEED; t += 0.001) {
+        update_blade_dynamics(soft, t, 0.001);
+        update_blade_dynamics(hard, t, 0.001);
+        softMax = std::max(softMax, std::fabs(soft.effectiveLean));
+        hardMax = std::max(hardMax, std::fabs(hard.effectiveLean));
+    }
+
+    REQUIRE(softMax <  hardMax);
+    REQUIRE(softMax == Approx(hardMax * 0.6).margin(1e-3));
+}
+
+TEST_CASE("swayAmplitude scale multiplies the lean", "[sway]") {
+    // At the same time/phase, ampScale=2.0 doubles the lean; ampScale=0 zeroes it.
+    Blade base = make_blade(0.3, 1.0);
+    Blade dbl  = make_blade(0.3, 1.0);
+    Blade zero = make_blade(0.3, 1.0);
+    const double t = 1.234;
+    update_blade_dynamics(base, t, 0.016, 1.0, 1.0);
+    update_blade_dynamics(dbl,  t, 0.016, 1.0, 2.0);
+    update_blade_dynamics(zero, t, 0.016, 1.0, 0.0);
+    REQUIRE(dbl.effectiveLean  == Approx(2.0 * base.effectiveLean).margin(1e-12));
+    REQUIRE(zero.effectiveLean == Approx(0.0).margin(1e-12));
+}
+
+TEST_CASE("swaySpeed scale stretches the phase advance", "[sway]") {
+    // speedScale=2.0 at time t equals the default at time 2t (pure phase scaling).
+    Blade fast = make_blade(0.1, 1.0);
+    Blade slow = make_blade(0.1, 1.0);
+    const double t = 0.9;
+    update_blade_dynamics(fast, t,       0.016, 2.0, 1.0);
+    update_blade_dynamics(slow, 2.0 * t, 0.016, 1.0, 1.0);
+    REQUIRE(fast.effectiveLean == Approx(slow.effectiveLean).margin(1e-12));
+}
+
+TEST_CASE("sim_tick applies the Sim sway scales to blades", "[sway]") {
+    // Proves the knobs are actually wired through the per-frame tick, not just
+    // the standalone helper: a sim with swayAmpScale=0 produces zero base lean.
+    Sim sim = sim_init(CANONICAL_TEST_SEED, 1920.0, DEFAULT_DENSITY);
+    sim.swayAmpScale   = 0.0;
+    sim.swaySpeedScale = 1.0;
+    sim_tick(sim, 0.5, nullptr, 0);
+    for (const Blade& b : sim.blades) {
+        // No ambient gust fired (gustVelocity stays 0), so effectiveLean is pure
+        // base lean, which ampScale=0 must flatten to 0.
+        REQUIRE(b.gustVelocity == Approx(0.0).margin(1e-12));
+        REQUIRE(b.effectiveLean == Approx(0.0).margin(1e-12));
+    }
+}
+
+TEST_CASE("phase offset shifts the sine wave", "[sway]") {
+    Blade a = make_blade(0.0,        1.0);
+    Blade b = make_blade(kPi / 2.0, 1.0);
+
+    update_blade_dynamics(a, 0.0, 0.001);
+    update_blade_dynamics(b, 0.0, 0.001);
+
+    // At t=0 with stiffness=1: a -> sin(0)*6 = 0; b -> sin(π/2)*6 = 6.
+    REQUIRE(a.effectiveLean == Approx(0.0).margin(1e-9));
+    REQUIRE(b.effectiveLean == Approx(BASE_AMPLITUDE).margin(1e-9));
+}
+
+TEST_CASE("gust velocity decays exponentially with dt", "[sway]") {
+    Blade b = make_blade(0.0, 1.0);
+    b.gustVelocity = 10.0;
+
+    // After 1 second, expect gustVelocity ≈ 10 * exp(-2.5).
+    update_blade_dynamics(b, 0.0, 1.0);
+    REQUIRE(b.gustVelocity == Approx(10.0 * std::exp(-DECAY_RATE * 1.0)).margin(1e-9));
+}
+
+TEST_CASE("gust velocity contributes to effective lean", "[sway]") {
+    Blade b = make_blade(0.0, 1.0);
+    b.gustVelocity = 2.0;
+
+    // tiny dt so decay is negligible
+    update_blade_dynamics(b, 0.0, 1e-6);
+    const double expectedFromGust = 2.0 * GUST_TO_LEAN_FACTOR;
+    // At t=0 sway contribution is sin(0)=0; only gust remains.
+    REQUIRE(b.effectiveLean == Approx(expectedFromGust).margin(1e-3));
+}

src/modules/DesktopGrass/DesktopGrass.Native.Tests/src/winter_tests.cpp

@@ -0,0 +1,463 @@
+#include "catch.hpp"
+
+#include "Sim.h"
+#include "Constants.h"
+#include "snapshot_data.h"
+
+#include <cstddef>
+#include <cmath>
+#include <algorithm>
+#include <array>
+#include <limits>
+#include <vector>
+
+using namespace desktopgrass;
+using namespace desktopgrass::test;
+
+namespace {
+constexpr double kTwoPi = 6.28318530717958647692;
+
+Sim MakeWinterTestSim() {
+    return sim_init(CANONICAL_TEST_SEED, 1920.0, 1.0);
+}
+
+void TickUntilFirstSnowflake(Sim& sim) {
+    for (int i = 0; i < 10000 && sim.entities.empty(); ++i) {
+        sim_tick(sim, 0.01, nullptr, 0);
+    }
+    REQUIRE_FALSE(sim.entities.empty());
+}
+}
+
+TEST_CASE("Winter constants are pinned", "[winter][constants]") {
+    REQUIRE(SNOWFLAKE_EMIT_RATE_PER_1920DIP == Approx(8.0));
+    REQUIRE(SNOWFLAKE_FALL_SPEED_MIN == Approx(20.0));
+    REQUIRE(SNOWFLAKE_FALL_SPEED_MAX == Approx(40.0));
+    REQUIRE(SNOWFLAKE_SIZE_MIN == Approx(1.5));
+    REQUIRE(SNOWFLAKE_SWAY_AMPLITUDE == Approx(10.0));
+    REQUIRE(SNOWFLAKE_PRNG_SALT == 0xC0FFEE1CECAFEBABull);
+    REQUIRE(SNOW_TIP_RADIUS_FACTOR == Approx(1.25));
+    REQUIRE(SNOW_TIP_COLOR == 0xFFFFFFFFu);
+}
+
+TEST_CASE("Winter blade cull is deterministic and ~25%", "[winter][cull]") {
+    // Pinned bitmask for indices 0..31 — must match the Win2D renderer exactly so
+    // both impls thin the same blades. '1' == culled (skipped in Winter).
+    const char* kExpected = "10100111000100000000000010000000";
+    for (uint32_t i = 0; i < 32; ++i) {
+        const bool expected = kExpected[i] == '1';
+        REQUIRE(winter_blade_culled(i) == expected);
+    }
+
+    REQUIRE(WINTER_CULL_MASK == 3u);
+
+    int culled = 0;
+    for (uint32_t i = 0; i < 2500; ++i) {
+        if (winter_blade_culled(i)) ++culled;
+    }
+    REQUIRE(culled == 624); // 24.96% of 2500 — effectively the target 25%
+}
+
+TEST_CASE("SetScene Winter initializes snowflake scheduler", "[winter][scene]") {
+    Sim sim = MakeWinterTestSim();
+    sim_set_scene(sim, Scene::Winter);
+
+    REQUIRE(sim.nextSnowflakeSpawnTime > sim.globalTime);
+    REQUIRE(sim.nextSnowflakeSpawnTime < 100.0);
+}
+
+TEST_CASE("First winter snowflake emits on scheduled tick", "[winter][entities]") {
+    Sim sim = MakeWinterTestSim();
+    sim_set_scene(sim, Scene::Winter);
+
+    TickUntilFirstSnowflake(sim);
+
+    REQUIRE(sim.entities.size() == 1);
+    REQUIRE(sim.entities[0].kind == EntityKind::Snowflake);
+}
+
+TEST_CASE("First winter snowflake matches spec-derived PRNG snapshot", "[winter][entities][snapshot]") {
+    Sim sim = MakeWinterTestSim();
+    sim_set_scene(sim, Scene::Winter);
+
+    TickUntilFirstSnowflake(sim);
+    REQUIRE(sim.entities.size() == 1);
+
+    Prng expected{};
+    prng_init(expected, CANONICAL_TEST_SEED ^ SNOWFLAKE_PRNG_SALT);
+    const double lambda = SNOWFLAKE_EMIT_RATE_PER_1920DIP * sim.monitorWidth / 1920.0;
+    const double firstInterval = prng_exponential(expected, lambda);
+    const double expectedSize = prng_uniform(expected, SNOWFLAKE_SIZE_MIN, SNOWFLAKE_SIZE_MAX);
+    const double expectedX = prng_uniform(expected, -20.0, sim.monitorWidth + 20.0);
+    const double expectedFallSpeed = prng_uniform(expected, SNOWFLAKE_FALL_SPEED_MIN, SNOWFLAKE_FALL_SPEED_MAX);
+    const double expectedRotation = prng_uniform(expected, 0.0, kTwoPi);
+    const double expectedRotationSpeed = prng_uniform(expected, -1.5, 1.5);
+    const uint32_t expectedSeed = prng_next_u32(expected);
+    const double nextInterval = prng_exponential(expected, lambda);
+
+    const Entity& e = sim.entities[0];
+    REQUIRE(e.size == Approx(expectedSize).margin(1e-12));
+    REQUIRE(e.x == Approx(expectedX).margin(1e-12));
+    REQUIRE(e.vy == Approx(expectedFallSpeed).margin(1e-12));
+    REQUIRE(e.rotation == Approx(expectedRotation).margin(1e-12));
+    REQUIRE(e.rotationSpeed == Approx(expectedRotationSpeed).margin(1e-12));
+    REQUIRE(e.seed == expectedSeed);
+    REQUIRE(sim.nextSnowflakeSpawnTime == Approx(firstInterval + nextInterval).margin(1e-12));
+}
+
+TEST_CASE("Snowflake sway velocity wobbles from seed phase", "[winter][entities]") {
+    Sim sim = MakeWinterTestSim();
+    sim.currentScene = Scene::Desert;
+    Entity e{};
+    e.kind = EntityKind::Snowflake;
+    e.seed = 0;
+    e.age = 0.0;
+    e.lifetime = 100.0;
+    sim.entities.push_back(e);
+
+    sim_tick_entities(sim, 0.0);
+
+    const double expectedVx = SNOWFLAKE_SWAY_AMPLITUDE * SNOWFLAKE_SWAY_FREQUENCY * kTwoPi * std::cos(0.0);
+    REQUIRE(sim.entities.size() == 1);
+    REQUIRE(sim.entities[0].vx == Approx(expectedVx).margin(1e-12));
+}
+
+TEST_CASE("Snowflakes are culled after lifetime", "[winter][entities]") {
+    Sim sim = MakeWinterTestSim();
+    sim.currentScene = Scene::Desert;
+    Entity e{};
+    e.kind = EntityKind::Snowflake;
+    e.lifetime = 1.0;
+    e.age = 0.9;
+    sim.entities.push_back(e);
+
+    sim_tick_entities(sim, 0.2);
+
+    REQUIRE(sim.entities.empty());
+}
+
+TEST_CASE("Snowflakes are culled below ground line", "[winter][entities]") {
+    Sim sim = MakeWinterTestSim();
+    sim.currentScene = Scene::Desert;
+    Entity e{};
+    e.kind = EntityKind::Snowflake;
+    e.y = sim.windowHeight + 5.0;
+    e.lifetime = 100.0;
+    sim.entities.push_back(e);
+
+    sim_tick_entities(sim, 0.0);
+
+    REQUIRE(sim.entities.empty());
+}
+
+TEST_CASE("Winter snowflake emitter honors max entity cap", "[winter][entities]") {
+    Sim sim = MakeWinterTestSim();
+    sim_set_scene(sim, Scene::Winter);
+    sim.nextSnowflakeSpawnTime = sim.globalTime;
+    for (int i = 0; i < MAX_ENTITIES_PER_MONITOR; ++i) {
+        Entity e{};
+        e.kind = EntityKind::Snowflake;
+        e.lifetime = 100.0;
+        sim.entities.push_back(e);
+    }
+
+    sim_tick_entities(sim, 0.0);
+
+    REQUIRE(sim.entities.size() <= static_cast<std::size_t>(MAX_ENTITIES_PER_MONITOR));
+    REQUIRE(sim.entities.size() == static_cast<std::size_t>(MAX_ENTITIES_PER_MONITOR));
+}
+
+TEST_CASE("Winter scene does not perturb first-blade snapshot", "[winter][snapshot]") {
+    Sim sim = MakeWinterTestSim();
+    REQUIRE(sim.blades[0].baseX == Approx(CANONICAL_FIRST_10[0].baseX).margin(1e-12));
+
+    sim_set_scene(sim, Scene::Winter);
+    REQUIRE(sim.blades[0].baseX == Approx(CANONICAL_FIRST_10[0].baseX).margin(1e-12));
+
+    sim_set_scene(sim, Scene::Grass);
+    REQUIRE(sim.blades[0].baseX == Approx(CANONICAL_FIRST_10[0].baseX).margin(1e-12));
+}
+
+TEST_CASE("Snowflakes do not emit in non-winter scenes", "[winter][entities][scene]") {
+    Sim sim = MakeWinterTestSim();
+
+    sim_set_scene(sim, Scene::Grass);
+    sim.nextSnowflakeSpawnTime = 0.0;
+    sim_tick(sim, 2.0, nullptr, 0);
+    REQUIRE(std::none_of(sim.entities.begin(), sim.entities.end(),
+        [](const Entity& e) { return e.kind == EntityKind::Snowflake; }));
+
+    sim_set_scene(sim, Scene::Desert);
+    sim.entities.clear();
+    sim.nextSnowflakeSpawnTime = 0.0;
+    sim_tick(sim, 2.0, nullptr, 0);
+    REQUIRE(sim.entities.empty());
+}
+
+namespace {
+int count_snow_puffs(const Sim& sim) {
+    int n = 0;
+    for (const Entity& e : sim.entities)
+        if (e.kind == EntityKind::SnowPuff) ++n;
+    return n;
+}
+
+InputEvent WinterClick(const Sim& sim, double x) {
+    InputEvent ev{};
+    ev.type = EventType::Click;
+    ev.x    = x;
+    ev.y    = sim.windowHeight - 5.0;
+    ev.time = sim.globalTime;
+    return ev;
+}
+}
+
+TEST_CASE("Snow puff constants are pinned", "[winter][puff][constants]") {
+    REQUIRE(SNOW_PUFF_COUNT_MIN == 9);
+    REQUIRE(SNOW_PUFF_COUNT_MAX == 16);
+    REQUIRE(SNOW_PUFF_SIZE_MIN == Approx(3.5));
+    REQUIRE(SNOW_PUFF_SIZE_MAX == Approx(8.0));
+    REQUIRE(SNOW_PUFF_GRAVITY == Approx(150.0));
+    REQUIRE(SNOW_PUFF_DRAG == Approx(1.6));
+    REQUIRE(SNOW_PUFF_SPREAD_RAD == Approx(1.25));
+    REQUIRE(SNOW_PUFF_PRNG_SALT == 0x5503FF1E5503FF1Eull);
+}
+
+TEST_CASE("Clicking the winter snowbank sheds a snow puff burst", "[winter][puff]") {
+    Sim sim = MakeWinterTestSim();
+    sim_set_scene(sim, Scene::Winter);
+
+    InputEvent ev = WinterClick(sim, 400.0);
+    sim_apply_click(sim, ev);
+
+    const int puffs = count_snow_puffs(sim);
+    REQUIRE(puffs >= SNOW_PUFF_COUNT_MIN);
+    REQUIRE(puffs <= SNOW_PUFF_COUNT_MAX);
+
+    // Every puff launches upward (y is screen-down, so up is negative vy) and
+    // spawns at or above the ground line.
+    for (const Entity& e : sim.entities) {
+        if (e.kind != EntityKind::SnowPuff) continue;
+        REQUIRE(e.vy < 0.0);
+        REQUIRE(e.y <= sim.windowHeight + 1e-9);
+    }
+}
+
+TEST_CASE("Snow puff only fires in Winter", "[winter][puff][scene]") {
+    Sim sim = MakeWinterTestSim();
+    sim_set_scene(sim, Scene::Grass);
+
+    InputEvent ev = WinterClick(sim, 400.0);
+    sim_apply_click(sim, ev);
+
+    REQUIRE(count_snow_puffs(sim) == 0);
+}
+
+TEST_CASE("A non-finite click sheds no snow puff", "[winter][puff][guard]") {
+    Sim sim = MakeWinterTestSim();
+    sim_set_scene(sim, Scene::Winter);
+
+    InputEvent ev{};
+    ev.type = EventType::Click;
+    ev.x    = std::numeric_limits<double>::quiet_NaN();
+    ev.y    = sim.windowHeight - 5.0;
+    ev.time = sim.globalTime;
+    sim_apply_click(sim, ev);
+
+    REQUIRE(count_snow_puffs(sim) == 0);
+}
+
+TEST_CASE("Snow puff burst rises then settles and is culled", "[winter][puff]") {
+    Sim sim = MakeWinterTestSim();
+    sim_set_scene(sim, Scene::Winter);
+
+    InputEvent ev = WinterClick(sim, 400.0);
+    sim_apply_click(sim, ev);
+    REQUIRE(count_snow_puffs(sim) > 0);
+
+    // 4 s easily exceeds SNOW_PUFF_LIFETIME_MAX (1.8 s); every puff should be
+    // culled (lifetime expiry and/or falling back below the ground line).
+    for (int i = 0; i < 200; ++i) sim_tick_entities(sim, 0.02);
+    REQUIRE(count_snow_puffs(sim) == 0);
+}
+
+TEST_CASE("Snow puff draw order matches a side PRNG stream", "[winter][puff][prng]") {
+    Sim sim = MakeWinterTestSim();
+    sim_set_scene(sim, Scene::Winter);
+
+    InputEvent ev = WinterClick(sim, 300.0);
+    sim_apply_click(sim, ev);
+
+    Prng side{};
+    prng_init(side, CANONICAL_TEST_SEED ^ SNOW_PUFF_PRNG_SALT);
+    const int expectedCount = SNOW_PUFF_COUNT_MIN
+        + static_cast<int>(prng_index(side, SNOW_PUFF_COUNT_MAX - SNOW_PUFF_COUNT_MIN + 1));
+    REQUIRE(count_snow_puffs(sim) == expectedCount);
+
+    // The first locked draw inside make_snow_puff is `size`.
+    const double expectedSize = prng_uniform(side, SNOW_PUFF_SIZE_MIN, SNOW_PUFF_SIZE_MAX);
+    for (const Entity& e : sim.entities) {
+        if (e.kind != EntityKind::SnowPuff) continue;
+        REQUIRE(e.size == Approx(expectedSize).margin(1e-12));
+        break;
+    }
+}
+
+TEST_CASE("Snow puff salt is unique among winter PRNG salts", "[winter][puff][prng]") {
+    const std::array<uint64_t, 15> otherSalts = {
+        REGROW_PRNG_SALT, FLOWER_PRNG_SALT, MUSHROOM_PRNG_SALT,
+        AMBIENT_GUST_PRNG_SALT, CACTUS_PRNG_SALT, TUMBLEWEED_PRNG_SALT,
+        CRITTER_PRNG_SALT, BUTTERFLY_PRNG_SALT, FIREFLY_PRNG_SALT,
+        BIRD_FLYBY_PRNG_SALT, SNOWFLAKE_PRNG_SALT,
+        PINE_PRNG_SALT, LEAF_PUFF_PRNG_SALT, SNOW_DRIFT_PRNG_SALT,
+    };
+    for (uint64_t s : otherSalts) {
+        REQUIRE(SNOW_PUFF_PRNG_SALT != s);
+    }
+}
+
+// ---------------------------------------------------------------------------
+// §21.1 snow drift (cursor-move spindrift)
+// ---------------------------------------------------------------------------
+
+namespace {
+// Prime the cursor baseline, then brush across at `x0`→`x1` over `dt` seconds in
+// the low snow band. Returns the velocity-carrying second event already applied.
+void WinterDrift(Sim& sim, double x0, double x1, double dt) {
+    const double y = sim.windowHeight - 5.0;
+    InputEvent prime{};
+    prime.type = EventType::Move;
+    prime.x = x0; prime.y = y; prime.time = sim.globalTime;
+    sim_apply_move(sim, prime);
+
+    InputEvent move{};
+    move.type = EventType::Move;
+    move.x = x1; move.y = y; move.time = sim.globalTime + dt;
+    sim_apply_move(sim, move);
+}
+}
+
+TEST_CASE("Snow drift constants are pinned", "[winter][drift][constants]") {
+    REQUIRE(SNOW_DRIFT_COUNT_MIN == 4);
+    REQUIRE(SNOW_DRIFT_COUNT_MAX == 8);
+    REQUIRE(SNOW_DRIFT_REACH_DIP == Approx(70.0));
+    REQUIRE(SNOW_DRIFT_MIN_SPEED == Approx(90.0));
+    REQUIRE(SNOW_DRIFT_COOLDOWN_SEC == Approx(0.12));
+    REQUIRE(SNOW_DRIFT_SIZE_SCALE == Approx(0.9));
+    REQUIRE(SNOW_DRIFT_SPEED_SCALE == Approx(0.85));
+    REQUIRE(SNOW_DRIFT_PRNG_SALT == 0x5D81F77D5D81F77Dull);
+}
+
+TEST_CASE("Brushing the cursor across the snowbank kicks up a drift wisp", "[winter][drift]") {
+    Sim sim = MakeWinterTestSim();
+    sim_set_scene(sim, Scene::Winter);
+
+    WinterDrift(sim, 300.0, 360.0, 0.05); // 60 DIP / 0.05 s = 1200 DIP/s
+
+    const int puffs = count_snow_puffs(sim);
+    REQUIRE(puffs >= SNOW_DRIFT_COUNT_MIN);
+    REQUIRE(puffs <= SNOW_DRIFT_COUNT_MAX);
+
+    // Drift grains are smaller than a click burst and still launch upward.
+    for (const Entity& e : sim.entities) {
+        if (e.kind != EntityKind::SnowPuff) continue;
+        REQUIRE(e.vy < 0.0);
+        REQUIRE(e.size <= SNOW_PUFF_SIZE_MAX * SNOW_DRIFT_SIZE_SCALE + 1e-9);
+        // Drift puffs originate at the snow surface beneath the cursor, not at
+        // the cursor's floating height: y sits within START_RADIUS of the
+        // ground even though the cursor is 5 DIP above it.
+        const double groundY = sim.windowHeight;
+        REQUIRE(e.y <= groundY + 1e-9);
+        REQUIRE(e.y >= groundY - SNOW_PUFF_START_RADIUS - 1e-9);
+    }
+}
+
+TEST_CASE("Snow drift only fires in Winter", "[winter][drift][scene]") {
+    Sim sim = MakeWinterTestSim();
+    sim_set_scene(sim, Scene::Grass);
+
+    WinterDrift(sim, 300.0, 360.0, 0.05);
+
+    REQUIRE(count_snow_puffs(sim) == 0);
+}
+
+TEST_CASE("A slow cursor brush kicks up no drift", "[winter][drift][gate]") {
+    Sim sim = MakeWinterTestSim();
+    sim_set_scene(sim, Scene::Winter);
+
+    WinterDrift(sim, 300.0, 302.0, 0.05); // 2 DIP / 0.05 s = 40 DIP/s < 90
+
+    REQUIRE(count_snow_puffs(sim) == 0);
+}
+
+TEST_CASE("A high cursor brush above the snow band kicks up no drift", "[winter][drift][gate]") {
+    Sim sim = MakeWinterTestSim();
+    sim_set_scene(sim, Scene::Winter);
+
+    // Inside the gust band but far above the low drift band near the ground.
+    const double y = sim.windowHeight - SNOW_DRIFT_REACH_DIP - 20.0;
+    InputEvent prime{};
+    prime.type = EventType::Move; prime.x = 300.0; prime.y = y; prime.time = sim.globalTime;
+    sim_apply_move(sim, prime);
+    InputEvent move{};
+    move.type = EventType::Move; move.x = 360.0; move.y = y; move.time = sim.globalTime + 0.05;
+    sim_apply_move(sim, move);
+
+    REQUIRE(count_snow_puffs(sim) == 0);
+}
+
+TEST_CASE("Snow drift respects the global cooldown", "[winter][drift][cooldown]") {
+    Sim sim = MakeWinterTestSim();
+    sim_set_scene(sim, Scene::Winter);
+
+    WinterDrift(sim, 300.0, 360.0, 0.05);
+    const int first = count_snow_puffs(sim);
+    REQUIRE(first >= SNOW_DRIFT_COUNT_MIN);
+
+    // Same frame (globalTime unchanged): a second qualifying brush is gated.
+    InputEvent again{};
+    again.type = EventType::Move;
+    again.x = 420.0; again.y = sim.windowHeight - 5.0; again.time = sim.globalTime + 0.10;
+    sim_apply_move(sim, again);
+    REQUIRE(count_snow_puffs(sim) == first);
+
+    // Advance past the cooldown: a fresh brush kicks up another wisp.
+    sim.globalTime += SNOW_DRIFT_COOLDOWN_SEC + 0.01;
+    InputEvent later{};
+    later.type = EventType::Move;
+    later.x = 480.0; later.y = sim.windowHeight - 5.0; later.time = sim.globalTime + 0.05;
+    sim_apply_move(sim, later);
+    REQUIRE(count_snow_puffs(sim) > first);
+}
+
+TEST_CASE("Snow drift moves leave the click puff stream untouched", "[winter][drift][prng]") {
+    Sim a = MakeWinterTestSim();
+    sim_set_scene(a, Scene::Winter);
+    Sim b = MakeWinterTestSim();
+    sim_set_scene(b, Scene::Winter);
+
+    // a brushes up some drift wisps first; b does not.
+    WinterDrift(a, 300.0, 360.0, 0.05);
+    const std::size_t aPreClick = a.entities.size();
+
+    // Both click identically; the click puffs must match byte-for-byte because
+    // the click stream is a separate PRNG from the drift stream.
+    InputEvent ca = WinterClick(a, 800.0);
+    sim_apply_click(a, ca);
+    InputEvent cb = WinterClick(b, 800.0);
+    sim_apply_click(b, cb);
+
+    // Collect the click puffs from each (a's are those appended after the drift).
+    std::vector<Entity> aClick(a.entities.begin() + static_cast<std::ptrdiff_t>(aPreClick), a.entities.end());
+    std::vector<Entity> bClick;
+    for (const Entity& e : b.entities)
+        if (e.kind == EntityKind::SnowPuff) bClick.push_back(e);
+
+    REQUIRE(aClick.size() == bClick.size());
+    for (std::size_t i = 0; i < aClick.size(); ++i) {
+        REQUIRE(aClick[i].size == Approx(bClick[i].size).margin(1e-12));
+        REQUIRE(aClick[i].vx == Approx(bClick[i].vx).margin(1e-12));
+        REQUIRE(aClick[i].vy == Approx(bClick[i].vy).margin(1e-12));
+        REQUIRE(aClick[i].lifetime == Approx(bClick[i].lifetime).margin(1e-12));
+    }
+}

src/modules/DesktopGrass/DesktopGrass.Native.Tests/third_party/README.md

@@ -0,0 +1,14 @@
+# DesktopGrass.Native.Tests — third_party
+
+This directory contains source vendored at known versions to keep the test
+build hermetic. None of it ships in the runtime binary.
+
+## catch2/catch.hpp
+
+[Catch2](https://github.com/catchorg/Catch2) v2.13.10 single-header
+amalgamation, vendored verbatim from the upstream release. License: Boost
+Software License 1.0. Copy lives at `catch2/catch.hpp`.
+
+We intentionally avoid pulling Catch2 from vcpkg/NuGet for this v1 — the
+single-header approach builds with `cl` out of the box and removes one
+moving piece from the test step.

src/modules/DesktopGrass/DesktopGrass.Native.Tests/vcpkg.json

@@ -0,0 +1,6 @@
+{
+  "name": "desktopgrass-native-tests",
+  "version-string": "1.0.0",
+  "description": "DesktopGrass Native test project. Catch2 single-header is vendored under third_party/catch2/ (license MIT) to keep the test build fully offline-friendly.",
+  "dependencies": []
+}

src/modules/DesktopGrass/DesktopGrass.Native/DesktopGrass.Native.rc

@@ -0,0 +1,11 @@
+// DesktopGrass.Native.rc
+//
+// Resource script: embeds the icon and the app manifest.
+
+#include <windows.h>
+#include "resource.h"
+
+IDI_APPICON  ICON  "res/icon.ico"
+IDI_TRAYICON ICON  "res/icon.ico"
+
+// Manifest binding handled by linker /MANIFESTUAC + <ApplicationManifest>.

src/modules/DesktopGrass/DesktopGrass.Native/DesktopGrass.Native.vcxproj

@@ -0,0 +1,178 @@
+<?xml version="1.0" encoding="utf-8"?>
+<Project DefaultTargets="Build" xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
+
+  <ItemGroup Label="ProjectConfigurations">
+    <ProjectConfiguration Include="Debug|x64">
+      <Configuration>Debug</Configuration>
+      <Platform>x64</Platform>
+    </ProjectConfiguration>
+    <ProjectConfiguration Include="Release|x64">
+      <Configuration>Release</Configuration>
+      <Platform>x64</Platform>
+    </ProjectConfiguration>
+    <ProjectConfiguration Include="Debug|ARM64">
+      <Configuration>Debug</Configuration>
+      <Platform>ARM64</Platform>
+    </ProjectConfiguration>
+    <ProjectConfiguration Include="Release|ARM64">
+      <Configuration>Release</Configuration>
+      <Platform>ARM64</Platform>
+    </ProjectConfiguration>
+  </ItemGroup>
+
+  <PropertyGroup Label="Globals">
+    <VCProjectVersion>17.0</VCProjectVersion>
+    <ProjectGuid>{B0D4E1B0-1F5E-4C2D-9F44-DA8C3F1A2A11}</ProjectGuid>
+    <RootNamespace>DesktopGrass.Native</RootNamespace>
+    <WindowsTargetPlatformVersion>10.0</WindowsTargetPlatformVersion>
+    <ProjectName>DesktopGrass.Native</ProjectName>
+  </PropertyGroup>
+
+  <Import Project="$(VCTargetsPath)\Microsoft.Cpp.Default.props" />
+
+  <PropertyGroup Condition="'$(Configuration)|$(Platform)'=='Debug|x64'" Label="Configuration">
+    <ConfigurationType>Application</ConfigurationType>
+    <UseDebugLibraries>true</UseDebugLibraries>
+    <PlatformToolset>v145</PlatformToolset>
+    <CharacterSet>Unicode</CharacterSet>
+  </PropertyGroup>
+  <PropertyGroup Condition="'$(Configuration)|$(Platform)'=='Release|x64'" Label="Configuration">
+    <ConfigurationType>Application</ConfigurationType>
+    <UseDebugLibraries>false</UseDebugLibraries>
+    <PlatformToolset>v145</PlatformToolset>
+    <WholeProgramOptimization>true</WholeProgramOptimization>
+    <CharacterSet>Unicode</CharacterSet>
+  </PropertyGroup>
+  <PropertyGroup Condition="'$(Configuration)|$(Platform)'=='Debug|ARM64'" Label="Configuration">
+    <ConfigurationType>Application</ConfigurationType>
+    <UseDebugLibraries>true</UseDebugLibraries>
+    <PlatformToolset>v145</PlatformToolset>
+    <CharacterSet>Unicode</CharacterSet>
+  </PropertyGroup>
+  <PropertyGroup Condition="'$(Configuration)|$(Platform)'=='Release|ARM64'" Label="Configuration">
+    <ConfigurationType>Application</ConfigurationType>
+    <UseDebugLibraries>false</UseDebugLibraries>
+    <PlatformToolset>v145</PlatformToolset>
+    <WholeProgramOptimization>true</WholeProgramOptimization>
+    <CharacterSet>Unicode</CharacterSet>
+  </PropertyGroup>
+
+  <Import Project="$(VCTargetsPath)\Microsoft.Cpp.props" />
+
+  <PropertyGroup>
+    <OutDir>$(MSBuildProjectDirectory)\..\..\..\..\$(Platform)\$(Configuration)\</OutDir>
+    <IntDir>$(MSBuildProjectDirectory)\obj\$(Platform)\$(Configuration)\</IntDir>
+    <TargetName>DesktopGrass.Native</TargetName>
+    <!-- DesktopGrass.Native uses no precompiled header; opt out of the PowerToys-wide PCH default. -->
+    <UsePrecompiledHeaders>false</UsePrecompiledHeaders>
+    <!-- Self-contained leaf module: opt out of the repo-wide CppCoreCheck-as-errors (cf. FileLocksmithCLI). -->
+    <RunCodeAnalysis>false</RunCodeAnalysis>
+  </PropertyGroup>
+
+  <ItemDefinitionGroup>
+    <ClCompile>
+      <LanguageStandard>stdcpp17</LanguageStandard>
+      <SDLCheck>true</SDLCheck>
+      <ConformanceMode>true</ConformanceMode>
+      <WarningLevel>Level3</WarningLevel>
+      <PreprocessorDefinitions>UNICODE;_UNICODE;NOMINMAX;%(PreprocessorDefinitions)</PreprocessorDefinitions>
+      <MultiProcessorCompilation>true</MultiProcessorCompilation>
+      <AdditionalIncludeDirectories>$(MSBuildProjectDirectory)\src;%(AdditionalIncludeDirectories)</AdditionalIncludeDirectories>
+    </ClCompile>
+    <Link>
+      <SubSystem>Windows</SubSystem>
+      <GenerateDebugInformation>true</GenerateDebugInformation>
+      <AdditionalDependencies>d3d11.lib;dxgi.lib;d2d1.lib;dcomp.lib;dwrite.lib;Shcore.lib;Shell32.lib;User32.lib;Gdi32.lib;Ole32.lib;%(AdditionalDependencies)</AdditionalDependencies>
+    </Link>
+    <ResourceCompile>
+      <PreprocessorDefinitions>UNICODE;_UNICODE;%(PreprocessorDefinitions)</PreprocessorDefinitions>
+      <AdditionalIncludeDirectories>$(MSBuildProjectDirectory);%(AdditionalIncludeDirectories)</AdditionalIncludeDirectories>
+    </ResourceCompile>
+    <Manifest>
+      <AdditionalManifestFiles>app.manifest</AdditionalManifestFiles>
+    </Manifest>
+  </ItemDefinitionGroup>
+
+  <ItemDefinitionGroup Condition="'$(Configuration)|$(Platform)'=='Debug|x64'">
+    <ClCompile>
+      <Optimization>Disabled</Optimization>
+      <RuntimeLibrary>MultiThreadedDebugDLL</RuntimeLibrary>
+      <PreprocessorDefinitions>_DEBUG;%(PreprocessorDefinitions)</PreprocessorDefinitions>
+    </ClCompile>
+  </ItemDefinitionGroup>
+  <ItemDefinitionGroup Condition="'$(Configuration)|$(Platform)'=='Release|x64'">
+    <ClCompile>
+      <Optimization>MaxSpeed</Optimization>
+      <RuntimeLibrary>MultiThreaded</RuntimeLibrary>
+      <PreprocessorDefinitions>NDEBUG;%(PreprocessorDefinitions)</PreprocessorDefinitions>
+      <FunctionLevelLinking>true</FunctionLevelLinking>
+      <IntrinsicFunctions>true</IntrinsicFunctions>
+    </ClCompile>
+    <Link>
+      <EnableCOMDATFolding>true</EnableCOMDATFolding>
+      <OptimizeReferences>true</OptimizeReferences>
+    </Link>
+  </ItemDefinitionGroup>
+
+  <ItemDefinitionGroup Condition="'$(Configuration)|$(Platform)'=='Debug|ARM64'">
+    <ClCompile>
+      <Optimization>Disabled</Optimization>
+      <RuntimeLibrary>MultiThreadedDebugDLL</RuntimeLibrary>
+      <PreprocessorDefinitions>_DEBUG;%(PreprocessorDefinitions)</PreprocessorDefinitions>
+    </ClCompile>
+  </ItemDefinitionGroup>
+  <ItemDefinitionGroup Condition="'$(Configuration)|$(Platform)'=='Release|ARM64'">
+    <ClCompile>
+      <Optimization>MaxSpeed</Optimization>
+      <RuntimeLibrary>MultiThreaded</RuntimeLibrary>
+      <PreprocessorDefinitions>NDEBUG;%(PreprocessorDefinitions)</PreprocessorDefinitions>
+      <FunctionLevelLinking>true</FunctionLevelLinking>
+      <IntrinsicFunctions>true</IntrinsicFunctions>
+    </ClCompile>
+    <Link>
+      <EnableCOMDATFolding>true</EnableCOMDATFolding>
+      <OptimizeReferences>true</OptimizeReferences>
+    </Link>
+  </ItemDefinitionGroup>
+
+  <ItemGroup>
+    <ClCompile Include="src\main.cpp" />
+    <ClCompile Include="src\App.cpp" />
+    <ClCompile Include="src\AutoStart.cpp" />
+    <ClCompile Include="src\Benchmark.cpp" />
+    <ClCompile Include="src\Config.cpp" />
+    <ClCompile Include="src\GrassWindow.cpp" />
+    <ClCompile Include="src\Renderer.cpp" />
+    <ClCompile Include="src\MouseHook.cpp" />
+    <ClCompile Include="src\Pacing.cpp" />
+    <ClCompile Include="src\Persistence.cpp" />
+    <ClCompile Include="src\Sim.cpp" />
+  </ItemGroup>
+
+  <ItemGroup>
+    <ClInclude Include="src\App.h" />
+    <ClInclude Include="src\AutoStart.h" />
+    <ClInclude Include="src\Benchmark.h" />
+    <ClInclude Include="src\Config.h" />
+    <ClInclude Include="src\Constants.h" />
+    <ClInclude Include="src\GrassWindow.h" />
+    <ClInclude Include="src\Json.h" />
+    <ClInclude Include="src\MouseHook.h" />
+    <ClInclude Include="src\Pacing.h" />
+    <ClInclude Include="src\Persistence.h" />
+    <ClInclude Include="src\Renderer.h" />
+    <ClInclude Include="src\Sim.h" />
+    <ClInclude Include="resource.h" />
+  </ItemGroup>
+
+  <ItemGroup>
+    <ResourceCompile Include="DesktopGrass.Native.rc" />
+  </ItemGroup>
+
+  <ItemGroup>
+    <None Include="app.manifest" />
+    <None Include="res\icon.ico" />
+  </ItemGroup>
+
+  <Import Project="$(VCTargetsPath)\Microsoft.Cpp.targets" />
+</Project>

src/modules/DesktopGrass/DesktopGrass.Native/app.manifest

@@ -0,0 +1,30 @@
+<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
+<assembly xmlns="urn:schemas-microsoft-com:asm.v1" manifestVersion="1.0">
+  <assemblyIdentity version="1.0.0.0"
+                    processorArchitecture="*"
+                    name="DesktopGrass.Native"
+                    type="win32"/>
+  <description>DesktopGrass — procedural grass on the desktop edge.</description>
+  <dependency>
+    <dependentAssembly>
+      <assemblyIdentity type="win32"
+                        name="Microsoft.Windows.Common-Controls"
+                        version="6.0.0.0"
+                        processorArchitecture="*"
+                        publicKeyToken="6595b64144ccf1df"
+                        language="*"/>
+    </dependentAssembly>
+  </dependency>
+  <application xmlns="urn:schemas-microsoft-com:asm.v3">
+    <windowsSettings>
+      <dpiAwareness xmlns="http://schemas.microsoft.com/SMI/2016/WindowsSettings">PerMonitorV2</dpiAwareness>
+      <longPathAware xmlns="http://schemas.microsoft.com/SMI/2016/WindowsSettings">true</longPathAware>
+    </windowsSettings>
+  </application>
+  <compatibility xmlns="urn:schemas-microsoft-com:compatibility.v1">
+    <application>
+      <!-- Windows 10 / 11 -->
+      <supportedOS Id="{8e0f7a12-bfb3-4fe8-b9a5-48fd50a15a9a}"/>
+    </application>
+  </compatibility>
+</assembly>