docs(03-01): complete JS toolchain plan

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

.planning/ROADMAP.md

@@ -12,8 +12,8 @@ Build a Kimai dashboard widget that displays a GitHub-style activity heatmap of
 
 Decimal phases appear between their surrounding integers in numeric order.
 
-- [ ] **Phase 1: Dev Environment** - Nix flake with local Kimai instance and seeded test data
+- [x] **Phase 1: Dev Environment** - Nix flake with local Kimai instance and seeded test data
-- [ ] **Phase 2: Plugin Scaffold + Data Layer** - Symfony bundle, dashboard widget, aggregation API with PHPUnit tests
+- [x] **Phase 2: Plugin Scaffold + Data Layer** - Symfony bundle, dashboard widget, aggregation API with PHPUnit tests
 - [ ] **Phase 3: Core Heatmap Rendering** - d3.js calendar grid with color mapping, labels, tooltips, theme integration, and JS tests
 - [ ] **Phase 4: Heatmap Interaction** - Click-through navigation, project/activity filtering, interaction tests
 - [ ] **Phase 5: Polish** - Streak indicator, summary stats, weekend styling
@@ -33,7 +33,7 @@ Decimal phases appear between their surrounding integers in numeric order.
 
 Plans:
 - [x] 01-01: Nix flake, process-compose, setup script, .gitignore
-- [ ] 01-02: Plugin scaffold + Kimai bootstrap verification
+- [x] 01-02: Plugin scaffold + Kimai bootstrap verification
 
 ### Phase 2: Plugin Scaffold + Data Layer
 **Goal**: Plugin is recognized by Kimai, shows a widget on the dashboard, and serves aggregated daily time data via API
@@ -44,11 +44,11 @@ Plans:
   2. A widget placeholder appears on the Kimai dashboard
   3. The API endpoint returns JSON with per-day aggregated hours and entry counts, correctly grouped by the user's timezone
   4. PHPUnit tests pass for the data aggregation service and API endpoint
-**Plans**: TBD
+**Plans**: phase-2/PLAN.md
 
 Plans:
-- [ ] 02-01: TBD
+- [x] 02-01: HeatmapService, PHPUnit tests, API controller
-- [ ] 02-02: TBD
+- [x] 02-02: Dashboard widget + template + DashboardSubscriber
 
 ### Phase 3: Core Heatmap Rendering
 **Goal**: The dashboard widget renders a fully styled d3.js calendar heatmap from live Kimai data
@@ -60,13 +60,13 @@ Plans:
   3. Day-of-week labels appear on the Y-axis and month boundary labels along the top
   4. Days with no tracked time render with a distinct "no data" color
   5. Colors use Kimai's theme CSS variables (works with both light and dark themes)
-**Plans**: TBD
+**Plans**: phase-3/PLAN.md
 **UI hint**: yes
 
 Plans:
-- [ ] 03-01: TBD
+- [x] 03-01: JS toolchain — npm, esbuild, TypeScript, Vitest
-- [ ] 03-02: TBD
+- [ ] 03-02: d3 calendar heatmap with color scale, labels, tooltips + Vitest tests
-- [ ] 03-03: TBD
+- [ ] 03-03: Twig template integration + asset serving
 
 ### Phase 4: Heatmap Interaction
 **Goal**: Users can click through to daily details and filter the heatmap by project or activity
@@ -106,8 +106,8 @@ Phases execute in numeric order: 1 -> 2 -> 3 -> 4 -> 5
 
 | Phase | Plans Complete | Status | Completed |
 |-------|----------------|--------|-----------|
-| 1. Dev Environment | 0/2 | Not started | - |
+| 1. Dev Environment | 2/2 | Done | 2026-04-08 |
-| 2. Plugin Scaffold + Data Layer | 0/2 | Not started | - |
+| 2. Plugin Scaffold + Data Layer | 2/2 | Done | 2026-04-08 |
-| 3. Core Heatmap Rendering | 0/3 | Not started | - |
+| 3. Core Heatmap Rendering | 1/3 | In progress | - |
 | 4. Heatmap Interaction | 0/2 | Not started | - |
 | 5. Polish | 0/2 | Not started | - |

.planning/STATE.md

@@ -3,8 +3,8 @@ gsd_state_version: 1.0
 milestone: v1.0
 milestone_name: milestone
 status: executing
