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>
Integrate DesktopGrass.Native as a PowerToys module
2026-07-01 07:59:36 +02:00 · 2026-06-09 09:09:22 -07:00 · 2026-06-09 05:00:13 -07:00 · 2026-06-09 17:06:40 +08:00 · 2026-06-09 17:06:17 +08:00 · 2026-06-08 22:56:09 +02:00
256 changed files with 36298 additions and 1449 deletions
--- a/.github/actions/spell-check/excludes.txt
+++ b/.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$
--- a/.github/actions/spell-check/expect.txt
+++ b/.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
@@ -981,7 +915,6 @@ LEFTTEXT
 Lenovo
 LError
 LEVELID
-LExit
 LFU
 LGD
 lhwnd
@@ -1021,7 +954,6 @@ lowlevel
 LOWORD
 lparam
 LPBITMAPINFOHEADER
-LPCFHOOKPROC
 lpch
 LPCITEMIDLIST
 LPCLSID
@@ -1040,7 +972,6 @@ LPMONITORINFO
 LPOSVERSIONINFOEXW
 LPQUERY
 lprc
-LPrivate
 LPSAFEARRAY
 lpstr
 lpsz
@@ -1054,7 +985,6 @@ LPW
 lpwcx
 lpwndpl
 lquadrant
-LReader
 LRESULT
 LSTATUS
 lstrcmp
@@ -1065,12 +995,9 @@ LTEXT
 LTM
 LTRREADING
 luid
-LUMA
 lusrmgr
-LVal
 LVDS
 LWA
-lwin
 LWIN
 LZero
 MAGTRANSFORM
@@ -1140,7 +1067,6 @@ mkdn
 mlcfg
 mmc
 mmcexe
-MMdd
 mmi
 mmsys
 mobileredirect
@@ -1166,7 +1092,6 @@ mouseutils
 MOVESIZEEND
 MOVESIZESTART
 MRM
-MRT
 mru
 msaccess
 MSAL
@@ -1177,8 +1102,6 @@ msdata
 msdia
 MSDL
 MSGFLT
-MSHCTX
-MSHLFLAGS
 msiexec
 MSIFASTINSTALL
 MSIHANDLE
@@ -1215,7 +1138,6 @@ myorg
 myrepo
 NAMECHANGE
 namespaceanddescendants
-Nanjing
 nao
 NCACTIVATE
 ncc
@@ -1241,7 +1163,6 @@ netcpl
 netframework
 netsetup
 netsh
-newcolor
 NEWDIALOGSTYLE
 NEWFILE
 NEWFILEHEADER
@@ -1254,7 +1175,6 @@ newrow
 nicksnettravels
 NIF
 nightlight
-NLog
 NLSTEXT
 NMAKE
 NNN
@@ -1344,7 +1264,6 @@ OFN
 ofs
 OICI
 OICIIO
-oldcolor
 olditem
 oldpath
 oldtheme
@@ -1375,7 +1294,6 @@ OUTOFCONTEXT
 Outptr
 outputtype
 outsettings
-outsourced
 OVERLAPPEDWINDOW
 Oversampling
 OVERWRITEPROMPT
@@ -1402,7 +1320,6 @@ PATINVERT
 PATPAINT
 pbc
 pbi
-PBlob
 PBP
 pbrush
 pcb
@@ -1413,6 +1330,7 @@ pchast
 PCIDLIST
 PCTSTR
 PCWSTR
+pdbs
 PDBs
 PDEVMODE
 PDFs
@@ -1424,7 +1342,6 @@ pdto
 pdtobj
 pdw
 Peb
-PElems
 Pels
 PELSHEIGHT
 PELSWIDTH
@@ -1441,7 +1358,6 @@ pguid
 phbm
 phbmp
 phicon
-PHL
 Photoshop
 photoshop
 phwnd
@@ -1449,7 +1365,6 @@ pici
 pidl
 PIDLIST
 pii
-pinboard
 pinfo
 pinvoke
 pipename
@@ -1474,6 +1389,7 @@ Pokedex
 Pomodoro
 popups
 POPUPWINDOW
+portfile
 POSITIONITEM
 POWERBROADCAST
 powerdisplay
@@ -1550,7 +1466,6 @@ psrm
 psrree
 pstatstg
 pstm
-PStr
 pstream
 pstrm
 PSYSTEM
@@ -1561,7 +1476,6 @@ PTCHAR
 ptcontrols
 ptd
 PTOKEN
-PToy
 ptstr
 ptsym
 pui
@@ -1572,7 +1486,6 @@ PWSTR
 pwsz
 pwtd
 qdc
-QDS
 qit
 QITAB
 QITABENT
@@ -1587,9 +1500,7 @@ quicklinks
 quickmask
 QUNS
 RAII
-RAlt
 randi
-RAquadrant
 rasterization
 Rasterize
 rasterizing
@@ -1607,7 +1518,6 @@ READMODE
 READOBJECTS
 recents
 RECTDESTINATION
-rectp
 RECTSOURCE
 recursesubdirs
 recyclebin
@@ -1666,8 +1576,6 @@ RIDEV
 RIGHTBUTTON
 RIGHTSCROLLBAR
 riid
-RKey
-RNumber
 rollups
 rop
 ROUNDSMALL
@@ -1697,9 +1605,9 @@ SAMESHORTCUTPREVIOUSLYMAPPED
 samsung
 sancov
 SAVEFAILED
-scanled
 schedtasks
 SCID
+SCL
 Scode
 SCREENFONTS
 screenruler
@@ -1875,6 +1783,7 @@ STDAPI
 stdc
 stdcpp
 stdcpplatest
+stdext
 STDMETHODCALLTYPE
 STDMETHODIMP
 steamapps
@@ -1905,7 +1814,6 @@ sublang
 SUBMODULEUPDATE
 subresource
 sug
-suntimes
 Superbar
 SUPPRESSMSGBOXES
 sut
@@ -1981,7 +1889,6 @@ thickframe
 THISCOMPONENT
 threadpool
 throughs
-Tianma
 TILEDWINDOW
 TILLSON
 timedate
@@ -1999,6 +1906,7 @@ TNP
 Toggleable
 tontrager
 Toolhelp
+toolsets
 toolwindow
 TOPDOWNDIB
 TOUCHEVENTF
@@ -2031,16 +1939,11 @@ UACUI
 UAL
 uap
 UBR
-UBreak
 ubrk
-UCallback
 ucrt
 ucrtd
 uefi
-UError
 uesc
-UFlags
-UHash
 UIA
 UIDs
 UIEx
@@ -2049,8 +1952,6 @@ uitests
 UITo
 ULONGLONG
 Ultrawide
-UMax
-UMin
 ums
 uncompilable
 UNCPRIORITY
@@ -2069,12 +1970,11 @@ UNORM
 unparsable
 unremapped
 Unsend
-unsubscribes
+Unsubscribes
 untriaged
 unvirtualized
 unwide
 unzoom
-UOffset
 UOI
 UPDATENOW
 updown
@@ -2090,7 +1990,6 @@ USEINSTALLERFORTEST
 USESHOWWINDOW
 USESTDHANDLES
 USRDLL
-UType
 uuidv
 uwp
 uxt
@@ -2101,17 +2000,16 @@ valuegenerator
 VARTYPE
 vbcscompiler
 vcamp
-vcenter
 VCENTER
 vcgtq
 VCINSTALLDIR
 vcp
 Vcpkg
+vcpkg
 vcpname
 VCRT
 vcruntime
 vcvars
-VDesktop
 vdupq
 VERBSONLY
 VERBW
@@ -2140,7 +2038,6 @@ vorrq
 VOS
 vpaddlq
 vqsubq
-vredraw
 VREDRAW
 vreinterpretq
 VSC
@@ -2153,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
@@ -2253,7 +2146,6 @@ WNDCLASSW
 wndproc
 wnode
 wom
-workerw
 WORKSPACESEDITOR
 WORKSPACESLAUNCHER
 WORKSPACESSNAPSHOTTOOL
@@ -2268,7 +2160,6 @@ wpr
 wprp
 wql
 wregex
-WReserved
 WResize
 WRITEOBJECTS
 Wrk
@@ -2286,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
--- a/.github/policies/resourceManagement.yml
+++ b/.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
--- a/.github/scripts/telemetry-pr-check.js
+++ b/.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;
--- a/.gitignore
+++ b/.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/
--- a/.gitmodules
+++ b/.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
--- a/.pipelines/ESRPSigning_core.json
+++ b/.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",
--- a/.pipelines/v2/release.yml
+++ b/.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
--- a/.pipelines/v2/templates/job-build-project.yml
+++ b/.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 }}
--- a/.pipelines/v2/templates/job-build-sdk.yml
+++ b/.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
--- a/.pipelines/v2/templates/steps-install-terrapin.yml
+++ b/.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)
--- a/.pipelines/v2/templates/steps-install-vcpkg.yml
+++ b/.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
--- a/.vsconfig
+++ b/.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"
  ]
 }
--- a/Cpp.Build.props
+++ b/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>
--- a/Cpp.Build.targets
+++ b/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>
--- a/Directory.Packages.props
+++ b/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" />
--- a/PowerToys.slnx
+++ b/PowerToys.slnx
@@ -68,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" />
@@ -471,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">
--- a/deps/expected-lite
+++ b/deps/expected-lite
--- a/deps/expected.props
+++ b/deps/expected.props
@@ -1,7 +0,0 @@
-<Project>
-	<ItemDefinitionGroup>
-		<ClCompile>
-			<AdditionalIncludeDirectories>$(MSBuildThisFileDirectory)expected-lite\include\nonstd\;%(AdditionalIncludeDirectories)</AdditionalIncludeDirectories>
-		</ClCompile>
-	</ItemDefinitionGroup>
-</Project>
--- a/deps/spdlog
+++ b/deps/spdlog
--- a/deps/spdlog-msvc-fix/include/spdlog-msvc-fix.h
+++ b/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
--- a/deps/spdlog.props
+++ b/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>
--- a/deps/vcpkg-overlays/spdlog/msvc-14.51-stdext-checked-array-iterator.patch
+++ b/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) {
--- a/deps/vcpkg-overlays/spdlog/portfile.cmake
+++ b/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")
--- a/deps/vcpkg-overlays/spdlog/vcpkg.json
+++ b/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
+    }
+  ]
+}
--- a/doc/devdocs/development/debugging.md
+++ b/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
--- a/doc/images/overview/Original/ShortcutGuide.png
+++ b/doc/images/overview/Original/ShortcutGuide.png
--- a/doc/images/overview/ShortcutGuide_large.png
+++ b/doc/images/overview/ShortcutGuide_large.png
--- a/doc/images/overview/ShortcutGuide_small.png
+++ b/doc/images/overview/ShortcutGuide_small.png
--- a/doc/specs/WinGet
+++ b/doc/specs/WinGet
@@ -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>

