trcc-linux 9.8.6__tar.gz → 9.8.7__tar.gz

{trcc_linux-9.8.6 → trcc_linux-9.8.7}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: trcc-linux
-Version: 9.8.6
+Version: 9.8.7
 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.8.6 → trcc_linux-9.8.7}/pyproject.toml

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

{trcc_linux-9.8.6 → trcc_linux-9.8.7}/src/trcc/__version__.py

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

{trcc_linux-9.8.6 → trcc_linux-9.8.7}/src/trcc/adapters/device/__init__.py

@@ -71,7 +71,8 @@ class DeviceFactory:
 
 # Side-effect imports: load each device module so its @register decorator
 # fires and populates the registry above.  Anything that imports
-# ``trcc.adapters.device`` triggers all five.
+# ``trcc.adapters.device`` triggers them all.
+from . import ali_lcd as _ali_lcd  # noqa: E402, F401
 from . import bulk_lcd as _bulk_lcd  # noqa: E402, F401
 from . import hid_lcd as _hid_lcd  # noqa: E402, F401
 from . import led as _led  # noqa: E402, F401

trcc_linux-9.8.7/src/trcc/adapters/device/ali_lcd.py

@@ -0,0 +1,141 @@
+"""AliLcd — Device implementation for USBLCDNew "Ali" variant LCD hardware.
+
+A DISTINCT bulk protocol from BulkLcd (GrandVision).  The Ali device
+(0416:5406, Elite Vision 360 ARGB) is driven by its own C# worker thread
+``ThreadSendDeviceDataALi`` (USBLCDNEW.decompiled.cs:548) — different write
+endpoint, handshake, validation, and a fixed 320x320 RGB565 canvas.  Sharing
+BulkLcd would mean a wire-selecting branch inside one class; the C# itself
+splits the two into separate threads, so we mirror that with a separate wire.
+
+Handshake:   write 16-byte request + 1024 zero pad → EP 0x02 (cs:571-577),
+             read 1024 → validate resp[0] in (101, 102) (cs:610).
+Frame send:  16-byte header + 320x320 RGB565 (204800 B) → EP 0x02,
+             then read a 16-byte ack (cs:646-660).  Fixed 204800-B buffer
+             (cs:628) — no PM/resolution table for this device.
+"""
+from __future__ import annotations
+
+import logging
+
+from ...core.errors import HandshakeError, TransportError
+from ...core.models import HandshakeResult, ProductInfo, Wire
+from ...core.ports import BulkTransport, Device
+from ...core.protocol import DeviceProfile
+from . import DeviceFactory
+
+log = logging.getLogger(__name__)
+
+
+# ── Wire constants (line-cited to USBLCDNEW.decompiled.cs) ──────────────
+
+_EP_WRITE = 0x02          # WriteEndpointID.Ep02 (cs:569) — NOT 0x01 (GrandVision)
+_EP_READ = 0x81           # ReadEndpointID.Ep01 (cs:568)
+
+# 16-byte handshake request + 1024-byte zero pad (cs:571-577).
+_HANDSHAKE_REQUEST = bytes([
+    0xF5, 0x00, 0x01, 0x00, 0xBC, 0xFF, 0xB6, 0xC8,
+    0x00, 0x00, 0x00, 0x00, 0x00, 0x04, 0x00, 0x00,
+]) + bytes(1024)
+
+# 16-byte frame header (cs:646-650); bytes[12:16] LE = 0x032000 = 204800.
+_FRAME_HEADER = bytes([
+    0xF5, 0x01, 0x01, 0x00, 0xBC, 0xFF, 0xB6, 0xC8,
+    0x00, 0x00, 0x00, 0x00, 0x00, 0x20, 0x03, 0x00,
+])
+
+_HANDSHAKE_READ_SIZE = 1024      # byte[1024] read buffer (cs:570)
+_ACK_READ_SIZE = 16              # Read(first, 0, 16, ...) (cs:660)
+_HANDSHAKE_TIMEOUT_MS = 1000
+_WRITE_TIMEOUT_MS = 5000
+_READ_TIMEOUT_MS = 1000
+
+# Fixed 320x320 RGB565 — new byte[204800] = 320*320*2 (cs:628).
+_WIDTH = 320
+_HEIGHT = 320
+_FRAME_BYTES = _WIDTH * _HEIGHT * 2
+_VALID_IDENTITY = (101, 102)     # resp[0] (cs:610)
+
+
+@DeviceFactory.register(Wire.BULK_ALI)
+class AliLcd(Device[BulkTransport]):
+    """USBLCDNew "Ali" bulk LCD (fixed 320x320 RGB565)."""
+
+    def __init__(self, info: ProductInfo, transport: BulkTransport) -> None:
+        super().__init__(info, transport)
+        # Fixed canvas — the C# hardcodes the 204800-B buffer, no PM table.
+        self._profile = DeviceProfile(_WIDTH, _HEIGHT, jpeg=False, big_endian=True)
+
+    @property
+    def profile(self) -> DeviceProfile | None:
+        """Fixed 320x320 RGB565 profile (no handshake-derived geometry)."""
+        return self._profile
+
+    # ── Device ABC ────────────────────────────────────────────────────
+
+    def connect(self) -> HandshakeResult:
+        log.info("AliLcd %s: opening transport", self.info.key)
+        if not self._transport.open():
+            log.error("AliLcd %s: transport open failed", self.info.key)
+            raise HandshakeError(f"Failed to open USB transport for {self.info.key}")
+
+        try:
+            self._transport.write(_EP_WRITE, _HANDSHAKE_REQUEST, _HANDSHAKE_TIMEOUT_MS)
+            resp = self._transport.read(_EP_READ, _HANDSHAKE_READ_SIZE, _HANDSHAKE_TIMEOUT_MS)
+        except TransportError as e:
+            log.error("AliLcd %s: handshake I/O failed: %s", self.info.key, e)
+            raise HandshakeError(f"AliLcd handshake I/O failed: {e}") from e
+
+        if len(resp) < 1 or resp[0] not in _VALID_IDENTITY:
+            log.error(
+                "AliLcd %s: handshake validation failed (len=%d, resp[0]=%s)",
+                self.info.key, len(resp), resp[0] if resp else "N/A",
+            )
+            raise HandshakeError(
+                f"AliLcd handshake validation failed "
+                f"(len={len(resp)}, resp[0]={resp[0] if resp else 'N/A'})"
+            )
+
+        model_id = resp[0] - 1     # obj3[0] = array[0] - 1 (cs:614)
+        result = HandshakeResult(
+            resolution=self._profile.resolution,
+            model_id=model_id,
+            pm_byte=resp[0],
+            fbl=self.info.fbl,
+            raw_response=bytes(resp[:64]),
+        )
+        self._handshake = result
+        log.info("AliLcd handshake OK: resp[0]=%d model_id=%d resolution=%s (RGB565)",
+                 resp[0], model_id, result.resolution)
+        return result
+
+    def send(self, payload: bytes) -> bool:
+        if not self._transport.is_open or self._handshake is None:
+            log.error("AliLcd %s: send() called before connect()", self.info.key)
+            raise TransportError(
+                f"AliLcd {self.info.key} not connected — call connect() first"
+            )
+
+        if len(payload) != _FRAME_BYTES:
+            log.warning("AliLcd %s: payload is %d bytes, expected %d (320x320 RGB565)",
+                        self.info.key, len(payload), _FRAME_BYTES)
+
+        frame = _FRAME_HEADER + payload
+        log.debug("AliLcd %s: sending %d-byte frame (RGB565, 320x320)",
+                  self.info.key, len(frame))
+
+        def _write_frame() -> bool:
+            # C# writes the header+buffer in one transfer, then reads a 16-B ack
+            # (cs:653-660).  One write call; PyUSB splits into USB packets.
+            self._transport.write(_EP_WRITE, frame, _WRITE_TIMEOUT_MS)
+            self._transport.read(_EP_READ, _ACK_READ_SIZE, _READ_TIMEOUT_MS)
+            return True
+
+        # Shared reconnect + recovery policy (base Device): one in-place
+        # close→open→handshake retry absorbs an intermittent NAK / heals a
+        # stale handle after resume, before escalating to the recovery tracker.
+        return self._send_with_recovery(_write_frame)
+
+    def disconnect(self) -> None:
+        log.info("AliLcd %s: disconnecting", self.info.key)
+        self._transport.close()
+        self._handshake = None

