Realmheart v0.8.0 — The Shell That Brings Receipts

Realmheart v0.8.0 — The Shell That Brings Receipts

Realmheart v0.8.0 builds on the stability work in v0.7.8, but the headline is not “a few more checks and a better install script.” Doctor and the installer both changed species. Doctor grew into a real diagnostics, incident, and controlled-repair subsystem; the installer became a transactional deployment orchestrator. The event pipeline and shell polish matter too—but these two overhauls are the center of gravity for this release.

What changed

Realmheart Doctor: from checks to a diagnostics system

• realmheart-doctor is now a standalone diagnostic product, not a thin dependency checklist: bounded probes collect concrete evidence and turn it into structured, component-aware health findings.
• Doctor and the installer now share one versioned product model instead of maintaining parallel inventories: 18 components, 63 dependencies, 65 capabilities, 38 artifacts, 59 health checks, and 9 build units.
• Added persistent health/change and incident history, post-update checks, privacy-redacted diagnostic reports, and machine-authored GitHub incident reports.
• Kept diagnosis separate from mutation. Inspection stays read-only; repairs require explicit authorization, privileged repairs require --allow-privileged, and Doctor rechecks the system to report whether a repair actually worked.
• Doctor now also serves as the installer's independent, read-only acceptance reviewer. It returns a clear KEEP, KEEP_WITH_WARNINGS, REVERT_RECOMMENDED, or INDETERMINATE recommendation—while the installer remains responsible for the transaction, final decision, and rollback.

The installer: rebuilt as a transactional deployment system

• Replaced the ad-hoc install flow with a modular Python installer designed to run as the normal desktop user; it asks for narrow elevation only where package or system operations need it.
• Added read-only environment/dependency preflight, source and manifest validation, install-mode detection, and an authoritative plan before any Realmheart transaction begins. --dry-run install shows the plan first.
• The native build runs as the user into an isolated CMake DESTDIR. The installer validates the staged payload before entering the live, journaled transaction.
• Added rollback/adoption/version safety snapshots, durable transaction journaling and recovery, observed-state verification, installed-state receipts, and ownership-aware uninstall.
• Hyprland configuration is managed as a complete tree while preserving hypr/custom/; Kitty and Fish use targeted managed/drop-in integration instead of replacing personal configuration. Privileged auth-helper/PAM changes receive their own verification and rollback accounting.
• The Doctor acceptance review is part of the install's keep-or-revert decision. Doctor cannot perform rollback itself, and the installer does not claim the new shell or FX plugin is active until a fresh session verifies activation.

Events and notifications

• Added the native event protocol, client, daemon, persistence/store layers, rate limiting, and CLI tooling.
• Added an event-focused notification surface for important Realmheart events, with geometry and lifecycle regression coverage.

Shell, workspace, and wallpaper polish

• Improved taskbar battery refresh/runtime estimates and workspace switching by scroll.
• Reduced launcher stalls and corrected secure lock-screen authentication-helper discovery.
• Made wallpaper selection monitor-aware and prevented an incorrect wallpaper flash during startup restoration.
• Improved sidebar transitions and reduced workspace-morph capture overhead.
• Hardened Mana Core wallpaper application so the backend handoff waits for an opaque cover frame’s presentation feedback; improved display-scale preview sizing and regression coverage.

Reliability and regression coverage

• Hardened renderer, service, installer, event, and UI lifecycle boundaries across a broad set of regressions.
• Expanded automated coverage for the new contracts and failure paths.

Verification

• cmake --build build-hybrid -j2 — passed.
• ctest --test-dir build-hybrid --output-on-failure -j1 — 113/113 passed, with one test explicitly skipped (realmheart_shell_effect_view_tests).
• PYTHONPATH=installer python3 -m unittest discover -s tests/installer -t . — 696 tests passed.
• Canonical manifest validation — passed: 18 components, 63 dependencies, 65 capabilities, 38 artifacts, and 9 build units.
• The Mana Core handoff change has automated regression coverage; this release does not claim live visual acceptance of that transition.

Installation

This is a source release. Build Realmheart locally against the host’s GTK, Wayland, Hyprland, and optional native-rendering dependencies. On CachyOS/Arch + Wayland + Hyprland, run python3 installer/realmheart_installer.py --dry-run install as your normal desktop user, review the READY plan, then install only after approving the requested operations. Never run the installer with sudo. See the install guide, installer operations and recovery, and the Doctor instructions in the README.

Full changelog

v0.7.8...v0.8.0

Realmheart is an unofficial fan project inspired by The Beginning After the End. It is not affiliated with TurtleMe, Tapas, Kakao Entertainment, or the series’ rights holders.

Realmheart v0.7.8 — The Great Bug-Fixing Montage

v0.7.8 is the big Realmheart repository-wide remediation release: the bug-fixing montage where the shell, services, renderers, installers, tests, and runtime boundaries all got dragged into the fucking arena.

This is not a single-feature release. It is the accumulated result of the full audit/remediation campaign that followed v0.7.7.

The audit scale

The campaign covered 253 bugs (They overlap each other ofc, not independant 253 bugs):

