fix(desktop): Restore Linux icons and GNOME dock pinning

[mwolson]

What Changed

Restores Linux overview icons after AppImage reinstallation and corrects launcher matching so GNOME can pin the running app to its visible launcher.

Addresses #10894 linux-wayland-desktop-icon.

Why

Shells that resolve the Wayland app id through desktop files and the icon theme need an icon on the hidden URL handler and lowercase theme icons. Startup installs those icons synchronously before Electron becomes ready; icon-cache refresh runs separately so it cannot hold up startup.

GNOME was matching the running window to that hidden handler instead of the visible launcher, which prevented pinning. The packaged launcher and AUR entries now advertise StartupWMClass=com.t3tools.T3Code, matching the existing window identity. The URL handler stays hidden, without a competing StartupWMClass. This avoids adding another visible launcher and preserves existing capture bindings.

UI Changes

Linux overview tiles show the T3 icon, and GNOME can associate the running window with its visible launcher for favorites and relaunching. No in-app UI changes. Screenshots are not included.

Isolated GNOME 50.4 tests with Electron 44.1.0 reproduced the hidden-entry matching failure and verified the corrected matching, favorites reload, and desktop-entry relaunch on Wayland and X11 through Xwayland. These used generated desktop-entry fixtures, not a packaged T3 AppImage or an AppImageLauncher installation.

Known Limitations

Existing AppImageLauncher entries need re-integration to pick up the corrected metadata. This does not migrate stale pinned IDs or remove entries for older AppImages. The reporter's exact GNOME 46/AppImageLauncher setup has not been retested.

Checklist

• This PR is small and focused
• I explained what changed and why
• I included before/after screenshots for any UI changes
• I included a video for animation/interaction changes

Summary by CodeRabbit

• New Features

  • Improved Linux desktop integration with consistent application icons for production and development installations.
  • Packaged icons are now installed in the appropriate user icon directories and refreshed when needed.
  • Desktop entries now reference the correct application icon and Wayland identity.

• Bug Fixes

  • Prevented unnecessary icon copying and cache refreshes when the installed icons are already current.
  • Icon setup failures no longer prevent the desktop application from starting.

[macroscopeapp]

Approvability

Verdict: Not approved

Macroscope's review found this PR not approvable — This PR changes production Linux startup behavior by copying user icon assets, refreshing the GTK cache, and changing launcher identity metadata, while also adding a timer-diagnostic suppression. The unresolved risk that the new StartupWMClass may not match X11 windows could result in incorrect dock or launcher grouping and warrants human validation.

^{Adjust the Minimum Blocking Severity for this repo — including turning it Off — in Settings. You can add or adjust custom eligibility rules. Learn more.}

[cursor]

Bugbot is paused — on-demand spend limit reached

Bugbot uses usage-based billing for this team and has hit its on-demand spend limit.

A team admin can raise the spend limit in the Cursor dashboard, or wait for the next billing cycle to continue.

[coderabbitai]

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

• @coderabbitai resume to resume automatic reviews.
• @coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

• ▶️ Resume reviews
• 🔍 Trigger review

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Essentials

Run ID: 7179063b-a3ec-4cf1-a5c3-13953861ac3a

📥 Commits

Reviewing files that changed from the base of the PR and between e16b8b0 and e23c2b8.

📒 Files selected for processing (4)

• apps/desktop/src/app/DesktopLinuxUrlHandler.test.ts
• apps/desktop/src/app/DesktopLinuxUrlHandler.ts
• apps/desktop/src/app/DesktopPreReadyPlatform.test.ts
• apps/desktop/src/app/DesktopPreReadyPlatform.ts

---

📝 Walkthrough

Walkthrough

Linux desktop entries now use Icon=t3code. Linux pre-ready setup copies packaged hicolor icons into the user data directory and refreshes the icon cache when needed. Tests cover icon naming, copying, cache refresh behavior, and startup ordering.

Changes

Linux icon integration

Layer / File(s)	Summary
Desktop entry and icon mapping apps/desktop/src/app/DesktopLinuxUrlHandler.ts, apps/desktop/src/app/DesktopLinuxUrlHandler.test.ts	The hidden Linux desktop entry declares Icon=t3code. Helpers derive lowercase icon names and generate hicolor installation operations. Tests cover mixed-case desktop IDs and generated targets.
AppImage icon installation apps/desktop/src/app/DesktopPreReadyPlatform.ts, apps/desktop/src/app/DesktopPreReadyPlatform.test.ts	Linux pre-ready setup copies changed AppImage icons, skips matching destinations, refreshes gtk-update-icon-cache, and completes copies before asynchronous layer work. Installation failures remain nonfatal.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Priority: ➖ Normal

