trcc-linux 8.2.3__tar.gz → 8.2.5__tar.gz

{trcc_linux-8.2.3 → trcc_linux-8.2.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: trcc-linux
-Version: 8.2.3
+Version: 8.2.5
 Summary: Linux implementation of Thermalright LCD Control Center
 Project-URL: Homepage, https://github.com/Lexonight1/thermalright-trcc-linux
 Project-URL: Documentation, https://github.com/Lexonight1/thermalright-trcc-linux#readme
@@ -69,7 +69,7 @@ Description-Content-Type: text/markdown
 [![Platform](https://img.shields.io/badge/platform-Linux-FCC624?logo=linux&logoColor=black)](https://github.com/Lexonight1/thermalright-trcc-linux)
 
 [![CI](https://github.com/Lexonight1/thermalright-trcc-linux/actions/workflows/ci.yml/badge.svg)](https://github.com/Lexonight1/thermalright-trcc-linux/actions/workflows/ci.yml)
-[![Tests](https://img.shields.io/badge/tests-4105_passed-brightgreen.svg)](https://github.com/Lexonight1/thermalright-trcc-linux/actions/workflows/ci.yml)
+[![Tests](https://img.shields.io/badge/tests-4116_passed-brightgreen.svg)](https://github.com/Lexonight1/thermalright-trcc-linux/actions/workflows/ci.yml)
 [![Coverage](https://img.shields.io/badge/coverage-70%25-brightgreen.svg)](https://github.com/Lexonight1/thermalright-trcc-linux/actions/workflows/ci.yml)
 [![Python](https://img.shields.io/badge/python-3.9%2B-blue.svg)](https://python.org)
 [![Code Style](https://img.shields.io/badge/code_style-ruff-D7FF64?logo=ruff&logoColor=black)](https://docs.astral.sh/ruff/)
@@ -99,7 +99,7 @@ Description-Content-Type: text/markdown
 [![Buy Me a Beer](https://img.shields.io/badge/Buy_Me_a_Beer-🍺-FF5F5F?style=flat)](https://buymeacoffee.com/Lexonight1)
 [![Ko-fi](https://img.shields.io/badge/Ko--fi-☕-FF5E5B?style=flat&logo=kofi&logoColor=white)](https://ko-fi.com/lexonight1)
 
-> Huge thanks to **[@javisaman](https://github.com/javisaman)**, **[@Xentrino](https://github.com/Xentrino)**, **[@loosethoughts19-hash](https://github.com/loosethoughts19-hash)**, **[@Mr-Renegade](https://github.com/Mr-Renegade)**, and **[@Reborn627](https://github.com/Reborn627)** for the beers — you guys are legends.
+> Huge thanks to **[@javisaman](https://github.com/javisaman)**, **[@Xentrino](https://github.com/Xentrino)**, **[@loosethoughts19-hash](https://github.com/loosethoughts19-hash)**, **[@Mr-Renegade](https://github.com/Mr-Renegade)**, **[@Reborn627](https://github.com/Reborn627)**, and **[@knappstar](https://github.com/knappstar)** for the beers — you guys are legends.
 
 Native Linux port of the Thermalright LCD Control Center (Windows TRCC 2.1.2). Control and customize the LCD displays and LED segment displays on Thermalright CPU coolers, AIO pump heads, and fan hubs — entirely from Linux.
 
@@ -328,6 +328,7 @@ curl -X POST http://localhost:9876/led/color \
 |----------|-------------|
 | [Install Guide](doc/INSTALL_GUIDE.md) | Installation for all major distros |
 | [CLI Reference](doc/CLI_REFERENCE.md) | All CLI commands with options and examples |
+| [API Reference](doc/API_REFERENCE.md) | All 43 REST API endpoints with request/response models |
 | [Troubleshooting](doc/TROUBLESHOOTING.md) | Common issues and fixes |
 | [New to Linux](doc/NEW_TO_LINUX.md) | Guide for Linux beginners |
 | [Changelog](doc/CHANGELOG.md) | Version history |
@@ -413,7 +414,7 @@ A big thanks to everyone who has contributed invaluable reports to this project:
 
 Thanks to everyone who took a moment to star this project — it means the world.
 
-**[alessa-lara](https://github.com/alessa-lara)** · **[ArcaneCoder404](https://github.com/ArcaneCoder404)** · **[betolink](https://github.com/betolink)** · **[bive242](https://github.com/bive242)** · **[BrunoLeguizamon05](https://github.com/BrunoLeguizamon05)** · **[cancos1](https://github.com/cancos1)** · **[codeflitting](https://github.com/codeflitting)** · **[dabombUSA](https://github.com/dabombUSA)** · **[damachine](https://github.com/damachine)** · **[emaspa](https://github.com/emaspa)** · **[honjow](https://github.com/honjow)** · **[jezzaw007](https://github.com/jezzaw007)** · **[jhlasnik](https://github.com/jhlasnik)** · **[jmo808](https://github.com/jmo808)** · **[mgaruccio](https://github.com/mgaruccio)** · **[michael-spinelli](https://github.com/michael-spinelli)** · **[mkogut](https://github.com/mkogut)** · **[nathanielhernandez](https://github.com/nathanielhernandez)** · **[oddajpierscien](https://github.com/oddajpierscien)** · **[Pewful2021](https://github.com/Pewful2021)** · **[Pikarz](https://github.com/Pikarz)** · **[Rehaell](https://github.com/Rehaell)** · **[rslater](https://github.com/rslater)** · **[Smokemic](https://github.com/Smokemic)** · **[spiritofjon](https://github.com/spiritofjon)** · **[Vydon](https://github.com/Vydon)** · **[Xentrino](https://github.com/Xentrino)** · **[Ziusz](https://github.com/Ziusz)**
+**[alessa-lara](https://github.com/alessa-lara)** · **[ArcaneCoder404](https://github.com/ArcaneCoder404)** · **[betolink](https://github.com/betolink)** · **[bive242](https://github.com/bive242)** · **[BrunoLeguizamon05](https://github.com/BrunoLeguizamon05)** · **[cancos1](https://github.com/cancos1)** · **[codeflitting](https://github.com/codeflitting)** · **[dabombUSA](https://github.com/dabombUSA)** · **[damachine](https://github.com/damachine)** · **[emaspa](https://github.com/emaspa)** · **[honjow](https://github.com/honjow)** · **[jezzaw007](https://github.com/jezzaw007)** · **[jhlasnik](https://github.com/jhlasnik)** · **[jmo808](https://github.com/jmo808)** · **[knappstar](https://github.com/knappstar)** · **[mgaruccio](https://github.com/mgaruccio)** · **[michael-spinelli](https://github.com/michael-spinelli)** · **[mkogut](https://github.com/mkogut)** · **[nathanielhernandez](https://github.com/nathanielhernandez)** · **[oddajpierscien](https://github.com/oddajpierscien)** · **[Pewful2021](https://github.com/Pewful2021)** · **[Pikarz](https://github.com/Pikarz)** · **[Rehaell](https://github.com/Rehaell)** · **[rslater](https://github.com/rslater)** · **[Smokemic](https://github.com/Smokemic)** · **[spiritofjon](https://github.com/spiritofjon)** · **[Vydon](https://github.com/Vydon)** · **[Xentrino](https://github.com/Xentrino)** · **[Ziusz](https://github.com/Ziusz)**
 
 ## Faulkers
 

{trcc_linux-8.2.3 → trcc_linux-8.2.5}/README.md

@@ -10,7 +10,7 @@
 [![Platform](https://img.shields.io/badge/platform-Linux-FCC624?logo=linux&logoColor=black)](https://github.com/Lexonight1/thermalright-trcc-linux)
 
 [![CI](https://github.com/Lexonight1/thermalright-trcc-linux/actions/workflows/ci.yml/badge.svg)](https://github.com/Lexonight1/thermalright-trcc-linux/actions/workflows/ci.yml)
-[![Tests](https://img.shields.io/badge/tests-4105_passed-brightgreen.svg)](https://github.com/Lexonight1/thermalright-trcc-linux/actions/workflows/ci.yml)
+[![Tests](https://img.shields.io/badge/tests-4116_passed-brightgreen.svg)](https://github.com/Lexonight1/thermalright-trcc-linux/actions/workflows/ci.yml)
 [![Coverage](https://img.shields.io/badge/coverage-70%25-brightgreen.svg)](https://github.com/Lexonight1/thermalright-trcc-linux/actions/workflows/ci.yml)
 [![Python](https://img.shields.io/badge/python-3.9%2B-blue.svg)](https://python.org)
 [![Code Style](https://img.shields.io/badge/code_style-ruff-D7FF64?logo=ruff&logoColor=black)](https://docs.astral.sh/ruff/)
@@ -40,7 +40,7 @@
 [![Buy Me a Beer](https://img.shields.io/badge/Buy_Me_a_Beer-🍺-FF5F5F?style=flat)](https://buymeacoffee.com/Lexonight1)
 [![Ko-fi](https://img.shields.io/badge/Ko--fi-☕-FF5E5B?style=flat&logo=kofi&logoColor=white)](https://ko-fi.com/lexonight1)
 
-> Huge thanks to **[@javisaman](https://github.com/javisaman)**, **[@Xentrino](https://github.com/Xentrino)**, **[@loosethoughts19-hash](https://github.com/loosethoughts19-hash)**, **[@Mr-Renegade](https://github.com/Mr-Renegade)**, and **[@Reborn627](https://github.com/Reborn627)** for the beers — you guys are legends.
+> Huge thanks to **[@javisaman](https://github.com/javisaman)**, **[@Xentrino](https://github.com/Xentrino)**, **[@loosethoughts19-hash](https://github.com/loosethoughts19-hash)**, **[@Mr-Renegade](https://github.com/Mr-Renegade)**, **[@Reborn627](https://github.com/Reborn627)**, and **[@knappstar](https://github.com/knappstar)** for the beers — you guys are legends.
 
 Native Linux port of the Thermalright LCD Control Center (Windows TRCC 2.1.2). Control and customize the LCD displays and LED segment displays on Thermalright CPU coolers, AIO pump heads, and fan hubs — entirely from Linux.
 
@@ -269,6 +269,7 @@ curl -X POST http://localhost:9876/led/color \
 |----------|-------------|
 | [Install Guide](doc/INSTALL_GUIDE.md) | Installation for all major distros |
 | [CLI Reference](doc/CLI_REFERENCE.md) | All CLI commands with options and examples |
+| [API Reference](doc/API_REFERENCE.md) | All 43 REST API endpoints with request/response models |
 | [Troubleshooting](doc/TROUBLESHOOTING.md) | Common issues and fixes |
 | [New to Linux](doc/NEW_TO_LINUX.md) | Guide for Linux beginners |
 | [Changelog](doc/CHANGELOG.md) | Version history |
@@ -354,7 +355,7 @@ A big thanks to everyone who has contributed invaluable reports to this project:
 
 Thanks to everyone who took a moment to star this project — it means the world.
 
-**[alessa-lara](https://github.com/alessa-lara)** · **[ArcaneCoder404](https://github.com/ArcaneCoder404)** · **[betolink](https://github.com/betolink)** · **[bive242](https://github.com/bive242)** · **[BrunoLeguizamon05](https://github.com/BrunoLeguizamon05)** · **[cancos1](https://github.com/cancos1)** · **[codeflitting](https://github.com/codeflitting)** · **[dabombUSA](https://github.com/dabombUSA)** · **[damachine](https://github.com/damachine)** · **[emaspa](https://github.com/emaspa)** · **[honjow](https://github.com/honjow)** · **[jezzaw007](https://github.com/jezzaw007)** · **[jhlasnik](https://github.com/jhlasnik)** · **[jmo808](https://github.com/jmo808)** · **[mgaruccio](https://github.com/mgaruccio)** · **[michael-spinelli](https://github.com/michael-spinelli)** · **[mkogut](https://github.com/mkogut)** · **[nathanielhernandez](https://github.com/nathanielhernandez)** · **[oddajpierscien](https://github.com/oddajpierscien)** · **[Pewful2021](https://github.com/Pewful2021)** · **[Pikarz](https://github.com/Pikarz)** · **[Rehaell](https://github.com/Rehaell)** · **[rslater](https://github.com/rslater)** · **[Smokemic](https://github.com/Smokemic)** · **[spiritofjon](https://github.com/spiritofjon)** · **[Vydon](https://github.com/Vydon)** · **[Xentrino](https://github.com/Xentrino)** · **[Ziusz](https://github.com/Ziusz)**
+**[alessa-lara](https://github.com/alessa-lara)** · **[ArcaneCoder404](https://github.com/ArcaneCoder404)** · **[betolink](https://github.com/betolink)** · **[bive242](https://github.com/bive242)** · **[BrunoLeguizamon05](https://github.com/BrunoLeguizamon05)** · **[cancos1](https://github.com/cancos1)** · **[codeflitting](https://github.com/codeflitting)** · **[dabombUSA](https://github.com/dabombUSA)** · **[damachine](https://github.com/damachine)** · **[emaspa](https://github.com/emaspa)** · **[honjow](https://github.com/honjow)** · **[jezzaw007](https://github.com/jezzaw007)** · **[jhlasnik](https://github.com/jhlasnik)** · **[jmo808](https://github.com/jmo808)** · **[knappstar](https://github.com/knappstar)** · **[mgaruccio](https://github.com/mgaruccio)** · **[michael-spinelli](https://github.com/michael-spinelli)** · **[mkogut](https://github.com/mkogut)** · **[nathanielhernandez](https://github.com/nathanielhernandez)** · **[oddajpierscien](https://github.com/oddajpierscien)** · **[Pewful2021](https://github.com/Pewful2021)** · **[Pikarz](https://github.com/Pikarz)** · **[Rehaell](https://github.com/Rehaell)** · **[rslater](https://github.com/rslater)** · **[Smokemic](https://github.com/Smokemic)** · **[spiritofjon](https://github.com/spiritofjon)** · **[Vydon](https://github.com/Vydon)** · **[Xentrino](https://github.com/Xentrino)** · **[Ziusz](https://github.com/Ziusz)**
 
 ## Faulkers
 

{trcc_linux-8.2.3 → trcc_linux-8.2.5}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "trcc-linux"
-version = "8.2.3"
+version = "8.2.5"
 description = "Linux implementation of Thermalright LCD Control Center"
 readme = "README.md"
 license = "GPL-3.0-or-later"

{trcc_linux-8.2.3 → trcc_linux-8.2.5}/src/trcc/__version__.py

@@ -1,4 +1,4 @@
 """TRCC Linux version information. History in doc/CHANGELOG.md."""
 
-__version__ = "8.2.3"
+__version__ = "8.2.5"
 __version_info__ = tuple(int(x) for x in __version__.split("."))

{trcc_linux-8.2.3 → trcc_linux-8.2.5}/src/trcc/adapters/infra/data_repository.py

@@ -21,9 +21,10 @@ import shutil
 import subprocess
 from typing import List, Optional
 
-from ...core.models import ThemeDir  # re-export for back-compat
+from ...core.models import ThemeDir  # noqa: F401 — re-export for back-compat
 from ...core.paths import (
     ASSETS_DIR,  # noqa: F401 — re-export
+    DATA_DIR,  # noqa: F401 — re-export
     RESOURCES_DIR,  # noqa: F401 — re-export
     USER_CONFIG_DIR,  # noqa: F401 — re-export
     USER_DATA_DIR,  # noqa: F401 — re-export
@@ -132,8 +133,6 @@ def _find_pkg_data_dir() -> str:
 # All runtime data goes to ~/.trcc/data/ — always writable, works on
 # pip, pipx, pacman, dnf, apt installs. No read-only pkg_dir issues.
 _PKG_DATA_DIR = _find_pkg_data_dir()
-DATA_DIR = USER_DATA_DIR
-THEMES_DIR = DATA_DIR
 
 RESOURCE_SEARCH_PATHS = [RESOURCES_DIR]
 
@@ -449,30 +448,17 @@ class DataManager:
     # Directory resolution
     # ------------------------------------------------------------------
 
-    @staticmethod
-    def _resolve_web_subdir(res_key: str, check_fn=None) -> str:
-        """Resolve a web subdirectory, preferring pkg_dir if it has content.
-
-        Falls back to user_dir (always writable — safe on system-wide installs).
-        """
-        if check_fn is None:
-            check_fn = DataManager._has_any_content
-        pkg_dir = os.path.join(DATA_DIR, 'web', res_key)
-        if check_fn(pkg_dir):
-            return pkg_dir
-        return os.path.join(USER_DATA_DIR, 'web', res_key)
-
     @staticmethod
     def get_web_dir(width: int, height: int) -> str:
         """Get cloud theme Web directory for a resolution."""
-        return DataManager._resolve_web_subdir(f'{width}{height}')
+        from ...core.paths import get_web_dir
+        return get_web_dir(width, height)
 
     @staticmethod
     def get_web_masks_dir(width: int, height: int) -> str:
         """Get cloud masks directory for a resolution."""
-        return DataManager._resolve_web_subdir(
-            f'zt{width}{height}', check_fn=ThemeDir.has_themes,
-        )
+        from ...core.paths import get_web_masks_dir
+        return get_web_masks_dir(width, height)
 
 
 # =========================================================================

{trcc_linux-8.2.3 → trcc_linux-8.2.5}/src/trcc/cli/_system.py

@@ -3,6 +3,7 @@ from __future__ import annotations
 
 import os
 import shlex
+import shutil
 import site
 import subprocess
 import sys
@@ -274,7 +275,6 @@ def setup_selinux():
     Required on SELinux-enforcing systems (Bazzite, Silverblue) where
     detach_kernel_driver() is silently blocked.
     """
-    import shutil
     import tempfile
 
     # Must be root
@@ -331,12 +331,11 @@ def setup_selinux():
     # Compile and install in temp directory
     try:
         with tempfile.TemporaryDirectory() as tmp:
-            import shutil as sh
             te_path = os.path.join(tmp, 'trcc_usb.te')
             mod_path = os.path.join(tmp, 'trcc_usb.mod')
             pp_path = os.path.join(tmp, 'trcc_usb.pp')
 
-            sh.copy2(te_src, te_path)
+            shutil.copy2(te_src, te_path)
 
             # checkmodule -M -m -o trcc_usb.mod trcc_usb.te
             r = subprocess.run(
@@ -379,8 +378,6 @@ def install_desktop():
     Reads the shipped .desktop file from the package assets directory.
     Works from both pip install and git clone.
     """
-    import shutil
-
     home = Path.home()
     app_dir = home / ".local" / "share" / "applications"
 
@@ -437,8 +434,6 @@ def setup_polkit():
     active desktop sessions can run dmidecode and smartctl without a
     password prompt. Requires root.
     """
-    import shutil
-
     if os.geteuid() != 0:
         return _sudo_reexec("setup-polkit")
 
@@ -494,9 +489,37 @@ def setup_polkit():
     return 0
 
 
+def _detect_install_method() -> str:
+    """Detect how trcc-linux was installed.
+
+    Returns 'pipx', 'pip', 'pacman', 'dnf', or 'apt'.
+    """
+    if 'pipx' in sys.prefix:
+        return 'pipx'
+    try:
+        from importlib.metadata import distribution
+        dist = distribution('trcc-linux')
+        installer = (dist.read_text('INSTALLER') or '').strip()
+        if installer == 'pip':
+            return 'pip'
+    except Exception:
+        pass
+    for mgr in ('pacman', 'dnf', 'apt'):
+        if shutil.which(mgr):
+            return mgr
+    return 'pip'
+
+
+def _is_externally_managed() -> bool:
+    """Check if the Python environment has PEP 668 EXTERNALLY-MANAGED marker."""
+    # The marker file lives next to the stdlib, e.g.
+    # /usr/lib/python3.12/EXTERNALLY-MANAGED
+    stdlib = Path(os.__file__).parent
+    return (stdlib / "EXTERNALLY-MANAGED").exists()
+
+
 def uninstall(*, yes: bool = False):
     """Remove all TRCC config, udev rules, autostart, and desktop files."""
-    import shutil
 
     from trcc.conf import Settings
 
@@ -560,12 +583,37 @@ def uninstall(*, yes: bool = False):
         subprocess.run(["udevadm", "control", "--reload-rules"], check=False)
         subprocess.run(["udevadm", "trigger"], check=False)
 
-    # Uninstall the pip package itself
-    print("\nUninstalling trcc-linux pip package...")
-    pip_cmd = [sys.executable, "-m", "pip", "uninstall", "trcc-linux"]
-    if yes:
-        pip_cmd.append("--yes")
-    subprocess.run(pip_cmd, check=False)
+    # Detect install method and uninstall the package accordingly
+    install_info = Settings.get_install_info()
+    method = install_info.get('method', _detect_install_method())
+
+    if method in ('pacman', 'dnf', 'apt'):
+        # System package — tell user to remove via their package manager
+        pkg_cmds = {
+            'pacman': 'sudo pacman -R trcc-linux',
+            'dnf': 'sudo dnf remove trcc-linux',
+            'apt': 'sudo apt remove trcc-linux',
+        }
+        print(f"\nInstalled via {method} — remove with:")
+        print(f"  {pkg_cmds[method]}")
+    elif method == 'pipx':
+        print("\nUninstalling trcc-linux via pipx...")
+        subprocess.run(["pipx", "uninstall", "trcc-linux"], check=False)
+    else:
+        # pip install — may need --break-system-packages on PEP 668 distros
+        print("\nUninstalling trcc-linux pip package...")
+        pip_cmd = [sys.executable, "-m", "pip", "uninstall", "trcc-linux"]
+        if yes:
+            pip_cmd.append("--yes")
+        if _is_externally_managed():
+            pip_cmd.append("--break-system-packages")
+        subprocess.run(pip_cmd, check=False)
+
+    # Clean stale shadow binary from old pip/pipx installs
+    stale_bin = Path.home() / ".local" / "bin" / "trcc"
+    if stale_bin.exists():
+        stale_bin.unlink()
+        print(f"Removed stale binary: {stale_bin}")
 
     return 0
 

{trcc_linux-8.2.3 → trcc_linux-8.2.5}/src/trcc/conf.py

@@ -33,9 +33,8 @@ from pathlib import Path
 from typing import Optional
 
 from .__version__ import __version__
-from .adapters.infra.data_repository import DataManager, ThemeDir
-from .core.models import LOCALE_TO_LANG
-from .core.paths import USER_CONFIG_DIR, USER_DATA_DIR
+from .core.models import LOCALE_TO_LANG, ThemeDir
+from .core.paths import USER_CONFIG_DIR, USER_DATA_DIR, get_web_dir, get_web_masks_dir
 
 log = logging.getLogger(__name__)
 
@@ -408,8 +407,8 @@ class Settings:
         """Resolve theme/web/mask directories for current resolution."""
         w, h = self._width, self._height
         self.theme_dir = ThemeDir.for_resolution(w, h)
-        self.web_dir = Path(DataManager.get_web_dir(w, h))
-        self.masks_dir = Path(DataManager.get_web_masks_dir(w, h))
+        self.web_dir = Path(get_web_dir(w, h))
+        self.masks_dir = Path(get_web_masks_dir(w, h))
 
     def resolve_cloud_dirs(self, rotation: int = 0) -> None:
         """Re-resolve cloud background/mask dirs for rotation.
@@ -421,8 +420,8 @@ class Settings:
         w, h = self._width, self._height
         if w != h and rotation in (90, 270):
             w, h = h, w
-        self.web_dir = Path(DataManager.get_web_dir(w, h))
-        self.masks_dir = Path(DataManager.get_web_masks_dir(w, h))
+        self.web_dir = Path(get_web_dir(w, h))
+        self.masks_dir = Path(get_web_masks_dir(w, h))
 
 
 # Module-level singleton — import and use directly

{trcc_linux-8.2.3 → trcc_linux-8.2.5}/src/trcc/core/models.py

@@ -177,7 +177,7 @@ class ThemeDir:
 
         Lazy-imports infrastructure constants from data_repository.
         """
-        from ..adapters.infra.data_repository import DATA_DIR, USER_DATA_DIR
+        from .paths import DATA_DIR, USER_DATA_DIR
         name = f'theme{width}{height}'
         user_dir = os.path.join(USER_DATA_DIR, name)
         if cls.has_themes(user_dir):

trcc_linux-8.2.5/src/trcc/core/paths.py

@@ -0,0 +1,74 @@
+"""Application path constants and directory resolution — single source of truth.
+
+Zero project imports. Safe to import from any module without circular deps.
+"""
+from __future__ import annotations
+
+import os
+
+# Navigate from core/ back to the trcc package root
+_TRCC_PKG = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+
+# Asset directories (inside trcc package)
+ASSETS_DIR = os.path.join(_TRCC_PKG, 'assets')
+RESOURCES_DIR = os.path.join(ASSETS_DIR, 'gui')
+
+# User config directory (~/.trcc/)
+USER_CONFIG_DIR = os.path.expanduser('~/.trcc')
+USER_DATA_DIR = os.path.join(USER_CONFIG_DIR, 'data')
+
+# Runtime data directory — always writable (~/.trcc/data/)
+DATA_DIR = USER_DATA_DIR
+
+
+# =========================================================================
+# Directory resolution — pure path logic, no I/O beyond os.path/os.listdir
+# =========================================================================
+
+def _has_any_content(d: str) -> bool:
+    """Check if a directory exists and has any files/subdirs."""
+    return os.path.isdir(d) and bool(os.listdir(d))
+
+
+def _has_themes(theme_dir: str) -> bool:
+    """Check if a directory contains valid theme subdirectories with PNGs.
+
+    Mirrors ThemeDir.has_themes — duplicated here to avoid circular import
+    with core/models.py (ThemeDir.for_resolution imports from this module).
+    """
+    if not os.path.isdir(theme_dir):
+        return False
+    for item in os.listdir(theme_dir):
+        item_path = os.path.join(theme_dir, item)
+        if (os.path.isdir(item_path)
+                and not item.startswith('.')
+                and not item.startswith('Custom_')):
+            if any(f.endswith('.png') for f in os.listdir(item_path)):
+                return True
+    return False
+
+
+def _resolve_web_subdir(
+    res_key: str,
+    check_fn: object = None,
+) -> str:
+    """Resolve a web subdirectory, preferring pkg_dir if it has content.
+
+    Falls back to user_dir (always writable — safe on system-wide installs).
+    """
+    if check_fn is None:
+        check_fn = _has_any_content
+    pkg_dir = os.path.join(DATA_DIR, 'web', res_key)
+    if check_fn(pkg_dir):  # type: ignore[operator]
+        return pkg_dir
+    return os.path.join(USER_DATA_DIR, 'web', res_key)
+
+
+def get_web_dir(width: int, height: int) -> str:
+    """Get cloud theme Web directory for a resolution."""
+    return _resolve_web_subdir(f'{width}{height}')
+
+
+def get_web_masks_dir(width: int, height: int) -> str:
+    """Get cloud masks directory for a resolution."""
+    return _resolve_web_subdir(f'zt{width}{height}', check_fn=_has_themes)