-stopped_at: Completed 02-01-PLAN
+stopped_at: Completed 03-01-PLAN.md
-last_updated: "2026-04-08T10:50:36.592Z"
+last_updated: "2026-04-08T11:12:34.889Z"
 last_activity: 2026-04-08
 progress:
   total_phases: 5
@@ -26,7 +26,7 @@ See: .planning/PROJECT.md (updated 2026-04-08)
 ## Current Position
 
 Phase: 2 of 5 (Plugin Scaffold + Data Layer)
-Plan: 1 of 2 in current phase
+Plan: 2 of 2 in current phase
 Status: Ready to execute
 Last activity: 2026-04-08
 
@@ -53,6 +53,7 @@ Progress: [██░░░░░░░░] 20%
 
 *Updated after each plan completion*
 | Phase 2 P02-01 | 5min | 5 tasks | 8 files |
+| Phase 03 P01 | 3min | 4 tasks | 7 files |
 
 ## Accumulated Context
 
@@ -72,6 +73,7 @@ Recent decisions affecting current work:
 - [Phase 1]: PHP memory_limit=1G required for Kimai cache warmup
 - [Phase 1]: process-compose API server disabled (-p 0) to avoid port 8080 conflict
 - [Phase 2]: Removed final from HeatmapService to allow PHPUnit mocking
+- [Phase 03]: IIFE format with KimaiHeatmap global for browser compat
 
 ### Pending Todos
 
@@ -83,6 +85,6 @@ None yet.
 
 ## Session Continuity
 
-Last session: 2026-04-08T10:50:36.590Z
+Last session: 2026-04-08T11:12:34.887Z
-Stopped at: Completed 02-01-PLAN
+Stopped at: Completed 03-01-PLAN.md
 Resume file: None

.planning/phase-3/03-01-SUMMARY.md

@@ -0,0 +1,64 @@
+---
+phase: "03"
+plan: "01"
+subsystem: js-toolchain
+tags: [typescript, esbuild, vitest, d3]
+dependency_graph:
+  requires: []
+  provides: [js-build-pipeline, ts-type-checking, js-test-runner]
+  affects: [assets/, Resources/public/]
+tech_stack:
+  added: [esbuild, typescript, vitest, jsdom, d3-scale, d3-selection, d3-time, d3-time-format, d3-scale-chromatic, d3-array]
+  patterns: [iife-bundle, esm-source]
+key_files:
+  created:
+    - package.json
+    - tsconfig.json
+    - vitest.config.ts
+    - assets/src/heatmap.ts
+    - assets/test/heatmap.test.ts
+    - Resources/public/heatmap.js
+  modified:
+    - .gitignore
+decisions:
+  - "IIFE format with KimaiHeatmap global name for browser compatibility"
+  - "ES2022 target with bundler moduleResolution"
+  - "jsdom environment for vitest d3 testing"
+metrics:
+  duration: "3min"
+  completed: "2026-04-08"
+---
+
+# Phase 3 Plan 01: JS Toolchain Setup Summary
+
+**One-liner:** esbuild + TypeScript + Vitest pipeline for d3 heatmap development with jsdom test environment.
+
+## What Was Done
+
+1. **package.json** -- Created with build/test scripts, installed d3 sub-modules as runtime deps and typescript/esbuild/vitest as dev deps
+2. **tsconfig.json** -- Strict TS config targeting ES2022 with bundler module resolution
+3. **vitest.config.ts** -- jsdom environment with globals enabled
+4. **Placeholder source and test** -- `assets/src/heatmap.ts` stub and passing test in `assets/test/heatmap.test.ts`
+5. **.gitignore** -- Added `.phpunit.result.cache`
+
+## Verification Results
+
+- `npm run build` -- Produces `Resources/public/heatmap.js` (537b minified)
+- `npm test` -- 2 tests pass (570ms)
+- `npx tsc --noEmit` -- No type errors
+
+## Deviations from Plan
+
+### Auto-fixed Issues
+
+**1. [Rule 2 - Missing] Added .phpunit.result.cache to .gitignore**
+- **Found during:** Task 4 verification
+- **Issue:** PHPUnit result cache file was showing as untracked
+- **Fix:** Added to .gitignore
+- **Files modified:** .gitignore
+
+## Commits
+
+| Task | Commit | Description |
+|------|--------|-------------|
+| 1-4  | 032b6f8 | feat: add JS toolchain -- esbuild, TypeScript, Vitest |