Pomodoro Ledger

A task-focused Pomodoro timer served from Cloudflare's edge. The web app in web/ (Svelte 5 and TypeScript) is built with Vite into dist/, which Cloudflare serves as static assets; a small Worker in src/ powers shared rooms and account sync.

Features

• Tasks with notes, checklists and cycle estimates, planned into Today, Upcoming days or Later
• Optional Today sections, a day plan with focus vs. time with breaks, and estimated start times
• Quick entry that reads days and estimates from the title, a When popover, and keyboard shortcuts (press ?)
• Labels, filters, focus history, charts, and finished-task tracking
• Sessions you forgot to time added by hand, and ones that ran too long corrected, marked as by hand in the journal
• Recurring tasks (daily, weekdays, chosen weekdays, monthly, or every few days, weeks or months), and unfinished tasks that roll over to today: always, ask, or never
• Your best time of day for focus, and a weekly recap that opens on the first visit of a new week
• Configurable timers, optional gentle ticking, and a floating Picture-in-Picture timer
• Optional soundscapes during focus (rain, ocean waves, a fireplace or brown noise), generated in the browser so nothing loops
• Installable as an app on phones (PWA) that opens offline, with a full-screen timer page and bottom tabs
• Optional sign-in to sync tasks, history, settings, and the running timer between devices
• Temporary shared rooms that sync timer status while keeping tasks and history private
• Public rooms to drop into, where everyone's timer follows the room's clock
• Quick reactions in rooms (👋 🎉 🔥 👍 ☕), with a one-tap 🎉 after each round
• A shared goal for a room you start (say 12 rounds), filled by every focus round anyone in it finishes
• A status on your face in rooms (deep in it, stuck, back in 2, wrapping up), set from your own face or keys 1–4

Project layout

web/                 the app (Vite root)
  index.html         page shell the components mount into
  src/main.ts        boot: global listeners, mounting the components, first render
  src/state.ts       shared state (tasks, settings, the timer) and the local/session storage helpers
  src/store.ts       saving tasks, settings and labels: this browser, or the account when signed in
  src/cloud.ts       account sync over a WebSocket, last write wins
  src/render.ts      redraws the components after a change
  src/ui.ts          handles to the mounted dialogs and popovers
  src/keys.ts        app-wide keyboard shortcuts
  src/sound.ts       bells and the optional ticking
  src/soundscape.ts  soundscapes during focus, made in an AudioWorklet (scapeWorklet.ts, lib/scapeSynth.ts)
  src/float.ts       the floating Picture-in-Picture timer
  src/layout.ts      dialog overlays and fitting the timer dial to the window
  src/pages.ts       phone pages; src/zen.ts full screen
  src/lib/*.ts       pure, tested logic: dates, the When parser, quick entry, list order, stats, settings, the timer dial, rooms, export files
  src/timer/         the timer engine (engine.ts) and the timer card
  src/tasks/         task helpers, actions, start-time plan and the task list
  src/progress/      the Progress page and its session actions
  src/composer/      the new-task box
  src/popovers/      the When, label and menu popovers
  src/settings/      the Settings dialog, and export and import
  src/room/          shared-room networking (net.ts) and its dialog and strip
  src/chrome/        top bar tools, banner, shortcut sheet, toast and tooltip
  src/styles/app.css styles
  public/            copied as-is: service worker, manifest, icons
src/                 Cloudflare Worker: rooms and the public room lobby (worker.js), sync (sync.js) and landing page counts (hits.js)
extension/           an experimental site blocker browser extension, not released (see extension/README.md)
tests/               Worker tests (node:test)

Develop

npm install
npm run dev      # builds, rebuilds on change, and serves app + Worker on http://localhost:8787
npm test         # type check, app unit tests (Vitest), Worker tests

npm run dev rebuilds on every save; reload the page to see changes.

Deploy

You need Node.js 20 or newer and a free Cloudflare account.

npm install
npx wrangler login     # opens a browser to authorize, once per machine
npm run deploy

npm run deploy builds the app and deploys it with the Worker. Wrangler prints your URL, for example https://pomodoro-ledger.<your-subdomain>.workers.dev.

To deploy from CI instead of wrangler login, set CLOUDFLARE_API_TOKEN (template "Edit Cloudflare Workers") and CLOUDFLARE_ACCOUNT_ID.

The YEAR_IN_FOCUS repository variable (or secret) decides when Year in focus shows up: on (the default when unset), off, a start day such as 2026-12-01, or a window such as 2026-12-01..2027-01-15. Dates are checked in the browser, so a window opens and closes on its own; changing the value needs a new deploy.

Demo data

Open /?demo=1 to force an interactive demo, for example http://localhost:8787/?demo=1. Demo changes stay in memory, reset on reload, and never affect the saved ledger. An unused browser profile also shows the example data automatically.

Data storage

Tasks, history, labels, and settings are always kept in the browser's local storage, so the app works offline. Without sign-in they stay on that device.

Settings → Data & sync → Export downloads all of it as one JSON file (pomodoro-ledger-YYYY-MM-DD.json), with or without an account. Import reads that file, or one from the account export, and shows what it holds before changing anything. Merge is the default: it adds new tasks, keeps the newer copy of each task as sync does, and keeps sessions from both copies. Replace makes this browser match the file and asks again first. The demo (?demo=1) can't export or import.

This is the beginning of the README. Read the rest at the original. Read the full README ↗