Release: Wombat

Wombat is the current DocsHub architecture.

Read the Roadmap

Glint architecture and maintenance #

This page describes the Glint 1.x codebase and maintainer workflow. For installation, controls, configuration, and platform notes, start with the Glint user documentation.

Design goals #

Glint is deliberately small, native, and local-only. Changes should preserve:

• direct Qt painter rendering without a browser or web runtime;
• graceful behavior when optional sensors or desktop capabilities are absent;
• isolation of platform-specific behavior behind runtime checks;
• local JSON preferences without accounts, telemetry, or a network service;
• one shared application path across Windows, macOS, and Linux; and
• minimal GitHub-exclusive packaging.

Repository structure #

main.py                         source convenience entry point
src/app.py                      QApplication, HUD, and tray lifecycle
src/core/sensors.py             portable and platform-specific sensor probes
src/core/settings_storage.py    validated, atomic JSON preferences
src/core/theme.py               bundled theme loading and colors
src/core/stats.py               pre-1.0 stats API compatibility wrapper
src/ui/hud.py                   frameless painter-rendered HUD and dragging
src/ui/settings.py              independent top-level Settings window
src/ui/tray.py                  tray actions and portable autostart entries
src/ui/layout.py                layout validation, creation, and persistence
src/ui/widgets/                 serializable painter widget classes
src/ui/lin_hud.py               pre-1.0 import compatibility alias for hud.py
src/ui/menu.py                  pre-1.0 launcher compatibility shim
src/themes.json                 bundled Default and Midnight themes
scripts/release.py              tag validation, PyInstaller builds, checksums
tests/                          core, UI, and release behavior tests
.github/workflows/              cross-platform checks and tagged releases

src.app:main creates one QApplication, applies the stable ZFordDev/Glint identity, shows GlassHUD, and installs TrayManager. The glint console command and python -m src use this same entry point.

Rendering and sampling #

GlassHUD is a frameless translucent tool window. It requests the bottom window layer when Qt and the desktop support that hint. A low-priority worker thread samples metrics at the configured interval and pushes results to the GUI thread over a queued connection, so dragging and painting never wait on sensor probes; shutdown cancels an in-flight sample cooperatively.

The sensor layer returns a stable dictionary regardless of platform. It uses:

• psutil for CPU, RAM, disks, network counters, and exposed temperatures;
• WMI on Windows as an optional CPU-temperature and GPU-usage fallback; and
• nvidia-smi when installed for NVIDIA usage and temperature.

On Windows the vendor-neutral GPU-counter fallback filters to 3D engine instances server-side and backs off automatically when a probe responds slowly, serving cached values until the provider becomes cheap again.

Optional probe failures are logged at debug level or converted to None. Widgets render missing values as unavailable rather than treating them as an application error.

Configuration lifecycle #

settings_storage.py validates every value before use. Refresh intervals are limited to 250–60,000 milliseconds and opacity to 20–100 percent. Invalid, unreadable, or missing data falls back to defaults. Saves use a temporary file followed by replacement to avoid leaving partially written JSON.

Layouts use the same configuration directory and validate widget types and geometry fields before instantiation; unreadable or malformed layout data falls back to defaults. HUD size and widget definitions are saved on a normal exit. The Settings window intentionally has no native parent: parenting it to the frameless HUD can make desktop environments present it as an attached tool panel instead of an independent window.

HUD movement first asks the window manager to perform a system move. This is required for Wayland and is also a good native path elsewhere. Manual global coordinate movement remains as a fallback, and the final position is persisted when the pointer is released.

Development workflow #

Install the development profile from the repository root:

python -m venv .venv
# Windows: .venv\Scripts\activate
# macOS/Linux: source .venv/bin/activate
python -m pip install -e ".[dev]"
ruff format --check .
ruff check .
python -m pytest
python main.py

Dependencies and optional development or release tools are declared only in pyproject.toml. Do not recreate a parallel requirements.txt dependency source.

GitHub’s Python checks run the formatter check, linter, and tests with Python 3.10 on Windows, macOS, and Linux. Qt uses its offscreen platform during CI, and Linux runners install the small set of system libraries required by Qt. Platform-sensitive changes still need focused testing on a real desktop.

Packaging and release process #

Glint uses PyInstaller on native GitHub-hosted runners. It produces separate Windows x86-64, macOS arm64, macOS x86-64, and Linux x86-64 archives. Stores, installers, package repositories, and the legacy updater are outside the 1.x distribution model.

For a release:

1. Update project.version in pyproject.toml and the changelog.
2. Merge the tested release change to main.
3. Create and push a matching tag such as v1.0.1.
4. Let the GitHub Release workflow verify the tag/version pair and all checks.
5. The workflow builds every native bundle, generates SHA256SUMS, and publishes the tagged GitHub Release only after all builds succeed.

The workflow’s manual rehearsal mode runs verification and builds without publishing. Publishing manually requires an existing matching tag. Releases are unsigned, so release notes should remind users about operating-system trust prompts and checksum verification.

Maintenance boundaries #

• Preserve unavailable-sensor fallbacks; sensor support cannot be guaranteed uniformly across hardware and operating systems.
• Treat Wayland window stacking as compositor policy, not a state Glint can force.
• Keep the Settings window top-level and test HUD dragging whenever Qt window flags change.
• Update the README, changelog, DocsHub release line, user page, and this page when supported platforms, packaging, or user-visible behavior changes.

Contribution guidance and the private vulnerability-reporting process live in the repository’s CONTRIBUTING.md and SECURITY.md.