# Pomobar

**Repository Path**: ursusit/pomobar

## Basic Information

- **Project Name**: Pomobar
- **Description**: 内置翻页时钟/白噪音/休息提醒/屏蔽模块。简洁实用。
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-09-13
- **Last Updated**: 2026-10-25

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Pomobar

Tray-first pomodoro timer for Windows 10/11 — tomato timer + fullscreen flip-clock focus mode + 12-sound white-noise mixer + 20-20-20 micro breaks + keep-awake, all local (SQLite), one-time purchase.

> 中文文档：[`README.md`](README.md)

## Highlights

- **Everything in one shell** — timer, flip-clock focus mode, soundscape mixer, eye-care breaks, keep-awake, idle awareness. No need to install four apps.
- **Tray-first & local-first** — start/pause without leaving the tray; no account, no cloud; data stays in local SQLite with CSV export and full JSON backup.
- **One-time purchase** — ¥19.99 (CNY, domestic QR channel) including 1 year of updates; international pricing is pending. Free tier: full timer, today list (3 rows), today stats, 3 basic soundscapes. 14-day all-features trial.
- **Windows-native polish** — tray progress ring, taskbar progress bar, four redundant end-of-phase channels (notification + chime + tray flash + taskbar), global hotkeys.
- **Multi-monitor done right** — micro-break overlays cover every display; the focus clock opens on the monitor holding the cursor.

## Feature map (v1.2, all shipped)

| Area | Features |
|---|---|
| Timer | Authoritative Rust state machine (25/5/15 defaults, 15–90 min focus), four user-configurable quick durations, auto-start toggles, suspension-freeze semantics |
| Tasks | Today list (≤9 rows, single-select as pomodoro label, estimate auto-check) |
| Focus mode | Fullscreen flip clock, countdown/count-up, dark/paper/film themes (Pro), auto-open, keep-awake |
| White noise | 12 synthesized soundscapes, per-track + master volume, 3 mix slots, auto-play on focus, fade-out on phase end |
| Breaks | 20-20-20 micro breaks, per-monitor overlays, offset rule vs pomodoro breaks |
| Stats | Today cards + task distribution, weekly/monthly bars, heatmap, streak, session history, CSV export (Pro) |
| System | Tray ring + menu, taskbar progress, global hotkeys (rebindable), idle auto-pause, autostart, single instance, window position memory, dark/light/system theme, zh/en |
| License | 14-day trial, offline Ed25519 key verification, Paddle Billing issuance worker, in-app update check |

### v1.1 feature pack (F32-F43)

- Per-task report aggregation + interruption/give-up metrics
- Daily pomodoro goal (🍅 n/goal) with celebration; session intentions
- Relocatable data directory (point it at OneDrive/WebDAV); WebDAV backup push/pull (Pro)
- `pomobar://start?minutes=25` deep links + CLI flags for automation
- Custom accent color with automatic AA-contrast derivation; Ocean/Forest/Rose focus themes (Pro)
- Repeating tasks (daily/weekdays/weekly N) with day-rollover generation
- Microsoft To Do import via OAuth device-code flow (Pro); read-only .ics agenda (Pro)
- BYOK AI: weekly review + task breakdown through your own OpenAI-compatible endpoint (Pro)
- Voice announcements (Pro), rotating micro-break guidance, do-not-disturb detection

### v1.2 competitive parity pack (F44-F51)

- Projects (custom colour, archive, per-project stats), single-level subtasks (`1/3` roll-up), inline `#tag` parsing
- Stats switch by task / project / #tag, estimate-vs-actual, 53-week year heatmap, today timeline
- Daily review auto-save → weekly digest includes the latest review snippet
- Four configurable quick-duration pills shared with keys 1-4
- Website blocking via a marked hosts block (one UAC prompt per focus session), auto-restore on end/exit, crash-leftover banner with one-click cleanup (free; ineffective if UAC is declined or the browser uses DoH/encrypted DNS)
- Backup format v2: projects, subtasks, tags, repeat templates, interruptions and reviews survive a round trip

> The 14-day trial is the full product (same features as the paid licence); the free tier starts after it. See PRD §4. Anti-rollback only defeats a clock moved backwards — **deleting the local `settings.json` resets the trial** (offline licence, no hardware fingerprint; disclosed limitation).
>
> Purchase: domestic WeChat/Alipay QR + emailed key (¥19.99 one-time, 1 year of updates). The two QR images under `public/purchase/` must be supplied before release; until then the purchase dialog offers the email contact. The Paddle issuance Worker is implemented but not deployed; see `docs/release.md`.
>
> The in-app update endpoint is the placeholder `updates.pomobar-app.example`; until a real domain is deployed, update checks fail gracefully. The updater public key is configured; the private key is not in the repo.