Severity of issue fixed: Low

Merge Risk: ⚪ Minimal · up to fc4ce

Linux AppImage startup now installs the lowercase desktop identity and icon aliases needed for Wayland compositor icon lookup. The desktop-entry and icon-copy behavior are covered, with no current merge-blocking risk identified.

Suggested reviewers: bil0000, juliusmarminge

Sequence Diagram(s)

sequenceDiagram
  participant DesktopPreReadyPlatform
  participant linuxDesktopIconInstallOperations
  participant APPDIR
  participant UserHicolorTree
  participant gtk-update-icon-cache
  DesktopPreReadyPlatform->>linuxDesktopIconInstallOperations: Build icon installation operations
  linuxDesktopIconInstallOperations-->>DesktopPreReadyPlatform: Return packaged and user icon paths
  DesktopPreReadyPlatform->>APPDIR: Read packaged icon metadata
  DesktopPreReadyPlatform->>UserHicolorTree: Copy changed icons
  DesktopPreReadyPlatform->>gtk-update-icon-cache: Refresh the icon cache

Loading

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 22.22% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 9 functions across 19 files.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Linked Issues check	✅ Passed	The changes satisfy issue #10894 by updating the Wayland app ID, adding Icon=t3code, and copying packaged hicolor icons into the user icon theme.
Out of Scope Changes check	✅ Passed	The changes remain focused on Linux desktop integration. Identifier updates in related runtime code, tests, documentation, and GNOME integration support the stated objectives.
Title check	✅ Passed	The title clearly identifies the two intended changes: restoring Linux icons and fixing GNOME dock pinning. It is concise and relevant to the pull request objectives.
Description check	✅ Passed	The description includes the required What Changed, Why, UI Changes, and Checklist sections. It explains the problem, implementation, testing, limitations, and screenshot status. The description is su…

• Fix all pre-merge checks with AI

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

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

[cursor]

Bugbot is paused — on-demand spend limit reached

Bugbot uses usage-based billing for this team and has hit its on-demand spend limit.

A team admin can raise the spend limit in the Cursor dashboard, or wait for the next billing cycle to continue.

Dismissing prior approval to re-evaluate fc4ce90

[cursor]

Bugbot is paused — on-demand spend limit reached

Bugbot uses usage-based billing for this team and has hit its on-demand spend limit.

A team admin can raise the spend limit in the Cursor dashboard, or wait for the next billing cycle to continue.

[eliath]

Reproduced on Ubuntu GNOME/X11 with nightly AppImage 0.0.41-nightly.20260911.1551

The root cause mentioned here matches my investigation: the generated com.t3tools.T3Code.desktop is rewritten on each launch without Icon=. This change fixes it.

[denniskasper]

Built and tested this branch on GNOME 46 with an AppImage. One finding.

Ubuntu 24.04.5, GNOME Shell 46.0 on X11, Ubuntu Dock v90. I fetched the PR head, rebased onto current main (d7819c1881, clean — your base was 12 days back), built the Linux AppImage, and launched it with an isolated HOME so it could not touch my daily install.

Everything the PR claims, it does. The entry it wrote carries Icon=t3code, and both names land in the theme:

hicolor/256x256/apps/t3code.png                20991
hicolor/256x256/apps/com.t3tools.t3code.png    20991
hicolor/icon-theme.cache                       160

GTK resolves them, so this is not just files in the right place:

t3code             -> …/hicolor/256x256/apps/t3code.png
com.t3tools.t3code -> …/hicolor/256x256/apps/com.t3tools.t3code.png
com.t3tools.T3Code -> NOT FOUND

The finding is that third line. The window's identity is mixed-case com.t3tools.T3Code (WM_CLASS = "com.t3tools.t3code", "com.t3tools.T3Code"), but linuxDesktopIconNames lowercases before installing. Icon theme lookups are case-sensitive, so a shell that uses the literal app id as an icon name — rather than lowercasing it like Noctalia, or resolving through the desktop file like GNOME — still finds nothing. Adding the un-lowercased name looks like a one-line change.

Scope limits, so this isn't read as more than it is: the isolated HOME means GNOME's own dash never saw these files, so I did not verify pinning or favorites, only that the files are installed and resolvable. X11, not Wayland. I also did not test AppImageLauncher re-integration.

Separately: _NET_WM_ICON on the main window is present but empty, on this build and on the released one. The window carries no icon of its own, so the entry and theme are doing all the work. Possibly relevant for X11 shells that prefer the window property.

I hit this bug independently before finding #10894 and reached the same diagnosis.

Prepared with Claude Opus 5 via Claude Code.