--- a/doc/thirdPartyRunPlugins.md
+++ b/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. |
--- a/installer/PowerToysSetup.slnx
+++ b/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>
--- a/installer/PowerToysSetupVNext/DesktopGrass.wxs
+++ b/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>
--- a/installer/PowerToysSetupVNext/PowerToysInstallerVNext.wixproj
+++ b/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" />
--- a/installer/PowerToysSetupVNext/Product.wxs
+++ b/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" />
--- a/installer/PowerToysSetupVNext/ShortcutGuide.wxs
+++ b/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>
--- a/installer/PowerToysSetupVNext/generateAllFileComponents.ps1
+++ b/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\"
--- a/src/ActionRunner/actionRunner.vcxproj
+++ b/src/ActionRunner/actionRunner.vcxproj
@@ -14,7 +14,6 @@
  <PropertyGroup Label="Configuration">
    
  </PropertyGroup>
-  <Import Project="$(RepoRoot)deps\expected.props" />
  <PropertyGroup>
    <ConfigurationType>Application</ConfigurationType>
  </PropertyGroup>
--- a/src/Update/PowerToys.Update.vcxproj
+++ b/src/Update/PowerToys.Update.vcxproj
@@ -14,7 +14,6 @@
  <PropertyGroup Label="Configuration">
    
  </PropertyGroup>
-  <Import Project="$(RepoRoot)deps\expected.props" />
  <PropertyGroup>
    <ConfigurationType>Application</ConfigurationType>
  </PropertyGroup>
--- a/src/common/UnitTests-CommonUtils/UnitTests-CommonUtils.vcxproj
+++ b/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>
--- a/src/common/logger/logger.vcxproj
+++ b/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>
--- a/src/common/updating/pch.h
+++ b/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>
--- a/src/common/updating/updating.cpp
+++ b/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)

--- a/src/common/updating/updating.h
+++ b/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);
--- a/src/common/updating/updating.vcxproj
+++ b/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>
    
