Skip to content

Commit 75df816

Browse files
0xarchit0xarchit
committed
docs: refactor readme.md
1 parent 144f6d9 commit 75df816

1 file changed

Lines changed: 120 additions & 28 deletions

File tree

‎README.md‎

Lines changed: 120 additions & 28 deletions
Original file line numberDiff line numberDiff line change
@@ -1,70 +1,162 @@
11
<div align="center">
2-
<img src="assets/pauseCat-banner.jpeg" alt="PauseCat Banner" width="80%">
2+
<img src="assets/pauseCat-banner.jpeg" alt="PauseCat Banner" width="85%">
33

4-
# 🐾 PauseCat
4+
# PauseCat
55
**The High-Performance, SaaS-Grade Break Reminder for Windows.**
6-
[![Status](https://img.shields.io/badge/Status-Active%20Development-000000.svg?style=for-the-badge&logo=rocket&logoColor=white&labelColor=000000&color=000000)](https://github.com/0xarchit/pauseCat/pulse)
6+
[![Version](https://img.shields.io/github/v/release/0xarchit/pauseCat?style=for-the-badge&logo=github&logoColor=white&labelColor=000000&color=000000)](https://github.com/0xarchit/pauseCat/releases)
7+
[![Build Status](https://img.shields.io/github/actions/workflow/status/0xarchit/pauseCat/release.yml?style=for-the-badge&logo=githubactions&logoColor=white&labelColor=000000&color=000000)](https://github.com/0xarchit/pauseCat/actions)
8+
[![Downloads](https://img.shields.io/github/downloads/0xarchit/pauseCat/total?style=for-the-badge&logo=rolldown&logoColor=white&labelColor=000000&color=000000)](https://github.com/0xarchit/pauseCat/releases)
79
[![License](https://img.shields.io/badge/License-Apache%202.0-000000.svg?style=for-the-badge&logo=apache&logoColor=white&labelColor=000000&color=000000)](LICENSE)
810
[![Rust](https://img.shields.io/badge/Rust-1.94+-000000.svg?style=for-the-badge&logo=rust&logoColor=white&labelColor=000000&color=000000)](https://rust-lang.org)
9-
11+
1012
---
1113
</div>
1214

13-
## 🌟 Overview
15+
## Overview
1416

15-
PauseCat is more than just a timer. It's a professional-grade Windows utility engineered in **Rust** and powered by **WebView2** to provide a seamless, non-intrusive break experience. Designed for high-performance workstations, it ensures you stay healthy without interrupting your flow with clunky or flickering overlays.
17+
PauseCat is a professional-grade Windows utility engineered in Rust and powered by WebView2 to provide a seamless, non-intrusive break experience. Designed for high-performance workstations, it ensures consistent health intervals without interrupting productivity with inefficient or flickering overlays.
1618

1719
<div align="center">
18-
<img src="assets/pauseCat-break.png" alt="PauseCat Break Interface" width="60%">
20+
<img src="assets/pauseCat-break.png" alt="PauseCat Break Interface" width="70%">
1921
<br>
20-
<em>The immersive, glassmorphic break interface.</em>
22+
<em>The immersive break interface.</em>
2123
</div>
2224

2325
---
2426

25-
## 🚀 Key Features
27+
## Key Features
28+
29+
### Advanced Visual Engine
30+
- **High-Fidelity Overlays:** Utilizes a GDI-based screen capture and pure Rust Gaussian blur implementation for instantaneous, flicker-free break transitions.
31+
- **Glassmorphic UI:** Hardware-accelerated WebView2 host providing a modern, semi-transparent interface with smooth animations and interactive components.
32+
- **Native UX Hardening:** Comprehensive protection against accidental gestures and system-level input interference to maintain application focus.
2633

27-
### 💎 Elite Visuals & UX
28-
- **Ultra-Fast Overlay:** Advanced pre-capture and Gaussian blur engine ensures reminders trigger with zero lag and no white flicker.
29-
- **Pro Designer UI:** Precision sliders for bubble size, glass translucency, and positioning with real-time live preview.
30-
- **Hardened Native UX:** 100% protection against accidental zoom gestures and hidden native scrollbars for a pure application feel.
34+
### Intelligent System Integration
35+
- **Session Awareness:** Monitors Windows Terminal Services (WTS) notifications to detect session locks, unlocks, and system sleep states, automatically pausing and resuming the timer.
36+
- **Media Control Synchronization:** Integration with System Media Transport Controls (SMTC) to intelligently manage background media playback during active break sessions.
37+
- **Theme Synchronization:** Real-time synchronization with Windows system theme preferences for a cohesive desktop experience.
3138

32-
### 🧠 Intelligent Logic
33-
- **Smart Session Guard:** Native awareness of Windows Lock (Win+L) and System Sleep states. The timer pauses and resumes exactly when you are at your desk.
34-
- **Intelligent Media Sync:** Native SMTC integration detects if music/video is playing and only pauses/resumes your media if it was active before the break.
39+
### Technical Excellence
40+
- **Optimized Performance:** Low-overhead Rust implementation resulting in a minimal memory footprint and a compact binary size of less than 2.5 MB.
41+
- **Reliable State Management:** Event-driven architecture powered by a central state machine to ensure consistent behavior across complex system events.
42+
- **Automated Update Pipeline:** Integrated update engine for secure version management and automated deployment via GitHub Releases.
43+
- **Robust Input Validation:** Enforced configuration limits and sanitization for work and break durations to ensure application stability.
44+
45+
---
3546

36-
### 🛠️ Engineering Excellence
37-
- **Lightweight Footprint:** Optimized Rust binary (< 2.5 MB) with shared WebView2 environments for professional resource management.
38-
- **Auto-Update Cycle:** Fully automated self-update system that downloads, installs, and relaunches the application from GitHub Releases.
39-
- **Security First:** Automated CodeQL v4 scanning and pinned GitHub Actions for total supply-chain security.
47+
## Architectural Overview
48+
49+
### System Workflow
50+
```mermaid
51+
graph TD
52+
A[Timer Engine] -- Heartbeat --> B{App State}
53+
B -- Break Triggered --> C[System Bridge]
54+
C -- Check Presence --> D{User Active?}
55+
D -- Yes --> E[Overlay Engine]
56+
D -- No --> F[Pause Timer]
57+
E -- GDI Snapshot --> G[Blur background]
58+
G -- WebView2 --> H[3D UI Layer]
59+
H -- User Dismiss --> I[Reset Timer]
60+
```
61+
62+
### Component Interaction
63+
```mermaid
64+
sequenceDiagram
65+
participant T as Timer Engine
66+
participant S as State Machine
67+
participant U as Updater / Syncer
68+
participant O as Overlay UI
69+
70+
T->>S: Interval Reached
71+
S->>U: Check Asset Integrity
72+
U-->>S: Asset Ready
73+
S->>O: Initialize (Inject Settings)
74+
O-->>S: User Dismissed
75+
S->>T: Resume Heartbeat
76+
```
4077

4178
---
4279

43-
## 💻 Development Workflow
80+
## Project Structure
81+
82+
```text
83+
pauseCat/
84+
├── assets/ # HTML/CSS UI and static assets
85+
├── src/
86+
│ ├── app.rs # Core application state machine
87+
│ ├── events.rs # Internal event definitions
88+
│ ├── main.rs # Entry point and Win32 loop
89+
│ ├── settings.rs # Persistence and configuration
90+
│ ├── system.rs # Win32 system hooks (Media, Theme, Presence)
91+
│ ├── timer.rs # Interruptible high-fidelity heartbeat
92+
│ ├── tray.rs # System tray and notification handler
93+
│ ├── updater.rs # GitHub API client and asset syncer
94+
│ └── overlay/
95+
│ ├── blur.rs # Gaussian blur implementation
96+
│ ├── capture.rs # GDI BitBlt screen capture
97+
│ └── webview.rs # WebView2 host and resource injection
98+
├── tests/ # Integration and unit test suite
99+
└── wix/ # WiX Toolset installer configuration
100+
```
101+
102+
103+
---
44104

45-
### 🛠 Build Standards
46-
To achieve the optimal binary size and performance, always use the following MSVC linker flags:
105+
## Development Workflow
106+
107+
### Prerequisites
108+
- Rust 1.94+
109+
- WebView2 Runtime
110+
- WiX Toolset v4+ (for installer builds)
111+
- UPX (for binary compression)
112+
113+
### Local Setup
114+
1. Clone the repository:
115+
```bash
116+
git clone https://github.com/0xarchit/pauseCat.git
117+
cd pauseCat
118+
```
119+
120+
2. Run in development mode:
121+
```bash
122+
cargo run
123+
```
124+
125+
3. Execute the test suite:
126+
```bash
127+
cargo test
128+
```
129+
130+
### Building for Release
131+
The release pipeline uses advanced link-time optimizations and binary compression.
47132
```powershell
48-
$env:RUSTFLAGS="-C link-arg=/OPT:REF -C link-arg=/OPT:ICF"
133+
# Optimized build with UPX
134+
$env:RUSTFLAGS="-C link-arg=/OPT:REF -C link-arg=/OPT:ICF -C link-arg=/INCREMENTAL:NO"
49135
cargo build --release
136+
upx --best --lzma target\release\pausecat.exe
137+
138+
# Build MSI
139+
wix build wix\main.wxs -ext WixToolset.UI.wixext -ext WixToolset.Util.wixext -o target\release\PauseCat_Installer.msi
50140
```
51141

52-
### 🌿 Git Policy
142+
---
143+
144+
### Git Policy
53145
- **Feature Isolation:** One branch per feature: `feature/<description>` or `fix/<description>`.
54146
- **Conventional Commits:** Use `feat:`, `fix:`, `refactor:`, `chore:`, `test:`.
55147
- **Main is Read-Only:** Never commit directly to `main`.
56148

57149
---
58150

59-
## 🏗 Installation
151+
## Installation
60152

61153
1. Download the latest `PauseCat_Installer.msi` from the [Releases](https://github.com/0xarchit/pauseCat/releases) page.
62154
2. The WiX installer handles everything: installation, autostart registry, and WebView2 runtime checks.
63-
3. Once installed, PauseCat lives in your **System Tray**.
155+
3. Once installed, PauseCat lives in your System Tray.
64156

65157
---
66158

67-
## 🤝 Contributing
159+
## Contributing
68160

69161
We welcome contributions! Please see our [CONTRIBUTING.md](.github/CONTRIBUTING.md) and [CODE_OF_CONDUCT.md](.github/CODE_OF_CONDUCT.md) for details.
70162

0 commit comments

Comments
 (0)