echoact 0.1.0__py3-none-any.whl

echoact/ui/i18n.py

@@ -0,0 +1,260 @@
+"""Display language, per F-86.
+
+Korean or English, defaulting to the operating system's language and falling
+back to English.  It is independent of the narration language in F-05 and of
+the source text, and A-22 requires that switching it leaves documents, job
+snapshots, and API responses unchanged -- which is why nothing outside
+``echoact.ui`` imports this module.  Error text on the wire comes from
+``echoact.errors``, in English, always.
+
+Strings are keyed by their English text rather than by an identifier.  That
+keeps a call site readable, makes a missing translation degrade to correct
+English instead of to a symbol, and means no registry to keep in step.  Where
+two English strings coincide but their Korean does not, pass a ``context``.
+
+Each UI module registers its own strings with ``add_korean`` from its own
+file, so the catalogue never becomes one contended table.
+"""
+
+from __future__ import annotations
+
+import locale
+import os
+from collections.abc import Callable, Mapping
+from enum import StrEnum
+
+
+class Lang(StrEnum):
+    EN = "en"
+    KO = "ko"
+    SYSTEM = "system"
+
+
+_KO: dict[str, str] = {}
+_CURRENT: Lang = Lang.EN
+_LISTENERS: list[Callable[[Lang], None]] = []
+
+
+def detect_system_language() -> Lang:
+    """Korean if the OS says so, English otherwise.
+
+    Checked in the order a user would expect to win: an explicit override,
+    then the process locale, then the OS default.  Anything unrecognised is
+    English, because F-86 names English as the fallback rather than the
+    nearest match.
+    """
+    for value in (
+        os.environ.get("ECHOACT_LANG"),
+        os.environ.get("LANG"),
+        os.environ.get("LC_ALL"),
+    ):
+        if value and value.lower().startswith("ko"):
+            return Lang.KO
+        if value and value.lower().startswith("en"):
+            return Lang.EN
+    try:
+        code = locale.getlocale()[0] or ""
+    except ValueError:
+        code = ""
+    if code.lower().startswith(("ko", "korean")):
+        return Lang.KO
+    return Lang.EN
+
+
+def set_language(lang: Lang) -> Lang:
+    """Switch the display language and notify listeners.  Returns the
+    resolved language, so a caller storing ``SYSTEM`` still learns which
+    one is in force."""
+    global _CURRENT
+    _CURRENT = detect_system_language() if lang is Lang.SYSTEM else lang
+    for fn in list(_LISTENERS):
+        fn(_CURRENT)
+    return _CURRENT
+
+
+def current() -> Lang:
+    return _CURRENT
+
+
+def on_change(fn: Callable[[Lang], None]) -> None:
+    """Register a retranslate callback.  Widgets rebuild their text here
+    rather than being recreated, so the switch keeps the user's place."""
+    _LISTENERS.append(fn)
+
+
+def add_korean(entries: Mapping[str, str], context: str | None = None) -> None:
+    """Contribute translations.  Called at import time by each UI module."""
+    prefix = f"{context}\x00" if context else ""
+    for source, korean in entries.items():
+        _KO[prefix + source] = korean
+
+
+def tr(text: str, context: str | None = None) -> str:
+    if _CURRENT is not Lang.KO:
+        return text
+    if context:
+        found = _KO.get(f"{context}\x00{text}")
+        if found is not None:
+            return found
+    return _KO.get(text, text)
+
+
+def untranslated() -> list[str]:
+    """Strings the Korean catalogue does not cover.
+
+    Not used at runtime; a test asserts this is empty for the strings the
+    app actually shows, so a new label cannot ship English-only by accident.
+    """
+    return sorted(k for k, v in _KO.items() if not v)
+
+
+def plural(n: int, singular: str, plural_form: str) -> str:
+    """English pluralises, Korean does not.
+
+    Written as one helper so no call site grows an ``if language ==`` of its
+    own; Korean returns the singular because Hangul marks number on the
+    noun only when it matters, and "1개의 문장" style counting reads wrong
+    for a running status line.
+    """
+    if _CURRENT is Lang.KO:
+        return singular
+    return singular if n == 1 else plural_form
+
+
+def duration(ms: int) -> str:
+    """m:ss, or h:mm:ss past an hour.  Identical in both languages, because
+    a timecode is not prose."""
+    total = max(0, ms) // 1000
+    h, rem = divmod(total, 3600)
+    m, s = divmod(rem, 60)
+    if h:
+        return f"{h}:{m:02d}:{s:02d}"
+    return f"{m}:{s:02d}"
+
+
+def approximate_duration(ms: int) -> str:
+    """A rough length for an estimate, where a timecode would imply more
+    precision than F-88 promises."""
+    total = max(0, ms) // 1000
+    if total < 60:
+        return tr("about {n} seconds").format(n=total)
+    minutes = round(total / 60)
+    if minutes < 60:
+        return tr("about {n} min").format(n=minutes)
+    hours = total / 3600
+    return tr("about {n} h").format(n=f"{hours:.1f}")
+
+
+def count(n: int) -> str:
+    """Thousands separators.  Korean uses the same grouping as English."""
+    return f"{n:,}"
+
+
+def bytes_size(n: int) -> str:
+    """Storage in GB (10^9), per Section 4.1's units rule."""
+    if n < 1000:
+        return f"{n} B"
+    for unit, div in (("GB", 10**9), ("MB", 10**6), ("kB", 10**3)):
+        if n >= div:
+            value = n / div
+            return f"{value:.1f} {unit}" if value < 100 else f"{value:.0f} {unit}"
+    return f"{n} B"
+
+
+def memory_size(n: int) -> str:
+    """Memory in GiB (2^30), per Section 4.1's units rule.  Deliberately a
+    different function from ``bytes_size``: the document uses different
+    units for storage and memory and conflating them misreports both."""
+    gib = n / (1 << 30)
+    if gib >= 1:
+        return f"{gib:.1f} GiB"
+    return f"{n / (1 << 20):.0f} MiB"
+
+
+# The strings shared across the app.  Module-specific text is registered by
+# the module that shows it.
+add_korean(
+    {
+        # identity and chrome
+        "EchoAct": "에코액트",
+        "Library": "라이브러리",
+        "Models": "모델",
+        "Settings": "설정",
+        "Help": "도움말",
+        "Close": "닫기",
+        "Cancel": "취소",
+        "Save": "저장",
+        "Delete": "삭제",
+        "Open": "열기",
+        "Done": "완료",
+        "Retry": "다시 시도",
+        "Continue": "계속",
+        "Back": "뒤로",
+        "Copy": "복사",
+        "Discard": "저장하지 않음",
+        # reading and playback
+        "Read aloud": "소리내어 읽기",
+        "Play": "재생",
+        "Pause": "일시정지",
+        "Stop": "정지",
+        "Stop reading": "읽기 중지",
+        "Previous segment": "이전 문장",
+        "Next segment": "다음 문장",
+        "Return to the reading position": "읽는 위치로 이동",
+        "Play as soon as ready": "준비되는 즉시 재생",
+        "Follow the reading position": "읽는 위치 따라가기",
+        "Highlighting unavailable": "강조 표시를 사용할 수 없음",
+        "The text no longer matches the audio.": "본문이 오디오와 더 이상 일치하지 않습니다.",
+        "Waiting for the next segment": "다음 문장을 기다리는 중",
+        "Paused": "일시정지됨",
+        "Playing": "재생 중",
+        "Stopped": "정지됨",
+        # generation
+        "Preparing the model": "모델 준비 중",
+        "Loading the model": "모델 불러오는 중",
+        "Generating": "생성 중",
+        "Complete": "완료됨",
+        "Canceled": "취소됨",
+        "Interrupted": "중단됨",
+        "Failed": "실패",
+        "Cancel generation": "생성 취소",
+        # voice settings
+        "Voice": "음성",
+        "Model": "모델",
+        "Language": "언어",
+        "Automatic": "자동",
+        "Korean": "한국어",
+        "English": "영어",
+        "Gender": "성별",
+        "Female": "여성",
+        "Male": "남성",
+        "Style": "말하기 스타일",
+        "Natural": "자연스럽게",
+        "Calm": "차분하게",
+        "Bright": "밝게",
+        "Narration": "내레이션",
+        "Tempo": "속도",
+        "Presets": "사전 설정",
+        # input
+        "{n} / {max} characters": "{n} / {max}자",
+        "Open a text file": "텍스트 파일 열기",
+        "Unsaved text": "저장하지 않은 본문",
+        "Replace the current text?": "현재 본문을 바꿀까요?",
+        # resources and service
+        "CPU": "CPU",
+        "Memory": "메모리",
+        "Resource budget": "자원 한도",
+        "Local service": "로컬 서비스",
+        "on": "켜짐",
+        "off": "꺼짐",
+        "Integrations unavailable": "연동을 사용할 수 없음",
+        # measurements
+        "about {n} seconds": "약 {n}초",
+        "about {n} min": "약 {n}분",
+        "about {n} h": "약 {n}시간",
+        "{n} segments": "{n}개 문장",
+        "1 segment": "문장 1개",
+    }
+)
+
+_CURRENT = detect_system_language()