--- a/src/logging/logging.vcxproj
+++ b/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>
--- a/src/logging/logging.vcxproj.filters
+++ b/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>
--- a/src/modules/AdvancedPaste/AdvancedPaste.FuzzTests/FuzzTests.cs
+++ b/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.
--- a/src/modules/AdvancedPaste/AdvancedPaste/Helpers/JsonHelper.cs
+++ b/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
--- a/src/modules/DesktopGrass/DesktopGrass.Native.Tests/DesktopGrass.Native.Tests.vcxproj
+++ b/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>
--- a/src/modules/DesktopGrass/DesktopGrass.Native.Tests/snapshot_gen.cpp
+++ b/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;
+}
--- a/src/modules/DesktopGrass/DesktopGrass.Native.Tests/src/ambient_gust_tests.cpp
+++ b/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);
+}
--- a/src/modules/DesktopGrass/DesktopGrass.Native.Tests/src/autostart_tests.cpp
+++ b/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());
+}
--- a/src/modules/DesktopGrass/DesktopGrass.Native.Tests/src/autumn_tests.cpp
+++ b/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]);
+        }
+    }
+}
--- a/src/modules/DesktopGrass/DesktopGrass.Native.Tests/src/bird_flyby_tests.cpp
+++ b/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));
+}
--- a/src/modules/DesktopGrass/DesktopGrass.Native.Tests/src/blade_gen_tests.cpp
+++ b/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);
+}
--- a/src/modules/DesktopGrass/DesktopGrass.Native.Tests/src/bunny_tests.cpp
+++ b/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));
+}
--- a/src/modules/DesktopGrass/DesktopGrass.Native.Tests/src/butterfly_tests.cpp
+++ b/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);
+    }
+}
+
--- a/src/modules/DesktopGrass/DesktopGrass.Native.Tests/src/cat_coat_tests.cpp
+++ b/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);
+}
--- a/src/modules/DesktopGrass/DesktopGrass.Native.Tests/src/cat_tests.cpp
+++ b/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);
+}
+
--- a/src/modules/DesktopGrass/DesktopGrass.Native.Tests/src/click_through_smoke_test.cpp
+++ b/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);
+}
--- a/src/modules/DesktopGrass/DesktopGrass.Native.Tests/src/config_tests.cpp
+++ b/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));
+}
--- a/src/modules/DesktopGrass/DesktopGrass.Native.Tests/src/critter_tests.cpp
+++ b/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));
+}
--- a/src/modules/DesktopGrass/DesktopGrass.Native.Tests/src/cut_tests.cpp
+++ b/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));
+}
--- a/src/modules/DesktopGrass/DesktopGrass.Native.Tests/src/desert_tests.cpp
+++ b/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));
+}
--- a/src/modules/DesktopGrass/DesktopGrass.Native.Tests/src/entity_skeleton_tests.cpp
+++ b/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
+}
--- a/src/modules/DesktopGrass/DesktopGrass.Native.Tests/src/firefly_tests.cpp
+++ b/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);
+}
+
--- a/src/modules/DesktopGrass/DesktopGrass.Native.Tests/src/flower_tests.cpp
+++ b/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));
+}
--- a/src/modules/DesktopGrass/DesktopGrass.Native.Tests/src/gust_tests.cpp
+++ b/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));
+}
--- a/src/modules/DesktopGrass/DesktopGrass.Native.Tests/src/hedgehog_tests.cpp
+++ b/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));
+}
--- a/src/modules/DesktopGrass/DesktopGrass.Native.Tests/src/main.cpp
+++ b/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"
--- a/src/modules/DesktopGrass/DesktopGrass.Native.Tests/src/mushroom_tests.cpp
+++ b/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);
+        }
+    }
+}
--- a/src/modules/DesktopGrass/DesktopGrass.Native.Tests/src/ocean_tests.cpp
+++ b/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]);
+    }
+}
--- a/src/modules/DesktopGrass/DesktopGrass.Native.Tests/src/pacing_tests.cpp
+++ b/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);
+}
--- a/src/modules/DesktopGrass/DesktopGrass.Native.Tests/src/persistence_tests.cpp
+++ b/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);
+}
--- a/src/modules/DesktopGrass/DesktopGrass.Native.Tests/src/pine_tests.cpp
+++ b/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));
+}
--- a/src/modules/DesktopGrass/DesktopGrass.Native.Tests/src/prng_tests.cpp
+++ b/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);
+}
--- a/src/modules/DesktopGrass/DesktopGrass.Native.Tests/src/prop_spacing_tests.cpp
+++ b/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);
+}
--- a/src/modules/DesktopGrass/DesktopGrass.Native.Tests/src/regrowth_tests.cpp
+++ b/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
+}
--- a/src/modules/DesktopGrass/DesktopGrass.Native.Tests/src/scene_tests.cpp
+++ b/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]);
+    }
+}
--- a/src/modules/DesktopGrass/DesktopGrass.Native.Tests/src/sheep_greeting_tests.cpp
+++ b/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);
+}
--- a/src/modules/DesktopGrass/DesktopGrass.Native.Tests/src/snapshot_data.h
+++ b/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
--- a/src/modules/DesktopGrass/DesktopGrass.Native.Tests/src/sway_tests.cpp
+++ b/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));
+}
--- a/src/modules/DesktopGrass/DesktopGrass.Native.Tests/src/winter_tests.cpp
+++ b/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));
+    }
+}
--- a/src/modules/DesktopGrass/DesktopGrass.Native.Tests/third_party/README.md
+++ b/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.
--- a/src/modules/DesktopGrass/DesktopGrass.Native.Tests/third_party/catch2/catch.hpp
+++ b/src/modules/DesktopGrass/DesktopGrass.Native.Tests/third_party/catch2/catch.hpp
--- a/src/modules/DesktopGrass/DesktopGrass.Native.Tests/vcpkg.json
+++ b/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": []
+}
--- a/src/modules/DesktopGrass/DesktopGrass.Native/DesktopGrass.Native.rc
+++ b/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>.
--- a/src/modules/DesktopGrass/DesktopGrass.Native/DesktopGrass.Native.vcxproj
+++ b/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>
--- a/src/modules/DesktopGrass/DesktopGrass.Native/app.manifest
+++ b/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>
--- a/src/modules/DesktopGrass/DesktopGrass.Native/res/icon.ico
+++ b/src/modules/DesktopGrass/DesktopGrass.Native/res/icon.ico
--- a/src/modules/DesktopGrass/DesktopGrass.Native/resource.h
+++ b/src/modules/DesktopGrass/DesktopGrass.Native/resource.h
@@ -0,0 +1,6 @@
+// resource.h
+
+#pragma once
+
+#define IDI_APPICON   101
+#define IDI_TRAYICON  102
--- a/src/modules/DesktopGrass/DesktopGrass.Native/src/App.cpp
+++ b/src/modules/DesktopGrass/DesktopGrass.Native/src/App.cpp
@@ -0,0 +1,577 @@
+// App.cpp
+
+#include "App.h"
+
+#include "AutoStart.h"
+#include "Constants.h"
+#include "Sim.h"
+#include "../resource.h"
+
+#include <shellscalingapi.h>
+#include <algorithm>
+#include <cstdio>
+#include <string>
+#include <utility>
+
+#pragma comment(lib, "shell32.lib")
+#pragma comment(lib, "Shcore.lib")
+#pragma comment(lib, "User32.lib")
+
+namespace desktopgrass {
+
+namespace {
+
+constexpr const wchar_t* kMsgWindowClass = L"DesktopGrass.Native.MessageWindow";
+
+// Fixed launch seed shared with the Win2D implementation so both produce
+// identical, deterministic per-monitor blade layouts.
+constexpr uint64_t kAppSeed = 0xD3C7C0F30070D511ull;
+
+// Per-monitor seed: combine the fixed app seed with the monitor's physical
+// origin so different screens get different — but stable across launches —
+// blade layouts. Mirrors Win2D App.cs exactly, including C# `(ulong)int`
+// sign-extension and unchecked uint64 multiply/wraparound semantics.
+uint64_t make_monitor_seed(const RECT& bounds) {
+    const uint64_t left = static_cast<uint64_t>(static_cast<int64_t>(bounds.left));
+    const uint64_t top  = static_cast<uint64_t>(static_cast<int64_t>(bounds.top));
+    return kAppSeed
+        ^ (left * 0xA0761D6478BD642Full)
+        ^ (top  * 0xE7037ED1A0B428DBull);
+}
+
+// EnumDisplayMonitors callback context.
+struct MonitorEnumCtx {
+    App*                app;
+    std::vector<RECT>   bounds;
+    std::vector<UINT>   dpis;
+};
+
+BOOL CALLBACK MonitorEnumProc(HMONITOR hMon, HDC, LPRECT, LPARAM lParam) {
+    auto* ctx = reinterpret_cast<MonitorEnumCtx*>(lParam);
+    MONITORINFO mi{};
+    mi.cbSize = sizeof(mi);
+    if (GetMonitorInfoW(hMon, &mi)) {
+        // Use the work area, not the full monitor rect, so the grass sits on
+        // top of the taskbar instead of being drawn behind it. On monitors with
+        // no taskbar (typical secondary displays), rcWork == rcMonitor.
+        ctx->bounds.push_back(mi.rcWork);
+        UINT xDpi = 96, yDpi = 96;
+        if (FAILED(GetDpiForMonitor(hMon, MDT_EFFECTIVE_DPI, &xDpi, &yDpi))) {
+            xDpi = 96;
+        }
+        ctx->dpis.push_back(xDpi);
+    }
+    return TRUE;
+}
+
+} // anonymous
+
+App::~App() {
+    DestroyAllGrassWindows();
+    RemoveTrayIcon();
+    if (trayMenu_) { DestroyMenu(trayMenu_); trayMenu_ = nullptr; }
+    DestroyMessageWindow();
+    uninstall_mouse_hook();
+}
+
+bool App::Initialize(HINSTANCE hInst) {
+    hInst_   = hInst;
+    config_  = config::LoadConfig();
+
+    QueryPerformanceFrequency(&qpcFreq_);
+    QueryPerformanceCounter(&qpcLast_);
+
+    hasPersistedState_ = persistence::LoadAppState(persistedState_);
+    if (hasPersistedState_) {
+        currentScene_ = persistedState_.scene;
+        currentCritter_ = persistedState_.critter;
+        currentCritterCount_ = persistedState_.critterCountOverride;
+        autoStart_ = persistedState_.autoStart;
+    }
+    if (!autostart::ReconcileWithState(autoStart_)) {
+        OutputDebugStringA("[DesktopGrass] unable to reconcile Start with Windows registry state\n");
+    }
+    lastPersistenceSaveMs_ = GetTickCount64();
+
+    if (!GrassWindow::RegisterWindowClass(hInst_)) return false;
+    if (!CreateMessageWindow())                    return false;
+    if (!CreateTrayIcon())                         return false;
+    if (!EnumerateMonitorsAndCreateWindows())      return false;
+
+    if (!install_mouse_hook(&queue_)) {
+        OutputDebugStringA("[DesktopGrass] install_mouse_hook failed\n");
+        // Non-fatal — the grass will still sway, just no gusts/cuts.
+    }
+
+    return true;
+}
+
+bool App::CreateMessageWindow() {
+    WNDCLASSEXW wc{};
+    wc.cbSize        = sizeof(wc);
+    wc.lpfnWndProc   = App::MessageWindowProc;
+    wc.hInstance     = hInst_;
+    wc.lpszClassName = kMsgWindowClass;
+
+    ATOM atom = RegisterClassExW(&wc);
+    if (atom == 0 && GetLastError() != ERROR_CLASS_ALREADY_EXISTS) {
+        return false;
+    }
+
+    msgHwnd_ = CreateWindowExW(
+        0, kMsgWindowClass, L"DesktopGrass.Msg",
+        0, 0, 0, 0, 0,
+        HWND_MESSAGE, nullptr, hInst_, this);
+    return msgHwnd_ != nullptr;
+}
+
+void App::DestroyMessageWindow() {
+    if (msgHwnd_) {
+        DestroyWindow(msgHwnd_);
+        msgHwnd_ = nullptr;
+    }
+}
+
+bool App::CreateTrayIcon() {
+    // Build the menu: Scene ▸ (radio: Grass / Desert / Winter / Autumn) | Quit.
+    // The Scene submenu is a child popup of trayMenu_; DestroyMenu is
+    // recursive so destroying trayMenu_ cleans up the submenu too.
+    trayMenu_ = CreatePopupMenu();
+    if (!trayMenu_) return false;
+    sceneSubmenu_ = CreatePopupMenu();
+    if (!sceneSubmenu_) return false;
+    AppendMenuW(sceneSubmenu_, MF_STRING, kMenuSceneGrass,  L"Grass");
+    AppendMenuW(sceneSubmenu_, MF_STRING, kMenuSceneDesert, L"Desert");
+    AppendMenuW(sceneSubmenu_, MF_STRING, kMenuSceneWinter, L"Winter");
+    AppendMenuW(sceneSubmenu_, MF_STRING, kMenuSceneAutumn, L"Autumn");
+    AppendMenuW(sceneSubmenu_, MF_STRING, kMenuSceneOcean,  L"Ocean");
+    AppendMenuW(trayMenu_, MF_POPUP | MF_STRING,
+                reinterpret_cast<UINT_PTR>(sceneSubmenu_), L"Scene");
+
+    critterSubmenu_ = CreatePopupMenu();
+    if (!critterSubmenu_) return false;
+    AppendMenuW(critterSubmenu_, MF_STRING, kMenuCritterNone,  L"None");
+    AppendMenuW(critterSubmenu_, MF_STRING, kMenuCritterSheep, L"Sheep");
+    AppendMenuW(critterSubmenu_, MF_STRING, kMenuCritterCat,   L"Cat");
+    AppendMenuW(critterSubmenu_, MF_STRING, kMenuCritterAll,   L"All");
+
+    petCountSubmenu_ = CreatePopupMenu();
+    if (!petCountSubmenu_) return false;
+    AppendMenuW(petCountSubmenu_, MF_STRING, kMenuPetCountRandom, L"Random");
+    for (int n : PET_COUNT_OPTIONS) {
+        AppendMenuW(petCountSubmenu_, MF_STRING,
+                    static_cast<UINT_PTR>(kMenuPetCount1 + (n - 1)),
+                    std::to_wstring(n).c_str());
+    }
+    AppendMenuW(critterSubmenu_, MF_SEPARATOR, 0, nullptr);
+    AppendMenuW(critterSubmenu_, MF_POPUP | MF_STRING,
+                reinterpret_cast<UINT_PTR>(petCountSubmenu_), L"Pet count");
+
+    AppendMenuW(trayMenu_, MF_POPUP | MF_STRING,
+                reinterpret_cast<UINT_PTR>(critterSubmenu_), L"Critter");
+
+    AppendMenuW(trayMenu_, MF_STRING, kMenuAutoStart, L"Start with Windows");
+    AppendMenuW(trayMenu_, MF_SEPARATOR, 0, nullptr);
+    AppendMenuW(trayMenu_, MF_STRING, kMenuQuit, L"Quit DesktopGrass");
+    UpdateSceneMenuCheck();
+    UpdateCritterMenuCheck();
+    UpdatePetCountMenuCheck();
+    UpdateAutoStartMenuCheck();
+
+    nid_ = {};
+    nid_.cbSize           = sizeof(nid_);
+    nid_.hWnd             = msgHwnd_;
+    nid_.uID              = kTrayIconId;
+    nid_.uFlags           = NIF_ICON | NIF_MESSAGE | NIF_TIP;
+    nid_.uCallbackMessage = kTrayMessage;
+
+    HICON icon = LoadIconW(hInst_, MAKEINTRESOURCEW(IDI_TRAYICON));
+    if (!icon) icon = LoadIconW(nullptr, IDI_APPLICATION);
+    nid_.hIcon = icon;
+    wcsncpy_s(nid_.szTip, L"Desktop Grass", _TRUNCATE);
+
+    BOOL ok = Shell_NotifyIconW(NIM_ADD, &nid_);
+    trayAdded_ = (ok == TRUE);
+    if (!trayAdded_) {
+        OutputDebugStringA("[DesktopGrass] Shell_NotifyIcon(NIM_ADD) failed\n");
+    }
+    return true; // non-fatal
+}
+
+void App::UpdateSceneMenuCheck() {
+    if (!sceneSubmenu_) return;
+    // Radio-style check: kMenuSceneGrass + Scene enum index.
+    const int activeId = kMenuSceneGrass + static_cast<int>(currentScene_);
+    CheckMenuRadioItem(sceneSubmenu_,
+                       kMenuSceneGrass, kMenuSceneOcean,
+                       activeId, MF_BYCOMMAND);
+}
+
+void App::SetScene(Scene s) {
+    if (s == currentScene_) {
+        UpdateSceneMenuCheck();
+        return;
+    }
+    currentScene_ = s;
+    for (auto& w : windows_) {
+        sim_set_scene(w->GetRenderer().GetSim(), s);
+    }
+    UpdateSceneMenuCheck();
+    SaveCurrentState();
+}
+
+void App::UpdateCritterMenuCheck() {
+    if (!critterSubmenu_) return;
+    const int activeId = kMenuCritterNone + static_cast<int>(currentCritter_);
+    CheckMenuRadioItem(critterSubmenu_,
+                       kMenuCritterNone, kMenuCritterAll,
+                       activeId, MF_BYCOMMAND);
+}
+
+void App::UpdatePetCountMenuCheck() {
+    if (!petCountSubmenu_) return;
+    const int activeId = currentCritterCount_ > 0
+        ? kMenuPetCount1 + (std::min(currentCritterCount_, PET_COUNT_MAX_PER_MONITOR) - 1)
+        : kMenuPetCountRandom;
+    CheckMenuRadioItem(petCountSubmenu_,
+                       kMenuPetCountRandom, kMenuPetCount6,
+                       activeId, MF_BYCOMMAND);
+}
+
+void App::UpdateAutoStartMenuCheck() {
+    if (!trayMenu_) return;
+    CheckMenuItem(trayMenu_, kMenuAutoStart,
+                  MF_BYCOMMAND | (autoStart_ ? MF_CHECKED : MF_UNCHECKED));
+}
+
+void App::SetAutoStart(bool enabled) {
+    if (enabled == autoStart_ && autostart::IsEnabled() == enabled) {
+        UpdateAutoStartMenuCheck();
+        return;
+    }
+
+    if (!autostart::SetEnabled(enabled)) {
+        OutputDebugStringA("[DesktopGrass] unable to update Start with Windows registry state\n");
+        UpdateAutoStartMenuCheck();
+        return;
+    }
+
+    autoStart_ = enabled;
+    UpdateAutoStartMenuCheck();
+    SaveCurrentState();
+}
+
+void App::SetCritter(CritterKind c) {
+    if (c == currentCritter_) {
+        UpdateCritterMenuCheck();
+        return;
+    }
+    currentCritter_ = c;
+    for (auto& w : windows_) {
+        sim_set_critter(w->GetRenderer().GetSim(), c);
+    }
+    UpdateCritterMenuCheck();
+    SaveCurrentState();
+}
+
+void App::SetCritterCount(int n) {
+    const int sanitized = n > 0 ? std::min(n, PET_COUNT_MAX_PER_MONITOR) : 0;
+    if (sanitized == currentCritterCount_) {
+        UpdatePetCountMenuCheck();
+        return;
+    }
+
+    currentCritterCount_ = sanitized;
+    for (auto& w : windows_) {
+        sim_set_critter_count(w->GetRenderer().GetSim(), currentCritterCount_);
+    }
+    UpdatePetCountMenuCheck();
+    SaveCurrentState();
+}
+
+void App::RemoveTrayIcon() {
+    if (trayAdded_) {
+        Shell_NotifyIconW(NIM_DELETE, &nid_);
+        trayAdded_ = false;
+    }
+}
+
+bool App::EnumerateMonitorsAndCreateWindows() {
+    DestroyAllGrassWindows();
+
+    MonitorEnumCtx ctx{ this, {}, {} };
+    EnumDisplayMonitors(nullptr, nullptr, MonitorEnumProc,
+                        reinterpret_cast<LPARAM>(&ctx));
+
+    if (ctx.bounds.empty()) return false;
+
+    for (size_t i = 0; i < ctx.bounds.size(); ++i) {
+        auto w = std::make_unique<GrassWindow>();
+        // Each monitor gets a deterministic seed derived from its physical
+        // origin (shared formula with Win2D) so blade patterns differ across
+        // monitors but stay stable across launches and line up with persisted
+        // cut records.
+        const uint64_t mseed = make_monitor_seed(ctx.bounds[i]);
+        if (w->Create(hInst_, ctx.bounds[i], ctx.dpis[i], mseed, config_.bladeDensity,
+                      config_.swaySpeed, config_.swayAmplitude)) {
+            ApplyPersistedStateToWindow(*w, ctx.bounds[i]);
+            w->Show();
+            windows_.push_back(std::move(w));
+        } else {
+            OutputDebugStringA("[DesktopGrass] GrassWindow::Create failed\n");
+        }
+    }
+    return !windows_.empty();
+}
+
+void App::DestroyAllGrassWindows() {
+    windows_.clear();
+}
+
+void App::OnDisplayChanged() {
+    SaveCurrentState();
+    EnumerateMonitorsAndCreateWindows();
+}
+
+void App::DispatchMouseEvents() {
+    // Drain the lock-free queue once. Each event is then routed to whichever
+    // GrassWindow's screen rect contains it.
+    RawMouseEvent raw[256];
+    while (true) {
+        std::size_t n = queue_.drain(raw, 256);
+        if (n == 0) break;
+
+        for (std::size_t i = 0; i < n; ++i) {
+            const RawMouseEvent& e = raw[i];
+            for (auto& w : windows_) {
+                const RECT& r = w->GetScreenBounds();
+                // Move events fire across the gust band; click events only
+                // when in the strip. The Sim's band-check (apply_move / click)
+                // re-filters in window-local coords. Here we route any event
+                // whose x is in the window's horizontal range — Move events
+                // need to update the prevCursor baseline even outside the
+                // band so the baseline stays accurate, and the spec already
+                // handles the band rejection.
+                if (e.screenX < r.left || e.screenX > r.right) continue;
+
+                // For move events we accept any y; for click events we only
+                // accept y inside the band.
+                if (e.type == EventType::Click) {
+                    if (e.screenY < r.top || e.screenY > r.bottom) continue;
+                }
+
+                // Convert to window-local DIPs.
+                const UINT dpi = w->GetRenderer().GetDpi();
+                const double scale = 96.0 / static_cast<double>(dpi);
+                InputEvent ie{};
+                ie.type = e.type;
+                ie.x    = (e.screenX - r.left) * scale;
+                ie.y    = (e.screenY - r.top)  * scale;
+                ie.time = e.timeSeconds;
+
+                // Apply directly to the sim. Note that this happens BEFORE
+                // sim_tick (which itself drains its events list), so we apply
+                // events through the per-tick path — collect into a per-window
+                // event vector instead.
+                // To keep things simple, push to the Sim immediately:
+                if (ie.type == EventType::Move) {
+                    sim_apply_move(w->GetRenderer().GetSim(), ie);
+                } else {
+                    sim_apply_click(w->GetRenderer().GetSim(), ie);
+                }
+                break; // each event belongs to at most one window
+            }
+        }
+        if (n < 256) break;
+    }
+}
+
+void App::RenderAllWindows(double dt) {
+    DispatchMouseEvents();
+    for (auto& w : windows_) {
+        w->RenderFrame(dt, nullptr, 0);
+    }
+}
+
+void App::ApplyPersistedStateToWindow(GrassWindow& window, const RECT& monitorBounds) {
+    Sim& sim = window.GetRenderer().GetSim();
+    sim_set_scene(sim, currentScene_);
+    sim_set_critter_count(sim, currentCritterCount_);
+    sim_set_critter(sim, currentCritter_);
+
+    if (!hasPersistedState_) return;
+
+    const int width = monitorBounds.right - monitorBounds.left;
+    const int height = monitorBounds.bottom - monitorBounds.top;
+    for (const persistence::MonitorState& monitor : persistedState_.monitors) {
+        if (monitor.width == width
+            && monitor.height == height
+            && monitor.left == monitorBounds.left
+            && monitor.top == monitorBounds.top) {
+            sim_apply_cuts(sim, monitor.cuts);
+            return;
+        }
+    }
+}
+
+persistence::AppState App::BuildAppState() {
+    persistence::AppState state;
+    state.version = 2;
+    state.scene = currentScene_;
+    state.critter = currentCritter_;
+    state.critterCountOverride = currentCritterCount_;
+    state.autoStart = autoStart_;
+
+    state.monitors.reserve(windows_.size());
+    for (const auto& w : windows_) {
+        const RECT& bounds = w->GetMonitorBounds();
+        persistence::MonitorState monitor;
+        monitor.width = bounds.right - bounds.left;
+        monitor.height = bounds.bottom - bounds.top;
+        monitor.left = bounds.left;
+        monitor.top = bounds.top;
+        const Sim& sim = w->GetRenderer().GetSim();
+        monitor.cuts = sim_get_cuts(sim);
+        state.monitors.push_back(std::move(monitor));
+    }
+
+    return state;
+}
+
+void App::SaveCurrentState() {
+    persistedState_ = BuildAppState();
+    hasPersistedState_ = true;
+    persistence::SaveAppState(persistedState_);
+    lastPersistenceSaveMs_ = GetTickCount64();
+}
+
+int App::Run() {
+    MSG msg{};
+    // Calm ambient content renders at the configured target fps (default 24
+    // via Config.h kTargetFpsDefault) to keep per-frame CPU low; motion is
+    // time-based (dt), so the rate only changes how often the same animation
+    // is sampled. The user can override this in config.json (targetFps).
+    const double kTargetFrameSec = 1.0 / static_cast<double>(config_.targetFps);
+
+    while (!quitRequested_) {
+        // Drain pending messages without blocking.
+        while (PeekMessageW(&msg, nullptr, 0, 0, PM_REMOVE)) {
+            if (msg.message == WM_QUIT) {
+                quitRequested_ = true;
+                break;
+            }
+            TranslateMessage(&msg);
+            DispatchMessageW(&msg);
+        }
+        if (quitRequested_) break;
+
+        // Compute dt.
+        LARGE_INTEGER now;
+        QueryPerformanceCounter(&now);
+        const double dt = static_cast<double>(now.QuadPart - qpcLast_.QuadPart) /
+                          static_cast<double>(qpcFreq_.QuadPart);
+        qpcLast_ = now;
+
+        RenderAllWindows(dt);
+
+        if (GetTickCount64() - lastPersistenceSaveMs_ >= 60000ull) {
+            SaveCurrentState();
+        }
+
+        // Pace to the target frame interval, accounting for the time already
+        // spent rendering/presenting this iteration so the cadence holds at
+        // the target fps regardless of how long Present blocked. The pacer
+        // uses a high-resolution waitable timer (Win 10 1803+) so the wait
+        // honours sub-15.6 ms remainders instead of getting clamped to the
+        // default system timer resolution. The wait returns early if input
+        // arrives, keeping the app responsive.
+        LARGE_INTEGER after;
+        QueryPerformanceCounter(&after);
+        const double elapsedSec = static_cast<double>(after.QuadPart - now.QuadPart) /
+                                  static_cast<double>(qpcFreq_.QuadPart);
+        const double remainingSec = kTargetFrameSec - elapsedSec;
+        pacer_.WaitUntilNextFrame(remainingSec);
+    }
+
+    SaveCurrentState();
+    return static_cast<int>(msg.wParam);
+}
+
+void App::RequestQuit() {
+    quitRequested_ = true;
+    PostQuitMessage(0);
+}
+
+LRESULT CALLBACK App::MessageWindowProc(HWND hwnd, UINT msg,
+                                        WPARAM wp, LPARAM lp)
+{
+    App* self = nullptr;
+    if (msg == WM_NCCREATE) {
+        auto* cs = reinterpret_cast<CREATESTRUCTW*>(lp);
+        self = reinterpret_cast<App*>(cs->lpCreateParams);
+        SetWindowLongPtrW(hwnd, GWLP_USERDATA, reinterpret_cast<LONG_PTR>(self));
+        if (self) self->msgHwnd_ = hwnd;
+    } else {
+        self = reinterpret_cast<App*>(GetWindowLongPtrW(hwnd, GWLP_USERDATA));
+    }
+    if (self) return self->HandleMessageWindowMessage(msg, wp, lp);
+    return DefWindowProcW(hwnd, msg, wp, lp);
+}
+
+LRESULT App::HandleMessageWindowMessage(UINT msg, WPARAM wp, LPARAM lp) {
+    switch (msg) {
+        case kTrayMessage:
+            if (LOWORD(lp) == WM_RBUTTONUP || LOWORD(lp) == WM_CONTEXTMENU) {
+                POINT pt;
+                GetCursorPos(&pt);
+                SetForegroundWindow(msgHwnd_);
+                TrackPopupMenu(trayMenu_,
+                               TPM_RIGHTBUTTON | TPM_BOTTOMALIGN,
+                               pt.x, pt.y, 0, msgHwnd_, nullptr);
+                PostMessageW(msgHwnd_, WM_NULL, 0, 0);
+            }
+            return 0;
+
+        case WM_COMMAND: {
+            const int id = LOWORD(wp);
+            if (id == kMenuPetCountRandom) {
+                SetCritterCount(0);
+                return 0;
+            }
+            if (id >= kMenuPetCount1 && id <= kMenuPetCount6) {
+                SetCritterCount(id - kMenuPetCount1 + 1);
+                return 0;
+            }
+            switch (id) {
+                case kMenuQuit:          RequestQuit();                       break;
+                case kMenuAutoStart:     SetAutoStart(!autoStart_);           break;
+                case kMenuSceneGrass:    SetScene(Scene::Grass);              break;
+                case kMenuSceneDesert:   SetScene(Scene::Desert);             break;
+                case kMenuSceneWinter:   SetScene(Scene::Winter);             break;
+                case kMenuSceneAutumn:   SetScene(Scene::Autumn);             break;
+    case kMenuSceneOcean:    SetScene(Scene::Ocean);              break;
+                case kMenuCritterNone:   SetCritter(CritterKind::None);       break;
+                case kMenuCritterSheep:  SetCritter(CritterKind::Sheep);      break;
+                case kMenuCritterCat:    SetCritter(CritterKind::Cat);        break;
+                case kMenuCritterAll:    SetCritter(CritterKind::Bunny);      break;
+            }
+            return 0;
+        }
+
+        case WM_DISPLAYCHANGE:
+            OnDisplayChanged();
+            return 0;
+
+        case WM_CLOSE:
+            // The smoke harness sends WM_CLOSE to the *grass* window, which
+            // PostQuitMessages from its WndProc. Also handle it here for
+            // robustness.
+            RequestQuit();
+            return 0;
+
+        default:
+            return DefWindowProcW(msgHwnd_, msg, wp, lp);
+    }
+}
+
+} // namespace desktopgrass
--- a/src/modules/DesktopGrass/DesktopGrass.Native/src/App.h
+++ b/src/modules/DesktopGrass/DesktopGrass.Native/src/App.h
@@ -0,0 +1,102 @@
+// App.h
+//
+// Application lifecycle. Owns the tray icon, the mouse hook, the per-monitor
+// GrassWindow list, and the message loop.
+
+#pragma once
+
+#define WIN32_LEAN_AND_MEAN
+#include <windows.h>
+#include <shellapi.h>
+
+#include <memory>
+#include <vector>
+
+#include "GrassWindow.h"
+#include "MouseHook.h"
+#include "Pacing.h"
+#include "Persistence.h"
+#include "Config.h"
+
+namespace desktopgrass {
+
+class App {
+public:
+    static constexpr UINT  kTrayMessage     = WM_APP + 100;
+    static constexpr UINT  kTrayIconId      = 1;
+    static constexpr int   kMenuQuit          = 1001;
+    static constexpr int   kMenuSceneGrass    = 1010;
+    static constexpr int   kMenuSceneDesert   = 1011;
+    static constexpr int   kMenuSceneWinter   = 1012;
+    static constexpr int   kMenuSceneAutumn   = 1013;
+    static constexpr int   kMenuSceneOcean    = 1014;
+    static constexpr int   kMenuCritterNone     = 1020;
+    static constexpr int   kMenuCritterSheep    = 1021;
+    static constexpr int   kMenuCritterCat      = 1022;
+    static constexpr int   kMenuCritterAll      = 1023;
+    static constexpr int   kMenuPetCountRandom  = 1030;
+    static constexpr int   kMenuPetCount1       = 1031;
+    static constexpr int   kMenuPetCount6       = 1036;
+    static constexpr int   kMenuAutoStart       = 1040;
+
+    App() = default;
+    ~App();
+
+    bool Initialize(HINSTANCE hInst);
+    int  Run();
+    void RequestQuit();
+    void SetScene(Scene s);
+    Scene GetScene() const { return currentScene_; }
+    void SetCritter(CritterKind c);
+    CritterKind GetCritter() const { return currentCritter_; }
+    void SetCritterCount(int n);
+    int  GetCritterCount() const { return currentCritterCount_; }
+
+private:
+    bool CreateMessageWindow();
+    bool CreateTrayIcon();
+    void RemoveTrayIcon();
+    void DestroyMessageWindow();
+    bool EnumerateMonitorsAndCreateWindows();
+    void DestroyAllGrassWindows();
+    void OnDisplayChanged();
+    void DispatchMouseEvents();
+    void RenderAllWindows(double dt);
+    void ApplyPersistedStateToWindow(GrassWindow& window, const RECT& monitorBounds);
+    persistence::AppState BuildAppState();
+    void SaveCurrentState();
+    void SetAutoStart(bool enabled);
+    void UpdateSceneMenuCheck();
+    void UpdateCritterMenuCheck();
+    void UpdatePetCountMenuCheck();
+    void UpdateAutoStartMenuCheck();
+
+    static LRESULT CALLBACK MessageWindowProc(HWND hwnd, UINT msg,
+                                              WPARAM wp, LPARAM lp);
+    LRESULT HandleMessageWindowMessage(UINT msg, WPARAM wp, LPARAM lp);
+
+    HINSTANCE                                   hInst_   = nullptr;
+    HWND                                        msgHwnd_ = nullptr;
+    HMENU                                       trayMenu_ = nullptr;
+    HMENU                                       sceneSubmenu_ = nullptr;
+    HMENU                                       critterSubmenu_ = nullptr;
+    HMENU                                       petCountSubmenu_ = nullptr;
+    NOTIFYICONDATAW                             nid_{};
+    bool                                        trayAdded_ = false;
+    MouseEventQueue                             queue_{};
+    std::vector<std::unique_ptr<GrassWindow>>   windows_;
+    config::Config                              config_{};
+    Scene                                       currentScene_ = SCENE_DEFAULT;
+    CritterKind                                 currentCritter_ = CRITTER_DEFAULT;
+    int                                         currentCritterCount_ = 0;
+    bool                                        autoStart_ = false;
+    bool                                        hasPersistedState_ = false;
+    persistence::AppState                       persistedState_{};
+    ULONGLONG                                   lastPersistenceSaveMs_ = 0;
+    LARGE_INTEGER                               qpcFreq_{};
+    LARGE_INTEGER                               qpcLast_{};
+    FramePacer                                  pacer_{};
+    bool                                        quitRequested_ = false;
+};
+
+} // namespace desktopgrass
--- a/src/modules/DesktopGrass/DesktopGrass.Native/src/AutoStart.cpp
+++ b/src/modules/DesktopGrass/DesktopGrass.Native/src/AutoStart.cpp
@@ -0,0 +1,107 @@
+#include "AutoStart.h"
+
+#define WIN32_LEAN_AND_MEAN
+#include <windows.h>
+
+#include <vector>
+
+#pragma comment(lib, "Advapi32.lib")
+
+namespace autostart {
+namespace {
+
+constexpr const wchar_t* kDefaultRunSubKey = L"Software\\Microsoft\\Windows\\CurrentVersion\\Run";
+std::wstring g_registryKeyOverride;
+
+std::wstring GetRegistrySubKey() {
+    return g_registryKeyOverride.empty() ? std::wstring(kDefaultRunSubKey) : g_registryKeyOverride;
+}
+
+} // namespace
+
+std::wstring GetRegistryValueName() {
+    return L"DesktopGrass.Native";
+}
+
+std::wstring GetCurrentExePath() {
+    std::vector<wchar_t> buffer(MAX_PATH);
+    while (true) {
+        const DWORD length = GetModuleFileNameW(nullptr, buffer.data(), static_cast<DWORD>(buffer.size()));
+        if (length == 0) {
+            return L"";
+        }
+        if (length < buffer.size()) {
+            return std::wstring(buffer.data(), length);
+        }
+        buffer.resize(buffer.size() * 2);
+    }
+}
+
+bool IsEnabled() {
+    HKEY key = nullptr;
+    const std::wstring subKey = GetRegistrySubKey();
+    const LSTATUS openStatus = RegOpenKeyExW(
+        HKEY_CURRENT_USER, subKey.c_str(), 0, KEY_QUERY_VALUE, &key);
+    if (openStatus != ERROR_SUCCESS) {
+        return false;
+    }
+
+    DWORD type = 0;
+    const std::wstring valueName = GetRegistryValueName();
+    const LSTATUS queryStatus = RegQueryValueExW(
+        key, valueName.c_str(), nullptr, &type, nullptr, nullptr);
+    RegCloseKey(key);
+
+    return queryStatus == ERROR_SUCCESS && (type == REG_SZ || type == REG_EXPAND_SZ);
+}
+
+bool SetEnabled(bool on) {
+    const std::wstring subKey = GetRegistrySubKey();
+    const std::wstring valueName = GetRegistryValueName();
+
+    if (on) {
+        const std::wstring path = GetCurrentExePath();
+        if (path.empty()) {
+            return false;
+        }
+
+        HKEY key = nullptr;
+        const LSTATUS createStatus = RegCreateKeyExW(
+            HKEY_CURRENT_USER, subKey.c_str(), 0, nullptr, REG_OPTION_NON_VOLATILE,
+            KEY_SET_VALUE, nullptr, &key, nullptr);
+        if (createStatus != ERROR_SUCCESS) {
+            return false;
+        }
+
+        const DWORD byteCount = static_cast<DWORD>((path.size() + 1) * sizeof(wchar_t));
+        const LSTATUS setStatus = RegSetValueExW(
+            key, valueName.c_str(), 0, REG_SZ,
+            reinterpret_cast<const BYTE*>(path.c_str()), byteCount);
+        RegCloseKey(key);
+        return setStatus == ERROR_SUCCESS;
+    }
+
+    HKEY key = nullptr;
+    const LSTATUS openStatus = RegOpenKeyExW(
+        HKEY_CURRENT_USER, subKey.c_str(), 0, KEY_SET_VALUE, &key);
+    if (openStatus == ERROR_FILE_NOT_FOUND) {
+        return true;
+    }
+    if (openStatus != ERROR_SUCCESS) {
+        return false;
+    }
+
+    const LSTATUS deleteStatus = RegDeleteValueW(key, valueName.c_str());
+    RegCloseKey(key);
+    return deleteStatus == ERROR_SUCCESS || deleteStatus == ERROR_FILE_NOT_FOUND;
+}
+
+bool ReconcileWithState(bool autoStart) {
+    return IsEnabled() == autoStart || SetEnabled(autoStart);
+}
+
+void SetRegistryKeyOverride(const std::wstring& subkey) {
+    g_registryKeyOverride = subkey;
+}
+
+} // namespace autostart
--- a/src/modules/DesktopGrass/DesktopGrass.Native/src/AutoStart.h
+++ b/src/modules/DesktopGrass/DesktopGrass.Native/src/AutoStart.h
@@ -0,0 +1,14 @@
+#pragma once
+
+#include <string>
+
+namespace autostart {
+
+bool IsEnabled();
+bool SetEnabled(bool on);
+std::wstring GetRegistryValueName();
+std::wstring GetCurrentExePath();
+bool ReconcileWithState(bool autoStart);
+void SetRegistryKeyOverride(const std::wstring& subkey);
+
+} // namespace autostart
--- a/src/modules/DesktopGrass/DesktopGrass.Native/src/Benchmark.cpp
+++ b/src/modules/DesktopGrass/DesktopGrass.Native/src/Benchmark.cpp
@@ -0,0 +1,328 @@
+// Benchmark.cpp
+//
+// See Benchmark.h. Minimal, side-effect-free measurement runner.
+
+#include "Benchmark.h"
+
+#include "GrassWindow.h"
+#include "Pacing.h"
+#include "Sim.h"
+
+#include <shellscalingapi.h>
+
+#include <algorithm>
+#include <cstdio>
+#include <cwchar>
+#include <cstring>
+#include <string>
+
+#pragma comment(lib, "Shcore.lib")
+#pragma comment(lib, "User32.lib")
+
+namespace desktopgrass::benchmark {
+
+namespace {
+
+// Same seed used by the production App so blade layouts are bit-identical
+// across production runs and benchmark runs at the same monitor origin.
+constexpr uint64_t kBenchmarkDefaultSeed = 0xD3C7C0F30070D511ull;
+
+bool ParseInt(const wchar_t* s, int& out) {
+    if (!s || !*s) return false;
+    wchar_t* end = nullptr;
+    long v = std::wcstol(s, &end, 10);
+    if (end == s || *end != L'\0') return false;
+    out = static_cast<int>(v);
+    return true;
+}
+
+bool ParseU64(const wchar_t* s, uint64_t& out) {
+    if (!s || !*s) return false;
+    wchar_t* end = nullptr;
+    int base = 10;
+    if (s[0] == L'0' && (s[1] == L'x' || s[1] == L'X')) {
+        base = 16;
+        s += 2;
+    }
+    unsigned long long v = std::wcstoull(s, &end, base);
+    if (end == s || *end != L'\0') return false;
+    out = static_cast<uint64_t>(v);
+    return true;
+}
+
+bool ParseScene(const wchar_t* s, Scene& out) {
+    int n = -1;
+    if (ParseInt(s, n) && n >= 0 && n < SCENE_COUNT) {
+        out = static_cast<Scene>(n);
+        return true;
+    }
+    if (_wcsicmp(s, L"grass")  == 0) { out = Scene::Grass;  return true; }
+    if (_wcsicmp(s, L"desert") == 0) { out = Scene::Desert; return true; }
+    if (_wcsicmp(s, L"winter") == 0) { out = Scene::Winter; return true; }
+    if (_wcsicmp(s, L"autumn") == 0) { out = Scene::Autumn; return true; }
+    if (_wcsicmp(s, L"ocean")  == 0) { out = Scene::Ocean;  return true; }
+    return false;
+}
+
+bool ParseCritter(const wchar_t* s, CritterKind& out) {
+    int n = -1;
+    if (ParseInt(s, n) && n >= 0 && n < CRITTER_COUNT) {
+        out = static_cast<CritterKind>(n);
+        return true;
+    }
+    if (_wcsicmp(s, L"none")  == 0) { out = CritterKind::None;  return true; }
+    if (_wcsicmp(s, L"sheep") == 0) { out = CritterKind::Sheep; return true; }
+    if (_wcsicmp(s, L"cat")   == 0) { out = CritterKind::Cat;   return true; }
+    if (_wcsicmp(s, L"bunny") == 0) { out = CritterKind::Bunny; return true; }
+    if (_wcsicmp(s, L"all")   == 0) { out = CritterKind::Bunny; return true; }
+    return false;
+}
+
+// Split an arg of the form `--key=value` into (key, value). If the arg is
+// `--key` with the value in the next arg, value is set to the next arg and
+// `consumedExtra` is true.
+struct KV {
+    std::wstring key;
+    const wchar_t* value = nullptr;
+    bool consumedExtra = false;
+};
+
+KV SplitArg(const wchar_t* arg, const wchar_t* nextArg) {
+    KV kv;
+    if (!arg || arg[0] != L'-' || arg[1] != L'-') return kv;
+    const wchar_t* eq = std::wcschr(arg, L'=');
+    if (eq) {
+        kv.key.assign(arg + 2, eq);
+        kv.value = eq + 1;
+    } else {
+        kv.key.assign(arg + 2);
+        if (nextArg && nextArg[0] != L'-') {
+            kv.value = nextArg;
+            kv.consumedExtra = true;
+        }
+    }
+    return kv;
+}
+
+// Get the primary monitor's work area + effective DPI.
+bool GetPrimaryMonitorInfo(RECT& workOut, UINT& dpiOut) {
+    POINT origin{ 0, 0 };
+    HMONITOR mon = MonitorFromPoint(origin, MONITOR_DEFAULTTOPRIMARY);
+    if (!mon) return false;
+    MONITORINFO mi{};
+    mi.cbSize = sizeof(mi);
+    if (!GetMonitorInfoW(mon, &mi)) return false;
+    workOut = mi.rcWork;
+    UINT xDpi = 96, yDpi = 96;
+    if (FAILED(GetDpiForMonitor(mon, MDT_EFFECTIVE_DPI, &xDpi, &yDpi))) {
+        xDpi = 96;
+    }
+    dpiOut = xDpi;
+    return true;
+}
+
+} // anonymous
+
+bool ParseOptions(int argc, wchar_t** argv, Options& out) {
+    // argv[0] is the executable; start at 1.
+    for (int i = 1; i < argc; ++i) {
+        const wchar_t* arg = argv[i];
+        if (!arg || arg[0] != L'-' || arg[1] != L'-') continue;
+        // --benchmark is handled by the caller (it's the mode switch) — skip.
+        if (_wcsicmp(arg, L"--benchmark") == 0) continue;
+
+        const wchar_t* nextArg = (i + 1 < argc) ? argv[i + 1] : nullptr;
+        KV kv = SplitArg(arg, nextArg);
+        if (kv.key.empty()) continue;
+        if (kv.consumedExtra) ++i;
+        if (!kv.value) continue;
+
+        if (_wcsicmp(kv.key.c_str(), L"scene") == 0) {
+            if (!ParseScene(kv.value, out.scene)) return false;
+        } else if (_wcsicmp(kv.key.c_str(), L"critter") == 0) {
+            if (!ParseCritter(kv.value, out.critter)) return false;
+        } else if (_wcsicmp(kv.key.c_str(), L"critter-count") == 0 ||
+                   _wcsicmp(kv.key.c_str(), L"crittercount") == 0) {
+            if (!ParseInt(kv.value, out.critterCount)) return false;
+        } else if (_wcsicmp(kv.key.c_str(), L"seed") == 0) {
+            if (!ParseU64(kv.value, out.seed)) return false;
+        } else if (_wcsicmp(kv.key.c_str(), L"duration") == 0) {
+            if (!ParseInt(kv.value, out.durationSec)) return false;
+            if (out.durationSec < 1) out.durationSec = 1;
+        } else if (_wcsicmp(kv.key.c_str(), L"width") == 0) {
+            if (!ParseInt(kv.value, out.widthPx)) return false;
+        } else if (_wcsicmp(kv.key.c_str(), L"height") == 0) {
+            if (!ParseInt(kv.value, out.heightPx)) return false;
+        } else if (_wcsicmp(kv.key.c_str(), L"fps") == 0 ||
+                   _wcsicmp(kv.key.c_str(), L"target-fps") == 0) {
+            if (!ParseInt(kv.value, out.targetFps)) return false;
+            if (out.targetFps < 1) out.targetFps = 1;
+        } else if (_wcsicmp(kv.key.c_str(), L"out") == 0 ||
+                   _wcsicmp(kv.key.c_str(), L"csv") == 0) {
+            out.outCsvPath.assign(kv.value);
+        } else if (_wcsicmp(kv.key.c_str(), L"hidden") == 0 ||
+                   _wcsicmp(kv.key.c_str(), L"hide") == 0) {
+            // Treat presence of the flag as `true`. Accept explicit value too.
+            int v = 1;
+            ParseInt(kv.value, v);
+            out.hideWindow = (v != 0);
+        }
+        // Unknown flags are silently ignored — older drivers stay compatible
+        // with newer binaries that add flags.
+    }
+    return true;
+}
+
+int Run(HINSTANCE hInst, const Options& opts) {
+    RECT primaryWork{};
+    UINT primaryDpi = 96;
+    if (!GetPrimaryMonitorInfo(primaryWork, primaryDpi)) {
+        std::fwprintf(stderr, L"[benchmark] failed to query primary monitor\n");
+        return 1;
+    }
+
+    const int primaryW = primaryWork.right - primaryWork.left;
+    const int primaryH = primaryWork.bottom - primaryWork.top;
+    const int targetW  = opts.widthPx  > 0 ? opts.widthPx  : primaryW;
+    const int defaultStripPx = static_cast<int>(
+        ((STRIP_HEIGHT + HEADROOM) * primaryDpi / 96.0) + 0.5);
+    const int targetH  = opts.heightPx > 0 ? opts.heightPx : defaultStripPx;
+
+    // GrassWindow.Create takes a "monitor work area" rect; it derives window
+    // origin/size from it. To honour width/height overrides while keeping the
+    // window pinned to the bottom-left of the primary work area, fabricate a
+    // monitorBounds rect of the requested width whose bottom matches the
+    // primary work-area bottom. Height is forced via the strip-DIP formula
+    // inside GrassWindow.Create; if the caller asked for a non-default
+    // heightPx we ignore that for the actual HWND (the renderer always uses
+    // STRIP_HEIGHT + HEADROOM in DIPs), but we still log targetH in the CSV
+    // header for traceability.
+    RECT monitorBounds = primaryWork;
+    monitorBounds.right = monitorBounds.left + targetW;
+    (void)targetH; // logged in CSV header below; HWND height is fixed by spec
+
+    if (!GrassWindow::RegisterWindowClass(hInst)) {
+        std::fwprintf(stderr, L"[benchmark] RegisterWindowClass failed\n");
+        return 1;
+    }
+
+    const uint64_t seed = opts.seed != 0 ? opts.seed : kBenchmarkDefaultSeed;
+
+    GrassWindow window;
+    if (!window.Create(hInst, monitorBounds, primaryDpi, seed,
+                       /*density=*/1.0, /*swaySpeed=*/1.0, /*swayAmplitude=*/1.0)) {
+        std::fwprintf(stderr, L"[benchmark] GrassWindow::Create failed\n");
+        return 1;
+    }
+
+    if (!opts.hideWindow) {
+        window.Show();
+    }
+
+    Sim& sim = window.GetRenderer().GetSim();
+    sim_set_scene(sim, opts.scene);
+    sim_set_critter_count(sim, opts.critterCount);
+    sim_set_critter(sim, opts.critter);
+
+    // Optional per-frame CSV.
+    FILE* csv = nullptr;
+    if (!opts.outCsvPath.empty()) {
+        if (_wfopen_s(&csv, opts.outCsvPath.c_str(), L"w, ccs=UTF-8") != 0 || !csv) {
+            std::fwprintf(stderr, L"[benchmark] failed to open %ls for write\n",
+                          opts.outCsvPath.c_str());
+            return 1;
+        }
+        std::fwprintf(csv,
+            L"# scene=%d critter=%d critter_count=%d seed=0x%016llX "
+            L"duration_s=%d target_fps=%d width_px=%d height_px=%d dpi=%u "
+            L"primary_work=%dx%d\n",
+            static_cast<int>(opts.scene),
+            static_cast<int>(opts.critter),
+            opts.critterCount,
+            static_cast<unsigned long long>(seed),
+            opts.durationSec, opts.targetFps, targetW, targetH,
+            primaryDpi, primaryW, primaryH);
+        std::fwprintf(csv, L"frame_index,t_seconds,dt_ms,render_ms\n");
+    }
+
+    LARGE_INTEGER qpcFreq{};
+    QueryPerformanceFrequency(&qpcFreq);
+    const double freq = static_cast<double>(qpcFreq.QuadPart);
+
+    LARGE_INTEGER tStart{};
+    QueryPerformanceCounter(&tStart);
+    LARGE_INTEGER tPrev = tStart;
+
+    const double durationS = static_cast<double>(opts.durationSec);
+    const double targetFrameSec = 1.0 / static_cast<double>(opts.targetFps);
+
+    long long frameIndex = 0;
+    bool userClosed = false;
+    FramePacer pacer;
+    int  exitCode = 0;
+
+    MSG msg{};
+    while (true) {
+        while (PeekMessageW(&msg, nullptr, 0, 0, PM_REMOVE)) {
+            if (msg.message == WM_QUIT) {
+                userClosed = true;
+                break;
+            }
+            TranslateMessage(&msg);
+            DispatchMessageW(&msg);
+        }
+        if (userClosed) break;
+
+        LARGE_INTEGER tNow{};
+        QueryPerformanceCounter(&tNow);
+        const double elapsedSinceStart =
+            static_cast<double>(tNow.QuadPart - tStart.QuadPart) / freq;
+        if (elapsedSinceStart >= durationS) break;
+
+        const double dt = static_cast<double>(tNow.QuadPart - tPrev.QuadPart) / freq;
+        tPrev = tNow;
+
+        LARGE_INTEGER tRenderStart{};
+        QueryPerformanceCounter(&tRenderStart);
+        window.RenderFrame(dt, nullptr, 0);
+        LARGE_INTEGER tRenderEnd{};
+        QueryPerformanceCounter(&tRenderEnd);
+
+        const double renderMs =
+            static_cast<double>(tRenderEnd.QuadPart - tRenderStart.QuadPart) * 1000.0 / freq;
+
+        if (csv) {
+            std::fwprintf(csv, L"%lld,%.6f,%.4f,%.4f\n",
+                          frameIndex, elapsedSinceStart, dt * 1000.0, renderMs);
+        }
+        ++frameIndex;
+
+        // Pace to target fps via the shared high-resolution waitable timer.
+        LARGE_INTEGER tAfter{};
+        QueryPerformanceCounter(&tAfter);
+        const double spentSec =
+            static_cast<double>(tAfter.QuadPart - tNow.QuadPart) / freq;
+        const double remaining = targetFrameSec - spentSec;
+        pacer.WaitUntilNextFrame(remaining);
+    }
+
+    if (csv) std::fclose(csv);
+
+    if (userClosed) exitCode = 2;
+
+    // Print one-line summary so the harness can capture even without parsing
+    // the CSV — written to stdout so it shows up in run logs.
+    LARGE_INTEGER tEnd{};
+    QueryPerformanceCounter(&tEnd);
+    const double totalSec =
+        static_cast<double>(tEnd.QuadPart - tStart.QuadPart) / freq;
+    const double effectiveFps = frameIndex > 0 && totalSec > 0
+        ? static_cast<double>(frameIndex) / totalSec
+        : 0.0;
+    std::wprintf(L"[benchmark] scene=%d frames=%lld duration_s=%.3f fps=%.2f exit=%d\n",
+                 static_cast<int>(opts.scene), frameIndex, totalSec, effectiveFps,
+                 exitCode);
+    return exitCode;
+}
+
+} // namespace desktopgrass::benchmark
--- a/src/modules/DesktopGrass/DesktopGrass.Native/src/Benchmark.h
+++ b/src/modules/DesktopGrass/DesktopGrass.Native/src/Benchmark.h
@@ -0,0 +1,55 @@
+// Benchmark.h
+//
+// Optional benchmark entry point used by tools/benchmark/ to measure renderer
+// cost in a deterministic, headless-ish run. NOT compiled into the production
+// path — main.cpp only invokes this when `--benchmark` appears on the command
+// line. Production code is untouched.
+//
+// The benchmark:
+//   * Creates ONE GrassWindow on the primary monitor's bottom strip (visible,
+//     same DComp/Direct2D path users see).
+//   * Skips the tray icon, MouseHook, persistence, and multi-monitor enum.
+//   * Forces a fixed scene + critter + seed so blade/entity content is
+//     reproducible across runs.
+//   * Renders for the requested duration, capturing per-frame CPU-side
+//     timings to a CSV.
+//   * Exits cleanly so an external driver can collect counters and move on.
+
+#pragma once
+
+#define WIN32_LEAN_AND_MEAN
+#include <windows.h>
+
+#include <cstdint>
+#include <string>
+
+#include "Constants.h"
+
+namespace desktopgrass::benchmark {
+
+struct Options {
+    Scene        scene        = Scene::Grass;
+    CritterKind  critter      = CRITTER_DEFAULT;
+    int          critterCount = 0;      // 0 = scene default (random species count)
+    uint64_t     seed         = 0;      // 0 = use the production app seed
+    int          durationSec  = 60;
+    int          widthPx      = 0;      // 0 = primary-monitor work-area width
+    int          heightPx     = 0;      // 0 = STRIP_HEIGHT + HEADROOM at primary DPI
+    int          targetFps    = 24;     // matches Config.h kTargetFpsDefault; overridable
+    std::wstring outCsvPath;            // empty = no per-frame log written
+    bool         hideWindow   = false;  // SW_HIDE instead of SW_SHOWNOACTIVATE
+};
+
+// Parse `--benchmark`-mode args. argv[0] should be the executable; subsequent
+// entries are recognized in the form `--key=value` or `--key value`. Unknown
+// flags are silently ignored so future production flags don't break older
+// harness invocations. Returns false if a required value is malformed.
+bool ParseOptions(int argc, wchar_t** argv, Options& out);
+
+// Run a single benchmark using `opts`. Returns the process exit code:
+//   0  -> ran for the full duration
+//   1  -> setup failure (window/renderer init, output CSV open)
+//   2  -> early exit (user closed the window before duration elapsed)
+int Run(HINSTANCE hInst, const Options& opts);
+
+} // namespace desktopgrass::benchmark
--- a/src/modules/DesktopGrass/DesktopGrass.Native/src/Config.cpp
+++ b/src/modules/DesktopGrass/DesktopGrass.Native/src/Config.cpp
@@ -0,0 +1,150 @@
+// Config.cpp
+
+#include "Config.h"
+
+#include "Json.h"
+
+#include <Windows.h>
+
+#include <algorithm>
+#include <cmath>
+#include <cstdlib>
+#include <filesystem>
+#include <fstream>
+#include <sstream>
+#include <string>
+
+namespace desktopgrass::config {
+namespace {
+
+// Annotated default config written verbatim on first run. JSONC comments are
+// tolerated by the loader, so users can keep these notes while editing.
+constexpr char kDefaultConfigTemplate[] =
+    "{\n"
+    "  // DesktopGrass settings. Edit and restart the app to apply.\n"
+    "  // This file is created once and never overwritten, so your edits stick.\n"
+    "  \"version\": 1,\n"
+    "\n"
+    "  // Animation frame rate. Lower = less CPU, choppier motion. Range 5-144.\n"
+    "  \"targetFps\": 24,\n"
+    "\n"
+    "  // Grass blade density. Lower = fewer blades (less CPU). Range 0.2-5.0.\n"
+    "  // Default 2.53125.\n"
+    "  \"bladeDensity\": 2.53125,\n"
+    "\n"
+    "  // Grass sway speed multiplier. 1.0 = default, 0.0 = still, higher = faster.\n"
+    "  // Range 0.0-3.0.\n"
+    "  \"swaySpeed\": 1.0,\n"
+    "\n"
+    "  // Grass sway amplitude multiplier (how far blades lean). 1.0 = default,\n"
+    "  // 0.0 = upright. Range 0.0-3.0.\n"
+    "  \"swayAmplitude\": 1.0\n"
+    "}\n";
+
+std::wstring DefaultConfigFilePath() {
+    wchar_t* localAppData = nullptr;
+    std::size_t length = 0;
+    _wdupenv_s(&localAppData, &length, L"LOCALAPPDATA");
+
+    std::filesystem::path path = localAppData && length > 0
+        ? std::filesystem::path(localAppData)
+        : std::filesystem::current_path();
+
+    if (localAppData) {
+        std::free(localAppData);
+    }
+
+    path /= L"DesktopGrass";
+    path /= L"config.json";
+    return path.wstring();
+}
+
+// Writes the annotated default config, but only if no file exists yet. Uses
+// CREATE_NEW so a concurrent writer or an existing user file is never clobbered.
+void TryWriteDefaultConfig(const std::filesystem::path& path) {
+    const std::filesystem::path directory = path.parent_path();
+    if (!directory.empty()) {
+        std::error_code ec;
+        std::filesystem::create_directories(directory, ec);
+    }
+
+    HANDLE handle = CreateFileW(path.c_str(), GENERIC_WRITE, 0, nullptr,
+                                CREATE_NEW, FILE_ATTRIBUTE_NORMAL, nullptr);
+    if (handle == INVALID_HANDLE_VALUE) {
+        return; // Already exists (or unwritable): leave it untouched.
+    }
+
+    DWORD written = 0;
+    WriteFile(handle, kDefaultConfigTemplate,
+              static_cast<DWORD>(sizeof(kDefaultConfigTemplate) - 1), &written, nullptr);
+    CloseHandle(handle);
+}
+
+template <typename T>
+T Clamp(T value, T lo, T hi) {
+    return value < lo ? lo : (value > hi ? hi : value);
+}
+
+// Clamps a config double, treating non-finite values (NaN/inf from malformed
+// input) as the supplied default so they can never poison the sim.
+double ClampFinite(double value, double lo, double hi, double fallback) {
+    if (!std::isfinite(value)) return fallback;
+    return Clamp(value, lo, hi);
+}
+
+Config ApplyAndClamp(const json::Value& root) {
+    Config cfg;
+    cfg.version = json::ReadInt(root, "version").value_or(kConfigVersion);
+
+    const int fps = json::ReadInt(root, "targetFps").value_or(kTargetFpsDefault);
+    cfg.targetFps = Clamp(fps, kTargetFpsMin, kTargetFpsMax);
+
+    const double density = json::ReadDouble(root, "bladeDensity").value_or(kBladeDensityDefault);
+    cfg.bladeDensity = ClampFinite(density, kBladeDensityMin, kBladeDensityMax, kBladeDensityDefault);
+
+    const double swaySpeed = json::ReadDouble(root, "swaySpeed").value_or(kSwaySpeedDefault);
+    cfg.swaySpeed = ClampFinite(swaySpeed, kSwaySpeedMin, kSwaySpeedMax, kSwaySpeedDefault);
+
+    const double swayAmp = json::ReadDouble(root, "swayAmplitude").value_or(kSwayAmplitudeDefault);
+    cfg.swayAmplitude = ClampFinite(swayAmp, kSwayAmplitudeMin, kSwayAmplitudeMax, kSwayAmplitudeDefault);
+
+    return cfg;
+}
+
+} // namespace
+
+std::wstring GetConfigFilePath() {
+    return DefaultConfigFilePath();
+}
+
+Config LoadConfig(const std::wstring& pathStr) {
+    const std::filesystem::path path(pathStr);
+
+    if (!std::filesystem::exists(path)) {
+        TryWriteDefaultConfig(path);
+        return Config{}; // Defaults match the template we just wrote.
+    }
+
+    std::ifstream file(path, std::ios::binary);
+    if (!file) {
+        return Config{};
+    }
+
+    std::ostringstream buffer;
+    buffer << file.rdbuf();
+    const std::string text = buffer.str();
+
+    json::Value root;
+    if (!json::Parse(text, root) || root.type != json::Value::Type::Object) {
+        OutputDebugStringA("DesktopGrass config: malformed config.json; using defaults.\n");
+        return Config{}; // Preserve the user's file; just fall back to defaults.
+    }
+
+    return ApplyAndClamp(root);
+}
+
+Config LoadConfig() {
+    return LoadConfig(GetConfigFilePath());
+}
+
+} // namespace desktopgrass::config
--- a/src/modules/DesktopGrass/DesktopGrass.Native/src/Config.h
+++ b/src/modules/DesktopGrass/DesktopGrass.Native/src/Config.h
@@ -0,0 +1,50 @@
+// Config.h
+//
+// User-editable settings loaded from config.json. Distinct from state.json
+// (which the app owns and rewrites): config.json is written once with annotated
+// defaults if missing, and thereafter only ever read — never overwritten — so a
+// user's hand edits are preserved. Loaded once at startup.
+
+#pragma once
+
+#include "Constants.h"
+
+#include <string>
+
+namespace desktopgrass::config {
+
+// Valid ranges and defaults for the exposed knobs. Defaults reproduce the app's
+// historical behavior exactly.
+constexpr int    kConfigVersion        = 1;
+constexpr int    kTargetFpsDefault      = 24;
+constexpr int    kTargetFpsMin          = 5;
+constexpr int    kTargetFpsMax          = 144;
+constexpr double kBladeDensityDefault   = DEFAULT_DENSITY; // 2.53125
+constexpr double kBladeDensityMin       = 0.2;
+constexpr double kBladeDensityMax       = 5.0;
+constexpr double kSwaySpeedDefault      = 1.0;
+constexpr double kSwaySpeedMin          = 0.0;
+constexpr double kSwaySpeedMax          = 3.0;
+constexpr double kSwayAmplitudeDefault  = 1.0;
+constexpr double kSwayAmplitudeMin      = 0.0;
+constexpr double kSwayAmplitudeMax      = 3.0;
+
+struct Config {
+    int    version       = kConfigVersion;
+    int    targetFps     = kTargetFpsDefault;
+    double bladeDensity  = kBladeDensityDefault;
+    double swaySpeed     = kSwaySpeedDefault;
+    double swayAmplitude = kSwayAmplitudeDefault;
+};
+
+// Loads config.json from the default location, creating an annotated default
+// file if it is missing. Returns clamped, validated values; on any error falls
+// back to defaults without overwriting an existing file. Always succeeds.
+Config LoadConfig();
+
+// Path overload for tests: reads/creates the config at the given path.
+Config LoadConfig(const std::wstring& path);
+
+std::wstring GetConfigFilePath();
+
+} // namespace desktopgrass::config
--- a/Show More
+++ b/Show More