fix(v3/windows): fix ICO tray icons and follow taskbar theme

[leaanthony]

Description

Replaces #6016 (same content, branched into this repo). Original work by @nik9play — their commits are preserved here, with one test commit added on top.

This fixes two Windows system tray icon problems:

• Setting an .ico file using SetIcon did not work, and the icon fell back to the default Wails icon. The complete .ico container was passed to CreateIconFromResourceEx, which expects a single icon image resource. The implementation now parses the .ico directory, validates its entries, and selects the best embedded image for the requested dimensions and display bit depth.
• Light and dark tray icons were selected using AppsUseLightTheme. That preference controls application appearance, which can differ from the taskbar theme. Tray icons now use SystemUsesLightTheme, while application windows continue to use AppsUseLightTheme.

The added test (TestDarkModeDetectionReadsExpectedRegistryValues in v3/pkg/w32/theme_test.go) covers that second point: it is table-driven over both detection functions and asserts that each opens the Themes\Personalize key, reads its own value name (AppsUseLightTheme vs SystemUsesLightTheme), and reports dark mode when the value is 0. Covering both together is what guards the distinction — a swap of the two key names would otherwise be silent.

The systray documentation now states that SetDarkModeIcon is supported on Windows and macOS.

Type of change

• Bug fix (non-breaking change which fixes an issue)
• This change requires a documentation update

How Has This Been Tested?

• Windows
• macOS
• Linux

Per #6016, the affected Windows packages were tested with go test ./pkg/w32 ./pkg/application, and small example apps confirmed both the ICO tray icon and the light/dark taskbar behaviour (screenshots in #6016).

For the added test: GOOS=windows go vet ./pkg/w32 and GOOS=windows go test -c ./pkg/w32 are clean. Because the test only parses theme.go as source, its assertions were also exercised on a non-Windows host and mutation-checked — reverting the tray function to AppsUseLightTheme, flipping == 0 to != 0, and misspelling the registry path each fail with a specific message.

Checklist:

• My code follows the general coding style of this project
• I have performed a self-review of my own code
• I have commented my code, particularly in hard-to-understand areas
• I have made corresponding changes to the documentation
• My changes generate no new warnings
• I have added tests that prove my fix is effective or that my feature works
• New and existing unit tests pass locally with my changes

🤖 Generated with Claude Code

https://claude.ai/code/session_01MECVhq4AGVic4Zvo8VJBKg

---

Generated by Claude Code

Summary by CodeRabbit

• New Features

  • Added support for dark-mode system tray icons on Windows and macOS.
  • Improved Windows theme detection to respond to both application and system theme changes.
  • Enhanced icon handling for PNG and ICO files, selecting the best available size and color depth.

• Documentation

  • Updated system tray guidance with dark-mode icon support and best practices.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: d7170a8e-404f-4413-9a5a-660d80ab9181

📥 Commits

Reviewing files that changed from the base of the PR and between 97a418b and 343ee37.

📒 Files selected for processing (6)

• docs/src/content/docs/features/menus/systray.mdx
• v3/pkg/application/application_windows.go
• v3/pkg/application/systemtray_windows.go
• v3/pkg/w32/icon.go
• v3/pkg/w32/theme.go
• v3/pkg/w32/theme_test.go

Included review availability: Your plan provides up to 10 included reviews per hour; 3 remain after this review.

---

Walkthrough

Windows theme tracking now includes system dark mode. Tray icons use the system theme. Windows icon loading now supports validated PNG and ICO resources with size and bit-depth selection. Theme detection tests and system tray documentation were updated.

Changes

Windows dark-mode and icon handling