echoact/ui/icons.py

@@ -0,0 +1,440 @@
+"""Icons drawn in code, not shipped as files.
+
+Two reasons rather than one.  N-30 requires icons to carry accessible names
+and descriptions, and an icon that is a character in a font gets whatever
+name the font gives it -- on Windows the transport glyphs render as colour
+emoji, which is both wrong for the theme and meaningless to a screen reader.
+And the light/dark switch has to recolour every mark; a bitmap cannot follow
+it, while a stroked path is redrawn in the current token colour for nothing.
+
+Everything here is a 24-unit square path stroked at 2 units with round caps,
+scaled to whatever size is asked for, so the whole set stays visually
+consistent without a designer's file to keep in sync.
+
+A few icons also have to reach Qt's stylesheet, which can only take a URL --
+the combo box arrow and the check mark.  Those are rendered once per theme
+into a cache directory and referenced by path; ``stylesheet_assets`` returns
+the mapping.
+"""
+
+from __future__ import annotations
+
+import tempfile
+from collections.abc import Callable
+from functools import lru_cache
+from pathlib import Path
+
+from PySide6.QtCore import QPointF, QRectF, QSize, Qt
+from PySide6.QtGui import QColor, QIcon, QPainter, QPainterPath, QPen, QPixmap
+
+# ----------------------------------------------------------------------
+# Path definitions.  Each takes a QPainterPath and draws in a 24x24 box.
+# ----------------------------------------------------------------------
+
+
+def _line(p: QPainterPath, x1: float, y1: float, x2: float, y2: float) -> None:
+    p.moveTo(x1, y1)
+    p.lineTo(x2, y2)
+
+
+def _play(p: QPainterPath) -> None:
+    p.moveTo(8, 5.5)
+    p.lineTo(18.5, 12)
+    p.lineTo(8, 18.5)
+    p.closeSubpath()
+
+
+def _pause(p: QPainterPath) -> None:
+    p.addRoundedRect(QRectF(8, 5.5, 2.6, 13), 1.3, 1.3)
+    p.addRoundedRect(QRectF(13.4, 5.5, 2.6, 13), 1.3, 1.3)
+
+
+def _stop(p: QPainterPath) -> None:
+    p.addRoundedRect(QRectF(7, 7, 10, 10), 2, 2)
+
+
+def _skip_back(p: QPainterPath) -> None:
+    p.moveTo(17, 6)
+    p.lineTo(9, 12)
+    p.lineTo(17, 18)
+    p.closeSubpath()
+    p.addRect(QRectF(6.5, 6, 1.6, 12))
+
+
+def _skip_forward(p: QPainterPath) -> None:
+    p.moveTo(7, 6)
+    p.lineTo(15, 12)
+    p.lineTo(7, 18)
+    p.closeSubpath()
+    p.addRect(QRectF(15.9, 6, 1.6, 12))
+
+
+def _chevron_down(p: QPainterPath) -> None:
+    p.moveTo(7, 10)
+    p.lineTo(12, 15)
+    p.lineTo(17, 10)
+
+
+def _chevron_up(p: QPainterPath) -> None:
+    p.moveTo(7, 14)
+    p.lineTo(12, 9)
+    p.lineTo(17, 14)
+
+
+def _chevron_right(p: QPainterPath) -> None:
+    p.moveTo(10, 7)
+    p.lineTo(15, 12)
+    p.lineTo(10, 17)
+
+
+def _check(p: QPainterPath) -> None:
+    p.moveTo(6, 12.5)
+    p.lineTo(10, 16.5)
+    p.lineTo(18, 7.5)
+
+
+def _close(p: QPainterPath) -> None:
+    _line(p, 7, 7, 17, 17)
+    _line(p, 17, 7, 7, 17)
+
+
+def _plus(p: QPainterPath) -> None:
+    _line(p, 12, 6, 12, 18)
+    _line(p, 6, 12, 18, 12)
+
+
+def _search(p: QPainterPath) -> None:
+    p.addEllipse(QPointF(11, 11), 5, 5)
+    _line(p, 14.8, 14.8, 18.5, 18.5)
+
+
+def _trash(p: QPainterPath) -> None:
+    _line(p, 5.5, 7, 18.5, 7)
+    p.moveTo(7.5, 7)
+    p.lineTo(8.4, 19)
+    p.lineTo(15.6, 19)
+    p.lineTo(16.5, 7)
+    p.moveTo(9.5, 7)
+    p.lineTo(9.5, 4.8)
+    p.lineTo(14.5, 4.8)
+    p.lineTo(14.5, 7)
+
+
+def _folder(p: QPainterPath) -> None:
+    p.moveTo(4, 18.5)
+    p.lineTo(4, 6)
+    p.lineTo(10, 6)
+    p.lineTo(11.8, 8.4)
+    p.lineTo(20, 8.4)
+    p.lineTo(20, 18.5)
+    p.closeSubpath()
+
+
+def _save(p: QPainterPath) -> None:
+    p.addRoundedRect(QRectF(5, 5, 14, 14), 2, 2)
+    p.addRect(QRectF(8.5, 5, 7, 5))
+    p.addRect(QRectF(8, 13, 8, 6))
+
+
+def _download(p: QPainterPath) -> None:
+    _line(p, 12, 4.5, 12, 15)
+    p.moveTo(7.5, 10.5)
+    p.lineTo(12, 15)
+    p.lineTo(16.5, 10.5)
+    _line(p, 5.5, 18.5, 18.5, 18.5)
+
+
+def _export(p: QPainterPath) -> None:
+    _line(p, 12, 15, 12, 4.5)
+    p.moveTo(7.5, 9)
+    p.lineTo(12, 4.5)
+    p.lineTo(16.5, 9)
+    _line(p, 5.5, 18.5, 18.5, 18.5)
+
+
+def _refresh(p: QPainterPath) -> None:
+    p.arcMoveTo(QRectF(5, 5, 14, 14), 60)
+    p.arcTo(QRectF(5, 5, 14, 14), 60, 280)
+    p.moveTo(15.5, 4.5)
+    p.lineTo(16.5, 8.6)
+    p.lineTo(12.4, 9.2)
+
+
+def _settings(p: QPainterPath) -> None:
+    """Sliders, not a gear.
+
+    A six-spoke gear collapses into something that reads as a sparkle below
+    about 18 px, which is the size this icon is actually used at.
+    """
+    for y, knob in ((7.5, 15.5), (12.0, 9.0), (16.5, 13.5)):
+        _line(p, 4.5, y, 19.5, y)
+        p.addEllipse(QPointF(knob, y), 2.1, 2.1)
+
+
+def _library(p: QPainterPath) -> None:
+    p.addRect(QRectF(5, 5.5, 3.4, 13))
+    p.addRect(QRectF(10, 5.5, 3.4, 13))
+    p.moveTo(15.6, 6.4)
+    p.lineTo(18.9, 5.7)
+    p.lineTo(20.4, 18.2)
+    p.lineTo(17.1, 18.9)
+    p.closeSubpath()
+
+
+def _cube(p: QPainterPath) -> None:
+    p.moveTo(12, 3.8)
+    p.lineTo(19.5, 8)
+    p.lineTo(19.5, 16)
+    p.lineTo(12, 20.2)
+    p.lineTo(4.5, 16)
+    p.lineTo(4.5, 8)
+    p.closeSubpath()
+    p.moveTo(4.5, 8)
+    p.lineTo(12, 12.2)
+    p.lineTo(19.5, 8)
+    p.moveTo(12, 12.2)
+    p.lineTo(12, 20.2)
+
+
+def _plug(p: QPainterPath) -> None:
+    _line(p, 9, 3.5, 9, 8)
+    _line(p, 15, 3.5, 15, 8)
+    p.moveTo(6.5, 8)
+    p.lineTo(17.5, 8)
+    p.lineTo(17.5, 12)
+    p.arcTo(QRectF(6.5, 6.5, 11, 11), 0, -180)
+    p.closeSubpath()
+    _line(p, 12, 17.5, 12, 20.5)
+
+
+def _volume(p: QPainterPath) -> None:
+    p.moveTo(4.5, 9.5)
+    p.lineTo(8, 9.5)
+    p.lineTo(12, 5.5)
+    p.lineTo(12, 18.5)
+    p.lineTo(8, 14.5)
+    p.lineTo(4.5, 14.5)
+    p.closeSubpath()
+    p.arcMoveTo(QRectF(11, 7.5, 9, 9), 60)
+    p.arcTo(QRectF(11, 7.5, 9, 9), 60, -120)
+
+
+def _volume_muted(p: QPainterPath) -> None:
+    p.moveTo(4.5, 9.5)
+    p.lineTo(8, 9.5)
+    p.lineTo(12, 5.5)
+    p.lineTo(12, 18.5)
+    p.lineTo(8, 14.5)
+    p.lineTo(4.5, 14.5)
+    p.closeSubpath()
+    _line(p, 15, 9.5, 20, 14.5)
+    _line(p, 20, 9.5, 15, 14.5)
+
+
+def _locate(p: QPainterPath) -> None:
+    """Return to the reading position (F-30)."""
+    p.addEllipse(QPointF(12, 12), 3, 3)
+    _line(p, 12, 3, 12, 6.5)
+    _line(p, 12, 17.5, 12, 21)
+    _line(p, 3, 12, 6.5, 12)
+    _line(p, 17.5, 12, 21, 12)
+
+
+def _info(p: QPainterPath) -> None:
+    p.addEllipse(QPointF(12, 12), 8, 8)
+    _line(p, 12, 11, 12, 16.5)
+    p.addEllipse(QPointF(12, 7.8), 0.2, 0.2)
+
+
+def _warning(p: QPainterPath) -> None:
+    p.moveTo(12, 4)
+    p.lineTo(21, 19.5)
+    p.lineTo(3, 19.5)
+    p.closeSubpath()
+    _line(p, 12, 9.5, 12, 14.5)
+    p.addEllipse(QPointF(12, 17), 0.2, 0.2)
+
+
+def _error(p: QPainterPath) -> None:
+    p.addEllipse(QPointF(12, 12), 8, 8)
+    _line(p, 9, 9, 15, 15)
+    _line(p, 15, 9, 9, 15)
+
+
+def _check_circle(p: QPainterPath) -> None:
+    p.addEllipse(QPointF(12, 12), 8, 8)
+    p.moveTo(8.2, 12.2)
+    p.lineTo(11, 15)
+    p.lineTo(15.8, 9.4)
+
+
+def _copy(p: QPainterPath) -> None:
+    p.addRoundedRect(QRectF(8.5, 4.5, 11, 13), 2, 2)
+    p.moveTo(15.5, 19.5)
+    p.lineTo(6.5, 19.5)
+    p.lineTo(6.5, 8)
+
+
+def _document(p: QPainterPath) -> None:
+    p.moveTo(6, 3.5)
+    p.lineTo(14, 3.5)
+    p.lineTo(18.5, 8)
+    p.lineTo(18.5, 20.5)
+    p.lineTo(6, 20.5)
+    p.closeSubpath()
+    p.moveTo(14, 3.5)
+    p.lineTo(14, 8)
+    p.lineTo(18.5, 8)
+
+
+def _pulse(p: QPainterPath) -> None:
+    """Activity: a heartbeat line, which reads at 16 px where a gauge does not."""
+    p.moveTo(3, 12)
+    p.lineTo(8, 12)
+    p.lineTo(10.5, 6)
+    p.lineTo(13.5, 18)
+    p.lineTo(16, 12)
+    p.lineTo(21, 12)
+
+
+def _more(p: QPainterPath) -> None:
+    for x in (7.0, 12.0, 17.0):
+        p.addEllipse(QPointF(x, 12), 0.9, 0.9)
+
+
+#: name -> (drawer, filled?, accessible name)
+#:
+#: The accessible name travels with the icon so that a caller cannot forget
+#: it; N-30 requires every icon to have one.
+_ICONS: dict[str, tuple[Callable[[QPainterPath], None], bool, str]] = {
+    "play": (_play, True, "Play"),
+    "pause": (_pause, True, "Pause"),
+    "stop": (_stop, True, "Stop"),
+    "skip-back": (_skip_back, True, "Previous segment"),
+    "skip-forward": (_skip_forward, True, "Next segment"),
+    "chevron-down": (_chevron_down, False, "Open"),
+    "chevron-up": (_chevron_up, False, "Close"),
+    "chevron-right": (_chevron_right, False, "Expand"),
+    "check": (_check, False, "Selected"),
+    "close": (_close, False, "Close"),
+    "plus": (_plus, False, "Add"),
+    "search": (_search, False, "Search"),
+    "trash": (_trash, False, "Delete"),
+    "folder": (_folder, False, "Open file"),
+    "save": (_save, False, "Save"),
+    "download": (_download, False, "Download"),
+    "export": (_export, False, "Export"),
+    "refresh": (_refresh, False, "Refresh"),
+    "settings": (_settings, False, "Settings"),
+    "library": (_library, False, "Library"),
+    "cube": (_cube, False, "Models"),
+    "plug": (_plug, False, "Connect an app"),
+    "pulse": (_pulse, False, "Activity"),
+    "volume": (_volume, False, "Volume"),
+    "volume-muted": (_volume_muted, False, "Muted"),
+    "locate": (_locate, False, "Return to the reading position"),
+    "info": (_info, False, "Information"),
+    "warning": (_warning, False, "Warning"),
+    "error": (_error, False, "Error"),
+    "check-circle": (_check_circle, False, "Done"),
+    "copy": (_copy, False, "Copy"),
+    "document": (_document, False, "Document"),
+    "more": (_more, True, "More"),
+}
+
+
+def accessible_name(name: str) -> str:
+    return _ICONS[name][2]
+
+
+def available() -> tuple[str, ...]:
+    return tuple(_ICONS)
+
+
+def _render(name: str, color: str, size: int, dpr: float, stroke: float) -> QPixmap:
+    drawer, filled, _ = _ICONS[name]
+    px = QPixmap(int(size * dpr), int(size * dpr))
+    px.setDevicePixelRatio(dpr)
+    px.fill(Qt.GlobalColor.transparent)
+
+    painter = QPainter(px)
+    painter.setRenderHint(QPainter.RenderHint.Antialiasing, True)
+    # Qt already folds the pixmap's device-pixel-ratio into the painter's
+    # transform, so the painter works in logical units and the scale is
+    # size/24 rather than size*dpr/24.  Multiplying by dpr here draws the
+    # path at twice its size and clips it against the pixmap.
+    painter.scale(size / 24.0, size / 24.0)
+
+    path = QPainterPath()
+    drawer(path)
+    c = QColor(color)
+    if filled:
+        painter.setPen(Qt.PenStyle.NoPen)
+        painter.fillPath(path, c)
+    else:
+        pen = QPen(c)
+        pen.setWidthF(stroke)
+        pen.setCapStyle(Qt.PenCapStyle.RoundCap)
+        pen.setJoinStyle(Qt.PenJoinStyle.RoundJoin)
+        painter.setPen(pen)
+        painter.drawPath(path)
+    painter.end()
+    return px
+
+
+@lru_cache(maxsize=512)
+def pixmap(name: str, color: str, size: int = 18, dpr: float = 1.0, stroke: float = 1.8) -> QPixmap:
+    return _render(name, color, size, dpr, stroke)
+
+
+@lru_cache(maxsize=512)
+def icon(name: str, color: str, disabled_color: str | None = None, size: int = 18) -> QIcon:
+    """A QIcon with a normal and a disabled rendering.
+
+    Both are supplied because N-09 requires unavailable controls to look
+    unavailable, and a single-pixmap icon stays at full contrast when Qt
+    disables the button.
+    """
+    ic = QIcon()
+    for dpr in (1.0, 2.0):
+        ic.addPixmap(_render(name, color, size, dpr, 1.8), QIcon.Mode.Normal, QIcon.State.Off)
+        if disabled_color:
+            ic.addPixmap(
+                _render(name, disabled_color, size, dpr, 1.8),
+                QIcon.Mode.Disabled,
+                QIcon.State.Off,
+            )
+    return ic
+
+
+def icon_size(size: int = 18) -> QSize:
+    return QSize(size, size)
+
+
+# ----------------------------------------------------------------------
+# Assets the stylesheet needs as files
+# ----------------------------------------------------------------------
+
+
+def _asset_dir() -> Path:
+    d = Path(tempfile.gettempdir()) / "echoact-ui-assets"
+    d.mkdir(parents=True, exist_ok=True)
+    return d
+
+
+def stylesheet_assets(theme_key: str, spec: dict[str, tuple[str, str, int]]) -> dict[str, str]:
+    """Render the marks Qt's stylesheet can only take as a URL.
+
+    ``spec`` maps a key to (icon name, colour, size).  Returns the same keys
+    mapped to forward-slash paths, which is what Qt expects inside
+    ``url(...)`` on every platform.  Files are written once per theme and
+    reused, so switching themes twice does not accumulate files.
+    """
+    out: dict[str, str] = {}
+    d = _asset_dir()
+    for key, (name, color, size) in spec.items():
+        path = d / f"{theme_key}-{key}-{size}.png"
+        if not path.exists():
+            _render(name, color, size, 2.0, 2.0).save(str(path))
+        out[key] = path.as_posix()
+    return out