## Documentation

- [PRD](docs/PRD.md) — positioning, competitor matrix, feature list F1–F31, free/Pro boundary, acceptance criteria
- [UI/UX spec](docs/UIUX.md) — design tokens (WCAG AA), window specs, interaction flows
- [MVP plan](docs/plans/2026-09-13-mvp-plan.md) — 16 tasks, architecture, constraints
- [Acceptance checklist](docs/acceptance-checklist.md) — manual test cases per feature
- [Install & usage](docs/install.md) · [Architecture](docs/architecture.md) · [Privacy](docs/privacy.md) · [Security](docs/security.md) · [Release runbook](docs/release.md)
- [Final handover audit 2026-10-20](docs/reviews/2026-10-20-final-skeptical-review.md) · [Round-8 minimal-granularity re-audit 2026-10-24](docs/reviews/2026-10-24-round8-skeptical-review.md) — confirmed defects, fixes, GUI evidence, residual external dependencies
- Reviews: [2026-09-13 skeptical](docs/reviews/2026-09-13-skeptical-review.md) · [2026-09-30 functional](docs/reviews/2026-09-30-functional-review.md) · [2026-10-02 final](docs/reviews/2026-10-02-final-review.md)

## Toolchain requirements

| Tool | Version | Notes |
|---|---|---|
| Node | ≥ 20 | Node 22 tested |
| pnpm | ≥ 9 | `npm i -g pnpm` or [corepack](https://pnpm.io/installation) |
| Rust | stable ≥ 1.80 (MSRV declared in `src-tauri/Cargo.toml`) | MSVC toolchain (`x86_64-pc-windows-msvc`) |
| MSVC Build Tools | VS 2022 "Desktop development with C++" **+** the **Windows 11 SDK** individual component | Both required. Missing SDK → `LNK1181: cannot open file kernel32.lib` at link time — a toolchain issue, not a project issue |
| WebView2 Runtime | preinstalled on Win 10 21H2+/11 | NSIS uses the WebView2 bootstrapper (downloads it when missing); offline machines need the Evergreen Runtime preinstalled |

> **Build terminal (important)**: do not run `cargo` from Git Bash/MSYS. Its `/usr/bin/link.exe` (coreutils) shadows the MSVC linker and fails with `link: extra operand '...rcgu.o'`. Use a Developer Command Prompt / PowerShell, or a shell where `vcvars64.bat` has run.
>
> **Environment self-check**:
> ```powershell
> Test-Path "C:\Program Files (x86)\Windows Kits\10\Lib"   # False = Windows SDK missing
> where.exe link.exe                                       # first hit must be ...\VC\Tools\MSVC\<ver>\bin\HostX64\x64\link.exe
> ```

## Development

```bash
pnpm install
pnpm tauri dev        # dev app with hot reload
pnpm test             # frontend unit tests (vitest)
cargo test            # Rust unit tests (timer state machine, db, license, digest)
node scripts/contrast-check.mjs   # WCAG AA check for design tokens
```

## Production build

```bash
pnpm tauri build      # NSIS installer under src-tauri/target/release/bundle/nsis/
```

## Repo layout

- `src/` — React frontend; one component tree per window, routed by the `?w=` query
- `src-tauri/` — Rust backend: `timer/` (authoritative state machine + tests), `commands.rs`, `tray.rs`, `taskbar.rs`, `settings.rs`, `db.rs` (SQLite), `idle.rs`, `keep_awake.rs`, `micro.rs` (break scheduler), `digest.rs` (weekly report), `license.rs` (Ed25519)
- `docs/` — PRD / UIUX spec / plan / reviews / assets sources
- `scripts/` — contrast checker, dev-env bootstrap, license keygen CLI, Paddle issuance worker (`scripts/worker/`)

## Data & privacy

All data lives in `%APPDATA%\com.vanxum.pomobar\` (`pomobar.db` + `settings.json`; relocatable via `--data-dir` or Settings). The uninstaller never touches it; Pro can export/import full JSON backups from Settings → General, and each import first writes a `pre-restore-backup.json` safety snapshot. WebDAV/AI/To Do credentials are stored in plain text in the local `settings.json` and are never uploaded by the app; see [`docs/privacy.md`](docs/privacy.md).