Severity	Findings
Critical	3
High	69
Medium	129
Low	52

Those 253 entries are an audit-finding count, not a claim of 253 independent bugs. The reports intentionally overlap: shared root causes were fixed once, then downstream findings were revalidated against the corrected primitive instead of receiving a pile of contradictory local patches.

What got hardened

Execution, lifetime, and shutdown

• Bounded shared work queues, cancellation, stale-generation handling, and shutdown behavior.
• Callback, timer, worker, renderer, and helper-process lifetime boundaries across repeated startup, restart, monitor replacement, and teardown.
• Truthful command/action results instead of reporting success after a failed launch, flush, or child process.
• Safer restart handshakes and bounded helper shutdown rather than letting the shell wait forever.

Hyprland, Wayland, and monitor state

• Bounded/nonblocking compositor queries and safer GTK-thread boundaries.
• Monitor identity, output reordering, hotplug, scale changes, workspace routing, and stale-state reconciliation.
• Fail-closed lock-submap behavior and explicit recovery when compositor state cannot be established or restored.
• Removal of incorrect “use another monitor's state” fallbacks for display-specific data.

Security and authentication

• Hardened PAM/helper ownership, privilege boundaries, protocol validation, deadlines, failure handling, and password lifetime.
• Removed credential exposure from command-line paths.
• Strengthened path containment, temporary-file handling, symlink/hardlink defenses, and bounded untrusted input/file I/O.
• Reworked the native Broken Seal routing so normal lock sources use Realmheart's lock flow, with hyprlock reserved as a fail-closed emergency fallback.
• Fixed the final post-authentication session-lock teardown crash so successful unlock no longer takes the shell down with it.

Rendering, effects, assets, and wallpaper

• GL/GTK renderer ownership, context recovery, shader validation, effect fallback, and plugin lifecycle handling.
• Installed asset discovery and source/install-root separation for Realmheart-FX, shaders, characters, wallpapers, and other runtime resources.
• Bounded image, thumbnail, cache, mesh, shader, and output allocations.
• Transactional wallpaper prepare/commit/persistence behavior and safer native-renderer recovery.
• Numeric edge handling for animation meshes, flow warp, springs, geometry, dimensions, and non-finite values.

Services and desktop integrations

• Media/MPRIS reconnection, audio fallback/restart, battery/system telemetry, and bounded metadata/artwork work.
• Wi-Fi, Bluetooth, power profiles, GameMode, Night Light, KeepAwake, and notification lifecycle correctness.
• Sidebar/taskbar state refresh, monitor changes, coalescing, unavailable-state reporting, and stale callback cleanup.
• Launcher command deadlines/output bounds and truthful command receipts.
• Notes ordering, durability, secure persistence, bounded retries, and failure reporting.
• Screenshot/OCR bounds, Lens handoff, clipboard/export behavior, and failure-status propagation.
• Workspace Overview, Mana Core, power-menu lifecycle, geometry, asset fallback, and action-result handling.

Installation and test truthfulness

• Hyprland configuration installation, clean-account setup, backup/overwrite behavior, service generation, PAM placement, FX loading, custom prefixes, and installed-tree discovery.
• Regression coverage for authentication, session handling, lock routing, installer behavior, installed assets, and shared service contracts.
• Test isolation and registration fixes so suites do not quietly pass against the ambient desktop, skip the behavior they claim to test, or leave detached processes and staging artifacts behind.

Verification

• Lock-routing contract tests passed.
• Hyprland installer clean-home and rerun contracts passed.
• The final Broken Seal authentication and unlock path was verified live: authentication succeeds, the animation completes, and Realmheart remains running.
• The release is a source release. Realmheart builds locally against the host's GTK, Wayland, Hyprland, and optional native-rendering dependencies.

The audit count should be read honestly: overlapping findings were consolidated, and some compositor/display behaviors still depend on the target machine and live environment. The point of this release is that the repository's failure boundaries, cleanup paths, install contracts, and regression coverage were systematically hardened instead of patched one symptom at a time.

Supported baseline

The release keeps the native Linux baseline described in the README: CachyOS/Arch Linux, Hyprland with the matching FX-plugin ABI, GTK 4.22 tested with GTK 4.12 as the minimum, and the native Wayland/EGL wallpaper backend. Read the installation and compatibility sections before deploying onto a heavily customized Hyprland setup.

The realmheart-fx.so plugin remains part of the shell's functional runtime rather than an optional decoration. Rebuild it after Hyprland updates because its ABI is compositor-version coupled.

Installation

cd ~
git clone --branch v0.7.8 https://github.com/kzahed610/Realmheart.git
cd Realmheart

Then follow the build, dependency, installer, and realmheart --doctor instructions in the README.

Full changelog

v0.7.7...v0.7.8

Realmheart is an unofficial fan project inspired by The Beginning After the End. It is not affiliated with TurtleMe, Tapas, Kakao Entertainment, or the series' rights holders.

Realmheart v0.7.7 — Stable as Far as Linux Allows It

This is the first Realmheart release I am comfortable calling stable on a specific, tested setup.

