Pomodoro for Spotify Car Thing

A focus timer for the Spotify Car Thing, with a shelf of swappable visual designs. Turn the wheel to set the time, press to start, hold to stop. Sessions are logged on the device so you can see today's focus, your streak, and the week behind you.

The Car Thing runs it as a bridgething webapp: a small React app served off the device, driven by its rotary encoder and buttons on an 800x480 screen.

Designs

Thirteen designs, switchable at any time from the design picker. They share one timer and one history; only the presentation changes.

EmberWarm glow, Time Timer dial (default)	E-inkCalm paper, minute by minute	Terminal80x24 phosphor, block digits
Game BoyPixel battle against WORK	Split-flapDepartures board, flipping digits	NixieGlowing tubes, neon lamps
ASCII campfireText-art fire that burns down	DoomWalk the corridor to the exit	BackroomsFound footage, focus in Level 0
MineshaftDig one block per minute	CockpitJetliner engine display, fly each focus as a leg	StarfieldWarp through the stars, recharge on breaks
JournalComputer Modern and TikZ

Controls

The Car Thing has a rotary encoder (the wheel), a press-in knob, four buttons along the top, a mic button, and a back button.

Input	Timer	Design picker	History
Turn wheel	Idle: set the duration. Running: add or remove whole minutes	Move through designs (live preview behind the picker)	Scroll days, clockwise toward today
Press knob	Start, pause, or resume	Apply the highlighted design	Back to the timer
Hold knob (0.7 s)	Stop the active phase, or skip a waiting break	—	—
Button 1 / 2 / 3	Preset 15 / 25 / 45 min	—	—
Button 4	Toggle history	—	Toggle history
Mic button	Open the design picker	Close	—
Back button	—	Close	Close

How the timer works

A classic Pomodoro set is four focus sessions. After each focus session comes a short break; after the fourth, a long break, then the set starts over.

• Defaults: 25 min focus, 5 min short break, 15 min long break.
• Ranges: focus 1-90, short break 1-30, long break 5-60 minutes.
• Focus flows straight into its break. A finished break waits idle, so the next focus starts on purpose.
• Breaks chain from the instant the previous phase ended, not from when the tick noticed, so a 5-minute break is exactly five minutes and never shows 05:01.
• Holding during a long break (stop or skip) ends the set and resets the count.

History

Every finished focus session, and any stopped one longer than a minute, is kept on the device (up to about a year of sessions). The history view shows a week at a time with daily focus totals, the busiest day, and the current streak of consecutive days with a finished session.

The clock

The Car Thing has no battery-backed real-time clock. A systemd guard saves the time every few minutes and restores it at boot, so after a power-off the clock resumes behind by however long the device was off. The app judges whether the clock is believable, strongest evidence first:

1. the paired phone's wall clock, when the gateway supplies one;
2. a logged session that ends in the "future" (the clock went backwards);
3. the boot id (a clock confirmed on a boot stays trusted until the next boot).

Designs surface this as an unobtrusive warning rather than silently logging sessions against a wrong time.

Architecture

Timer logic and presentation are kept apart.

• timer.ts is the pure state machine: press, turn, hold, complete, and history encoding. No React, no device calls.
• model.ts derives a TimerView / HistoryView from that state: everything a design needs to draw, already computed (countdown string, progress, schedule, streak, today's totals).
• Each design under src/themes/<id>/ renders only that view model, plus a matching history screen. Adding a design is a folder and one entry in src/themes/index.ts; it never touches timer logic.
• App.tsx wires device input (wheel, knob, buttons) to the state machine, runs the tick, and handles persistence.

Storage

State is persisted through the bridgething daemon's per-app store, with localStorage as a fallback for the moment before the socket settles and for desktop development where there is no daemon. Keys:

• pomodoro.v1 — timer state (debounced writes)
• pomodoro.history.v1 — session history, in a compact array form
• pomodoro.theme.v1 — selected design
• pomodoro.clock-trust.v1 — the boot id on which the clock was last confirmed

Completion chimes use whichever device earcon looks like a notification sound.

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