fix(desktop): Install lowercase Linux icons for Wayland overview

[mwolson]

What Changed

Linux AppImage windows keep the T3 icon in niri and Noctalia overview after a Shelly or AppImageLauncher reinstall.

Fixes #10894 linux-wayland-desktop-icon.

Why

Those shells look up the running window by its Wayland app id, then resolve Icon= and a lowercased id through the icon theme. They do not use the window pixmap. The hidden URL-handler file now has Icon=t3code, and startup copies one 256px t3code icon plus a com.t3tools.t3code alias into the user theme when dest size differs. Qt, GTK, Omarchy, Noctalia, and Dank Material Shell scale that raster. The Wayland id stays com.t3tools.T3Code, so existing niri and Hyprland capture binds keep working.

Copies stay synchronous in pre-ready setup so Electron does not become ready before Clerk registers URL schemes. They skip files that are already the right size so a normal launch is not extra disk work. Icon-cache refresh runs in the background after a real copy so a stuck helper cannot hold the app at startup. The PNGs are on disk before that refresh, so overview can still resolve them if the cache lags.

UI Changes

Overview and workspace tiles should show the T3 icon after an AppImage reinstall. No in-app UI change. This PR does not include screenshots.

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 — The PR adds synchronous Linux startup filesystem work and a detached icon-cache process, alongside new desktop-entry icon behavior. It also introduces a file-level suppression for the global-timers static-analysis diagnostic, so the change warrants human review.

^{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 describes the primary icon-installation change for Linux Wayland overviews. It is concise and specific.
Description check	✅ Passed	The description includes all required sections and explains the change, motivation, UI impact, and checklist status. However, it states that the Wayland ID remains com.t3tools.T3Code, which conflict…

• 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.