Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Known Limitations and Design Debt

This chapter documents known architectural limitations and design tradeoffs. Understanding these helps contributors make informed decisions and avoid re-discovering known issues.

Issue: Context menus currently use a fullscreen transparent overlay surface. This has several drawbacks:

  • Memory waste: ~140 MB VRAM per 4K monitor for a transparent surface
  • Layering bugs: The overlay doesn’t correctly layer popups on top of other windows in all cases
  • Conflicts: Can interfere with other layer surfaces on the Background layer

Correct approach: Use zwlr_layer_surface_v1::get_popup to create proper xdg_popup surfaces. However, iced_layershell does not currently expose this.

Workaround: The current fullscreen overlay approach was also chosen because iced has a HiDPI scaling regression where newly created surfaces initially render blurry.

Related: GitHub Issue #491

Memory Usage

Issue: ashell’s process RSS (total memory) is 100–300 MB, despite the application heap being only ~3.5 MB.

Breakdown (from DHAT profiling):

  • Font system (fontdb + cosmic_text): ~59% of peak heap
  • Shader compilation (naga/wgpu): ~16%
  • A bare wgpu application uses >50 MB RSS

Factors that increase usage:

  • High-refresh-rate monitors (reported: 300 MB on a 240 Hz 49“ ultra-wide)
  • Multiple monitors
  • Complex bar configurations with many modules

Possible improvements:

  • Adding a tiny-skia CPU renderer could reduce RAM by ~80 MB (at the cost of CPU usage and battery)
  • Users can set renderer.backend = "egl" in the iced configuration as a partial workaround

Related: GitHub Issue #529

Services Refactoring

Issue: The service layer has inconsistencies across different services. Some use broadcast channels, others use mpsc. Error handling patterns vary.

Status: This is an ongoing refactoring effort tracked in GitHub Issue #445. The network service is the most problematic, with unreliable WiFi scanning and incompatible architectural patterns between the NetworkManager and IWD backends.

No Test Suite

Issue: The project currently has no automated test suite. The UI is tested manually, and services are verified by running ashell on real hardware.

Impact: Regressions can slip through, especially for compositor-specific behavior (Hyprland vs. Niri) or hardware-specific features (brightness, Bluetooth).

NVIDIA Compatibility

Issue: ashell can crash or fail to render on NVIDIA GPUs with the Niri compositor.

Workaround: Set the WGPU_BACKEND=gl environment variable to use the OpenGL backend instead of Vulkan.

Related: GitHub Issue #471

Icon Index Staleness

Issue: The XDG icon indexes in services/xdg_icons.rs (SYSTEM_ICON_NAMES, DESKTOP_ICON_INDEX) are built once via LazyLock and never rebuilt. Resolution results, including misses, are cached for the process lifetime.

Impact: Newly installed applications and runtime icon-theme changes are not picked up until ashell is restarted. This affects both the tray and the workspace window icons.

Why not fixed: Because the indexes are static within a session, invalidating the result cache alone changes nothing (re-resolution reads the same frozen data), and dropping negative cache entries would only re-run the expensive fuzzy scans on every event for the same result. A proper fix means making the indexes rebuildable (a periodic or event-driven refresh), which is disproportionate to the payoff for a status bar.