trackerkeeper

A frosted, cross-platform PySide6 app base — the shared starter every wolfgang warehaus app is baked from.

trackerkeeper is a fork-and-own starter, not a dependency. Clone it, rename it, delete what you don't need, and build. It solves the cross-platform window chrome, the design system, and the platform scaffolding once — so a new app is mostly its own idea plus a thin layer on top.

It boots to a themed, frosted, frameless window with a live Settings dialog — a blank canvas with the hard parts already done. See docs/PHILOSOPHY.md for the why.

What you get

• AppWindow — a frosted, frameless main window that's borderless on KDE Wayland and Windows (with the native-frame smooth-resize fix), shapes compositor blur to a rounded self-painted body, and falls back to a near-opaque panel where blur isn't available (never see-through).
• Design system — a three-family theme (frosted dark/light + solid), accent presets with WCAG-safe glyph contrast, scalable typography tiers, a 4-based spacing/radius scale. Live theme + accent switching, OS-following auto mode.
• Widget kit — FrostedDialog, the Selector dropdown, IconButton with crisp HiDPI icons, keyboard-nav helpers, a top bar that doubles as the titlebar.
• Cross-platform scaffolding — platform_compat, threaded async_io, the per-platform backend pattern (autostart / notifications / power), a minimal AppBus signal bus, slim persistent Settings, single-instance.
• HiDPI done right — PassThrough fractional scaling + device-pixel snapping.
• Languages for free — Qt translation catalogs wired at boot, plural-aware strings, locale-safe number/date/duration formatting (trackerkeeper.i18n.fmt), RTL-mirrored chrome. See docs/TRANSLATING.md.
• Accessible by default — every kit control announces to screen readers (a test fails the build on unnamed ones), visible keyboard-focus states, a keyboard path for every mouse path. See docs/ACCESSIBILITY.md.
• Structured logging — an opt-in rotating file log (~1 MB × 3) in the app's state dir, console noise capped at WARNING, TRACKERKEEPER_LOG=debug to turn it up.
• Settings migrations — a versioned run-once migration runner (meta/schema_version), so a renamed key never strands an installed user.
• Credentials store — save_secret/load_secret: OS keyring first, an encrypted per-machine blob (AES-GCM, or DPAPI on Windows) as the fallback — plaintext never touches disk.
• Second-launch file forwarding — double-click a document while the app is open and the running instance raises + receives it (AppBus.files_received).
• Update chip — a quiet daily GitHub release check with a dismissable Download / What's-new pill in the top bar; store/AUR builds stay silent.
• Diagnostics bundle — a "Copy diagnostics" button that snapshots versions, platform, theme/blur state, settings (secrets excluded), and the log tail.

Quick start

git clone https://github.com/wolfgangwarehaus/trackerkeeper.git
cd trackerkeeper
pip install -e .
python -m trackerkeeper          # or: trackerkeeper  (the console script)

Runs straight from a checkout — the flat layout means no install is strictly required (python -m trackerkeeper).

Make it yours

1. Rename the package + set your identity. Rename the trackerkeeper/ package to your app, then set your identity in one place — trackerkeeper/identity.py (org, app, display_name). It's the single source the QSettings handle, the Qt app/org names, the window title, and the Windows AUMID all read. (Or, for programmatic control, call trackerkeeper.configure(org=…, app=…, display_name=…) once, before importing the app — the font-scale loader reads identity at import time.)
2. Boot your content. Call trackerkeeper.run_app(lambda window: YourWidget(window)) — it does the full cross-platform boot (identity, blur, HiDPI, single-instance, persisted theme, window geometry, the settings dialog) and shows your content. (Or, for the quickest start, just edit trackerkeeper/app.py::_placeholder.)
3. Extend the bus. Add your app's signals by subclassing AppBus (trackerkeeper/bus.py); the base stays minimal.
4. Keep it light. Heavy/native deps (a PDF engine, mpv, …) go in [project.optional-dependencies], never the PySide6-only core.

Layout

trackerkeeper/
  app.py          # main() + the placeholder you replace
  window.py       # AppWindow — the frosted cross-platform chrome
  top_bar.py      # the titlebar / top bar
  settings_dialog.py
  bus.py          # AppBus (signal bus)
  settings.py     # slim QSettings wrapper
  theme.py  design_tokens.py  color_tokens.py  ui_helpers.py   # the design system
  blur/  win_frameless.py  frosted_dialog.py  selector.py  icon_button.py  icons.py
  autostart/  notifications/  power/   # per-platform backend pattern
docs/PHILOSOPHY.md

License

GPL-2.0-or-later (matching the warehaus family). It's a starter you own — feel free to relicense your fork.