Imported from heldernoid/agentic-build-templates (projects/automation-productivity/pomodoro-dashboard/AGENTS.md). Install upstream with npx skills add heldernoid/agentic-build-templates --skill pomodoro-dashboard. Copyright stays with the author.

pomodoro-dashboard - Build Instructions

Stack

• React 18 + TypeScript + Vite (SPA, no backend required)
• Tailwind CSS for utility classes
• localStorage for all persistence (sessions, tasks, settings, stats)
• Web Audio API for tick sound and alarm bell
• Notification API for desktop alerts
• Optional: SQLite via better-sqlite3 if an optional stats export server is added

Package manager

Use pnpm exclusively. Never use npm or yarn.

pnpm install
pnpm dev
pnpm build
pnpm typecheck
pnpm test

Code standards

• TypeScript strict mode. Zero any types. All function parameters and return types annotated.
• Node.js built-in imports use the node: prefix where applicable (server-side code only).
• No emojis anywhere in code, comments, or output strings.
• No em dashes in any text. Use a regular hyphen or rewrite the sentence.
• English only in all user-facing strings.
• Boolean environment variables represented as 0 or 1, never "true" or "false".
• All React components are function components with typed props.
• State lives as close to its consumer as possible. Lift only when necessary.

Project structure

pomodoro-dashboard/
  src/
    App.tsx
    main.tsx
    lib/
      storage.ts       # localStorage read/write wrappers
      timer.ts         # countdown logic, interval management
      audio.ts         # Web Audio API tick and alarm
      stats.ts         # session aggregation helpers
      notifications.ts # Notification API wrapper
    components/
      Timer.tsx
      TimerControls.tsx
      TaskList.tsx
      TaskItem.tsx
      StatsPanel.tsx
      SettingsModal.tsx
      HeatmapChart.tsx
      ProgressRing.tsx
    pages/
      Dashboard.tsx
      Stats.tsx
      Tasks.tsx
      Settings.tsx
    types/
      index.ts
  index.html
  vite.config.ts
  tsconfig.json
  package.json

Checkpoint format

After each part, write results to TEST_REPORT.md using this format:

## Part N - [name] - YYYY-MM-DD

### Build
- pnpm build: PASS
- pnpm typecheck: PASS

### Tests
- pnpm test: N passed, 0 failed

### Notes
...

Stop and wait for "go ahead" before proceeding to the next part.

Timer accuracy

Use Date.now() snapshots, not cumulative interval ticks, to compute elapsed time. This prevents drift when the browser tab is backgrounded. On each tick, compute remaining = endTime - Date.now().

localStorage schema

All keys prefixed with pomo_:

• pomo_settings - JSON object with durations and preferences
• pomo_tasks - JSON array of task objects
• pomo_sessions - JSON array of completed session records
• pomo_state - current timer state (for page reload recovery)

Security baseline

• No network requests (pure SPA).
• No eval or dynamic code execution.
• Notification permission requested only on explicit user action (never on page load).
• Audio context created only after a user gesture (browser policy).

Design

Follow DESIGN-SPECS.md and all files in design-mocks/ exactly. Do not invent UI not shown in the mocks.