v0.7.7 was verified from a clean CachyOS account rather than only my development account. The complete path was exercised: fresh configure, build, test suite, dependency checks, config installation, logout/login, systemd startup, FX loading, and live visual inspection.

If your machine matches the baseline below and you install the dependencies first, Realmheart should behave like the showcase instead of turning into an archaeological dig through paths from my machine.

Supported baseline

Component	Validated target
Distribution	CachyOS / Arch Linux
Compositor	Hyprland 0.56.2 (0.56.x plugin ABI)
Display	1920x1080 at 60 Hz
Scale	1
GTK	4.22 tested; 4.12 minimum
Wallpaper backend	Native Wayland/EGL

This is a deliberately narrow compatibility claim. Ultrawide, 4K, fractional scaling, mixed multi-monitor setups, older Hyprland releases, and distributions outside the Arch family are still experimental.

What you should expect to work

On the supported baseline, the current release includes:

• Realmheart starting automatically as a systemd user service after login.
• The required realmheart-fx.so plugin loading automatically at Hyprland startup.
• The vertical taskbar, workspace previews, system statistics, media controls, battery details, clock, notifications, and quick notes.
• The launcher with app search, window focusing, calculator, fish commands, clipboard history, and the full emoji index.
• The right sidebar with Wi-Fi, Bluetooth, volume, brightness, Night Light, power profiles, GameMode, and notification history.
• Native wallpaper rendering, wallpaper switching, and matugen-driven theme regeneration.
• Workspace overview and the Mana Core Selector.
• The Broken Seal lock screen with PAM authentication.
• The animated power menu and compositor-driven Realmheart window effects.
• Screenshots, region capture, and recording when their optional command-line dependencies are installed.

What changed since v0.7.6

Fresh-account installation

• Added the complete portable Hyprland configuration tree used by Realmheart.
• Added install-hypr-configs.sh, including timestamped backups for files it replaces.
• Added a generated realmheart.service user unit and automatic shell startup.
• Added automatic installation and startup of the FX loader.
• Fixed the first-run Lua reload race where hyprland.lua could load before realmheart_fx.lua existed.
• Fixed sudo-aware home resolution so config installation does not accidentally target /root.
• Added a regression test that exercises both a clean HOME and a second installer run.

Portable runtime discovery

• FX assets now resolve from the plugin location instead of depending on the development machine's absolute source path.
• Power-menu, workspace, and lock-screen shaders can locate their assets after the repository is copied to another account.
• Stale CMake caches from another checkout/account are detected instead of failing later with cryptic path errors.

Visual cleanup

• Removed inherited light GTK backgrounds from every Realmheart layer window.
• Fixed the white lock-screen background seen on clean accounts.
• Fixed white system-stat, media-control, and notification-dismiss buttons.
• Fixed white workspace/battery popover arrows.
• Removed the white borders around system-usage progress bars.

Launcher, configs, and project packaging

• Shipped the full emoji index in both the Fuzzel script and compiled fallback.
• Added and corrected the default Realmheart application keybinds.
• Added the public screenshot gallery, showcase video, and Void showcase wallpaper.
• Added the GPL-3.0 license and rewrote the README around the actual supported setup.

The FX plugin is required

realmheart-fx.so is part of the shell, not an optional decoration. The lock screen, power menu, and Realmheart's window transitions depend on it.

The build should produce:

build-hybrid/realmheart-fx.so

If CMake reports Realmheart FX plugin disabled, stop and install the matching Hyprland/GLES development files before continuing. The installer handles loading the plugin; you do not need a manual hyprctl plugin load command.

The plugin is compiled against Hyprland's internal ABI. Rebuild Realmheart after every Hyprland update and start a fresh Hyprland session before loading it again.

Installation expectations

v0.7.7 is a source release. GitHub provides the source archives; Realmheart must be built locally against your installed GTK, Wayland, and Hyprland stack.

For the supported automatic-loader path, clone it as ~/Realmheart:

cd ~
git clone https://github.com/kzahed610/Realmheart.git
cd Realmheart

Then follow the tagged build and installation instructions, including the dependency installation and realmheart --doctor check.

install-hypr-configs.sh installs Realmheart's opinionated Hyprland configuration, the FX loader, and the user service. Existing destination files receive timestamped .bak copies. Read the installer section before running it if you already maintain a heavily customized Hyprland setup.

After the first install, log out and back into Hyprland. A plain hyprctl reload does not replay the hyprland.start hooks that launch the service and FX plugin.

Verification receipts

This tag was cut only after the following passed:

• Clean CMake configure and complete build.
• Required realmheart-fx.so artifact present.
• 69/69 (NICE) CTest tests passed.
• realmheart --doctor found every dependency on the validation machine.
• Clean-account installer first run and overwrite/backup rerun passed.
• Realmheart user service started successfully after login.
• FX plugin and shader assets resolved from the clean account.
• Live visual verification of the lock screen, taskbar popovers, system statistics, media controls, and notification controls.

Full changelog

v0.7.6...v0.7.7

Realmheart is an unofficial fan project inspired by The Beginning After the End. It is not affiliated with TurtleMe, Tapas, Kakao Entertainment, or the series' rights holders.