trcc-linux 9.7.9__tar.gz → 9.8.0__tar.gz

{trcc_linux-9.7.9 → trcc_linux-9.8.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: trcc-linux
-Version: 9.7.9
+Version: 9.8.0
 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

{trcc_linux-9.7.9 → trcc_linux-9.8.0}/pyproject.toml

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

{trcc_linux-9.7.9 → trcc_linux-9.8.0}/src/trcc/__version__.py

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

{trcc_linux-9.7.9 → trcc_linux-9.8.0}/src/trcc/adapters/device/bulk_lcd.py

@@ -147,6 +147,7 @@ class BulkLcd(Device[BulkTransport]):
             width=base.width, height=base.height,
             jpeg=(self._pm not in _RGB565_PMS),
             big_endian=base.big_endian, rotate=base.rotate,
+            widescreen=base.widescreen,
             encode_baseline=encode_baseline,
             encode_base=encode_base, encode_invert=base.encode_invert,
             encode_sub_bases=(),  # folded into encode_base above

{trcc_linux-9.7.9 → trcc_linux-9.8.0}/src/trcc/adapters/system/_hotplug.py

@@ -108,6 +108,13 @@ def _import_dbus_glib() -> tuple[Any, Any] | None:
     log.debug("_import_dbus_glib: called")
     try:
         import dbus  # pyright: ignore[reportMissingImports]
+
+        # NOTE (investigated 2026-06-27): importing gi emits two
+        # DeprecationWarnings on Python 3.14 (GLib.unix_signal_add_full +
+        # asyncio event-loop policy) from PyGObject's OWN internals — not our
+        # calls.  Latest gi (3.56.3) still warns; our 3.12 floor is clean.
+        # Upstream + cosmetic, and this guarded import already degrades
+        # gracefully.  Leave it — don't filter blindly or monkeypatch gi.
         import gi  # noqa: F401  # pyright: ignore[reportMissingImports]
         from dbus.mainloop.glib import (  # pyright: ignore[reportMissingImports]
             DBusGMainLoop,

{trcc_linux-9.7.9 → trcc_linux-9.8.0}/src/trcc/adapters/system/_udev.py

@@ -17,9 +17,11 @@ Per-wire subsystem mapping:
 Every device also gets `power/control="auto"` +
 `power/autosuspend_delay_ms="10000"` so the kernel autosuspends the device
 ~10s after our frame stream stops; the firmware sleeps the panel in response
-to the USB suspend (the mechanism the Windows app relies on — #143).  This
-MUST match packaging/udev/99-trcc-lcd.rules — the two are the same rule from
-two sources and drifting them re-breaks panel sleep.
+to the USB suspend (the mechanism the Windows app relies on — #143).  The
+EXCEPTION is `_NO_AUTOSUSPEND` devices, whose firmware re-enumerates instead of
+sleeping under suspend (a reconnect loop — #201); they pin `power/control="on"`.
+This MUST match packaging/udev/99-trcc-lcd.rules — the two are the same rule
+from two sources and drifting them re-breaks panel sleep / the loop fix.
 
 For SCSI devices we additionally write /etc/modprobe.d/trcc-lcd.conf
 forcing `usb-storage` Bulk-Only (not UAS) so /dev/sgN is reliably
@@ -71,6 +73,19 @@ _WIRE_SUBSYSTEMS: dict[Wire, tuple[str, ...]] = {
 }
 
 
+# Devices whose firmware can't survive USB autosuspend.  The kernel suspends the
+# port ~10s after our frame stream stops; instead of sleeping the panel, these
+# re-enumerate, the kernel re-suspends ~10s later, and you get a reconnect loop
+# every ~10-15s (#201, em73es' ChiZhu GrandVision 360).  They pin
+# power/control="on" (never autosuspend) instead of the "auto" the other panels
+# use for idle-sleep (#143).  87ad:70db (USB/bulk) is reporter-confirmed;
+# 87cd:70db (its SCSI sibling, same product family) is included by inference.
+_NO_AUTOSUSPEND: frozenset[tuple[int, int]] = frozenset({
+    (0x87ad, 0x70db),
+    (0x87cd, 0x70db),
+})
+
+
 # ── Rule generation ──────────────────────────────────────────────────
 
 
@@ -95,11 +110,12 @@ def build_udev_rules() -> str:
                 f'{attr}{{idProduct}}=="{pid:04x}", '
                 f'MODE="0666"'
             )
+        control = "on" if (vid, pid) in _NO_AUTOSUSPEND else "auto"
         lines.append(
             f'ACTION=="add", SUBSYSTEM=="usb", '
             f'ATTR{{idVendor}}=="{vid:04x}", '
             f'ATTR{{idProduct}}=="{pid:04x}", '
-            f'ATTR{{power/control}}="auto", '
+            f'ATTR{{power/control}}="{control}", '
             f'ATTR{{power/autosuspend_delay_ms}}="10000"'
         )
         lines.append("")

{trcc_linux-9.7.9 → trcc_linux-9.8.0}/src/trcc/app.py

@@ -320,13 +320,26 @@ class App:
         # Active theme → reload from the rotated-resolution theme dir.  Shared
         # resolver with RestoreLastTheme so connect-restore + runtime rotation
         # agree on the oriented variant (#136).
+        #
+        # reset_overrides=False: a rotation re-roots the SAME theme to its
+        # oriented variant — it is NOT an explicit theme switch.  The original
+        # C# app rotates at the render layer and NEVER drops the user's overlay/
+        # background/mask edits on rotate; legacy's startup restore likewise
+        # re-applied them.  Resetting here (the old default=True) PERSIST-CLEARED
+        # user_overlay_elements + stopped video + reverted the cloud background —
+        # so on a connect/restart the user's "last preview with changes" was lost
+        # before RestoreLastTheme could replay it.  Preserve them; the dedicated
+        # cloud-background + mask reload blocks below still re-resolve those two
+        # to the oriented resolution.  (Catalog selection + encode are untouched,
+        # so the hardware-verified widescreen behavior in #169 is unaffected.)
         if s.current_theme:
             cur = Path(s.current_theme)
             cand = oriented_theme_path(self, key, cur, degrees=event.degrees)
             if cand != cur:
-                log.info("_on_orientation_changed: reload theme %s → %s",
-                         cur.name, cand)
-                self.dispatch(LoadTheme(key=key, path=cand))
+                log.info("_on_orientation_changed: reload theme %s → %s "
+                         "(preserve overrides)", cur.name, cand)
+                self.dispatch(LoadTheme(key=key, path=cand,
+                                        reset_overrides=False))
 
         # Active cloud background → re-apply from the rotated-resolution web dir.
         # Stored as ``web/{res}/<id>``; ``LoadCloudTheme`` now materialises per

{trcc_linux-9.7.9 → trcc_linux-9.8.0}/src/trcc/core/commands/_helpers.py

@@ -54,11 +54,19 @@ def oriented_theme_path(
         degrees = app.settings.for_device(key).orientation
     bw, bh = oriented_resolution(device.profile.resolution, degrees)
     paths = app.platform.paths()
-    for base in (paths.theme_dir(bw, bh), paths.user_theme_dir(bw, bh)):
-        cand = base / stored.name
-        if cand.exists():
-            return cand
-    return stored
+    # Re-root for ORIENTATION only — preserve the tree the user actually
+    # selected (their saved theme vs the shipped one).  A user-saved theme and
+    # a shipped theme can share a name (they coexist); re-resolving shipped-first
+    # would silently swap the user's last preview for the shipped default of the
+    # same name on every rotation/restore, losing their changes. Fall back to
+    # ``stored`` when the same-name oriented variant isn't on disk in that tree
+    # (the renderer pixel-rotates the art).
+    if stored.is_relative_to(paths.user_content_dir()):
+        base = paths.user_theme_dir(bw, bh)
+    else:
+        base = paths.theme_dir(bw, bh)
+    cand = base / stored.name
+    return cand if cand.exists() else stored
 
 
 _VIDEO_EXTS_FOR_SAVE = frozenset({".mp4", ".mov", ".webm", ".zt", ".mkv", ".avi"})
@@ -76,6 +84,9 @@ _MASK_IMAGE_EXTS = frozenset({".png", ".jpg", ".jpeg", ".bmp", ".webp"})
 _LEGACY_MASK_FILENAME = "01.png"
 
 
+_LEGACY_BG_FILENAME = "00.png"
+
+
 _IMAGE_EXTS = frozenset({".png", ".jpg", ".jpeg", ".bmp", ".webp"})
 
 
@@ -229,6 +240,11 @@ def _require_connected_device(app: App, key: str) -> Any:
     log.debug("_require_connected_device: key=%s", key)
     device = app.get(key)
     if not device.is_connected:
+        # DeviceNotConnectedError propagates PAST App.dispatch (no try/except
+        # there), so without this the rejected wire command is invisible in the
+        # log.  Warn with the key — the universal "acted before connect" trace.
+        log.warning("%s: wire command dispatched before ConnectDevice — "
+                    "device attached but not connected", key)
         raise DeviceNotConnectedError(
             f"{key} not connected — dispatch ConnectDevice first"
         )

{trcc_linux-9.7.9 → trcc_linux-9.8.0}/src/trcc/core/commands/device.py

@@ -980,6 +980,8 @@ class UploadBootAnimation(Command[BootAnimationResult]):
                 message=f"{self.key} is not a SCSI LCD (boot animation is SCSI-only)",
             )
         if not device.is_connected:
+            log.warning("UploadBootAnimation %s: device not connected — "
+                        "dispatched before ConnectDevice", self.key)
             raise DeviceNotConnectedError(
                 f"{self.key} not connected — dispatch ConnectDevice first"
             )
@@ -1088,7 +1090,7 @@ class SetBrightness(Command[BrightnessResult]):
         if not 0 <= self.percent <= 100:
             return BrightnessResult(
                 ok=False, key=self.key, percent=self.percent,
-                message="Brightness out of range (0–100)",
+                message=f"Brightness out of range (0–100): {self.percent}",
             )
         app.settings.set_brightness(self.key, self.percent)
         _invalidate_scene(app, self.key)

{trcc_linux-9.7.9 → trcc_linux-9.8.0}/src/trcc/core/commands/led.py

@@ -73,6 +73,8 @@ class SetLedColors(Command[LedColorsResult]):
                 message=f"{self.key} is not an LED device",
             )
         if not device.is_connected:
+            log.warning("SetLedColors %s: device not connected — "
+                        "dispatched before ConnectDevice", self.key)
             raise DeviceNotConnectedError(
                 f"{self.key} not connected — dispatch ConnectDevice first"
             )
@@ -184,6 +186,10 @@ class RenderLed(Command[LedColorsResult]):
                 message=f"{self.key} is not an LED device",
             )
         if not device.is_connected:
+            # Per-frame command (DEBUG) — not-connected here is a transient
+            # race with disconnect, not a user mis-step; keep it off INFO.
+            log.debug("RenderLed %s: device not connected — skipping frame",
+                      self.key)
             raise DeviceNotConnectedError(
                 f"{self.key} not connected — dispatch ConnectDevice first"
             )

{trcc_linux-9.7.9 → trcc_linux-9.8.0}/src/trcc/core/commands/theme.py

@@ -21,6 +21,7 @@ from ..events import (
     ThemeLoaded,
     ThemeSaved,
 )
+from ..geometry import content_is_portrait, plan_orientation
 from ..registry import find_product
 from ..results import (
     CloudCategoryEntry,
@@ -45,6 +46,7 @@ from ..results import (
 from ._base import Command
 from ._helpers import (
     _IMAGE_EXTS,
+    _LEGACY_BG_FILENAME,
     _LEGACY_MASK_FILENAME,
     _VIDEO_EXTS_FOR_LOAD,
     _VIDEO_EXTS_FOR_SAVE,
@@ -70,6 +72,17 @@ if TYPE_CHECKING:
 log = logging.getLogger(__name__)
 
 
+def _theme_preview(theme_dir: Path) -> str:
+    """Tile image for a theme dir: ``Theme.png`` → ``00.png`` → any ``*.png``
+    → ``""``.  Single source for the browser tile so every UI agrees."""
+    for name in ("Theme.png", "00.png"):
+        candidate = theme_dir / name
+        if candidate.is_file():
+            return str(candidate)
+    any_png = next(theme_dir.glob("*.png"), None)
+    return str(any_png) if any_png is not None else ""
+
+
 @dataclass(frozen=True, slots=True)
 class LoadTheme(Command[ThemeResult]):
     """Parse a theme, persist it, render the first frame, and send it.
@@ -377,7 +390,27 @@ class SaveTheme(Command[ThemeResult]):
                 message=(f"no active theme for {self.key} — load one first"),
             )
 
-        resolution = _resolve_oriented_resolution(app, self.key)
+        device_settings = app.settings.for_device(self.key)
+        # Save into the folder matching the COMPOSED orientation, not the raw
+        # angle — the content's parent folder IS the orientation.  A connected
+        # device carries its profile, so we key the resolution on the same
+        # plan_orientation decision the renderer uses: a portrait selection
+        # (portrait mask / portrait theme) → theme{h}{w}; landscape content →
+        # theme{w}{h}.  This makes save + reload agree — a theme always reloads
+        # into the orientation it was composed in.  Disconnected (no live
+        # profile) falls back to the angle-keyed resolution, unchanged.
+        device = app.devices.get(self.key)
+        profile = device.profile if device is not None else None
+        if profile is not None:
+            portrait = content_is_portrait(
+                theme, profile, device_settings.mask_path,
+                device_settings.mask_visible,
+            )
+            resolution = plan_orientation(
+                profile, device_settings.orientation, portrait,
+            ).canvas
+        else:
+            resolution = _resolve_oriented_resolution(app, self.key)
         if resolution is None:
             log.warning(
                 "SaveTheme: cannot resolve resolution for %s "
@@ -393,7 +426,6 @@ class SaveTheme(Command[ThemeResult]):
 
         import shutil
         target = app.platform.paths().user_theme_dir(w, h) / self.name
-        device_settings = app.settings.for_device(self.key)
         log.info(
             "SaveTheme: source=%s target=%s resolution=%dx%d "
             "bg_override=%r mask_override=%r user_elements=%d "
@@ -413,33 +445,57 @@ class SaveTheme(Command[ThemeResult]):
                 message=f"A theme named {self.name!r} already exists.",
             )
 
+        # Build into a staging dir, THEN atomically swap it over the target.
+        # The theme being saved is usually the target ITSELF (re-saving the
+        # loaded theme — a prior save re-points the active theme at the saved
+        # dir), so deleting the target up-front would destroy the source's own
+        # background/mask BEFORE _build_manifest reads them — the cause of the
+        # "source theme has no background" data loss.  Staging keeps the source
+        # intact until every asset is captured, and makes overwrite crash-safe.
+        staging = target.parent / f".{self.name}.saving"
         try:
             target.parent.mkdir(parents=True, exist_ok=True)
-            if target.exists():
-                log.warning("SaveTheme: overwriting existing theme %s", target)
-                shutil.rmtree(target)
-            target.mkdir(exist_ok=False)
+            if staging.exists():
+                shutil.rmtree(staging)
+            staging.mkdir(exist_ok=False)
         except OSError as e:
-            log.warning("SaveTheme: mkdir failed for %s: %s", target, e)
+            log.warning("SaveTheme: mkdir failed for staging %s: %s", staging, e)
             return ThemeResult(
                 ok=False, key=self.key, theme_name=self.name,
-                message=f"failed to create target directory: {e}",
+                message=f"failed to create staging directory: {e}",
             )
 
         try:
             manifest = self._build_manifest(
-                app, target, theme, device_settings, w, h,
+                app, staging, theme, device_settings, w, h,
             )
-            self._write_manifest(target, manifest)
-            self._write_thumbnail(app, target, theme)
+            self._write_manifest(staging, manifest)
+            self._write_thumbnail(app, staging, theme)
         except (OSError, ThemeError, TrccError) as e:
-            log.exception("SaveTheme: assembly failed; rolling back %s", target)
-            shutil.rmtree(target, ignore_errors=True)
+            log.exception("SaveTheme: assembly failed; discarding staging %s",
+                          staging)
+            shutil.rmtree(staging, ignore_errors=True)
             return ThemeResult(
                 ok=False, key=self.key, theme_name=self.name,
                 message=f"failed to assemble saved theme: {e}",
             )
 
+        # Swap staging → target.  Every source asset is now captured in staging,
+        # so removing the (possibly ==source) target is safe.
+        try:
+            if target.exists():
+                log.warning("SaveTheme: overwriting existing theme %s", target)
+                shutil.rmtree(target)
+            staging.replace(target)
+        except OSError as e:
+            log.exception("SaveTheme: finalize failed; discarding staging %s",
+                          staging)
+            shutil.rmtree(staging, ignore_errors=True)
+            return ThemeResult(
+                ok=False, key=self.key, theme_name=self.name,
+                message=f"failed to finalize saved theme: {e}",
+            )
+
         # Saved theme is now fully self-contained — drop the device's
         # overrides + user edits, then re-point BOTH the live active
         # theme (what the renderer reads via app.active_themes) and the
@@ -561,16 +617,22 @@ class SaveTheme(Command[ThemeResult]):
         width: int,
         height: int,
     ) -> str | None:
-        """Store the resolved current background; return its library ref.
-
-        Image → canonical PNG bytes into the user library (deduped),
-        returning the ref.  Video → bundled verbatim as ``Theme.<ext>``
-        in the theme dir (returns ``None``; videos reload via the in-dir
-        convention).  ``DeviceSettings.background_path`` (cloud override)
-        wins over the source theme's bundled background.
+        """Link the resolved current background into the saved theme dir.
+
+        Every asset a saved theme uses is a SYMLINK into the shared data tree —
+        no bytes duplicated; only the DC/config (``trcc.json``) is a real copy
+        edited per save.  The background links in under its standard in-dir name
+        — ``00.png`` for an image, ``Theme.<ext>`` for a video — so the loader
+        finds it by convention and no manifest ref is needed (returns ``None``).
+
+        Asset home (the symlink target): a catalog asset (cloud
+        ``cloud_theme_dir`` / user ``user_background_dir`` ``web/{w}{h}``) is
+        linked in place; a loose image/video is first stored into the user
+        library (deduped, native res) and the link points there.  On a
+        filesystem WITHOUT symlink support the asset is REFERENCED instead (the
+        ``web/{w}{h}/…`` ref is returned and the loader resolves it).
+        ``DeviceSettings.background_path`` (override) wins over the source theme.
         """
-        import shutil
-
         src = self._pick_asset(
             s.background_path, app.themes.background_path(theme), "background",
         )
@@ -580,17 +642,36 @@ class SaveTheme(Command[ThemeResult]):
             return None
 
         ext = src.suffix.lower()
-        if ext in _VIDEO_EXTS_FOR_SAVE:
-            dst = target / f"Theme{ext}"
-            shutil.copy2(src, dst)
-            log.info("SaveTheme: video bg bundled → %s", dst)
-            return None
+        is_video = ext in _VIDEO_EXTS_FOR_SAVE
+        paths = app.platform.paths()
+        src_resolved = src.resolve()
 
-        surface = app.renderer.open_image(src)
-        ref = app.themes.store_background(
-            app.renderer.encode_png(surface), ".png", width, height,
-        )
-        log.info("SaveTheme: image bg %s → library ref %s", src.name, ref)
+        # Stable home for the asset (what the symlink points at) + the ref that
+        # names it (the no-symlink fallback).  Catalog asset → link in place;
+        # loose asset → give it a deduped home in the user library first.
+        canonical: Path | None = None
+        ref: str | None = None
+        for root in (paths.user_background_dir(width, height),
+                     paths.cloud_theme_dir(width, height)):
+            if src_resolved.is_relative_to(root.resolve()):
+                canonical = src_resolved
+                ref = f"web/{width}{height}/{src.name}"
+                break
+        if canonical is None:
+            data = (src.read_bytes() if is_video
+                    else app.renderer.encode_png(app.renderer.open_image(src)))
+            ref = app.themes.store_background(
+                data, ext if is_video else ".png", width, height,
+            )
+            canonical = paths.user_background_dir(width, height) / Path(ref).name
+
+        in_dir = f"Theme{ext}" if is_video else _LEGACY_BG_FILENAME
+        if self._try_symlink(target / in_dir, canonical):
+            log.info("SaveTheme: background %s → symlink %s → %s (no copy)",
+                     src.name, in_dir, canonical)
+            return None
+        log.info("SaveTheme: background %s → reference %s (no symlink support)",
+                 src.name, ref)
         return ref
 
     def _store_mask(
@@ -612,12 +693,13 @@ class SaveTheme(Command[ThemeResult]):
         the user's edited metrics live inline in the saved manifest's
         ``elements``, so no DC is written here.
 
-        A theme's OWN bundled mask (not in any catalog) is copied
-        theme-local into the saved dir as ``01.png`` — self-contained, yet
-        still never in the catalog.  Returns the ref for a catalog mask, or
-        ``None`` for a theme-local one (``mask_path`` then falls back to the
-        in-dir ``01.png``) and for no-mask.  ``DeviceSettings.mask_path``
-        (user/cloud override) wins over the source theme's mask.
+        A theme's OWN bundled / loose mask (not in any catalog) is first stored
+        into the user mask library (deduped) and the symlink points there.  On a
+        filesystem WITHOUT symlink support the mask is REFERENCED instead (the
+        ``web/zt{w}{h}/<id>`` ref is returned and the loader resolves it).  The
+        mask's own ``config1.dc`` stays with the mask in the library; the saved
+        theme's overlay layout lives in its own ``trcc.json`` (baked elements).
+        ``DeviceSettings.mask_path`` (override) wins over the source theme's mask.
         """
         src = self._pick_asset(
             s.mask_path, app.themes.mask_path(theme), "mask",
@@ -626,29 +708,59 @@ class SaveTheme(Command[ThemeResult]):
             log.info("SaveTheme: no mask to save (neither override nor source)")
             return None
 
-        # Catalog mask (cloud or prior upload) → reference it, never copy.
-        src_resolved = src.resolve()
         paths = app.platform.paths()
-        for root in (paths.cloud_mask_dir(width, height),
-                     paths.user_mask_dir(width, height)):
-            if src_resolved.is_relative_to(root.resolve()):
-                ref = f"web/zt{width}{height}/{src.parent.name}"
-                log.info("SaveTheme: mask %s is a catalog mask → reference "
-                         "%s (no copy)", src.parent.name, ref)
-                return ref
+        src_resolved = src.resolve()
+        mask_dir = src_resolved.parent
+
+        # Stable home for the mask's 01.png (symlink target) + its ref (the
+        # no-symlink fallback).  Catalog mask → link in place; loose mask → give
+        # it a deduped home in the user mask library first.
+        canonical: Path | None = None
+        ref: str | None = None
+        for root in (paths.user_mask_dir(width, height),
+                     paths.cloud_mask_dir(width, height)):
+            if mask_dir.is_relative_to(root.resolve()):
+                canonical = src_resolved
+                ref = f"web/zt{width}{height}/{mask_dir.name}"
+                break
+        if canonical is None:
+            try:
+                image = src.read_bytes()
+            except OSError as e:
+                log.warning("SaveTheme: could not read mask %s (%s) — mask "
+                            "omitted", src, e)
+                return None
+            ref = app.themes.store_mask(image, width, height)
+            canonical = (paths.user_mask_dir(width, height)
+                         / Path(ref).name / _LEGACY_MASK_FILENAME)
+
+        if self._try_symlink(target / _LEGACY_MASK_FILENAME, canonical):
+            log.info("SaveTheme: mask %s → symlink 01.png → %s (no copy)",
+                     src.name, canonical)
+            return None
+        log.info("SaveTheme: mask %s → reference %s (no symlink support)",
+                 src.name, ref)
+        return ref
 
-        # Theme's own bundled mask → copy theme-local so the saved theme is
-        # self-contained, without adding to the user mask catalog.
-        import shutil
-        dst = target / _LEGACY_MASK_FILENAME
+    @staticmethod
+    def _try_symlink(link: Path, asset: Path) -> bool:
+        """Create *link* as a symlink to *asset*.
+
+        True on success; False when the filesystem can't symlink (e.g. Windows
+        without the privilege, exotic FS) so the caller falls back to a manifest
+        reference.  An existing entry at *link* (a prior save's symlink) is
+        replaced.  *asset* is linked as an absolute path so the link resolves
+        regardless of the theme dir's location.
+        """
         try:
-            shutil.copy2(src, dst)
+            if link.is_symlink() or link.exists():
+                link.unlink()
+            link.symlink_to(asset)
+            return True
         except OSError as e:
-            log.warning("SaveTheme: theme-local mask copy failed (%s) — mask "
-                        "omitted", e)
-            return None
-        log.info("SaveTheme: bundled mask %s → theme-local %s", src.name, dst)
-        return None
+            log.info("SaveTheme: symlink %s → %s unavailable (%s) — referencing",
+                     link, asset, e)
+            return False
 
     @staticmethod
     def _write_manifest(target: Path, manifest: dict) -> None:
@@ -1056,11 +1168,15 @@ class ListThemes(Command[ThemesListResult]):
     directory: Path | None = None
 
     def execute(self, app: App) -> ThemesListResult:
+        paths = app.platform.paths()
         if self.directory is not None:
             roots = [self.directory]
         elif self.resolution is not None:
-            paths = app.platform.paths()
             w, h = self.resolution
+            # Shipped (program / cloud-downloaded) themes FIRST, the user's
+            # saved themes AFTER — both listed, neither hiding the other (dedupe
+            # by PATH, not name, so a same-named user + shipped pair both belong,
+            # told apart by ``origin``). (#theme-collision)
             roots = [paths.theme_dir(w, h), paths.user_theme_dir(w, h)]
         else:
             return ThemesListResult(
@@ -1068,16 +1184,22 @@ class ListThemes(Command[ThemesListResult]):
                 message="ListThemes requires resolution=(w,h) or directory=...",
             )
 
-        seen: set[Path] = set()
+        # Origin is location-derived (theme under user_data_dir → "user"), so
+        # it is correct in directory mode too and replaces name heuristics.
+        user_root = paths.user_data_dir().resolve()
+        seen_paths: set[Path] = set()
         entries: list[ThemeListEntry] = []
         for root in roots:
             for theme in app.themes.list(root):
-                if theme.path in seen:
+                resolved = theme.path.resolve()
+                if resolved in seen_paths:
                     continue
-                seen.add(theme.path)
+                seen_paths.add(resolved)
                 entries.append(ThemeListEntry(
                     name=theme.name, resolution=theme.resolution,
                     path=str(theme.path),
+                    preview=str(_theme_preview(theme.path)),
+                    origin="user" if resolved.is_relative_to(user_root) else "shipped",
                 ))
         target_str = "; ".join(str(r) for r in roots)
         return ThemesListResult(
@@ -1389,6 +1511,10 @@ class RestoreLastTheme(Command[ThemeResult]):
         # the theme's bundled layout (that's an explicit-switch behavior).
         candidate = Path(stored)
         if candidate.is_dir():
+            # Load EXACTLY the persisted path (re-rooted to the current
+            # orientation).  A user save never overwrites the shipped theme of
+            # the same name, so restore must NOT re-resolve a shipped pointer to
+            # the user one — it loads whatever the user last selected.
             candidate = oriented_theme_path(app, self.key, candidate)
             return LoadTheme(
                 key=self.key, path=candidate, reset_overrides=False,