{trcc_linux-9.8.6 → trcc_linux-9.8.7}/src/trcc/adapters/system/_udev.py

@@ -69,6 +69,7 @@ _WIRE_SUBSYSTEMS: dict[Wire, tuple[str, ...]] = {
     Wire.HID:  ("hidraw", "usb"),
     Wire.LED:  ("hidraw", "usb"),
     Wire.BULK: ("usb",),
+    Wire.BULK_ALI: ("usb",),
     Wire.LY:   ("usb",),
 }
 

{trcc_linux-9.8.6 → trcc_linux-9.8.7}/src/trcc/adapters/system/linux.py

@@ -13,6 +13,7 @@ Key pieces:
 from __future__ import annotations
 
 import ctypes
+import errno
 import logging
 import os
 from pathlib import Path
@@ -219,6 +220,20 @@ class LinuxScsiTransport(ScsiTransport):
             return True
         except OSError as e:
             log.error("LinuxScsiTransport: open failed for %s: %s", self._path, e)
+            if e.errno == errno.EACCES:
+                # A resolved-but-unreadable node almost always means setup was
+                # never run: the /dev/sd* block fallback is root-only (the udev
+                # 0666 rule only covers scsi_generic), and even /dev/sg* is
+                # root-only until the setup rule lands.  Name the remediation
+                # instead of a bare EACCES.  (#217)
+                is_block = self._path.startswith("/dev/sd")
+                detail = ("this is a root-only block node (the sg kernel module "
+                          "isn't loaded) — " if is_block else "")
+                log.warning(
+                    "LinuxScsiTransport: permission denied on %s — %srun "
+                    "`trcc system setup` then reboot to load sg and grant "
+                    "0666 access without sudo (#217)", self._path, detail,
+                )
             return False
 
     def close(self) -> None:

