diff --git a/README.md b/README.md new file mode 100644 index 0000000..ffa9d0a --- /dev/null +++ b/README.md @@ -0,0 +1,127 @@ +
+ +Boost Focus Timer icon: a pixel-art coffee cup + +# Boost Focus Timer + +A calm, keyboard-friendly focus timer with to-dos, habits, goals and session history. +Runs as a web app or as a browser extension, and keeps every bit of data in your own browser. + +[![CI](https://github.com/ttncode/boost-focus-timer/actions/workflows/ci.yml/badge.svg)](https://github.com/ttncode/boost-focus-timer/actions/workflows/ci.yml) +![Node 24+](https://img.shields.io/badge/node-%E2%89%A524-339933?logo=node.js&logoColor=white) +![Next.js 16](https://img.shields.io/badge/Next.js-16-000000?logo=next.js) +![Data stays local](https://img.shields.io/badge/data-local%20only-374151) + +A focus session in progress: a pixel-art rocket climbs as the countdown runs, with Pause, Done and Reset buttons + +
+ +## What you get + +- **Focus timer** with pause, resume, breaks, extend-on-complete and goal history (press ↑/↓ in the goal field). +- **Pixel-art progress animations** — a coffee cup that fills, a battery that charges, a rocket that lifts off — plus an auto-shuffle option. +- **To-dos** with time estimates, notes, drag-and-drop ordering, a backlog and archive; start a focus session straight from a to-do. +- **Habits** with 7- and 30-day grids and notes per day. +- **Goals** with target dates, comments and archive. +- **Focus summary**: daily focus chart, metrics, week-over-week comparison, time by tag and an editable session log. +- **Boost**: a private feed of notes, links, images and videos to keep yourself motivated. +- **Configurable keyboard shortcuts** for every main action, with an in-app editor (Ctrl+/). +- **No account, no server, no tracking.** Everything is stored in `localStorage` on the device you use. + +| Choose an animation | Plan the day | See your progress | +| --- | --- | --- | +| Animation picker with Coffee Cup, Battery and Rocket cards | To-do list with time estimates, totals and a backlog drop zone | Focus summary with a daily focus bar chart and metric cards | + +## Quick start + +Requirements: **Node.js 24 or newer** (see `.nvmrc`) and npm. + +```bash +git clone https://github.com/ttncode/boost-focus-timer.git +cd boost-focus-timer +npm ci +npm run dev +``` + +Open . To serve an optimized build instead, run `npm run build && npm start`. + +## Install as a browser extension + +The extension is the same app packaged for Chromium-based browsers (Chrome, Edge, Brave, Opera). + +```bash +npm run build:extension +``` + +This writes an unpacked extension to `dist/extension/` and a zip to `dist/boost-focus-timer-extension-.zip`. + +1. Open `chrome://extensions` (or `edge://extensions`) and turn on **Developer mode**. +2. Click **Load unpacked** and select `dist/extension`. +3. Click the toolbar icon to open the timer in a tab. Clicking again focuses the existing tab instead of opening a second timer. +4. Optional: assign a global shortcut for **Open Boost Focus Timer** at `chrome://extensions/shortcuts`. + +Extension data lives in the extension's own storage, separate from the web app's. Firefox is not supported yet. + +## Keyboard shortcuts + +Press Ctrl+/ to open the shortcut list. Click a key to change it, press the new combination, Esc to cancel or Backspace to remove it. **Reset All to Default** restores everything. Assigning a combination that is already in use moves it to the new action. + +| Group | Action | Default | +| --- | --- | --- | +| Navigate | Focus · To-Dos · Habits · Goals · Boost | Alt+1 … Alt+5 | +| | Focus summary | Alt+H | +| | About Me · Tags | Alt+P · Alt+T | +| | Open / close menu | Alt+M | +| Focus timer | Start / pause / resume | Alt+S | +| | Switch focus / break | Alt+B | +| | End or complete session | Alt+X | +| | Edit focus goal · Choose animation | Alt+G · Alt+A | +| | Add tag | Alt+Shift+T | +| Lists | New item on the current page | Alt+N | +| | Post to Boost · Attach media | Ctrl+Enter · Alt+U | +| App | Edit display name | Alt+Shift+N | +| | Show or hide the shortcut list | Ctrl+/ | + +Shortcuts without Ctrl, Alt or Meta are ignored while you type in a field. Hover a button to see its current shortcut. On Linux, Chrome reserves Alt+1…8 for switching tabs; rebind those if they clash. + +
+Keyboard Shortcuts panel listing grouped actions with editable key chips +
+ +## Your data + +All records — sessions, tags, to-dos, habits, goals, posts and settings — are kept in this browser's `localStorage` under keys starting with `bft:`. + +- Nothing is uploaded, and there is no sync between browsers or devices. +- Clearing site data for the app (or removing the extension) deletes everything. +- Images or videos attached to Boost posts are shown for the current session only; after a reload the post keeps its text. + +## Development + +| Command | What it does | +| --- | --- | +| `npm run dev` | Start the dev server on port 3000 | +| `npm run lint` | ESLint | +| `npm run typecheck` | TypeScript, no emit | +| `npm test` | Unit tests with Node's built-in test runner (`tests/`) | +| `npm run build` | Production build (standalone server output) | +| `npm run build:extension` | Static export packaged as a Manifest V3 extension | +| `npm run icons` | Regenerate the app and extension icons from the pixel grid in `scripts/generate-icons.mjs` | +| `npm run check` | Lint, typecheck, test and build — the same gate CI runs | + +Project layout: + +```text +src/app/ Next.js routes, root layout, icons and web manifest +src/components/ The app: shell, focus timer, pages, Boost feed, hotkeys +src/components/lib/ localStorage data layer (local-db) and session helpers +extension/ Extension service worker +scripts/ Icon generator and extension build +tests/ Unit tests +``` + +Built with Next.js 16, React 19, TypeScript, Tailwind CSS 4, dnd-kit and Recharts. + +## Status + +Personal project, used daily by its author. Not affiliated with any company or product of a similar name. There is no open-source license yet, so all rights are reserved; ask before reusing the code. diff --git a/docs/screenshots/animations.png b/docs/screenshots/animations.png new file mode 100644 index 0000000..181ea11 Binary files /dev/null and b/docs/screenshots/animations.png differ diff --git a/docs/screenshots/focus-running.png b/docs/screenshots/focus-running.png new file mode 100644 index 0000000..58ddaca Binary files /dev/null and b/docs/screenshots/focus-running.png differ diff --git a/docs/screenshots/focus-summary.png b/docs/screenshots/focus-summary.png new file mode 100644 index 0000000..cf17fd2 Binary files /dev/null and b/docs/screenshots/focus-summary.png differ diff --git a/docs/screenshots/shortcuts.png b/docs/screenshots/shortcuts.png new file mode 100644 index 0000000..6f7467e Binary files /dev/null and b/docs/screenshots/shortcuts.png differ diff --git a/docs/screenshots/todos.png b/docs/screenshots/todos.png new file mode 100644 index 0000000..b7685f7 Binary files /dev/null and b/docs/screenshots/todos.png differ