Layer / File(s)	Summary
Icon resource validation and selection v3/pkg/w32/icon.go	Icon creation validates PNG and ICO data, selects suitable ICO entries, preserves resource lifetime, and uses the correct large-icon height metric.
System theme detection contract v3/pkg/w32/theme.go, v3/pkg/w32/theme_test.go	The Windows system theme helper reads SystemUsesLightTheme. AST tests verify registry access and dark-mode comparisons.
Theme change and tray integration v3/pkg/application/application_windows.go, v3/pkg/application/systemtray_windows.go	Application state tracks both theme values and emits SystemThemeChanged when either changes. Tray icons use the system theme.
Documentation updates docs/src/content/docs/features/menus/systray.mdx	The documentation describes dark-mode icon support and testing guidance for Windows and macOS.

Estimated code review effort: 4 (Complex) | ~45 minutes

Merge Risk: ⚪ Minimal · up to 343ee

This PR corrects Windows ICO tray icon handling and aligns tray icon selection with the taskbar theme; no actionable merge-blocking risk remains after normal checks.

Sequence Diagram(s)

sequenceDiagram
  participant Windows
  participant Application
  participant w32
  participant SystemTray
  Windows->>Application: WM_SETTINGCHANGE
  Application->>w32: Read application and system dark-mode state
  w32-->>Application: Theme state values
  Application->>Application: Emit SystemThemeChanged when either value changes
  SystemTray->>w32: Read system dark-mode state
  w32-->>SystemTray: Select dark or light tray icon

Loading

Poem

A rabbit checks the icons bright,
Then sorts the ICOs just right.

Dark system skies inform the tray,
Windows themes now guide the way,
And docs record the hop today.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 50.00% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 18 functions across 5 files. (1 skipped: …	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly summarizes the two primary changes: fixing Windows ICO tray icons and aligning tray behavior with the taskbar theme.
Description check	✅ Passed	The description covers the issue context, fixes, motivation, testing, documentation update, and checklist. It is mostly complete, although it does not provide wails doctor output or explicitly list …
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

Full details: Description check

Explanation

The description covers the issue context, fixes, motivation, testing, documentation update, and checklist. It is mostly complete, although it does not provide wails doctor output or explicitly list dependencies.

Full details: Docstring Coverage

Explanation

Docstring coverage is 50.00% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 18 functions across 5 files. (1 skipped: 1 unsupported.)

✨ Finishing Touches 💡 1

📝 Generate docstrings 💡

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch claude/runtime-keepalive-pr-7vjlwm

Warning

Some tools did not complete. Review the errors below.

🔧 golangci-lint (2.12.2)

level=error msg="[linters_context] typechecking error: build constraints exclude all Go files in /v3/pkg/w32"

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[Copilot]

Pull request overview

This PR fixes Windows v3 system tray icon behavior by (1) correctly extracting a single embedded image from .ico containers before calling CreateIconFromResourceEx, and (2) making tray icon light/dark selection follow the taskbar/system surfaces theme (SystemUsesLightTheme) rather than the apps theme (AppsUseLightTheme). It also adds an AST-based test to lock in the registry value-name distinction and updates systray documentation accordingly.

Changes:

• Add IsSystemCurrentlyDarkMode() to read SystemUsesLightTheme from the Personalize registry key.
• Update Windows systray icon selection to use system-surface theme detection.
• Add a table-driven AST test ensuring both dark-mode detection functions open the correct registry key/value and treat 0 as dark mode.

Reviewed changes

Copilot reviewed 6 out of 6 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
v3/pkg/w32/theme.go	Adds system-surface dark mode detection via SystemUsesLightTheme.
v3/pkg/w32/theme_test.go	Adds AST-based regression test to prevent swapping AppsUseLightTheme vs SystemUsesLightTheme.
v3/pkg/w32/icon.go	Implements ICO directory parsing and selects a best-fit embedded image resource for icon creation.
v3/pkg/application/systemtray_windows.go	Switches tray icon selection to system-surface dark mode detection.
v3/pkg/application/application_windows.go	Tracks both app and system-surface theme state to emit theme-change events when either changes.
docs/src/content/docs/features/menus/systray.mdx	Documents SetDarkModeIcon as supported on Windows and macOS.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[leaanthony]

Closing — superseded. #6016 was merged with the identical content (same tree), so this branch has nothing left to contribute.

---

Generated by Claude Code