{trcc_linux-9.8.6 → trcc_linux-9.8.7}/src/trcc/core/commands/__init__.py

@@ -127,6 +127,7 @@ from .theme import (
     LoadImage,
     LoadTheme,
     LoadVideo,
+    RestoreDeviceState,
     RestoreLastTheme,
     SaveTheme,
     UploadCustomMask,
@@ -190,6 +191,7 @@ __all__ = [
     "RenderDcStandalone",
     "RenderLed",
     "ResetDevice",
+    "RestoreDeviceState",
     "RestoreLastTheme",
     "RunDoctor",
     "RunHealthCheck",

{trcc_linux-9.8.6 → trcc_linux-9.8.7}/src/trcc/core/commands/theme.py

@@ -1533,6 +1533,85 @@ class RestoreLastTheme(Command[ThemeResult]):
             key=self.key, path=resolved, reset_overrides=False,
         ).execute(app)
 
+@dataclass(frozen=True, slots=True)
+class RestoreDeviceState(Command[ThemeResult]):
+    """Ensure *key* has a renderable display state from persisted settings.
+
+    The shared "make this device show something" path every UI dispatches at
+    its display-start entry — the GUI on connect, the CLI ``display play`` /
+    ``keepalive`` before their loop, the API ``restore-theme`` endpoint.
+    Idempotent: a no-op when a theme is already active (a daemon / GUI already
+    primed it), so it's safe to dispatch unconditionally at each entry.
+
+    Order (mirrors the GUI connect-restore, minus GUI-only widget restore):
+      1. Active theme already loaded → done.
+      2. ``RestoreLastTheme`` — the persisted theme + its mask + overlays +
+         bundled video (preserves the device's overrides).
+      3. No persisted theme → auto-load the first available theme
+         (``ListThemes`` → ``LoadTheme``), matching the GUI first-install
+         auto-load so a fresh device still shows something.
+      4. Replay the persisted ``background_path`` video override
+         (``PlayVideo``) so a cloud / user video resumes on top of the theme.
+
+    Steps 2-3 render + send an immediate first frame, which also leaves a
+    cached frame — so a keepalive resend has something to push (the terminal
+    "No cached frame — render at least once first" gap this closes). (#150)
+    """
+    key: str
+
+    def execute(self, app: App) -> ThemeResult:
+        log.info("RestoreDeviceState: key=%s", self.key)
+        existing = app.active_themes.get(self.key)
+        if existing is not None:
+            log.info("RestoreDeviceState: %s already has an active theme — no-op",
+                     self.key)
+            return ThemeResult(ok=True, key=self.key, theme_name=existing.name,
+                               theme_path=str(existing.path),
+                               message="Display state already active")
+
+        # 2. Persisted theme (reset_overrides=False preserves overlay/mask edits).
+        RestoreLastTheme(key=self.key).execute(app)
+
+        # 3. Nothing persisted → first available theme (GUI first-install parity).
+        #    Resolve via the shared oriented resolver (device profile → native →
+        #    registry) so a rotate panel lists its portrait catalog, matching
+        #    where the GUI browser lists themes.
+        if app.active_themes.get(self.key) is None:
+            resolution = _resolve_oriented_resolution(app, self.key)
+            if resolution is None:
+                log.warning("RestoreDeviceState: %s — cannot resolve resolution "
+                            "to auto-load a theme", self.key)
+            else:
+                listing = ListThemes(resolution=resolution).execute(app)
+                if listing.themes:
+                    first = Path(listing.themes[0].path)
+                    log.info("RestoreDeviceState: %s no persisted theme — "
+                             "auto-loading first theme %s", self.key, first)
+                    LoadTheme(key=self.key, path=first).execute(app)
+
+        theme = app.active_themes.get(self.key)
+        if theme is None:
+            log.warning("RestoreDeviceState: %s — no theme available to restore",
+                        self.key)
+            return ThemeResult(
+                ok=False, key=self.key,
+                message=("No theme available for this device — install themes "
+                         "or load a theme first"),
+            )
+
+        # 4. Resume the persisted cloud / user video background over the theme.
+        bg = app.settings.for_device(self.key).background_path
+        if bg:
+            log.info("RestoreDeviceState: %s replaying persisted background %s",
+                     self.key, bg)
+            PlayVideo(key=self.key, path=Path(bg)).execute(app)
+
+        return ThemeResult(
+            ok=True, key=self.key, theme_name=theme.name,
+            theme_path=str(theme.path),
+            message=f"Display state restored ({theme.name})",
+        )
+
 @dataclass(frozen=True, slots=True)
 class ListCloudThemes(Command[CloudThemesListResult]):
     """List themes available in Thermalright's hosted catalog.

{trcc_linux-9.8.6 → trcc_linux-9.8.7}/src/trcc/core/models.py

@@ -20,6 +20,7 @@ class Wire(str, Enum):
     SCSI = "scsi"
     HID = "hid"
     BULK = "bulk"
+    BULK_ALI = "bulk_ali"
     LY = "ly"
     LED = "led"
 
@@ -28,7 +29,7 @@ class Wire(str, Enum):
 # Thermalright logo after ~2-3 s unless frames keep arriving.  The per-device
 # send worker keepalive-resends the last frame for these.  SCSI/HID latch;
 # LED has no screen.  (Legacy ``run_static_loop`` covered exactly Bulk + LY.)
-VOLATILE_FRAME_WIRES: frozenset[Wire] = frozenset({Wire.BULK, Wire.LY})
+VOLATILE_FRAME_WIRES: frozenset[Wire] = frozenset({Wire.BULK, Wire.BULK_ALI, Wire.LY})
 
 
 class Kind(str, Enum):

{trcc_linux-9.8.6 → trcc_linux-9.8.7}/src/trcc/core/protocol.py

@@ -55,13 +55,17 @@ class DeviceProfile:
     # encode_pm_bases is the LIVE source for encode_baseline: a PM (PingMu)
     # keyed hardware-mount rotation (e.g. PM=6 → 180° for the FW360 Ultra).
     encode_pm_bases: tuple[tuple[int, int], ...] = ()   # ((pm, base), ...) LIVE
-    # encode_base / encode_invert / encode_sub_bases are recorded-but-UNWIRED:
-    # the C# unified per-resolution model (angle = base + direction*sign).  Our
-    # rotate-flag pipeline already covers widescreen rotation, so they are NOT
-    # applied — wiring them needs widescreen hardware verification.
+    # encode_base / encode_invert are LIVE for widescreen JPEG panels: wire_angle
+    # routes them to resolve_encode_angle = (encode_base − orientation) [invert
+    # defaults True], the C# ImageToJpg per-resolution switch (854×480→base 0,
+    # 1600×720/1920×462→base 180).  The C# base is FIXED per resolution and
+    # sub-INDEPENDENT (TRCC.decompiled.cs:65285+), so encode_sub_bases stays
+    # empty for every profile — folding sub into the base was a phantom that put
+    # widescreen 180° off at 90/270 (#203/#169).  Kept for a future device only
+    # if the C# is ever found to vary the base by sub; do not populate blind.
     encode_base: int = 0
-    encode_invert: bool = True   # (unwired — see above)
-    encode_sub_bases: tuple[tuple[int, int], ...] = ()  # ((sub, base), ...) unwired
+    encode_invert: bool = True
+    encode_sub_bases: tuple[tuple[int, int], ...] = ()  # ((sub, base), ...) — unused
 
     @property
     def resolution(self) -> tuple[int, int]:
@@ -94,16 +98,22 @@ FBL_PROFILES: dict[int, DeviceProfile] = {
     100: DeviceProfile(320,  320,  big_endian=True),
     101: DeviceProfile(320,  320,  big_endian=True),
     102: DeviceProfile(320,  320,  big_endian=True),
+    # Widescreen encode base is FIXED per resolution, sub-INDEPENDENT — the C#
+    # ImageToJpg switch keys only on the resolution flag + user orientation
+    # (TRCC.decompiled.cs:65285+): is854x480/is960x540/is1280x480/is800x480 → 0,
+    # is1600x720/is1920x462 → 180.  Every value is base + default encode_invert
+    # (=True) so resolve_encode_angle sends (base − orientation), matching the C#
+    # at EVERY sub.  The old encode_sub_bases overrides (folding sub into base)
+    # + FBL 224's encode_invert=False were a phantom — no C# basis — and put the
+    # frame 180° off at 90/270 for the affected subs. (#203/#169)
     114: DeviceProfile(1600, 720,  jpeg=True, rotate=True, widescreen=True,
-                       encode_base=180, encode_sub_bases=((3, 0),)),
-    128: DeviceProfile(1280, 480,  jpeg=True, rotate=True, widescreen=True,
-                       encode_sub_bases=((2, 90),)),
+                       encode_base=180),
+    128: DeviceProfile(1280, 480,  jpeg=True, rotate=True, widescreen=True),
     129: DeviceProfile(480,  480,
                        encode_pm_bases=((6, 180),)),                # alias for 72
     192: DeviceProfile(1920, 462,  jpeg=True, rotate=True, widescreen=True,
-                       encode_base=180, encode_sub_bases=((2, 0), (3, 0), (4, 0))),
-    224: DeviceProfile(854,  480,  jpeg=True, rotate=True, widescreen=True,
-                       encode_invert=False, encode_sub_bases=((2, 180),)),
+                       encode_base=180),
+    224: DeviceProfile(854,  480,  jpeg=True, rotate=True, widescreen=True),
 }
 # fmt: on
 
@@ -334,7 +344,7 @@ def wire_angle(
 
       * non-widescreen rotate panels → :func:`wire_rotation` (``base − orient``)
       * widescreen JPEG rotate panels → :func:`resolve_encode_angle` (the
-        hardware-verified #169 per-resolution encode table)
+        C#-source-verified per-resolution encode base, #203/#169)
       * squares / non-rotate panels → user orientation only (``360 − orient``)
 
     A portrait-content theme on a rotate panel is pre-rotated at compose time

{trcc_linux-9.8.6 → trcc_linux-9.8.7}/src/trcc/core/registry.py

@@ -51,10 +51,11 @@ ALL_DEVICES: dict[tuple[int, int], ProductInfo] = {
         vid=0x0416, pid=0x5406,
         vendor="Winbond",
         product="LCD Display",
-        # Elite Vision 360 ARGB (#212): enumerates vendor-specific with two BULK
-        # endpoints, never a /dev/sg* node — it is a BULK device, not SCSI.  Its
-        # PM/resolution table already lives in _BULK_VARIANTS (variants.py).
-        wire=Wire.BULK, kind=Kind.LCD,
+        # Elite Vision 360 ARGB (#212): USBLCDNew "Ali" variant — driven by its
+        # own C# worker (ThreadSendDeviceDataALi), a DISTINCT bulk protocol from
+        # GrandVision (write EP 0x02, F5-handshake, validate resp[0]∈{101,102},
+        # fixed 320x320 RGB565).  Not PM-table-driven — see adapters/device/ali_lcd.py.
+        wire=Wire.BULK_ALI, kind=Kind.LCD,
         device_type=4, fbl=100,
         native_resolution=(320, 320),
         orientations=(0, 90, 180, 270),

{trcc_linux-9.8.6 → trcc_linux-9.8.7}/src/trcc/core/variants.py

@@ -159,7 +159,8 @@ _VARIANT_REGISTRY: dict[
     (0x87AD, 0x70DB): _BULK_VARIANTS,
     (0x87CD, 0x70DB): _BULK_VARIANTS,
     (0x0402, 0x3922): _BULK_VARIANTS,
-    (0x0416, 0x5406): _BULK_VARIANTS,
+    # 0416:5406 (Elite Vision 360) is the Wire.BULK_ALI variant — fixed
+    # 320x320 RGB565, no PM table (see adapters/device/ali_lcd.py). (#212)
 }
 
 

{trcc_linux-9.8.6 → trcc_linux-9.8.7}/src/trcc/ui/api/display.py

@@ -36,7 +36,7 @@ from ...core.commands import (
     PauseVideo,
     PlayVideo,
     RenderAndSend,
-    RestoreLastTheme,
+    RestoreDeviceState,
     SeekVideo,
     SendColor,
     SetBackgroundMode,
@@ -815,9 +815,14 @@ def tick(key: str, request: Request) -> RenderResponse:
 
 @router.post("/restore-theme", response_model=ThemeResponse)
 def restore_theme(key: str, request: Request) -> ThemeResponse:
-    """Reload the device's persisted theme."""
+    """Restore the device's display state (persisted theme + background).
+
+    Dispatches the unified ``RestoreDeviceState`` — persisted theme, or the
+    first available theme when none is saved, then replays the persisted
+    background video — the same path the GUI/CLI use at their display entry.
+    """
     log.info("api POST /devices/{key}/display/restore-theme: key=%s", key)
-    result = request.app.state.trcc.dispatch(RestoreLastTheme(key=key))
+    result = request.app.state.trcc.dispatch(RestoreDeviceState(key=key))
     http_error_if_failed(result)
     return to_theme_response(result)
 

{trcc_linux-9.8.6 → trcc_linux-9.8.7}/src/trcc/ui/api/main.py

@@ -21,6 +21,7 @@ from __future__ import annotations
 import hmac
 import logging
 import time
+from typing import TYPE_CHECKING
 
 from fastapi import FastAPI, Request
 from fastapi.responses import JSONResponse
@@ -28,6 +29,9 @@ from fastapi.staticfiles import StaticFiles
 
 from ...__version__ import __version__
 from ...app import App
+
+if TYPE_CHECKING:
+    from ...core.ports import Platform
 from . import config, devices, display, led, system, theme
 from . import trcc as _trcc_router
 
@@ -223,8 +227,27 @@ def build_app(trcc: App | None = None) -> FastAPI:
     return api
 
 
-def serve(host: str = "127.0.0.1", port: int = 8080) -> None:
-    """Run the API with uvicorn (blocking)."""
+def run(platform: Platform | None = None, *,
+        host: str = "127.0.0.1", port: int = 8080) -> int:
+    """Serve the REST API from an injected ``Platform`` (blocking).  Returns the
+    exit code.
+
+    The unified UI-launch contract (see ``METHOD_UI.md``): the composition root
+    injects the ``Platform`` port; this UI composes its App from it (a headless
+    ``QtRenderer`` — the API renders preview frames but has no widgets) and
+    ``build_app`` wraps it in the ASGI surface.  ``platform=None`` uses the host
+    platform; the dev mock injects a ``MockPlatform``.
+    """
     import uvicorn
 
-    uvicorn.run(build_app(), host=host, port=port, log_level="info")
+    from ..._boot import trcc
+    from ...adapters.render.qt import QtRenderer
+
+    app = trcc(platform=platform, renderer=QtRenderer())
+    uvicorn.run(build_app(trcc=app), host=host, port=port, log_level="info")
+    return 0
+
+
+def serve(host: str = "127.0.0.1", port: int = 8080) -> None:
+    """Back-compat entry — serve on the host platform (blocking)."""
+    run(host=host, port=port)

{trcc_linux-9.8.6 → trcc_linux-9.8.7}/src/trcc/ui/cli/display.py

@@ -27,6 +27,7 @@ from ...core.commands import (
     PlayVideo,
     RenderAndSend,
     RenderDcStandalone,
+    RestoreDeviceState,
     RestoreLastTheme,
     SeekVideo,
     SendColor,
@@ -221,7 +222,14 @@ def load_image(
     of the same image are cheap (no re-copy).
     """
     log.info("cli display load-image: key=%s path=%s", key, path)
-    dispatch_echo(LoadImage(key=key, path=path))
+    # LoadImage → LoadTheme renders on the wire; attach the device first so a
+    # fresh CLI process doesn't fail "not connected".  Idempotent.  (#150)
+    app_obj = get_app()
+    ensure_connected(app_obj, key)
+    result = app_obj.dispatch(LoadImage(key=key, path=path))
+    typer.echo(result.message)
+    if not result.ok:
+        raise typer.Exit(code=1)
 
 
 @app.command("load-video")
@@ -437,6 +445,13 @@ def play(
 
     app_obj = get_app()
     ensure_connected(app_obj, key)   # once, before the loop (not per tick)
+    # Self-prime: a fresh CLI process holds no in-memory theme, so RenderAndSend
+    # would fail "No active theme".  Restore the device's persisted display
+    # state (theme + background) the way the GUI does on connect.  (#150)
+    restore = app_obj.dispatch(RestoreDeviceState(key=key))
+    if not restore.ok:
+        typer.echo(restore.message, err=True)
+        raise typer.Exit(code=1)
     tick_s = interval if interval is not None else app_obj.settings.app.refresh_interval_s
     tick_s = max(0.05, tick_s)
 
@@ -762,7 +777,15 @@ def keepalive(
             f"Keepalive on {key} every {interval:.3f}s "
             f"(metric refresh every {metric_interval:.1f}s, Ctrl-C to stop)…"
         )
-    result = get_app().dispatch(KeepAliveLoop(
+    app_obj = get_app()
+    ensure_connected(app_obj, key)
+    # Self-prime persisted display state so a rendered frame exists to resend
+    # — closes the "No cached frame — render at least once first" gap.  (#150)
+    restore = app_obj.dispatch(RestoreDeviceState(key=key))
+    if not restore.ok:
+        typer.echo(restore.message, err=True)
+        raise typer.Exit(code=1)
+    result = app_obj.dispatch(KeepAliveLoop(
         key=key, count=count,
         interval_s=interval, metric_interval_s=metric_interval,
     ))

{trcc_linux-9.8.6 → trcc_linux-9.8.7}/src/trcc/ui/cli/theme.py

@@ -22,7 +22,7 @@ from ...core.commands import (
     SaveTheme,
     UploadCustomMask,
 )
-from ._ctx import get_app
+from ._ctx import ensure_connected, get_app
 
 log = logging.getLogger(__name__)
 
@@ -114,6 +114,10 @@ def create(
         key, name, background, mask, metric,
     )
     app_obj = get_app()
+    # This CLI process holds no attached devices; LoadImage → LoadTheme renders
+    # on the wire, so attach first or it fails "not connected".  Idempotent when
+    # a daemon/GUI already owns the device.  (#150)
+    ensure_connected(app_obj, key)
 
     bg_result = app_obj.dispatch(LoadImage(key=key, path=background))
     if not bg_result.ok:
@@ -292,7 +296,12 @@ def cloud_load(
 ) -> None:
     """Download a cloud theme and load it on a device."""
     log.info("cli theme cloud-load: key=%s theme_id=%s", key, theme_id)
-    result = get_app().dispatch(LoadCloudTheme(key=key, theme_id=theme_id))
+    app_obj = get_app()
+    # LoadCloudTheme dispatches PlayVideo on the wire; this stateless CLI
+    # process must attach the device first or it fails "Not attached".
+    # Idempotent when a daemon/GUI already holds it.  (#150)
+    ensure_connected(app_obj, key)
+    result = app_obj.dispatch(LoadCloudTheme(key=key, theme_id=theme_id))
     typer.echo(result.message)
     if result.theme_path:
         typer.echo(f"  staged at: {result.theme_path}")