docs(phase-08): complete phase execution

- getHourlyAggregation with timezone-correct CONVERT_TZ
- getDayHourAggregation with weekStart-relative day index
- getUserCustomers and getUserActivities cascade queries
- activity/customer filter params on getDailyAggregation
- Inject EntityManagerInterface for testable DBAL access

.planning/PROJECT.md

@@ -23,9 +23,21 @@ At a glance, see where your time went — a visual map of tracking activity that
 
 ### Active
 
-- [ ] Heatmap cells toggle between hours-per-day and entry-count display
-- [ ] Configurable time range (not locked to a single preset)
-- [ ] Activity filtering (project filter shipped, activity deferred)
+- [ ] Switchable visualization modes (year, week, day, combined day/hour)
+- [ ] Native TomSelect entity pickers with customer→project→activity cascade
+- [ ] Activity filtering via cascading pickers
+- [ ] Toggle between hours-per-day and entry-count display
+- ✓ Mode switcher (year/week) and metric toggle (hours/count) — Phase 7
+
+## Current Milestone: v1.1 Modes & Filtering
+
+**Goal:** Multiple visualization modes and richer filtering using Kimai-native UI components
+
+**Target features:**
+- Switchable views: year-mode, week-mode (day-of-week), day-mode (time-of-day), combined day/hour
+- Native TomSelect entity pickers replacing plain `<select>` — customer→project→activity cascade
+- Activity filtering (descoped from v1.0)
+- Toggle between hours-per-day and entry-count display
 
 ### Out of Scope
 
@@ -34,7 +46,7 @@ At a glance, see where your time went — a visual map of tracking activity that
 - Export/sharing of heatmap images — no audience for personal use
 - Real-time updates — refresh on page load is fine
 - Custom color theme picker — Kimai theme integration is sufficient
-- Hour-of-day matrix — different visualization, scope creep
+- Configurable time range selector — deferred to future milestone
 - Multi-user comparison — personal tracking tool
 
 ## Context
@@ -64,4 +76,4 @@ Dev environment: Nix flake with process-compose, MariaDB 11.4, Kimai 2.52.0.
 | Descope activity filtering | Project filter sufficient for personal use | ✓ Acceptable |
 
 ---
-*Last updated: 2026-04-08 after v1.0 milestone*
+*Last updated: 2026-04-09 after Phase 7 complete*

.planning/REQUIREMENTS.md

@@ -0,0 +1,84 @@
+# Requirements: Kimai Heatmap Plugin v1.1
+
+**Defined:** 2026-04-08
+**Core Value:** At a glance, see where your time went -- a visual map of tracking activity that makes patterns obvious
+
+## v1.1 Requirements
+
+Requirements for Modes & Filtering milestone. Each maps to roadmap phases.
+
+### Visualization Modes
+
+- [ ] **VIZ-01**: Mode switcher UI allows toggling between year, week, day, and combined views
+- [ ] **VIZ-02**: Week-mode renders day-of-week aggregation showing which weekdays are busiest
+- [ ] **VIZ-03**: Day-mode renders time-of-day heatmap showing when during the day work happens
+- [ ] **VIZ-04**: Combined mode renders 7x24 day/hour punchcard matrix
+- [ ] **VIZ-05**: Hours vs entry-count toggle switches color scale metric across all modes
+
+### Entity Pickers & Filtering
+
+- [ ] **FILT-01**: Customer->project->activity cascading TomSelect pickers replace plain <select>
+- [ ] **FILT-02**: Activity filtering narrows heatmap data to a specific activity
+- [ ] **FILT-03**: Customer filtering narrows heatmap data to all projects under a customer
+
+### Backend
+
+- [ ] **API-01**: API endpoint accepts mode param returning hour-level and day/hour aggregation data
+- [ ] **API-02**: API endpoint accepts activity and customer filter params with own controller endpoints
+
+### Polish
+
+- [ ] **POL-01**: Color scale legend gradient bar showing value range for current mode/metric
+
+### Testing
+
+- [ ] **TEST-01**: Vitest tests for mode switcher, each renderer, and display toggle
+- [ ] **TEST-02**: Vitest tests for TomSelect cascade behavior and filter integration
+- [ ] **TEST-03**: PHPUnit tests for hour-level and day/hour aggregation queries
+
+## Future Requirements
+
+- Configurable time range selector (3 months, 6 months, year, custom)
+- Persistent filter/mode state via URL params or localStorage
+- Animated transitions between visualization modes
+- Responsive widget sizing adapting to dashboard column width
+
+## Out of Scope
+
+| Feature | Reason |
+|---------|--------|
+| Billable vs non-billable split | Personal time tracking, not client billing |
+| Real-time / live updates | Page reload sufficient for daily-granularity data |
+| Export/share heatmap as image | No audience for personal use |
+| Multi-user comparison | Personal tracking tool |
+| Mobile-specific layout | Desktop Kimai dashboard only |
+| Reuse Kimai's KimaiFormSelect.js | Coupled to Kimai's plugin container, cannot work in widget context |
+| Reuse Kimai's API routes for pickers | Require IsGranted('API') permission, need own endpoints |
+
+## Traceability
+
+| Requirement | Phase | Status |
+|-------------|-------|--------|
+| VIZ-01 | Phase 7 | Pending |
+| VIZ-02 | Phase 7 | Pending |
+| VIZ-03 | Phase 9 | Pending |
+| VIZ-04 | Phase 9 | Pending |
+| VIZ-05 | Phase 7 | Pending |
+| FILT-01 | Phase 10 | Pending |
+| FILT-02 | Phase 8 | Pending |
+| FILT-03 | Phase 8 | Pending |
+| API-01 | Phase 8 | Pending |
+| API-02 | Phase 8 | Pending |
+| POL-01 | Phase 9 | Pending |
+| TEST-01 | Phase 7 | Pending |
+| TEST-02 | Phase 10 | Pending |
+| TEST-03 | Phase 8 | Pending |
+
+**Coverage:**
+- v1.1 requirements: 14 total
+- Mapped to phases: 14
+- Unmapped: 0
+
+---
+*Requirements defined: 2026-04-08*
+*Traceability updated: 2026-04-08*

.planning/ROADMAP.md

@@ -3,6 +3,7 @@
 ## Milestones
 
 - ✅ **v1.0 MVP** — Phases 1-5 (shipped 2026-04-08) — [archive](milestones/v1.0-ROADMAP.md)
+- 🚧 **v1.1 Modes & Filtering** — Phases 6-10 (in progress)
 
 ## Phases
 
@@ -17,8 +18,92 @@
 
 </details>
 
+### v1.1 Modes & Filtering
+
+- [ ] **Phase 6: Renderer Architecture** - Refactor monolithic renderHeatmap into strategy-pattern mode system with state management
+- [ ] **Phase 7: Mode Switcher + Week Mode** - First visible v1.1 feature: mode switcher UI, week-mode renderer, hours/count toggle
+- [ ] **Phase 8: Backend Aggregation + Filtering** - Hour-level and day/hour aggregation queries, activity/customer filtering, custom endpoints
+- [ ] **Phase 9: Day + Combined Modes** - Day-of-week and time-of-day renderers, combined punchcard matrix, color scale legend
+- [ ] **Phase 10: Entity Pickers** - TomSelect cascading customer/project/activity pickers replacing plain selects
+
+## Phase Details
+
+### Phase 6: Renderer Architecture
+**Goal**: Existing year-view heatmap works identically but through a mode-dispatched renderer system ready for new visualization modes
+**Depends on**: Phase 5 (v1.0 shipped codebase)
+**Requirements**: None (architectural enabler -- all v1.1 features depend on this refactor)
+**Success Criteria** (what must be TRUE):
+  1. Year-view heatmap renders identically to v1.0 behavior (no visual regression)
+  2. Tooltip, color scale, and cell click handler are extracted as shared utilities reusable by any renderer
+  3. A HeatmapState object tracks mode, display metric, and filters -- UI changes flow through state
+  4. Adding a new visualization mode requires only implementing a ModeRenderer interface and registering it
+**Plans:** 2 plans
+Plans:
+- [x] 06-01-PLAN.md — Type contracts, state, registry, and shared utility extraction
+- [x] 06-02-PLAN.md — YearModeRenderer, orchestrator rewrite, test migration, visual check
+
+### Phase 7: Mode Switcher + Week Mode
+**Goal**: Users can switch between year and week visualization modes and toggle between hours and entry-count display
+**Depends on**: Phase 6
+**Requirements**: VIZ-01, VIZ-02, VIZ-05, TEST-01
+**Success Criteria** (what must be TRUE):
+  1. A segmented control in the widget header lets the user switch between year and week views
+  2. Week-mode shows a day-of-week aggregation heatmap revealing which weekdays are busiest
+  3. Hours/count toggle switches the color scale metric across both year and week modes without re-fetching data
+  4. Switching modes preserves the current filter selection
+  5. Vitest tests cover mode switcher interaction, week renderer output, and display toggle behavior
+**Plans:** 2 plans
+Plans:
+- [x] 07-01-PLAN.md — UI controls (mode switcher + metric toggle), Twig template, orchestrator wiring
+- [x] 07-02-PLAN.md — WeekModeRenderer implementation, registration, visual verification
+**UI hint**: yes
+
+### Phase 8: Backend Aggregation + Filtering
+**Goal**: Backend serves hour-level and day/hour aggregation data and accepts activity and customer filter params via custom endpoints
+**Depends on**: Phase 6
+**Requirements**: API-01, API-02, FILT-02, FILT-03, TEST-03
+**Success Criteria** (what must be TRUE):
+  1. API endpoint accepts a mode param and returns hourly aggregation data (for day-mode) and day/hour aggregation data (for combined mode)
+  2. Activity filter param narrows heatmap data to entries matching a specific activity
+  3. Customer filter param narrows heatmap data to all projects under a selected customer
+  4. Custom cascade endpoints (/heatmap/customers, /heatmap/projects, /heatmap/activities) return entity lists using session auth (not API auth)
+  5. PHPUnit tests cover hourly aggregation, day/hour aggregation, and filter parameter handling
+**Plans:** 2 plans
+Plans:
+- [x] 08-01-PLAN.md — Service layer: aggregation methods, cascade queries, filter support
+- [x] 08-02-PLAN.md — Controller: mode dispatch, cascade endpoints, TS types
+
+### Phase 9: Day + Combined Modes
+**Goal**: Users can view time-of-day and day/hour punchcard visualizations with a color scale legend
+**Depends on**: Phase 7 (mode switcher), Phase 8 (backend aggregation data)
+**Requirements**: VIZ-03, VIZ-04, POL-01
+**Success Criteria** (what must be TRUE):
+  1. Day-mode renders a time-of-day heatmap showing when during the day work happens (24 hour slots)
+  2. Combined mode renders a 7x24 punchcard matrix showing day-of-week vs hour-of-day patterns
+  3. Mode switcher now offers all four modes (year, week, day, combined) and all work end-to-end
+  4. A color scale legend gradient bar shows the value range for the current mode and metric
+**Plans**: TBD
+**UI hint**: yes
+
+### Phase 10: Entity Pickers
+**Goal**: Users filter the heatmap using Kimai-native TomSelect pickers with customer/project/activity cascade
+**Depends on**: Phase 8 (custom cascade endpoints)
+**Requirements**: FILT-01, TEST-02
+**Success Criteria** (what must be TRUE):
+  1. Customer, project, and activity pickers use TomSelect with search/autocomplete replacing plain select elements
+  2. Selecting a customer filters the project picker to that customer's projects and the activity picker to matching activities
+  3. Selecting a project filters the activity picker to that project's activities
+  4. Clearing a parent picker resets child pickers and updates the heatmap accordingly
+  5. Vitest tests cover cascade behavior, empty states, and filter-to-heatmap integration
+**Plans**: TBD
+**UI hint**: yes
+
 ## Progress
 
+**Execution Order:**
+Phases execute in numeric order: 6 -> 7 -> 8 -> 9 -> 10
+Note: Phases 7 and 8 can execute in parallel (both depend only on Phase 6).
+
 | Phase | Milestone | Plans Complete | Status | Completed |
 |-------|-----------|----------------|--------|-----------|
 | 1. Dev Environment | v1.0 | 2/2 | Complete | 2026-04-08 |
@@ -26,3 +111,8 @@
 | 3. Core Heatmap Rendering | v1.0 | 3/3 | Complete | 2026-04-08 |
 | 4. Heatmap Interaction | v1.0 | 2/2 | Complete | 2026-04-08 |
 | 5. Polish | v1.0 | 2/2 | Complete | 2026-04-08 |
+| 6. Renderer Architecture | v1.1 | 0/2 | Planned | - |
+| 7. Mode Switcher + Week Mode | v1.1 | 0/2 | Planned | - |
+| 8. Backend Aggregation + Filtering | v1.1 | 0/2 | Not started | - |
+| 9. Day + Combined Modes | v1.1 | 0/? | Not started | - |
+| 10. Entity Pickers | v1.1 | 0/? | Not started | - |

.planning/STATE.md

@@ -1,16 +1,16 @@
 ---
 gsd_state_version: 1.0
-milestone: v1.0
-milestone_name: MVP
-status: shipped
-stopped_at: Milestone v1.0 complete
-last_updated: "2026-04-08T21:30:00.000Z"
-last_activity: 2026-04-08
+milestone: v1.1
+milestone_name: Modes & Filtering
+status: executing
+stopped_at: Phase 8 context gathered
+last_updated: "2026-04-09T20:01:00.260Z"
+last_activity: 2026-04-09
 progress:
   total_phases: 5
-  completed_phases: 5
-  total_plans: 11
-  completed_plans: 11
+  completed_phases: 3
+  total_plans: 6
+  completed_plans: 6
   percent: 100
 ---
 
@@ -21,19 +21,45 @@ progress:
 See: .planning/PROJECT.md (updated 2026-04-08)
 
 **Core value:** At a glance, see where your time went -- a visual map of tracking activity that makes patterns obvious
-**Current focus:** Planning next milestone
+**Current focus:** v1.1 Modes & Filtering -- Phase 7 ready to discuss
 
 ## Current Position
 
-Phase: All v1.0 phases complete
-Plan: N/A
-Status: v1.0 shipped
-Last activity: 2026-04-08
+Phase: 9 of 10 (day + combined modes)
+Plan: Not started
+Status: Ready to execute
+Last activity: 2026-04-09
 
-Progress: [██████████] 100%
+Progress: [██░░░░░░░░] 20%
+
+## Performance Metrics
+
+**Velocity (v1.0):**
+
+- Total plans completed: 15
+- Phases completed: 5
+
+**v1.1:**
+
+- Plans completed: 2
+- Phases completed: 1
+
+## Accumulated Context
+
+### Decisions
+
+- Renderer refactor (strategy pattern) must happen before any new modes
+- Week-mode uses client-side aggregation of existing DayEntry data (no backend changes)
+- TomSelect must be bundled (not available as Kimai global), deferred to last phase
+- Custom controller endpoints needed for entity data (Kimai API routes require IsGranted('API'))
+- Kimai plugin PHP files must live at bundle root (not src/) for PSR-4 autoloading compatibility
+
+### Blockers/Concerns
+
+None.
 
 ## Session Continuity
 
-Last session: 2026-04-08
-Stopped at: Milestone v1.0 complete
-Resume file: None
+Last session: 2026-04-09T15:21:54.701Z
+Stopped at: Phase 8 context gathered
+Resume file: .planning/phases/08-backend-aggregation-filtering/08-CONTEXT.md

.planning/phases/06-renderer-architecture/06-01-PLAN.md

@@ -0,0 +1,455 @@
+---
+phase: 06-renderer-architecture
+plan: 01
+type: execute
+wave: 1
+depends_on: []
+files_modified:
+  - assets/src/types.ts
+  - assets/src/state.ts
+  - assets/src/renderers/types.ts
+  - assets/src/renderers/registry.ts
+  - assets/src/shared/tooltip.ts
+  - assets/src/shared/color-scale.ts
+  - assets/src/shared/stats.ts
+  - assets/src/shared/date-utils.ts
+  - assets/test/state.test.ts
+  - assets/test/registry.test.ts
+  - assets/test/tooltip.test.ts
+  - assets/test/color-scale.test.ts
+  - assets/test/date-utils.test.ts
+autonomous: true
+requirements: []
+
+must_haves:
+  truths:
+    - "ModeRenderer interface and RenderContext type are exported from renderers/types.ts"
+    - "HeatmapState can be created with createInitialState() and defaults to year mode, hours metric"
+    - "Renderer registry accepts registration and retrieves by mode string"
+    - "Tooltip create/show/hide functions work identically to inline code in v1.0 heatmap.ts"
+    - "Color scale builds correctly for both hours and count metrics"
+    - "Stats functions (calculateStreak, calculateStats, renderStats) produce identical output from new location"
+    - "Date utility functions (buildDateMap, generateCells, getWeekInterval) produce identical output from new location"
+  artifacts:
+    - path: "assets/src/renderers/types.ts"
+      provides: "ModeRenderer interface, RenderContext type"
+      exports: ["ModeRenderer", "RenderContext"]
+    - path: "assets/src/state.ts"
+      provides: "HeatmapState creation"
+      exports: ["createInitialState", "HeatmapState", "HeatmapMode", "DisplayMetric", "FilterState"]
+    - path: "assets/src/renderers/registry.ts"
+      provides: "Renderer registration and lookup"
+      exports: ["registerRenderer", "getRenderer"]
+    - path: "assets/src/shared/tooltip.ts"
+      provides: "Tooltip lifecycle functions"
+      exports: ["createTooltip", "showTooltip", "hideTooltip"]
+    - path: "assets/src/shared/color-scale.ts"
+      provides: "Color scale factory"
+      exports: ["buildColorScale", "FALLBACK_COLORS"]
+    - path: "assets/src/shared/stats.ts"
+      provides: "Stats calculation and rendering"
+      exports: ["calculateStreak", "calculateStats", "renderStats", "HeatmapStats"]
+    - path: "assets/src/shared/date-utils.ts"
+      provides: "Date grid utilities"
+      exports: ["buildDateMap", "generateCells", "getWeekInterval", "DayCell", "DATE_FORMAT", "DISPLAY_FORMAT"]
+  key_links:
+    - from: "assets/src/shared/color-scale.ts"
+      to: "assets/src/types.ts"
+      via: "imports DayEntry, DisplayMetric"
+      pattern: "import.*DayEntry.*DisplayMetric.*from"
+    - from: "assets/src/renderers/types.ts"
+      to: "assets/src/types.ts"
+      via: "imports HeatmapData, HeatmapConfig"
+      pattern: "import.*HeatmapData.*HeatmapConfig.*from"
+    - from: "assets/src/renderers/types.ts"
+      to: "assets/src/state.ts"
+      via: "imports HeatmapState"
+      pattern: "import.*HeatmapState.*from"
+---
+
+<objective>
+Create all building blocks for the strategy-pattern renderer system: type definitions, state management, renderer registry, and extracted shared utilities.
+
+Purpose: Establish the module structure and contracts that Plan 02 will wire together. Every function extracted here already exists in heatmap.ts -- this is pure decomposition.
+Output: 8 new source files + 5 new test files. Zero changes to runtime behavior.
+</objective>
+
+<execution_context>
+@/home/toph/code/toph/kimai-heatmap/.claude/get-shit-done/workflows/execute-plan.md
+@/home/toph/code/toph/kimai-heatmap/.claude/get-shit-done/templates/summary.md
+</execution_context>
+
+<context>
+@.planning/PROJECT.md
+@.planning/ROADMAP.md
+@.planning/STATE.md
+@.planning/phases/06-renderer-architecture/06-RESEARCH.md
+
+<interfaces>
+<!-- Current types from assets/src/types.ts that all new modules will reference -->
+From assets/src/types.ts:
+```typescript
+export interface DayEntry {
+  date: string; // "YYYY-MM-DD"
+  hours: number;
+  count: number;
+}
+
+export interface HeatmapData {
+  days: DayEntry[];
+  range: {
+    begin: string;
+    end: string;
+  };
+}
+
+export interface HeatmapConfig {
+  cellSize: number;
+  cellGap: number;
+  marginTop: number;
+  marginLeft: number;
+  marginBottom: number;
+}
+
+export interface ProjectOption {
+  id: number;
+  name: string;
+}
+```
+
+From assets/src/heatmap.ts (functions to extract):
+```typescript
+// Lines 47-53: buildDateMap
+function buildDateMap(days: DayEntry[]): Map<string, DayEntry> { ... }
+
+// Lines 55-57: getWeekInterval
+function getWeekInterval(weekStart: string) { ... }
+
+// Lines 59-92: generateCells (returns DayCell[])
+function generateCells(begin: Date, end: Date, dateMap: Map<string, DayEntry>, weekStart: string = 'monday'): DayCell[] { ... }
+
+// Lines 94-99: createTooltip
+function createTooltip(): HTMLDivElement { ... }
+
+// Lines 101-125: calculateStreak (exported)
+export function calculateStreak(days: DayEntry[]): number { ... }
+
+// Lines 127-131: HeatmapStats interface (exported)
+export interface HeatmapStats { ... }
+
+// Lines 133-148: calculateStats (exported)
+export function calculateStats(days: DayEntry[]): HeatmapStats { ... }
+
+// Lines 150-174: renderStats
+function renderStats(container: HTMLElement, days: DayEntry[]): void { ... }
+
+// Lines 200-205: color scale setup (inline in renderHeatmap)
+const colorScale = scaleQuantize<string>().domain([0, maxHours]).range(colors);
+```
+</interfaces>
+</context>
+
+<tasks>
+
+<task type="auto" tdd="true">
+  <name>Task 1: Create type contracts, state module, and renderer registry</name>
+  <files>
+    assets/src/types.ts,
+    assets/src/state.ts,
+    assets/src/renderers/types.ts,
+    assets/src/renderers/registry.ts,
+    assets/test/state.test.ts,
+    assets/test/registry.test.ts
+  </files>
+  <read_first>
+    assets/src/types.ts,
+    assets/src/heatmap.ts
+  </read_first>
+  <behavior>
+    - state.test.ts: createInitialState('monday') returns { mode: 'year', metric: 'hours', filters: { projectId: null, customerId: null, activityId: null }, weekStart: 'monday', data: null }
+    - state.test.ts: createInitialState('sunday') returns state with weekStart: 'sunday'
+    - registry.test.ts: registerRenderer(renderer) then getRenderer('year') returns that renderer
+    - registry.test.ts: getRenderer('nonexistent') throws Error with message containing 'Unknown heatmap mode'
+    - registry.test.ts: registering a second renderer for same mode overwrites the first
+  </behavior>
+  <action>
+    1. **assets/src/types.ts** -- Add new types alongside existing ones (do NOT remove existing exports):
+       ```typescript
+       export type DisplayMetric = 'hours' | 'count';
+       export type HeatmapMode = 'year' | 'week' | 'day' | 'combined';
+
+       export interface FilterState {
+         projectId: number | null;
+         customerId: number | null;
+         activityId: number | null;
+       }
+       ```
+       Keep all existing interfaces (DayEntry, HeatmapData, HeatmapConfig, ProjectOption) unchanged.
+
+    2. **assets/src/state.ts** -- Create state factory:
+       ```typescript
+       import type { HeatmapData, HeatmapMode, DisplayMetric, FilterState } from './types';
+
+       export interface HeatmapState {
+         mode: HeatmapMode;
+         metric: DisplayMetric;
+         filters: FilterState;
+         weekStart: string;
+         data: HeatmapData | null;
+       }
+
+       export function createInitialState(weekStart: string): HeatmapState {
+         return {
+           mode: 'year',
+           metric: 'hours',
+           filters: { projectId: null, customerId: null, activityId: null },
+           weekStart,
+           data: null,
+         };
+       }
+       ```
+       Re-export HeatmapState from this file. Keep it as a plain interface, not a class.
+
+    3. **assets/src/renderers/types.ts** -- Create renderer contracts:
+       ```typescript
+       import type { HeatmapData, HeatmapConfig } from '../types';
+       import type { HeatmapState } from '../state';
+
+       export interface RenderContext {
+         container: HTMLElement;
+         data: HeatmapData;
+         state: HeatmapState;
+         config: HeatmapConfig;
+         onCellClick?: (dateStr: string) => void;
+       }
+
+       export interface ModeRenderer {
+         readonly mode: string;
+         render(ctx: RenderContext): void;
+         destroy?(): void;
+       }
+       ```
+
+    4. **assets/src/renderers/registry.ts** -- Create registry:
+       ```typescript
+       import type { ModeRenderer } from './types';
+
+       const renderers = new Map<string, ModeRenderer>();
+
+       export function registerRenderer(renderer: ModeRenderer): void {
+         renderers.set(renderer.mode, renderer);
+       }
+
+       export function getRenderer(mode: string): ModeRenderer {
+         const r = renderers.get(mode);
+         if (!r) throw new Error(`Unknown heatmap mode: ${mode}`);
+         return r;
+       }
+       ```
+
+    5. **assets/test/state.test.ts** -- Write tests first (TDD red), then verify green:
+       - Test createInitialState returns correct default shape for 'monday' and 'sunday'
+       - Test that data is null, mode is 'year', metric is 'hours'
+
+    6. **assets/test/registry.test.ts** -- Write tests first (TDD red), then verify green:
+       - Test registerRenderer + getRenderer roundtrip
+       - Test getRenderer throws for unknown mode
+       - Test overwrite behavior
+       - IMPORTANT: After each test run, clear the registry. Since the registry uses module-level state, add a `clearRegistry()` export for testing, or create a fresh mock renderer per test. Simplest: add `export function clearRegistry(): void { renderers.clear(); }` to registry.ts and call it in beforeEach.
+  </action>
+  <verify>
+    <automated>npx vitest run assets/test/state.test.ts assets/test/registry.test.ts</automated>
+  </verify>
+  <acceptance_criteria>
+    - assets/src/types.ts contains `export type DisplayMetric = 'hours' | 'count'`
+    - assets/src/types.ts contains `export type HeatmapMode = 'year' | 'week' | 'day' | 'combined'`
+    - assets/src/types.ts contains `export interface FilterState`
+    - assets/src/types.ts still contains `export interface DayEntry` (not removed)
+    - assets/src/state.ts contains `export function createInitialState`
+    - assets/src/state.ts contains `export interface HeatmapState`
+    - assets/src/renderers/types.ts contains `export interface ModeRenderer`
+    - assets/src/renderers/types.ts contains `export interface RenderContext`
+    - assets/src/renderers/registry.ts contains `export function registerRenderer`
+    - assets/src/renderers/registry.ts contains `export function getRenderer`
+    - assets/test/state.test.ts exits 0
+    - assets/test/registry.test.ts exits 0
+    - Existing tests still pass: `npx vitest run assets/test/stats.test.ts` exits 0
+  </acceptance_criteria>
+  <done>
+    All new type/state/registry modules exist with correct exports. New tests pass. Existing tests unaffected (heatmap.ts unchanged yet).
+  </done>
+</task>
+
+<task type="auto" tdd="true">
+  <name>Task 2: Extract shared utilities from heatmap.ts</name>
+  <files>
+    assets/src/shared/tooltip.ts,
+    assets/src/shared/color-scale.ts,
+    assets/src/shared/stats.ts,
+    assets/src/shared/date-utils.ts,
+    assets/test/tooltip.test.ts,
+    assets/test/color-scale.test.ts,
+    assets/test/date-utils.test.ts
+  </files>
+  <read_first>
+    assets/src/heatmap.ts,
+    assets/src/types.ts,
+    assets/src/state.ts
+  </read_first>
+  <behavior>
+    - tooltip.test.ts: createTooltip() returns HTMLDivElement with className 'heatmap-tooltip' and display 'none'
+    - tooltip.test.ts: createTooltip() removes any existing .heatmap-tooltip elements before creating new one
+    - tooltip.test.ts: showTooltip() sets display to 'block' and positions tooltip
+    - tooltip.test.ts: hideTooltip() sets display to 'none'
+    - color-scale.test.ts: buildColorScale with hours metric returns scaleQuantize using hours values
+    - color-scale.test.ts: buildColorScale with count metric returns scaleQuantize using count values
+    - color-scale.test.ts: buildColorScale with empty array returns scale with domain [0, 1]
+    - date-utils.test.ts: buildDateMap creates Map keyed by date string
+    - date-utils.test.ts: generateCells returns correct count for date range
+    - date-utils.test.ts: generateCells marks weekend cells correctly
+    - date-utils.test.ts: getWeekInterval returns timeMonday for 'monday', timeSunday for 'sunday'
+  </behavior>
+  <action>
+    Extract functions from heatmap.ts into new modules. At this point, do NOT modify heatmap.ts -- only create the new shared/ files with copied (not moved) logic. Plan 02 will do the actual switchover.
+
+    1. **assets/src/shared/tooltip.ts** -- Extract from heatmap.ts lines 94-99 and the inline tooltip logic at lines 262-296:
+       ```typescript
+       export function createTooltip(): HTMLDivElement {
+         // Clean up stale tooltips (from heatmap.ts line 263)
+         document.querySelectorAll('.heatmap-tooltip').forEach(el => el.remove());
+
+         const tip = document.createElement('div');
+         tip.className = 'heatmap-tooltip';
+         tip.style.display = 'none';
+         tip.style.position = 'fixed';
+         document.body.appendChild(tip);
+         return tip;
+       }
+
+       export function showTooltip(
+         tip: HTMLDivElement,
+         html: string,
+         anchorRect: DOMRect,
+         cellSize: number,
+       ): void {
+         tip.innerHTML = html;
+         tip.style.display = 'block';
+         tip.style.left = `${anchorRect.left + cellSize / 2}px`;
+         tip.style.top = `${anchorRect.top - tip.offsetHeight - 8}px`;
+       }
+
+       export function hideTooltip(tip: HTMLDivElement): void {
+         tip.style.display = 'none';
+       }
+       ```
+       Note: createTooltip in the new module appends to document.body and sets position: fixed (consolidating the scattered tooltip setup from renderHeatmap). The old createTooltip in heatmap.ts did NOT append or set position -- that was done inline. The new version consolidates both.
+
+    2. **assets/src/shared/color-scale.ts** -- Extract from heatmap.ts lines 16, 200-205:
+       ```typescript
+       import { scaleQuantize } from 'd3-scale';
+       import { max } from 'd3-array';
+       import type { DayEntry, DisplayMetric } from '../types';
+
+       export const FALLBACK_COLORS = ['#9be9a8', '#40c463', '#30a14e', '#216e39'];
+
+       export function buildColorScale(
+         days: DayEntry[],
+         metric: DisplayMetric = 'hours',
+       ): ReturnType<typeof scaleQuantize<string>> {
+         const accessor = metric === 'hours'
+           ? (d: DayEntry) => d.hours
+           : (d: DayEntry) => d.count;
+         const maxVal = max(days, accessor) || 1;
+         return scaleQuantize<string>().domain([0, maxVal]).range(FALLBACK_COLORS);
+       }
+       ```
+       The resolveColors() function from heatmap.ts always returns FALLBACK_COLORS (the Tabler check is a no-op). Do not replicate resolveColors -- just use FALLBACK_COLORS directly.
+
+    3. **assets/src/shared/stats.ts** -- Extract from heatmap.ts lines 101-174:
+       Copy calculateStreak, HeatmapStats interface, calculateStats, and renderStats verbatim. These functions need these imports:
+       ```typescript
+       import { timeDay } from 'd3-time';
+       import { timeFormat } from 'd3-time-format';
+       import type { DayEntry } from '../types';
+       ```
+       The DATE_FORMAT and DISPLAY_FORMAT constants used by stats (lines 24-25 of heatmap.ts) must also be available. Define them locally in stats.ts:
+       ```typescript
+       const DATE_FORMAT = timeFormat('%Y-%m-%d');
+       const DISPLAY_FORMAT = timeFormat('%a, %b %-d, %Y');
+       ```
+
+    4. **assets/src/shared/date-utils.ts** -- Extract from heatmap.ts lines 20-92:
+       Copy DayCell interface, DAY_LABELS_MONDAY, DAY_LABELS_SUNDAY, getDayLabels, MONTH_FORMAT, DATE_FORMAT, DISPLAY_FORMAT, buildDateMap, getWeekInterval, generateCells. Exports:
+       ```typescript
+       export { DayCell, buildDateMap, getWeekInterval, generateCells, getDayLabels, DATE_FORMAT, DISPLAY_FORMAT, MONTH_FORMAT, DAY_LABELS_MONDAY, DAY_LABELS_SUNDAY };
+       ```
+       Imports needed:
+       ```typescript
+       import { timeMonday, timeSunday, timeDay, timeMonth } from 'd3-time';
+       import { timeFormat } from 'd3-time-format';
+       import type { DayEntry } from '../types';
+       ```
+
+    5. Write test files FIRST (TDD red), then create source files to make them green. For each test file, import from the new shared/ module path.
+
+    6. After all new tests pass, run existing tests to confirm they still pass (heatmap.ts is unchanged, so they must).
+  </action>
+  <verify>
+    <automated>npx vitest run assets/test/tooltip.test.ts assets/test/color-scale.test.ts assets/test/date-utils.test.ts && npx vitest run</automated>
+  </verify>
+  <acceptance_criteria>
+    - assets/src/shared/tooltip.ts contains `export function createTooltip`
+    - assets/src/shared/tooltip.ts contains `export function showTooltip`
+    - assets/src/shared/tooltip.ts contains `export function hideTooltip`
+    - assets/src/shared/color-scale.ts contains `export const FALLBACK_COLORS`
+    - assets/src/shared/color-scale.ts contains `export function buildColorScale`
+    - assets/src/shared/color-scale.ts contains `import type { DayEntry, DisplayMetric }`
+    - assets/src/shared/stats.ts contains `export function calculateStreak`
+    - assets/src/shared/stats.ts contains `export function calculateStats`
+    - assets/src/shared/stats.ts contains `export function renderStats`
+    - assets/src/shared/stats.ts contains `export interface HeatmapStats`
+    - assets/src/shared/date-utils.ts contains `export function buildDateMap`
+    - assets/src/shared/date-utils.ts contains `export function generateCells`
+    - assets/src/shared/date-utils.ts contains `export function getWeekInterval`
+    - assets/src/shared/date-utils.ts contains `export interface DayCell`
+    - All new test files exit 0: `npx vitest run assets/test/tooltip.test.ts assets/test/color-scale.test.ts assets/test/date-utils.test.ts`
+    - All existing tests still pass: `npx vitest run` exits 0
+  </acceptance_criteria>
+  <done>
+    All shared utility modules exist with correct exports and passing tests. heatmap.ts is unchanged -- the new modules are copies, not yet wired in. Full test suite green.
+  </done>
+</task>
+
+</tasks>
+
+<threat_model>
+## Trust Boundaries
+
+| Boundary | Description |
+|----------|-------------|
+| Browser -> Plugin JS | Plugin JS consumes API data and renders SVG. No new boundaries in this refactor. |
+
+## STRIDE Threat Register
+
+| Threat ID | Category | Component | Disposition | Mitigation Plan |
+|-----------|----------|-----------|-------------|-----------------|
+| T-06-01 | T (Tampering) | shared/tooltip.ts | accept | Tooltip uses innerHTML with data already trusted (from own API response). No new attack surface -- identical to v1.0 code. XSS risk is pre-existing and out of scope for a refactor phase. |
+| T-06-02 | D (Denial of Service) | renderers/registry.ts | accept | Registry is module-level Map populated at import time with known renderers. No user input reaches it. |
+</threat_model>
+
+<verification>
+1. `npx vitest run` -- all tests pass (existing + new)
+2. `npm run build` -- esbuild produces heatmap.js without errors (heatmap.ts unchanged, new files are standalone)
+3. New modules are importable: each test file successfully imports from shared/ and renderers/ paths
+</verification>
+
+<success_criteria>
+- 8 new source files created under assets/src/ (state.ts, renderers/types.ts, renderers/registry.ts, shared/tooltip.ts, shared/color-scale.ts, shared/stats.ts, shared/date-utils.ts, plus types.ts extended)
+- 5 new test files pass (state, registry, tooltip, color-scale, date-utils)
+- 4 existing test files still pass (heatmap, stats, interaction, filter)
+- esbuild still produces valid output
+</success_criteria>
+
+<output>
+After completion, create `.planning/phases/06-renderer-architecture/06-01-SUMMARY.md`
+</output>

.planning/phases/06-renderer-architecture/06-01-SUMMARY.md

@@ -0,0 +1,124 @@
+---
+phase: 06-renderer-architecture
+plan: 01
+subsystem: ui
+tags: [typescript, d3, strategy-pattern, state-management]
+
+requires:
+  - phase: 01-05 (v1.0)
+    provides: heatmap.ts monolith with all rendering logic
+provides:
+  - ModeRenderer interface and RenderContext type contracts
+  - HeatmapState creation via createInitialState()
+  - Renderer registry (registerRenderer/getRenderer)
+  - Shared tooltip, color-scale, stats, date-utils modules
+affects: [06-02, 06-03, 07-mode-renderers]
+
+tech-stack:
+  added: []
+  patterns: [strategy-pattern renderer registry, state factory function, shared utility extraction]
+
+key-files:
+  created:
+    - assets/src/state.ts
+    - assets/src/renderers/types.ts
+    - assets/src/renderers/registry.ts
+    - assets/src/shared/tooltip.ts
+    - assets/src/shared/color-scale.ts
+    - assets/src/shared/stats.ts
+    - assets/src/shared/date-utils.ts
+    - assets/test/state.test.ts
+    - assets/test/registry.test.ts
+    - assets/test/tooltip.test.ts
+    - assets/test/color-scale.test.ts
+    - assets/test/date-utils.test.ts
+  modified:
+    - assets/src/types.ts
+
+key-decisions:
+  - "clearRegistry() exported for test isolation of module-level Map"
+  - "Tooltip consolidated: createTooltip now appends to body and sets fixed positioning (was scattered inline in heatmap.ts)"
+  - "FALLBACK_COLORS used directly in color-scale, resolveColors() dropped (always returned same value)"
+
+patterns-established:
+  - "Strategy pattern: ModeRenderer interface with mode string key, render(ctx), optional destroy()"
+  - "State factory: plain interface + createInitialState() function, no class"
+  - "Shared utilities: pure functions extracted to assets/src/shared/ with independent tests"
+
+requirements-completed: []
+
+duration: 2min
+completed: 2026-04-09
+---
+
+# Phase 6 Plan 01: Foundation Modules Summary
+
+**Strategy-pattern renderer contracts, state factory, registry, and 4 shared utility modules extracted from heatmap.ts monolith**
+
+## Performance
+
+- **Duration:** 2 min
+- **Started:** 2026-04-09T07:31:40Z
+- **Completed:** 2026-04-09T07:34:36Z
+- **Tasks:** 2
+- **Files modified:** 13
+
+## Accomplishments
+- Created ModeRenderer/RenderContext type contracts for strategy-pattern rendering
+- Built state module with HeatmapState interface and createInitialState() factory
+- Built renderer registry with register/get/clear operations
+- Extracted tooltip, color-scale, stats, and date-utils as standalone shared modules
+- All 62 tests pass (20 new + 42 existing), esbuild still produces valid output
+
+## Task Commits
+
+Each task was committed atomically:
+
+1. **Task 1: Create type contracts, state module, and renderer registry** - `fe24e8b` (feat)
+2. **Task 2: Extract shared utilities from heatmap.ts** - `b9b2565` (feat)
+
+## Files Created/Modified
+- `assets/src/types.ts` - Added DisplayMetric, HeatmapMode, FilterState types
+- `assets/src/state.ts` - HeatmapState interface and createInitialState() factory
+- `assets/src/renderers/types.ts` - ModeRenderer and RenderContext interfaces
+- `assets/src/renderers/registry.ts` - Renderer registration and lookup with clearRegistry()
+- `assets/src/shared/tooltip.ts` - Consolidated tooltip create/show/hide functions
+- `assets/src/shared/color-scale.ts` - buildColorScale with DisplayMetric support
+- `assets/src/shared/stats.ts` - calculateStreak, calculateStats, renderStats
+- `assets/src/shared/date-utils.ts` - buildDateMap, generateCells, getWeekInterval, DayCell
+- `assets/test/state.test.ts` - 2 tests for state factory
+- `assets/test/registry.test.ts` - 3 tests for registry
+- `assets/test/tooltip.test.ts` - 5 tests for tooltip lifecycle
+- `assets/test/color-scale.test.ts` - 4 tests for color scale
+- `assets/test/date-utils.test.ts` - 6 tests for date utilities
+
+## Decisions Made
+- clearRegistry() exported from registry.ts for test isolation (module-level Map needs clearing between tests)
+- Tooltip creation consolidated: new createTooltip() appends to body with fixed positioning (was scattered across multiple lines in heatmap.ts)
+- resolveColors() dropped from color-scale module -- it always returned FALLBACK_COLORS
+
+## Deviations from Plan
+
+None - plan executed exactly as written.
+
+## Issues Encountered
+None.
+
+## User Setup Required
+None - no external service configuration required.
+
+## Next Phase Readiness
+- All building blocks ready for Plan 02 to wire heatmap.ts to use shared modules
+- ModeRenderer interface ready for year-mode renderer implementation
+- State and registry ready for mode switching logic
+
+## Self-Check: PASSED
+
+- All 12 created files exist on disk
+- Both task commits verified (fe24e8b, b9b2565)
+- Full test suite: 62/62 passing
+- esbuild: produces valid output
+
+---
+*Phase: 06-renderer-architecture*
+*Completed: 2026-04-09*

.planning/phases/06-renderer-architecture/06-02-PLAN.md

@@ -0,0 +1,679 @@
+---
+phase: 06-renderer-architecture
+plan: 02
+type: execute
+wave: 2
+depends_on: ["06-01"]
+files_modified:
+  - assets/src/heatmap.ts
+  - assets/src/renderers/year.ts
+  - assets/src/renderers/types.ts
+  - assets/test/heatmap.test.ts
+  - assets/test/stats.test.ts
+  - assets/test/interaction.test.ts
+  - assets/test/filter.test.ts
+autonomous: false
+requirements: []
+
+must_haves:
+  truths:
+    - "Year-view heatmap renders identically to v1.0 (same SVG structure, classes, attributes)"
+    - "Tooltip, color scale, and cell click handler come from shared utilities, not inline code"
+    - "HeatmapState object tracks mode, display metric, and filters"
+    - "Adding a new mode requires only implementing ModeRenderer and calling registerRenderer()"
+    - "KimaiHeatmap.init global entry point works unchanged in browser"
+    - "All existing test behaviors pass from new import locations"
+  artifacts:
+    - path: "assets/src/renderers/year.ts"
+      provides: "YearModeRenderer implementing ModeRenderer"
+      exports: ["YearModeRenderer"]
+    - path: "assets/src/heatmap.ts"
+      provides: "Slim orchestrator with init() and doRender()"
+      exports: ["init"]
+    - path: "Resources/public/heatmap.js"
+      provides: "Built IIFE bundle with KimaiHeatmap.init"
+  key_links:
+    - from: "assets/src/heatmap.ts"
+      to: "assets/src/renderers/registry.ts"
+      via: "getRenderer(state.mode)"
+      pattern: "getRenderer\\(state\\.mode\\)"
+    - from: "assets/src/heatmap.ts"
+      to: "assets/src/renderers/year.ts"
+      via: "registerRenderer(new YearModeRenderer())"
+      pattern: "registerRenderer.*YearModeRenderer"
+    - from: "assets/src/renderers/year.ts"
+      to: "assets/src/shared/tooltip.ts"
+      via: "imports createTooltip, showTooltip, hideTooltip"
+      pattern: "import.*createTooltip.*from.*shared/tooltip"
+    - from: "assets/src/renderers/year.ts"
+      to: "assets/src/shared/color-scale.ts"
+      via: "imports buildColorScale"
+      pattern: "import.*buildColorScale.*from.*shared/color-scale"
+    - from: "assets/src/renderers/year.ts"
+      to: "assets/src/shared/date-utils.ts"
+      via: "imports generateCells, buildDateMap, getWeekInterval"
+      pattern: "import.*generateCells.*from.*shared/date-utils"
+---
+
+<objective>
+Wire the building blocks from Plan 01 into a working strategy-pattern system: create YearModeRenderer, rewrite heatmap.ts as a slim orchestrator, and migrate all test imports.
+
+Purpose: Complete the refactor so that heatmap.ts dispatches rendering through the registry and the year-view works identically to v1.0.
+Output: Working renderer architecture with all tests passing from new module locations.
+</objective>
+
+<execution_context>
+@/home/toph/code/toph/kimai-heatmap/.claude/get-shit-done/workflows/execute-plan.md
+@/home/toph/code/toph/kimai-heatmap/.claude/get-shit-done/templates/summary.md
+</execution_context>
+
+<context>
+@.planning/PROJECT.md
+@.planning/ROADMAP.md
+@.planning/STATE.md
+@.planning/phases/06-renderer-architecture/06-RESEARCH.md
+@.planning/phases/06-renderer-architecture/06-UI-SPEC.md
+@.planning/phases/06-renderer-architecture/06-01-SUMMARY.md
+
+<interfaces>
+<!-- From Plan 01 outputs -->
+From assets/src/renderers/types.ts:
+```typescript
+export interface RenderContext {
+  container: HTMLElement;
+  data: HeatmapData;
+  state: HeatmapState;
+  config: HeatmapConfig;
+  onCellClick?: (dateStr: string) => void;
+}
+
+export interface ModeRenderer {
+  readonly mode: string;
+  render(ctx: RenderContext): void;
+  destroy?(): void;
+}
+```
+
+From assets/src/state.ts:
+```typescript
+export interface HeatmapState {
+  mode: HeatmapMode;
+  metric: DisplayMetric;
+  filters: FilterState;
+  weekStart: string;
+  data: HeatmapData | null;
+}
+
+export function createInitialState(weekStart: string): HeatmapState;
+```
+
+From assets/src/renderers/registry.ts:
+```typescript
+export function registerRenderer(renderer: ModeRenderer): void;
+export function getRenderer(mode: string): ModeRenderer;
+```
+
+From assets/src/shared/tooltip.ts:
+```typescript
+export function createTooltip(): HTMLDivElement;
+export function showTooltip(tip: HTMLDivElement, html: string, anchorRect: DOMRect, cellSize: number): void;
+export function hideTooltip(tip: HTMLDivElement): void;
+```
+
+From assets/src/shared/color-scale.ts:
+```typescript
+export const FALLBACK_COLORS: string[];
+export function buildColorScale(days: DayEntry[], metric?: DisplayMetric): ReturnType<typeof scaleQuantize<string>>;
+```
+
+From assets/src/shared/stats.ts:
+```typescript
+export function calculateStreak(days: DayEntry[]): number;
+export function calculateStats(days: DayEntry[]): HeatmapStats;
+export interface HeatmapStats { totalHours: number; avgHours: number; busiestDay: { date: string; hours: number } | null; }
+export function renderStats(container: HTMLElement, days: DayEntry[]): void;
+```
+
+From assets/src/shared/date-utils.ts:
+```typescript
+export interface DayCell { date: Date; dateStr: string; entry: DayEntry | null; week: number; day: number; isWeekend: boolean; }
+export function buildDateMap(days: DayEntry[]): Map<string, DayEntry>;
+export function getWeekInterval(weekStart: string): typeof timeMonday;
+export function generateCells(begin: Date, end: Date, dateMap: Map<string, DayEntry>, weekStart?: string): DayCell[];
+export function getDayLabels(weekStart: string): string[];
+export const DATE_FORMAT: (d: Date) => string;
+export const DISPLAY_FORMAT: (d: Date) => string;
+export const MONTH_FORMAT: (d: Date) => string;
+```
+
+From assets/src/types.ts:
+```typescript
+export interface DayEntry { date: string; hours: number; count: number; }
+export interface HeatmapData { days: DayEntry[]; range: { begin: string; end: string; }; }
+export interface HeatmapConfig { cellSize: number; cellGap: number; marginTop: number; marginLeft: number; marginBottom: number; }
+export interface ProjectOption { id: number; name: string; }
+export type DisplayMetric = 'hours' | 'count';
+export type HeatmapMode = 'year' | 'week' | 'day' | 'combined';
+export interface FilterState { projectId: number | null; customerId: number | null; activityId: number | null; }
+```
+</interfaces>
+</context>
+
+<tasks>
+
+<task type="auto">
+  <name>Task 1: Create YearModeRenderer and rewrite heatmap.ts orchestrator</name>
+  <files>
+    assets/src/renderers/year.ts,
+    assets/src/renderers/types.ts,
+    assets/src/heatmap.ts
+  </files>
+  <read_first>
+    assets/src/heatmap.ts,
+    assets/src/renderers/types.ts,
+    assets/src/state.ts,
+    assets/src/renderers/registry.ts,
+    assets/src/shared/tooltip.ts,
+    assets/src/shared/color-scale.ts,
+    assets/src/shared/stats.ts,
+    assets/src/shared/date-utils.ts,
+    assets/src/types.ts
+  </read_first>
+  <action>
+    **Part A: Update assets/src/renderers/types.ts -- add emptyMessage to RenderContext**
+
+    Add an optional `emptyMessage?: string;` field to the RenderContext interface (after onCellClick). This preserves the filtered empty message behavior from v1.0 where "No tracking data for this project" was shown when filtering produced empty results.
+
+    **Part B: Create assets/src/renderers/year.ts**
+
+    Extract the body of `renderHeatmap()` (lines 176-302 of current heatmap.ts) into a `YearModeRenderer` class implementing `ModeRenderer`. The render() method must produce IDENTICAL SVG output.
+
+    Structure:
+    ```typescript
+    import { select } from 'd3-selection';
+    import { timeMonth } from 'd3-time';
+    import { max } from 'd3-array';
+    import type { ModeRenderer, RenderContext } from './types';
+    import { createTooltip, showTooltip, hideTooltip } from '../shared/tooltip';
+    import { buildColorScale } from '../shared/color-scale';
+    import {
+      buildDateMap, generateCells, getWeekInterval, getDayLabels,
+      MONTH_FORMAT, DISPLAY_FORMAT, type DayCell,
+    } from '../shared/date-utils';
+
+    export class YearModeRenderer implements ModeRenderer {
+      readonly mode = 'year';
+      private tooltip: HTMLDivElement | null = null;
+
+      render(ctx: RenderContext): void {
+        ctx.container.innerHTML = '';
+
+        // Handle empty data -- use ctx.emptyMessage if provided, else default
+        if (!ctx.data.days || ctx.data.days.length === 0) {
+          const msg = document.createElement('div');
+          msg.textContent = ctx.emptyMessage || 'No tracking data available';
+          msg.style.padding = '1rem';
+          msg.style.color = 'var(--tblr-secondary, #6c757d)';
+          ctx.container.appendChild(msg);
+          return;
+        }
+
+        // Destroy previous tooltip
+        this.destroy();
+        this.tooltip = createTooltip();
+
+        const weekStart = ctx.state.weekStart;
+        const dateMap = buildDateMap(ctx.data.days);
+        const begin = new Date(ctx.data.range.begin);
+        const end = new Date(ctx.data.range.end);
+        const cells = generateCells(begin, end, dateMap, weekStart);
+
+        // Build color scale using state metric (hours vs count)
+        const colorScale = buildColorScale(ctx.data.days, ctx.state.metric);
+
+        const { cellGap, marginTop, marginLeft, marginBottom } = ctx.config;
+        const numWeeks = (max(cells, (c) => c.week) ?? 0) + 1;
+
+        // Compute cell size to fill available width, capped
+        const containerWidth = ctx.container.clientWidth || 800;
+        const maxCellSize = 22;
+        const minCellSize = 10;
+        const cellSize = Math.min(maxCellSize, Math.max(minCellSize, Math.floor((containerWidth - marginLeft) / numWeeks) - cellGap));
+        const step = cellSize + cellGap;
+        const svgWidth = marginLeft + numWeeks * step;
+        const svgHeight = marginTop + 7 * step + marginBottom;
+
+        const wrapper = document.createElement('div');
+        wrapper.style.maxWidth = `${svgWidth}px`;
+        wrapper.style.margin = '0 auto';
+        ctx.container.appendChild(wrapper);
+
+        const svg = select(wrapper)
+          .append('svg')
+          .attr('width', svgWidth)
+          .attr('height', svgHeight)
+          .attr('class', 'heatmap-svg');
+
+        // Month labels
+        const weekInterval = getWeekInterval(weekStart);
+        const months: { date: Date; week: number }[] = [];
+        const firstWeekDay = weekInterval.floor(begin);
+        timeMonth.range(timeMonth.ceil(begin), end).forEach((m) => {
+          months.push({ date: m, week: weekInterval.count(firstWeekDay, m) });
+        });
+
+        svg.selectAll('.month-label')
+          .data(months)
+          .join('text')
+          .attr('class', 'heatmap-label month-label')
+          .attr('x', (d) => marginLeft + d.week * step)
+          .attr('y', marginTop - 6)
+          .text((d) => MONTH_FORMAT(d.date));
+
+        // Day labels
+        svg.selectAll('.day-label')
+          .data(getDayLabels(weekStart))
+          .join('text')
+          .attr('class', 'heatmap-label day-label')
+          .attr('x', marginLeft - 6)
+          .attr('y', (_d, i) => marginTop + i * step + cellSize - 2)
+          .attr('text-anchor', 'end')
+          .text((d) => d);
+
+        // Cells with tooltip and click
+        const tooltip = this.tooltip;
+        svg.selectAll('.heatmap-cell')
+          .data(cells)
+          .join('rect')
+          .attr('class', (d) => {
+            let cls = 'heatmap-cell';
+            if (!d.entry) cls += ' heatmap-empty';
+            if (d.isWeekend) cls += ' heatmap-weekend';
+            return cls;
+          })
+          .attr('x', (d) => marginLeft + d.week * step)
+          .attr('y', (d) => marginTop + d.day * step)
+          .attr('width', cellSize)
+          .attr('height', cellSize)
+          .attr('fill', (d) => (d.entry ? colorScale(d.entry.hours) : ''))
+          .on('mouseenter', function (event: MouseEvent, d: DayCell) {
+            const hours = d.entry ? d.entry.hours.toFixed(1) : '0.0';
+            const count = d.entry ? d.entry.count : 0;
+            const html = `<strong>${DISPLAY_FORMAT(d.date)}</strong><br>${hours}h (${count} entries)`;
+            const rect = (event.target as SVGRectElement).getBoundingClientRect();
+            showTooltip(tooltip, html, rect, cellSize);
+          })
+          .on('mouseleave', function () {
+            hideTooltip(tooltip);
+          })
+          .on('click', function (_event: MouseEvent, d: DayCell) {
+            if (!ctx.onCellClick) return;
+            ctx.onCellClick(d.dateStr);
+          });
+      }
+
+      destroy(): void {
+        this.tooltip?.remove();
+        this.tooltip = null;
+      }
+    }
+    ```
+
+    CRITICAL details preserved from current renderHeatmap():
+    - Cell size computation: `Math.min(22, Math.max(10, Math.floor((containerWidth - marginLeft) / numWeeks) - cellGap))`
+    - SVG wrapper div with max-width and margin:0 auto
+    - Cell classes: `heatmap-cell`, `heatmap-empty`, `heatmap-weekend` -- same logic
+    - Cell `rx` and `ry` are NOT set (CSS handles border-radius) -- do NOT add them
+    - Color scale: uses buildColorScale(days, metric). For v1.0 the metric is always 'hours' but the infrastructure is ready for 'count'.
+    - Tooltip HTML: `<strong>${DISPLAY_FORMAT(d.date)}</strong><br>${hours}h (${count} entries)`
+    - Empty cell fill: empty string `''` (CSS `.heatmap-empty` handles it)
+
+    NOTE on color scale in cell fill: The current v1.0 code uses `colorScale(d.entry.hours)` directly. The new buildColorScale returns a scale that accepts the metric value. Since the default metric is 'hours', `colorScale(d.entry.hours)` is correct for 'hours' metric. For 'count' metric (future), the renderer would need `colorScale(d.entry.count)`. To handle both, the cell fill should be:
+    ```typescript
+    .attr('fill', (d) => {
+      if (!d.entry) return '';
+      const val = ctx.state.metric === 'hours' ? d.entry.hours : d.entry.count;
+      return colorScale(val);
+    })
+    ```
+    This is a forward-compatible change that is a no-op for v1.0 (metric is always 'hours').
+
+    **Part C: Rewrite assets/src/heatmap.ts as slim orchestrator**
+
+    Replace the 413-line file with a ~100-line orchestrator:
+    - Remove ALL functions that moved to shared/ modules: buildDateMap, generateCells, getWeekInterval, createTooltip, calculateStreak, calculateStats, renderStats, getDayLabels, resolveColors, renderHeatmap
+    - Remove: DayCell interface, FALLBACK_COLORS, DAY_LABELS_MONDAY, DAY_LABELS_SUNDAY, MONTH_FORMAT, DATE_FORMAT, DISPLAY_FORMAT, DEFAULT_CONFIG, HeatmapStats interface
+    - Keep `init()` as the ONLY export (esbuild IIFE entry point)
+    - Import and register YearModeRenderer at module level
+    - Use HeatmapState to track mode/metric/filters
+
+    Complete new heatmap.ts:
+    ```typescript
+    import type { HeatmapData, ProjectOption } from './types';
+    import { createInitialState } from './state';
+    import type { HeatmapState } from './state';
+    import { getRenderer, registerRenderer } from './renderers/registry';
+    import { YearModeRenderer } from './renderers/year';
+    import { renderStats } from './shared/stats';
+
+    // Register built-in renderers
+    registerRenderer(new YearModeRenderer());
+
+    export function init(container: HTMLElement): void {
+      const baseUrl = container.getAttribute('data-url');
+      if (!baseUrl) {
+        console.error('KimaiHeatmap: missing data-url attribute');
+        return;
+      }
+
+      const timesheetUrl = container.getAttribute('data-timesheet-url') || '/en/timesheet/';
+      const weekStart = container.getAttribute('data-week-start') || 'monday';
+      const projectsJson = container.getAttribute('data-projects');
+      const projects: ProjectOption[] = projectsJson ? JSON.parse(projectsJson) : [];
+
+      const state: HeatmapState = createInitialState(weekStart);
+
+      const onCellClick = (dateStr: string): void => {
+        const daterange = `${dateStr} - ${dateStr}`;
+        let url = `${timesheetUrl}?daterange=${encodeURIComponent(daterange)}`;
+        if (state.filters.projectId) {
+          url += `&projects[]=${state.filters.projectId}`;
+        }
+        window.location.href = url;
+      };
+
+      // Build wrapper layout
+      container.innerHTML = '';
+      const wrapper = document.createElement('div');
+      wrapper.className = 'heatmap-wrapper';
+
+      const svgArea = document.createElement('div');
+      svgArea.className = 'heatmap-svg-area';
+      wrapper.appendChild(svgArea);
+
+      const doRender = () => {
+        if (!state.data) return;
+        const renderer = getRenderer(state.mode);
+        renderer.destroy?.();
+        renderer.render({
+          container: svgArea,
+          data: state.data,
+          state,
+          config: { cellSize: 13, cellGap: 2, marginTop: 20, marginLeft: 30, marginBottom: 4 },
+          onCellClick,
+          emptyMessage: state.filters.projectId ? 'No tracking data for this project' : undefined,
+        });
+        renderStats(container, state.data.days);
+        svgArea.scrollLeft = svgArea.scrollWidth;
+      };
+
+      // Build filter dropdown (only if projects exist)
+      if (projects.length > 0) {
+        const filterDiv = document.createElement('div');
+        filterDiv.className = 'heatmap-filter';
+
+        const selectEl = document.createElement('select');
+        selectEl.className = 'form-select form-select-sm';
+        selectEl.setAttribute('aria-label', 'Filter by project');
+
+        const defaultOpt = document.createElement('option');
+        defaultOpt.value = '';
+        defaultOpt.textContent = 'All Projects';
+        selectEl.appendChild(defaultOpt);
+
+        for (const p of projects) {
+          const opt = document.createElement('option');
+          opt.value = String(p.id);
+          opt.textContent = p.name;
+          selectEl.appendChild(opt);
+        }
+
+        selectEl.addEventListener('change', () => {
+          const val = selectEl.value;
+          state.filters.projectId = val ? parseInt(val, 10) : null;
+          const fetchUrl = val ? `${baseUrl}?project=${val}` : baseUrl;
+
+          fetch(fetchUrl)
+            .then(res => {
+              if (!res.ok) throw new Error(`HTTP ${res.status}`);
+              return res.json() as Promise<HeatmapData>;
+            })
+            .then(data => {
+              state.data = data;
+              doRender();
+            })
+            .catch(err => {
+              console.error('KimaiHeatmap: failed to load filtered data', err);
+            });
+        });
+
+        filterDiv.appendChild(selectEl);
+        wrapper.appendChild(filterDiv);
+      }
+
+      container.appendChild(wrapper);
+
+      // Re-render on window resize (debounced)
+      let resizeTimer: ReturnType<typeof setTimeout>;
+      window.addEventListener('resize', () => {
+        clearTimeout(resizeTimer);
+        resizeTimer = setTimeout(() => {
+          if (state.data) doRender();
+        }, 200);
+      });
+
+      // Initial data fetch
+      fetch(baseUrl)
+        .then(res => {
+          if (!res.ok) throw new Error(`HTTP ${res.status}`);
+          return res.json() as Promise<HeatmapData>;
+        })
+        .then(data => {
+          state.data = data;
+          doRender();
+        })
+        .catch(err => {
+          console.error('KimaiHeatmap: failed to load data', err);
+          svgArea.textContent = 'Failed to load heatmap data';
+        });
+    }
+    ```
+
+    CRITICAL: The variable name for the select element MUST be `selectEl` (not `select`) to avoid shadowing the d3 `select` import. However, since d3 `select` is no longer imported in heatmap.ts (it moved to year.ts), `select` as a variable name would work. But use `selectEl` for clarity and to avoid confusion.
+
+    CRITICAL: The `activeProjectId` closure variable from v1.0 is replaced by `state.filters.projectId`. The onCellClick handler reads from state.filters.projectId instead of a separate closure var.
+  </action>
+  <verify>
+    <automated>npm run build && npm run build:dev</automated>
+  </verify>
+  <acceptance_criteria>
+    - assets/src/renderers/year.ts contains `export class YearModeRenderer implements ModeRenderer`
+    - assets/src/renderers/year.ts contains `readonly mode = 'year'`
+    - assets/src/renderers/year.ts contains `import { createTooltip, showTooltip, hideTooltip } from '../shared/tooltip'`
+    - assets/src/renderers/year.ts contains `import { buildColorScale } from '../shared/color-scale'`
+    - assets/src/renderers/year.ts contains `import { buildDateMap, generateCells, getWeekInterval` (from shared/date-utils)
+    - assets/src/renderers/types.ts contains `emptyMessage?: string`
+    - assets/src/heatmap.ts does NOT contain `function renderHeatmap`
+    - assets/src/heatmap.ts does NOT contain `function buildDateMap`
+    - assets/src/heatmap.ts does NOT contain `function calculateStreak`
+    - assets/src/heatmap.ts does NOT contain `FALLBACK_COLORS`
+    - assets/src/heatmap.ts contains `import { createInitialState } from './state'`
+    - assets/src/heatmap.ts contains `import { getRenderer, registerRenderer } from './renderers/registry'`
+    - assets/src/heatmap.ts contains `import { YearModeRenderer } from './renderers/year'`
+    - assets/src/heatmap.ts contains `registerRenderer(new YearModeRenderer())`
+    - assets/src/heatmap.ts contains `export function init`
+    - assets/src/heatmap.ts contains `getRenderer(state.mode)`
+    - `npm run build` exits 0 (IIFE bundle builds successfully)
+    - Resources/public/heatmap.js contains `KimaiHeatmap` (IIFE global intact)
+  </acceptance_criteria>
+  <done>
+    YearModeRenderer created. heatmap.ts rewritten as slim orchestrator. esbuild produces valid IIFE bundle with KimaiHeatmap.init intact.
+  </done>
+</task>
+
+<task type="auto">
+  <name>Task 2: Migrate test imports and verify full suite</name>
+  <files>
+    assets/test/heatmap.test.ts,
+    assets/test/stats.test.ts,
+    assets/test/interaction.test.ts,
+    assets/test/filter.test.ts
+  </files>
+  <read_first>
+    assets/test/heatmap.test.ts,
+    assets/test/stats.test.ts,
+    assets/test/interaction.test.ts,
+    assets/test/filter.test.ts,
+    assets/src/heatmap.ts,
+    assets/src/renderers/year.ts,
+    assets/src/shared/stats.ts,
+    assets/src/shared/date-utils.ts
+  </read_first>
+  <action>
+    Update all test file imports to point to new module locations. The tests themselves should NOT change logic -- only import paths and how renderHeatmap is invoked.
+
+    **assets/test/heatmap.test.ts:**
+    - OLD: `import { renderHeatmap } from '../src/heatmap'`
+    - The `renderHeatmap` function no longer exists. Rewrite this test to use YearModeRenderer directly.
+    - New imports:
+      ```typescript
+      import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+      import { YearModeRenderer } from '../src/renderers/year';
+      import type { RenderContext } from '../src/renderers/types';
+      import type { HeatmapData } from '../src/types';
+      import { createInitialState } from '../src/state';
+      ```
+    - Add a `renderer` variable: `let renderer: YearModeRenderer;` initialized in beforeEach as `renderer = new YearModeRenderer();`
+    - Add afterEach to clean up: `renderer.destroy(); document.querySelectorAll('.heatmap-tooltip').forEach(el => el.remove());`
+    - Build RenderContext helper:
+      ```typescript
+      const DEFAULT_CONFIG = { cellSize: 13, cellGap: 2, marginTop: 20, marginLeft: 30, marginBottom: 4 };
+      function makeCtx(data: HeatmapData, overrides?: Partial<RenderContext>): RenderContext {
+        return {
+          container,
+          data,
+          state: createInitialState('monday'),
+          config: DEFAULT_CONFIG,
+          ...overrides,
+        };
+      }
+      ```
+    - Replace all `renderHeatmap(container, data)` with `renderer.render(makeCtx(data))`
+    - Replace `renderHeatmap(container, data, undefined, undefined, undefined, 'sunday')` with `renderer.render(makeCtx(data, { state: createInitialState('sunday') }))`
+    - Replace `renderHeatmap(container, data, undefined, onClick)` with `renderer.render(makeCtx(data, { onCellClick: onClick }))`
+    - All test assertions remain identical -- same SVG structure, same classes, same tooltip behavior
+
+    **assets/test/stats.test.ts:**
+    - OLD: `import { calculateStreak, calculateStats } from '../src/heatmap'`
+    - NEW: `import { calculateStreak, calculateStats } from '../src/shared/stats'`
+    - No other changes needed. All test logic stays the same.
+
+    **assets/test/interaction.test.ts:**
+    - OLD: `import { renderHeatmap, init } from '../src/heatmap'`
+    - The `renderHeatmap` import must change. Split into two import statements:
+      ```typescript
+      import { init } from '../src/heatmap';
+      import { YearModeRenderer } from '../src/renderers/year';
+      import { createInitialState } from '../src/state';
+      import type { RenderContext } from '../src/renderers/types';
+      ```
+    - For the `describe('click navigation')` block (tests that used renderHeatmap directly):
+      - Add `let renderer: YearModeRenderer;` and initialize in beforeEach
+      - Add cleanup in afterEach: `renderer.destroy(); document.querySelectorAll('.heatmap-tooltip').forEach(el => el.remove());`
+      - Replace `renderHeatmap(container, MOCK_DATA, undefined, onClick)` with `renderer.render({ container, data: MOCK_DATA, state: createInitialState('monday'), config: { cellSize: 13, cellGap: 2, marginTop: 20, marginLeft: 30, marginBottom: 4 }, onCellClick: onClick })`
+      - Replace `renderHeatmap(container, MOCK_DATA)` with `renderer.render({ container, data: MOCK_DATA, state: createInitialState('monday'), config: { cellSize: 13, cellGap: 2, marginTop: 20, marginLeft: 30, marginBottom: 4 } })`
+    - The `describe('init click navigation')` block stays unchanged -- still uses `init` from heatmap.ts.
+
+    **assets/test/filter.test.ts:**
+    - OLD: `import { init } from '../src/heatmap'`
+    - This import is UNCHANGED -- `init` is still exported from heatmap.ts. No changes needed to this file.
+
+    After updating imports, run full test suite. All 4 existing test files + 5 new test files from Plan 01 must pass.
+  </action>
+  <verify>
+    <automated>npx vitest run</automated>
+  </verify>
+  <acceptance_criteria>
+    - assets/test/heatmap.test.ts does NOT contain `import { renderHeatmap } from '../src/heatmap'`
+    - assets/test/heatmap.test.ts contains `import { YearModeRenderer } from '../src/renderers/year'`
+    - assets/test/heatmap.test.ts contains `import { createInitialState } from '../src/state'`
+    - assets/test/stats.test.ts contains `import { calculateStreak, calculateStats } from '../src/shared/stats'`
+    - assets/test/stats.test.ts does NOT contain `from '../src/heatmap'`
+    - assets/test/interaction.test.ts contains `import { YearModeRenderer }`
+    - assets/test/interaction.test.ts does NOT contain `import { renderHeatmap`
+    - assets/test/interaction.test.ts contains `import { init } from '../src/heatmap'`
+    - `npx vitest run` exits 0 with all test files passing
+    - `npm run build` exits 0
+  </acceptance_criteria>
+  <done>
+    All test imports migrated to new module locations. Full test suite (9 files) passes. esbuild produces valid bundle.
+  </done>
+</task>
+
+<task type="checkpoint:human-verify" gate="blocking">
+  <name>Task 3: Visual regression check of rendered heatmap</name>
+  <files>Resources/public/heatmap.js</files>
+  <action>
+    Build the dev bundle and verify in a running Kimai instance that the heatmap renders identically to v1.0.
+
+    Steps for the human verifier:
+    1. Run `npm run build:dev` to build with sourcemap
+    2. Start local Kimai dev environment
+    3. Navigate to the dashboard
+    4. Verify the heatmap renders identically to before:
+       - Cells are colored with green scale (4 shades: #9be9a8, #40c463, #30a14e, #216e39)
+       - Hover shows tooltip with date, hours, entries
+       - Click navigates to timesheet filtered by date
+       - Stats row shows streak, total, avg, busiest
+       - Filter dropdown works (if projects exist)
+       - Window resize re-renders correctly
+    5. Open browser console -- no errors should appear
+    6. Check `typeof KimaiHeatmap.init` in console -- should be 'function'
+  </action>
+  <verify>
+    <automated>npm run build:dev && echo "Build successful -- manual visual check required"</automated>
+  </verify>
+  <done>
+    Human confirms heatmap renders identically to v1.0. No visual regressions. No console errors. KimaiHeatmap.init works.
+  </done>
+</task>
+
+</tasks>
+
+<threat_model>
+## Trust Boundaries
+
+| Boundary | Description |
+|----------|-------------|
+| Browser -> Plugin JS | Unchanged from v1.0. init() reads data-* attributes and fetches from API. |
+| API response -> Renderer | JSON data rendered as SVG. Tooltip uses innerHTML with API-sourced data. |
+
+## STRIDE Threat Register
+
+| Threat ID | Category | Component | Disposition | Mitigation Plan |
+|-----------|----------|-----------|-------------|-----------------|
+| T-06-03 | T (Tampering) | renderers/year.ts tooltip innerHTML | accept | Pre-existing v1.0 pattern. Data comes from own backend API (trusted). No user-controlled input reaches innerHTML beyond what the Kimai backend already sanitizes. Addressing XSS in tooltip is a separate concern, not introduced by this refactor. |
+| T-06-04 | S (Spoofing) | heatmap.ts init() data-url attribute | accept | Pre-existing v1.0 pattern. data-url is set server-side in Twig template. Attacker would need to modify server response to change it. |
+</threat_model>
+
+<verification>
+1. `npx vitest run` -- all 9 test files pass (4 existing migrated + 5 new from Plan 01)
+2. `npm run build` -- IIFE bundle builds without errors
+3. `npm run build:dev` -- sourcemap build works
+4. Browser: KimaiHeatmap.init renders year heatmap identically to v1.0
+5. Browser console: no errors on load, hover, click, filter, resize
+</verification>
+
+<success_criteria>
+- YearModeRenderer exists and implements ModeRenderer interface
+- heatmap.ts is a slim orchestrator (~80-120 lines, down from 413)
+- renderHeatmap() no longer exists as a standalone function
+- All test files import from new module locations
+- Full test suite passes (9 files)
+- esbuild produces valid IIFE bundle
+- Visual regression check passes (human verification)
+</success_criteria>
+
+<output>
+After completion, create `.planning/phases/06-renderer-architecture/06-02-SUMMARY.md`
+</output>

.planning/phases/06-renderer-architecture/06-02-SUMMARY.md

@@ -0,0 +1,112 @@
+---
+phase: 06-renderer-architecture
+plan: 02
+subsystem: ui
+tags: [typescript, d3, strategy-pattern, renderer, refactor]
+
+requires:
+  - phase: 06-01
+    provides: ModeRenderer interface, RenderContext, registry, shared utility modules
+provides:
+  - YearModeRenderer implementing ModeRenderer for year-view heatmap
+  - Slim heatmap.ts orchestrator dispatching through renderer registry
+  - All test imports migrated to new module locations
+affects: [06-03, 07-mode-renderers]
+
+tech-stack:
+  added: []
+  patterns: [strategy-pattern dispatch via getRenderer(state.mode), metric-aware color fill]
+
+key-files:
+  created:
+    - assets/src/renderers/year.ts
+  modified:
+    - assets/src/renderers/types.ts
+    - assets/src/heatmap.ts
+    - assets/test/heatmap.test.ts
+    - assets/test/stats.test.ts
+    - assets/test/interaction.test.ts
+
+key-decisions:
+  - "Cell fill uses metric-aware accessor (hours vs count) for forward-compatible display toggle"
+  - "emptyMessage added to RenderContext to preserve filtered empty state messages"
+
+patterns-established:
+  - "Renderer dispatch: getRenderer(state.mode).render(ctx) in doRender()"
+  - "Module-level renderer registration: registerRenderer(new YearModeRenderer()) at import time"
+
+requirements-completed: []
+
+duration: 3min
+completed: 2026-04-09
+---
+
+# Phase 6 Plan 02: Renderer Wiring Summary
+
+**YearModeRenderer wired into strategy-pattern orchestrator, heatmap.ts reduced from 413 to 116 lines, all 62 tests passing**
+
+## Performance
+
+- **Duration:** 3 min
+- **Started:** 2026-04-09T07:44:14Z
+- **Completed:** 2026-04-09T07:47:26Z
+- **Tasks:** 2 automated + 1 checkpoint (pending human verification)
+- **Files modified:** 6
+
+## Accomplishments
+- Created YearModeRenderer that produces identical SVG output to v1.0 renderHeatmap()
+- Rewrote heatmap.ts as slim orchestrator using registry dispatch pattern
+- Migrated all test imports to new module locations -- 62/62 tests pass across 9 files
+- Added metric-aware cell fill (forward-compatible for hours/count toggle)
+
+## Task Commits
+
+Each task was committed atomically:
+
+1. **Task 1: Create YearModeRenderer and rewrite heatmap.ts orchestrator** - `aab3915` (feat)
+2. **Task 2: Migrate test imports and verify full suite** - `881718e` (refactor)
+3. **Task 3: Visual regression check** - checkpoint (pending human verification)
+
+## Files Created/Modified
+- `assets/src/renderers/year.ts` - YearModeRenderer implementing ModeRenderer with full year heatmap rendering
+- `assets/src/renderers/types.ts` - Added emptyMessage to RenderContext
+- `assets/src/heatmap.ts` - Slim orchestrator (116 lines, down from 413)
+- `assets/test/heatmap.test.ts` - Migrated from renderHeatmap to YearModeRenderer.render()
+- `assets/test/stats.test.ts` - Import path changed to shared/stats
+- `assets/test/interaction.test.ts` - Migrated from renderHeatmap to YearModeRenderer.render()
+
+## Decisions Made
+- Cell fill uses `ctx.state.metric === 'hours' ? d.entry.hours : d.entry.count` for forward-compatible metric toggle (no-op for v1.0 where metric is always 'hours')
+- emptyMessage added as optional field on RenderContext to preserve "No tracking data for this project" filtered empty message
+
+## Deviations from Plan
+
+None - plan executed exactly as written.
+
+## Issues Encountered
+None.
+
+## User Setup Required
+None - no external service configuration required.
+
+## Checkpoint: Visual Regression Check
+
+**Status:** Automated verification passed (build:dev succeeds). Manual visual verification pending.
+
+Verification steps for human:
+1. Start local Kimai dev environment
+2. Navigate to dashboard
+3. Verify heatmap renders identically: cells colored green, tooltip on hover, click navigates to timesheet, stats row present, filter dropdown works, resize re-renders
+4. Check browser console -- no errors
+5. Verify `typeof KimaiHeatmap.init === 'function'` in console
+
+## Next Phase Readiness
+- Renderer architecture fully wired -- adding new modes requires only implementing ModeRenderer and calling registerRenderer()
+- Ready for Plan 03 (mode switcher UI and additional renderers)
+
+## Self-Check: PASSED
+
+- All 6 created/modified files exist on disk
+- Both task commits verified (aab3915, 881718e)
+- Full test suite: 62/62 passing across 9 files
+- esbuild: produces valid IIFE bundle (38.9kb minified)

.planning/phases/06-renderer-architecture/06-HUMAN-UAT.md

@@ -0,0 +1,32 @@
+---
+status: passed
+phase: 06-renderer-architecture
+source: [06-VERIFICATION.md]
+started: 2026-04-09T10:00:00Z
+updated: 2026-04-09T10:15:00Z
+---
+
+## Current Test
+
+[complete]
+
+## Tests
+
+### 1. Visual Regression Check
+expected: Heatmap renders identically to v1.0 — green cells (4 shades), tooltip on hover (date, hours, entries), click navigates to timesheet filtered by date, stats row (streak, total, avg, busiest), filter dropdown works, window resize re-renders correctly
+result: passed
+
+### 2. Runtime Console Check
+expected: No JS errors on load/hover/click/filter/resize. `typeof KimaiHeatmap.init === 'function'` returns true in console.
+result: passed
+
+## Summary
+
+total: 2
+passed: 2
+issues: 0
+pending: 0
+skipped: 0
+blocked: 0
+
+## Gaps

.planning/phases/06-renderer-architecture/06-RESEARCH.md

@@ -0,0 +1,395 @@
+# Phase 6: Renderer Architecture - Research
+
+**Researched:** 2026-04-09
+**Domain:** TypeScript strategy pattern refactor for d3.js multi-mode heatmap
+**Confidence:** HIGH
+
+## Summary
+
+Phase 6 is a pure refactoring phase: decompose the 413-line monolithic `heatmap.ts` into a strategy-pattern renderer system where adding a new visualization mode means implementing a `ModeRenderer` interface and registering it. No new features ship -- the year-view must render identically to v1.0.
+
+The current code has clear seams for extraction. `renderHeatmap()` handles cell generation, color scaling, tooltips, and click handlers all inline. `init()` manages state (current data, active project filter) via closure variables. The refactor creates three layers: (1) a `HeatmapState` object owning mode/metric/filter state, (2) shared utilities (tooltip, color scale, cell click), and (3) mode-specific renderers that consume state and utilities.
+
+**Primary recommendation:** Use TypeScript interfaces + a renderer registry map. No external libraries needed -- this is a structural refactor of existing code with existing dependencies.
+
+## Standard Stack
+
+### Core (no changes from v1.0)
+| Library | Version | Purpose | Why Standard |
+|---------|---------|---------|--------------|
+| d3-selection | ^3.0.0 | DOM binding | Already in use, all renderers will use it |
+| d3-scale | ^4.0.2 | Color quantization | Shared color scale utility |
+| d3-time | ^3.1.0 | Date math | Year-mode cell layout |
+| d3-time-format | ^4.1.0 | Date formatting | Tooltip display |
+| d3-array | ^3.2.4 | Data aggregation | max(), extent() for scales |
+
+### Testing (no changes)
+| Library | Version | Purpose |
+|---------|---------|---------|
+| vitest | ^4.1.3 | Test runner |
+| jsdom | ^29.0.2 | DOM environment |
+
+### No New Dependencies
+This phase adds zero new packages. The strategy pattern and state management are pure TypeScript constructs. [VERIFIED: codebase analysis]
+
+## Architecture Patterns
+
+### Current Structure (v1.0)
+```
+assets/src/
+  heatmap.ts     # 413 lines -- everything in one file
+  types.ts       # DayEntry, HeatmapData, HeatmapConfig, ProjectOption
+```
+
+### Target Structure (Phase 6)
+```
+assets/src/
+  types.ts              # Extended with HeatmapState, ModeRenderer, DisplayMetric
+  state.ts              # HeatmapState class -- mode, metric, filters, data
+  renderers/
+    registry.ts         # Mode -> Renderer map, getRenderer()
+    year.ts             # YearModeRenderer -- extracted from current renderHeatmap()
+    types.ts            # ModeRenderer interface, RenderContext
+  shared/
+    tooltip.ts          # createTooltip(), showTooltip(), hideTooltip()
+    color-scale.ts      # buildColorScale() -- shared quantize scale factory
+    cells.ts            # Cell click handler factory, cell class builder
+    stats.ts            # calculateStreak(), calculateStats(), renderStats()
+    date-utils.ts       # generateCells(), buildDateMap(), getWeekInterval()
+  heatmap.ts            # Slim orchestrator: init() + doRender() dispatching to registry
+```
+
+### Pattern 1: ModeRenderer Interface
+**What:** Each visualization mode implements a common interface. The orchestrator asks the registry for the current mode's renderer and calls `render()`.
+**When to use:** Every new mode (week, day, combined) implements this interface.
+
+```typescript
+// assets/src/renderers/types.ts
+export interface RenderContext {
+  container: HTMLElement;      // The SVG area div
+  data: HeatmapData;          // Raw day entries from API
+  state: HeatmapState;        // Current mode, metric, filters
+  config: HeatmapConfig;      // Cell size, margins
+  onCellClick?: (dateStr: string) => void;
+}
+
+export interface ModeRenderer {
+  readonly mode: string;       // 'year' | 'week' | 'day' | 'combined'
+  render(ctx: RenderContext): void;
+  destroy?(): void;            // Cleanup tooltips, listeners
+}
+```
+
+[ASSUMED -- interface design based on strategy pattern best practices]
+
+### Pattern 2: HeatmapState
+**What:** A single state object tracks the current mode, display metric, and active filters. UI changes mutate state, then trigger a re-render.
+**When to use:** Any time a user action changes what the heatmap displays.
+
+```typescript
+// assets/src/state.ts
+export type DisplayMetric = 'hours' | 'count';
+export type HeatmapMode = 'year' | 'week' | 'day' | 'combined';
+
+export interface FilterState {
+  projectId: number | null;
+  customerId: number | null;
+  activityId: number | null;
+}
+
+export interface HeatmapState {
+  mode: HeatmapMode;
+  metric: DisplayMetric;
+  filters: FilterState;
+  weekStart: string;
+  data: HeatmapData | null;
+}
+
+export function createInitialState(weekStart: string): HeatmapState {
+  return {
+    mode: 'year',
+    metric: 'hours',
+    filters: { projectId: null, customerId: null, activityId: null },
+    weekStart,
+    data: null,
+  };
+}
+```
+
+[ASSUMED -- state shape designed to support Phases 7-10 requirements]
+
+### Pattern 3: Renderer Registry
+**What:** A map from mode string to renderer instance. New modes register themselves; the orchestrator just does `registry.get(state.mode).render(ctx)`.
+
+```typescript
+// assets/src/renderers/registry.ts
+import type { ModeRenderer } from './types';
+
+const renderers = new Map<string, ModeRenderer>();
+
+export function registerRenderer(renderer: ModeRenderer): void {
+  renderers.set(renderer.mode, renderer);
+}
+
+export function getRenderer(mode: string): ModeRenderer {
+  const r = renderers.get(mode);
+  if (!r) throw new Error(`Unknown heatmap mode: ${mode}`);
+  return r;
+}
+```
+
+[ASSUMED -- standard registry pattern]
+
+### Pattern 4: Shared Utility Extraction
+**What:** Tooltip, color scale, and click handler logic pulled out of `renderHeatmap()` into reusable functions.
+
+The current code has these inline:
+- **Tooltip** (lines 94-99, 284-296): `createTooltip()`, mouseenter/mouseleave handlers
+- **Color scale** (lines 200-205): `scaleQuantize` setup from data max
+- **Cell click** (lines 297-300): click handler calling `onCellClick(dateStr)`
+- **Stats** (lines 101-174): `calculateStreak()`, `calculateStats()`, `renderStats()`
+- **Date utils** (lines 47-92): `buildDateMap()`, `generateCells()`, `getWeekInterval()`
+
+Each becomes a standalone module importable by any renderer.
+
+### Anti-Patterns to Avoid
+- **God state object with methods:** Keep state as plain data. Renderers and the orchestrator read it; only `init()` mutates it. No class with 15 methods.
+- **Renderer knowing about DOM outside its container:** Each renderer gets a `container` div and only touches that. Tooltip appends to `document.body` but that's the tooltip utility's concern, not the renderer's.
+- **Event listener leaks:** Each renderer must clean up its tooltip and event listeners in `destroy()` before a new render. The current code already handles this (`container.innerHTML = ''` and removing stale tooltips).
+- **Breaking the IIFE global:** The esbuild output is `--format=iife --global-name=KimaiHeatmap`. The entry point must continue to export `init` on that global. Internal module structure is esbuild's concern.
+
+## Don't Hand-Roll
+
+| Problem | Don't Build | Use Instead | Why |
+|---------|-------------|-------------|-----|
+| Observable state / pub-sub | Custom event system | Callback-based re-render | This widget has one consumer (the orchestrator). A reactive framework is massive overkill for a single widget. Mutate state, call `doRender()`. |
+| Module bundling | Custom loader | esbuild (already configured) | esbuild handles the multi-file TS -> single IIFE bundle. No config changes needed for adding files. |
+| Color scale | Custom interpolation | d3-scale `scaleQuantize` | Already in use. Extract, don't rewrite. |
+
+**Key insight:** This refactor is about decomposition, not new capabilities. Every function already exists in `heatmap.ts` -- the work is extraction and interface definition.
+
+## Common Pitfalls
+
+### Pitfall 1: Breaking the esbuild IIFE entry point
+**What goes wrong:** Refactoring the entry point changes what `KimaiHeatmap.init` resolves to in the browser.
+**Why it happens:** Moving `init()` to a different file or changing its export signature.
+**How to avoid:** Keep `assets/src/heatmap.ts` as the entry point. It imports everything internally and exports `init`. The esbuild command stays identical.
+**Warning signs:** `KimaiHeatmap.init is not a function` in browser console.
+
+### Pitfall 2: Tooltip cleanup between renders
+**What goes wrong:** Stale tooltips pile up on `document.body` when switching modes or re-rendering.
+**Why it happens:** Each `render()` creates a new tooltip div but doesn't remove the old one.
+**How to avoid:** The tooltip utility must track and clean up its previous instance. Current code already does `document.querySelectorAll('.heatmap-tooltip').forEach(el => el.remove())` -- centralize this in the tooltip module.
+**Warning signs:** Multiple `.heatmap-tooltip` elements in DOM inspector.
+
+### Pitfall 3: Over-engineering state management
+**What goes wrong:** Building a reactive store, subscriptions, or middleware for a widget that has one consumer.
+**Why it happens:** Applying SPA patterns to a dashboard widget.
+**How to avoid:** Plain object + imperative `doRender()` call. The `init()` function owns the render loop. State changes -> call `doRender()`. That's it.
+**Warning signs:** Words like "subscribe", "dispatch", "reducer" appearing in widget code.
+
+### Pitfall 4: Tests coupled to implementation details
+**What goes wrong:** Existing tests break because they import internal functions that moved files.
+**Why it happens:** Tests import `calculateStreak` from `'../src/heatmap'` -- if that function moves to `'../src/shared/stats'`, imports break.
+**How to avoid:** Re-export moved functions from `heatmap.ts` (barrel pattern) OR update all test imports in the same commit. The second approach is cleaner -- tests should import from the module that owns the function.
+**Warning signs:** Test files with `import from '../src/heatmap'` for functions that now live elsewhere.
+
+### Pitfall 5: Visual regression from refactor
+**What goes wrong:** SVG output changes subtly (attribute order, class names, positioning) and nobody notices.
+**Why it happens:** Extracting code sometimes changes initialization order or default values.
+**How to avoid:** Add a snapshot test that captures the SVG output of `renderHeatmap()` with known data. Compare before and after refactor. The existing tests already check cell count, classes, and tooltips -- they're good regression guards.
+**Warning signs:** Heatmap "looks slightly off" after deploy.
+
+## Code Examples
+
+### Extracting the tooltip utility
+```typescript
+// assets/src/shared/tooltip.ts
+export function createTooltip(): HTMLDivElement {
+  // Clean up any stale tooltips
+  document.querySelectorAll('.heatmap-tooltip').forEach(el => el.remove());
+
+  const tip = document.createElement('div');
+  tip.className = 'heatmap-tooltip';
+  tip.style.display = 'none';
+  tip.style.position = 'fixed';
+  document.body.appendChild(tip);
+  return tip;
+}
+
+export function showTooltip(
+  tip: HTMLDivElement,
+  html: string,
+  anchorRect: DOMRect,
+  cellSize: number,
+): void {
+  tip.innerHTML = html;
+  tip.style.display = 'block';
+  tip.style.left = `${anchorRect.left + cellSize / 2}px`;
+  tip.style.top = `${anchorRect.top - tip.offsetHeight - 8}px`;
+}
+
+export function hideTooltip(tip: HTMLDivElement): void {
+  tip.style.display = 'none';
+}
+```
+Source: extracted from current heatmap.ts lines 94-99, 284-296 [VERIFIED: codebase]
+
+### Extracting the color scale
+```typescript
+// assets/src/shared/color-scale.ts
+import { scaleQuantize } from 'd3-scale';
+import { max } from 'd3-array';
+import type { DayEntry, DisplayMetric } from '../types';
+
+const FALLBACK_COLORS = ['#9be9a8', '#40c463', '#30a14e', '#216e39'];
+
+export function buildColorScale(
+  days: DayEntry[],
+  metric: DisplayMetric = 'hours',
+): ReturnType<typeof scaleQuantize<string>> {
+  const accessor = metric === 'hours' ? (d: DayEntry) => d.hours : (d: DayEntry) => d.count;
+  const maxVal = max(days, accessor) || 1;
+  return scaleQuantize<string>().domain([0, maxVal]).range(FALLBACK_COLORS);
+}
+```
+Source: extracted from current heatmap.ts lines 200-205 [VERIFIED: codebase]
+
+### Year renderer implementing ModeRenderer
+```typescript
+// assets/src/renderers/year.ts (sketch)
+import type { ModeRenderer, RenderContext } from './types';
+import { createTooltip, showTooltip, hideTooltip } from '../shared/tooltip';
+import { buildColorScale } from '../shared/color-scale';
+import { generateCells, buildDateMap, getWeekInterval } from '../shared/date-utils';
+// ... d3 imports
+
+export class YearModeRenderer implements ModeRenderer {
+  readonly mode = 'year';
+  private tooltip: HTMLDivElement | null = null;
+
+  render(ctx: RenderContext): void {
+    ctx.container.innerHTML = '';
+    this.tooltip = createTooltip();
+    // ... existing renderHeatmap() logic using ctx.data, ctx.state, ctx.config
+  }
+
+  destroy(): void {
+    this.tooltip?.remove();
+    this.tooltip = null;
+  }
+}
+```
+[ASSUMED -- implementation sketch, actual extraction follows current code structure]
+
+### Slim orchestrator init
+```typescript
+// assets/src/heatmap.ts (after refactor, sketch)
+import { createInitialState } from './state';
+import { getRenderer, registerRenderer } from './renderers/registry';
+import { YearModeRenderer } from './renderers/year';
+import { renderStats } from './shared/stats';
+
+// Register built-in renderers
+registerRenderer(new YearModeRenderer());
+
+export function init(container: HTMLElement): void {
+  const weekStart = container.getAttribute('data-week-start') || 'monday';
+  const state = createInitialState(weekStart);
+
+  // ... same data-url/projects parsing as current init()
+
+  const doRender = () => {
+    if (!state.data) return;
+    const renderer = getRenderer(state.mode);
+    renderer.destroy?.();
+    renderer.render({
+      container: svgArea,
+      data: state.data,
+      state,
+      config: DEFAULT_CONFIG,
+      onCellClick,
+    });
+    renderStats(container, state.data.days);
+  };
+
+  // ... fetch, filter, resize logic unchanged
+}
+```
+[ASSUMED -- orchestration sketch]
+
+## Validation Architecture
+
+### Test Framework
+| Property | Value |
+|----------|-------|
+| Framework | Vitest ^4.1.3 |
+| Config file | `vitest.config.ts` |
+| Quick run command | `npm test` |
+| Full suite command | `npm test` |
+
+### Phase Requirements -> Test Map
+
+Phase 6 has no formal requirement IDs (it is an architectural enabler). Testing maps to success criteria:
+
+| Criterion | Behavior | Test Type | Automated Command | File Exists? |
+|-----------|----------|-----------|-------------------|-------------|
+| SC-1 | Year-view renders identically to v1.0 | unit | `npx vitest run assets/test/heatmap.test.ts` | Yes (existing) |
+| SC-2 | Shared utilities are importable and work | unit | `npx vitest run assets/test/tooltip.test.ts` | No -- Wave 0 |
+| SC-3 | HeatmapState tracks mode/metric/filters | unit | `npx vitest run assets/test/state.test.ts` | No -- Wave 0 |
+| SC-4 | Registry dispatches to correct renderer | unit | `npx vitest run assets/test/registry.test.ts` | No -- Wave 0 |
+
+### Sampling Rate
+- **Per task commit:** `npm test`
+- **Per wave merge:** `npm test`
+- **Phase gate:** All existing tests pass + new unit tests for extracted modules
+
+### Wave 0 Gaps
+- [ ] `assets/test/state.test.ts` -- covers SC-3 (HeatmapState creation and mutation)
+- [ ] `assets/test/registry.test.ts` -- covers SC-4 (renderer registration and lookup)
+- [ ] `assets/test/tooltip.test.ts` -- covers SC-2 (tooltip create/show/hide lifecycle)
+- [ ] `assets/test/color-scale.test.ts` -- covers SC-2 (color scale with hours and count metrics)
+
+## Assumptions Log
+
+| # | Claim | Section | Risk if Wrong |
+|---|-------|---------|---------------|
+| A1 | ModeRenderer interface shape (mode, render, destroy) | Architecture Patterns | Low -- interface is internal, easily adjusted before Phase 7 |
+| A2 | HeatmapState includes customerId/activityId fields for future phases | Architecture Patterns | Low -- adding fields later is trivial |
+| A3 | DisplayMetric 'hours' vs 'count' toggle reads from state.metric | Code Examples | Low -- this is the only sensible design given VIZ-05 |
+| A4 | Plain object state + imperative re-render is sufficient (no reactive store) | Common Pitfalls | Medium -- if filter interactions become complex in Phase 10, may need pub/sub. But can add later. |
+
+## Open Questions
+
+1. **Should stats rendering move inside the renderer or stay in the orchestrator?**
+   - What we know: Stats (streak, total, avg, busiest) are mode-agnostic in v1.0 but may differ by mode later (week-mode might show "busiest weekday" instead of "busiest day").
+   - What's unclear: Whether future modes need custom stats.
+   - Recommendation: Keep `renderStats()` in the orchestrator for now. If a mode needs custom stats, the `ModeRenderer` interface can gain an optional `renderStats()` method later.
+
+2. **Should the filter dropdown stay in `init()` or become its own module?**
+   - What we know: Phase 10 replaces the plain `<select>` with TomSelect cascading pickers.
+   - What's unclear: Whether extracting filters now saves work in Phase 10.
+   - Recommendation: Leave filter construction in `init()` for Phase 6. Phase 10 will gut it anyway. Extracting now is churn.
+
+## Sources
+
+### Primary (HIGH confidence)
+- Codebase analysis: `assets/src/heatmap.ts` (413 lines), `assets/src/types.ts`, all test files
+- `package.json` -- verified dependencies and build config
+- `vitest.config.ts` -- verified test setup
+
+### Secondary (MEDIUM confidence)
+- None needed -- this phase is purely about restructuring existing code
+
+### Tertiary (LOW confidence)
+- None
+
+## Metadata
+
+**Confidence breakdown:**
+- Standard stack: HIGH -- no new dependencies, verified from package.json
+- Architecture: HIGH -- based on direct analysis of 413-line source file with clear extraction seams
+- Pitfalls: HIGH -- derived from actual code patterns (tooltip cleanup, esbuild IIFE, test imports)
+
+**Research date:** 2026-04-09
+**Valid until:** 2026-05-09 (stable -- no external dependencies changing)

.planning/phases/06-renderer-architecture/06-REVIEW.md

@@ -0,0 +1,97 @@
+---
+phase: 06-renderer-architecture
+reviewed: 2026-04-09T14:00:00Z
+depth: standard
+files_reviewed: 10
+files_reviewed_list:
+  - assets/src/heatmap.ts
+  - assets/src/renderers/registry.ts
+  - assets/src/renderers/types.ts
+  - assets/src/renderers/year.ts
+  - assets/src/shared/color-scale.ts
+  - assets/src/shared/date-utils.ts
+  - assets/src/shared/stats.ts
+  - assets/src/shared/tooltip.ts
+  - assets/src/state.ts
+  - assets/src/types.ts
+findings:
+  critical: 0
+  warning: 3
+  info: 2
+  total: 5
+status: issues_found
+---
+
+# Phase 06: Code Review Report
+
+**Reviewed:** 2026-04-09T14:00:00Z
+**Depth:** standard
+**Files Reviewed:** 10
+**Status:** issues_found
+
+## Summary
+
+The renderer architecture refactor is clean and well-structured. The extraction of shared utilities (tooltip, color-scale, stats, date-utils) into focused modules is solid, and the renderer registry pattern is simple and appropriate. No security vulnerabilities or critical bugs found. The issues below are defensive coding gaps and a minor cleanup item.
+
+## Warnings
+
+### WR-01: Unchecked JSON.parse can crash init
+
+**File:** `assets/src/heatmap.ts:21`
+**Issue:** `JSON.parse(projectsJson)` will throw a `SyntaxError` if the `data-projects` attribute contains malformed JSON. This would crash the entire `init()` function, leaving the heatmap unrendered with no user-facing error.
+**Fix:**
+```typescript
+let projects: ProjectOption[] = [];
+if (projectsJson) {
+  try {
+    projects = JSON.parse(projectsJson);
+  } catch {
+    console.error('KimaiHeatmap: invalid data-projects JSON');
+  }
+}
+```
+
+### WR-02: Resize listener never removed -- leaks on repeated init()
+
+**File:** `assets/src/heatmap.ts:107-112`
+**Issue:** The `resize` event listener is added but never removed. If `init()` is called multiple times on the same or different containers (e.g., SPA navigation, widget reload), each call adds another listener. The old listeners reference stale closures and DOM elements.
+**Fix:** Return a cleanup function or store the listener reference for removal:
+```typescript
+const onResize = () => {
+  clearTimeout(resizeTimer);
+  resizeTimer = setTimeout(() => {
+    if (state.data) doRender();
+  }, 200);
+};
+window.addEventListener('resize', onResize);
+// Store for cleanup: return { destroy: () => window.removeEventListener('resize', onResize) };
+```
+
+### WR-03: innerHTML usage in stats renders data into DOM unsanitized
+
+**File:** `assets/src/shared/stats.ts:79`
+**Issue:** `statsDiv.innerHTML = parts.join('')` injects content built from `DISPLAY_FORMAT(d)` output and numeric values. Currently safe because the data sources are controlled (d3 date formatter output and numbers), but the innerHTML pattern is fragile -- if a future change introduces user-controlled strings into `parts`, it becomes an XSS vector. The same pattern exists in `tooltip.ts:18` with `tip.innerHTML = html`.
+**Fix:** Consider using `textContent` with structured DOM creation instead of innerHTML, or document the safety invariant with a comment so future maintainers know the constraint.
+
+## Info
+
+### IN-01: Unused import -- timeMonth in date-utils.ts
+
+**File:** `assets/src/shared/date-utils.ts:1`
+**Issue:** `timeMonth` is imported from `d3-time` but never used in this module. It is used in `renderers/year.ts` which imports it directly.
+**Fix:** Remove `timeMonth` from the import:
+```typescript
+import { timeMonday, timeSunday, timeDay } from 'd3-time';
+```
+
+### IN-02: console.error calls as runtime logging
+
+**File:** `assets/src/heatmap.ts:14,95,125`
+**Issue:** Three `console.error` calls serve as runtime error reporting. These are appropriate for a Kimai plugin context (no structured logging available), but worth noting as intentional rather than debug artifacts.
+**Fix:** No action needed. If the project later adopts a logging abstraction, consolidate these.
+
+---
+
+_Reviewed: 2026-04-09T14:00:00Z_
+_Reviewer: Claude (gsd-code-reviewer)_
+_Depth: standard_

.planning/phases/06-renderer-architecture/06-UI-SPEC.md

@@ -0,0 +1,150 @@
+---
+phase: 6
+slug: renderer-architecture
+status: draft
+shadcn_initialized: false
+preset: none
+created: 2026-04-09
+---
+
+# Phase 6 — UI Design Contract
+
+> Visual and interaction contract for the renderer architecture refactor. This phase ships zero visual changes -- the contract documents the existing v1.0 visual baseline as a regression guard.
+
+---
+
+## Design System
+
+| Property | Value |
+|----------|-------|
+| Tool | none |
+| Preset | not applicable |
+| Component library | Tabler (Kimai host app) |
+| Icon library | not applicable (no icons in this phase) |
+| Font | `var(--tblr-font-sans-serif)` (inherited from Kimai/Tabler) |
+
+**Note:** This plugin renders inside a Kimai dashboard card (`@theme/embeds/card.html.twig`). All surface colors, fonts, and border styles inherit from Tabler CSS custom properties. No standalone design system is used or needed.
+
+---
+
+## Spacing Scale
+
+Declared values from existing v1.0 CSS (must remain unchanged after refactor):
+
+| Token | Value | Usage |
+|-------|-------|-------|
+| cell-gap | 2px | Gap between heatmap cells (SVG attribute, not CSS) |
+| tooltip-pad | 6px 10px | Tooltip internal padding |
+| wrapper-gap | 16px | Gap between heatmap SVG area and filter dropdown |
+| stats-gap | 16px | Gap between stat items in footer row |
+| stats-top | 12px | Padding above stats row |
+| filter-top | 20px | Padding above filter dropdown (desktop) |
+
+Exceptions: Cell size and margins are controlled by `HeatmapConfig` in TypeScript (not CSS). These values must transfer unchanged to `DEFAULT_CONFIG` in the refactored code.
+
+---
+
+## Typography
+
+All typography inherits from Kimai/Tabler. The plugin declares only two overrides:
+
+| Role | Size | Weight | Line Height | Source |
+|------|------|--------|-------------|--------|
+| SVG label | 10px | 400 (normal) | default | `.heatmap-label` in heatmap.css |
+| Tooltip / Stats | 0.8125rem (13px) | 400 (normal) | default | `.heatmap-tooltip`, `.heatmap-stats` |
+| Stat value | 0.8125rem (13px) | 600 (semibold) | default | `.heatmap-stats .stat-value` |
+
+No new typography tokens in this phase.
+
+---
+
+## Color
+
+All colors use Tabler CSS custom properties. The plugin does not declare its own palette.
+
+| Role | Value | Usage |
+|------|-------|-------|
+| Body text | `var(--tblr-body-color)` | SVG labels, stat values, tooltip text |
+| Surface | `var(--tblr-bg-surface)` | Tooltip background |
+| Surface secondary | `var(--tblr-bg-surface-secondary)` | Empty heatmap cells |
+| Border | `var(--tblr-border-color)` | Tooltip border |
+| Secondary text | `var(--tblr-secondary, #6c757d)` | Stat labels |
+| Heatmap scale | `['#9be9a8', '#40c463', '#30a14e', '#216e39']` | Cell fill intensity (4-step quantize) |
+
+**Regression constraint:** The 4-color heatmap scale array must remain identical in `shared/color-scale.ts` after extraction. These are hardcoded GitHub-green values, not Tabler variables.
+
+Accent reserved for: not applicable (no accent color in this phase).
+
+---
+
+## Copywriting Contract
+
+Phase 6 introduces no new copy. Existing copy must survive the refactor unchanged:
+
+| Element | Copy | Location after refactor |
+|---------|------|------------------------|
+| Tooltip: date line | `{formatted date}` | `shared/tooltip.ts` |
+| Tooltip: hours line | `{N}h {M}m` | `shared/tooltip.ts` |
+| Tooltip: entries line | `{N} entries` | `shared/tooltip.ts` |
+| Stats: streak | `Current streak: {N} days` | `shared/stats.ts` |
+| Stats: total | `Total: {N}h` | `shared/stats.ts` |
+| Stats: average | `Daily avg: {N}h` | `shared/stats.ts` |
+| Stats: busiest | `Busiest: {date}` | `shared/stats.ts` |
+| Empty state | No explicit empty state (heatmap renders with all-empty cells) | `renderers/year.ts` |
+| Error state | No explicit error state (console.error only) | `heatmap.ts` orchestrator |
+| Primary CTA | not applicable (no user actions beyond hover/click) | -- |
+| Destructive confirmation | not applicable (no destructive actions) | -- |
+
+---
+
+## Interaction Contract
+
+No new interactions. Existing interactions must work identically after refactor:
+
+| Interaction | Behavior | Must survive in |
+|-------------|----------|-----------------|
+| Cell hover | Show tooltip with date, hours, entry count | `shared/tooltip.ts` + renderer |
+| Cell click | Navigate to Kimai timesheet filtered by date | `RenderContext.onCellClick` callback |
+| Cell hover (weekend) | Same tooltip, slightly reduced opacity (0.65 vs 0.75) | `.heatmap-weekend:hover` CSS (unchanged) |
+| Filter select change | Re-render heatmap with filtered project data | `heatmap.ts` orchestrator via `HeatmapState.filters` |
+| Window resize | Re-render to fit container width | `heatmap.ts` orchestrator (resize listener) |
+
+---
+
+## Regression Checklist
+
+These visual properties must be pixel-identical before and after the refactor:
+
+- [ ] Cell border-radius: `rx=2 ry=2`
+- [ ] Cell hover opacity: `0.75` (normal), `0.65` (weekend)
+- [ ] Tooltip shadow: `0 2px 8px rgba(0,0,0,0.12)`
+- [ ] Tooltip border-radius: `4px`
+- [ ] Empty cell fill: `var(--tblr-bg-surface-secondary)`
+- [ ] Heatmap color scale: 4 greens `#9be9a8 #40c463 #30a14e #216e39`
+- [ ] Stats layout: flex row with `16px` gap, wrapping
+- [ ] SVG month/day labels: `10px` sans-serif
+- [ ] Filter dropdown position: right side on desktop, above on mobile (<1330px)
+- [ ] Scroll behavior: horizontal scroll on `.heatmap-svg-area`
+
+---
+
+## Registry Safety
+
+| Registry | Blocks Used | Safety Gate |
+|----------|-------------|-------------|
+| not applicable | none | not applicable |
+
+No component registries or third-party blocks in this phase.
+
+---
+
+## Checker Sign-Off
+
+- [ ] Dimension 1 Copywriting: PASS
+- [ ] Dimension 2 Visuals: PASS
+- [ ] Dimension 3 Color: PASS
+- [ ] Dimension 4 Typography: PASS
+- [ ] Dimension 5 Spacing: PASS
+- [ ] Dimension 6 Registry Safety: PASS
+
+**Approval:** pending

.planning/phases/06-renderer-architecture/06-VERIFICATION.md

@@ -0,0 +1,108 @@
+---
+phase: 06-renderer-architecture
+verified: 2026-04-09T10:00:00Z
+status: human_needed
+score: 4/4 must-haves verified
+human_verification:
+  - test: "Load Kimai dashboard and verify heatmap renders identically to v1.0"
+    expected: "Cells colored with 4-shade green scale, tooltip on hover shows date/hours/entries, click navigates to timesheet, stats row present, filter dropdown works, window resize re-renders"
+    why_human: "Visual regression cannot be verified programmatically -- SVG structure matches but pixel-level rendering needs eyeballs"
+  - test: "Open browser console on dashboard page"
+    expected: "No JavaScript errors. typeof KimaiHeatmap.init === 'function'"
+    why_human: "Runtime behavior in actual Kimai environment with Symfony asset pipeline"
+---
+
+# Phase 6: Renderer Architecture Verification Report
+
+**Phase Goal:** Existing year-view heatmap works identically but through a mode-dispatched renderer system ready for new visualization modes
+**Verified:** 2026-04-09T10:00:00Z
+**Status:** human_needed
+**Re-verification:** No -- initial verification
+
+## Goal Achievement
+
+### Observable Truths
+
+| # | Truth | Status | Evidence |
+|---|-------|--------|----------|
+| 1 | Year-view heatmap renders identically to v1.0 (no visual regression) | VERIFIED (automated) | YearModeRenderer produces same SVG structure: same cell classes (heatmap-cell, heatmap-empty, heatmap-weekend), same tooltip HTML, same color scale, same cell-size computation. 124/124 tests pass including migrated heatmap/interaction tests. Visual confirmation pending human. |
+| 2 | Tooltip, color scale, and cell click handler extracted as shared utilities reusable by any renderer | VERIFIED | `shared/tooltip.ts` exports createTooltip/showTooltip/hideTooltip. `shared/color-scale.ts` exports buildColorScale with DisplayMetric param. YearModeRenderer imports all from shared/ paths. |
+| 3 | HeatmapState object tracks mode, display metric, and filters -- UI changes flow through state | VERIFIED | `state.ts` defines HeatmapState with mode/metric/filters/weekStart/data. `createInitialState('monday')` returns defaults. heatmap.ts creates state, passes via RenderContext to renderer. Filter changes mutate `state.filters.projectId` then call `doRender()`. |
+| 4 | Adding a new visualization mode requires only implementing ModeRenderer interface and registering it | VERIFIED | ModeRenderer interface in `renderers/types.ts` with `mode: string`, `render(ctx)`, optional `destroy()`. Registry in `renderers/registry.ts` with registerRenderer/getRenderer. heatmap.ts dispatches via `getRenderer(state.mode)`. Adding a mode = implement interface + call `registerRenderer(new FooRenderer())`. |
+
+**Score:** 4/4 truths verified (automated checks)
+
+### Required Artifacts
+
+| Artifact | Expected | Status | Details |
+|----------|----------|--------|---------|
+| `assets/src/renderers/year.ts` | YearModeRenderer implementing ModeRenderer | VERIFIED | 131 lines, implements full year heatmap rendering with shared utility imports |
+| `assets/src/renderers/types.ts` | ModeRenderer interface, RenderContext type | VERIFIED | Exports both interfaces, includes emptyMessage field |
+| `assets/src/renderers/registry.ts` | Renderer registration and lookup | VERIFIED | registerRenderer/getRenderer/clearRegistry exported |
+| `assets/src/state.ts` | HeatmapState creation | VERIFIED | HeatmapState interface + createInitialState factory |
+| `assets/src/shared/tooltip.ts` | Tooltip lifecycle functions | VERIFIED | createTooltip/showTooltip/hideTooltip exported |
+| `assets/src/shared/color-scale.ts` | Color scale factory | VERIFIED | buildColorScale with DisplayMetric support, FALLBACK_COLORS |
+| `assets/src/shared/stats.ts` | Stats calculation and rendering | VERIFIED | calculateStreak/calculateStats/renderStats/HeatmapStats |
+| `assets/src/shared/date-utils.ts` | Date grid utilities | VERIFIED | buildDateMap/generateCells/getWeekInterval/getDayLabels/DayCell + format constants |
+| `assets/src/types.ts` | Extended type definitions | VERIFIED | Added DisplayMetric, HeatmapMode, FilterState alongside existing interfaces |
+| `assets/src/heatmap.ts` | Slim orchestrator | VERIFIED | 128 lines (down from 413), imports from registry/state/shared modules |
+| `Resources/public/heatmap.js` | Built IIFE bundle with KimaiHeatmap.init | VERIFIED | 38.9kb minified, KimaiHeatmap global present |
+
+### Key Link Verification
+
+| From | To | Via | Status | Details |
+|------|----|-----|--------|---------|
+| heatmap.ts | renderers/registry.ts | `getRenderer(state.mode)` | WIRED | Line 45: `const renderer = getRenderer(state.mode)` |
+| heatmap.ts | renderers/year.ts | `registerRenderer(new YearModeRenderer())` | WIRED | Line 9: module-level registration |
+| heatmap.ts | state.ts | `createInitialState(weekStart)` | WIRED | Line 23: state creation |
+| heatmap.ts | shared/stats.ts | `renderStats(container, state.data.days)` | WIRED | Line 55: stats rendering in doRender() |
+| renderers/year.ts | shared/tooltip.ts | imports createTooltip/showTooltip/hideTooltip | WIRED | Lines 5, 116, 119: full tooltip lifecycle used |
+| renderers/year.ts | shared/color-scale.ts | imports buildColorScale | WIRED | Line 6, 40: scale built and used for cell fill |
+| renderers/year.ts | shared/date-utils.ts | imports generateCells, buildDateMap, getWeekInterval | WIRED | Lines 7-10, 34-37: all used for cell generation |
+| renderers/types.ts | types.ts | imports HeatmapData, HeatmapConfig | WIRED | Line 1 |
+| renderers/types.ts | state.ts | imports HeatmapState | WIRED | Line 2 |
+
+### Behavioral Spot-Checks
+
+| Behavior | Command | Result | Status |
+|----------|---------|--------|--------|
+| Full test suite passes | `npx vitest run` | 18 files, 124 tests, all passing | PASS |
+| esbuild produces valid bundle | `npm run build` | 38.9kb output, no errors | PASS |
+| KimaiHeatmap global in bundle | grep KimaiHeatmap in bundle | Found | PASS |
+| Old functions removed from heatmap.ts | grep renderHeatmap/buildDateMap/FALLBACK_COLORS | 0 matches | PASS |
+| heatmap.ts is slim | wc -l | 128 lines (down from 413) | PASS |
+
+### Requirements Coverage
+
+No requirement IDs assigned to this phase (architectural enabler). All v1.1 features depend on this refactor.
+
+### Anti-Patterns Found
+
+| File | Line | Pattern | Severity | Impact |
+|------|------|---------|----------|--------|
+| None found | - | - | - | - |
+
+No TODOs, FIXMEs, placeholders, or stub patterns found in any phase 6 source files.
+
+### Human Verification Required
+
+### 1. Visual Regression Check
+
+**Test:** Build dev bundle (`npm run build:dev`), start local Kimai, navigate to dashboard
+**Expected:** Heatmap renders identically to v1.0: green-shaded cells, tooltip on hover with date/hours/entries, click navigates to timesheet with date filter, stats row (streak/total/avg/busiest), filter dropdown works, window resize re-renders correctly
+**Why human:** SVG structure verified programmatically via tests, but actual visual rendering in browser with CSS and Kimai theme integration requires eyeballs
+
+### 2. Runtime Console Check
+
+**Test:** Open browser console on Kimai dashboard with heatmap loaded
+**Expected:** No JavaScript errors. `typeof KimaiHeatmap.init` returns `'function'`
+**Why human:** Verifying runtime behavior in actual Symfony/Kimai environment with asset pipeline
+
+### Gaps Summary
+
+No automated gaps found. All truths verified, all artifacts exist and are substantive, all key links wired. The only remaining verification is visual regression in a running Kimai instance (human verification items above).
+
+---
+
+_Verified: 2026-04-09T10:00:00Z_
+_Verifier: Claude (gsd-verifier)_

.planning/phases/07-mode-switcher-week-mode/07-01-PLAN.md

@@ -0,0 +1,264 @@
+---
+phase: 07-mode-switcher-week-mode
+plan: 01
+type: execute
+wave: 1
+depends_on: []
+files_modified:
+  - Resources/views/widget/heatmap.html.twig
+  - assets/src/ui/controls.ts
+  - assets/src/heatmap.ts
+  - Resources/public/heatmap.css
+  - assets/test/controls.test.ts
+autonomous: true
+requirements: [VIZ-01, VIZ-05, TEST-01]
+must_haves:
+  truths:
+    - "A segmented control in the widget header shows Year and Week buttons"
+    - "Clicking Week sets state.mode to week and triggers doRender"
+    - "A separate compact segmented control shows Hours and Count buttons"
+    - "Clicking Count sets state.metric to count and triggers doRender"
+    - "Controls persist across re-renders (live in card header, not SVG area)"
+    - "Stats row is hidden when mode is week, shown when mode is year"
+  artifacts:
+    - path: "assets/src/ui/controls.ts"
+      provides: "createModeControl and createMetricControl functions"
+      exports: ["createModeControl", "createMetricControl"]
+    - path: "Resources/views/widget/heatmap.html.twig"
+      provides: "Controls placeholder div in card header"
+      contains: "heatmap-controls"
+    - path: "assets/test/controls.test.ts"
+      provides: "Tests for mode switcher and metric toggle"
+      min_lines: 40
+  key_links:
+    - from: "assets/src/heatmap.ts"
+      to: "assets/src/ui/controls.ts"
+      via: "import createModeControl, createMetricControl"
+      pattern: "import.*controls"
+    - from: "assets/src/ui/controls.ts"
+      to: "state.mode / state.metric"
+      via: "onChange callbacks"
+      pattern: "onChange"
+---
+
+<objective>
+Build the mode switcher and hours/count toggle UI controls, wire them into the heatmap orchestrator, and add the Twig template placeholder.
+
+Purpose: Enables switching between year/week modes and hours/count metrics -- the UI backbone for all v1.1 visualization features.
+Output: Two Tabler nav-segmented controls in the widget header, wired to HeatmapState, with tests.
+</objective>
+
+<execution_context>
+@/home/toph/code/toph/kimai-heatmap/.claude/get-shit-done/workflows/execute-plan.md
+@/home/toph/code/toph/kimai-heatmap/.claude/get-shit-done/templates/summary.md
+</execution_context>
+
+<context>
+@.planning/PROJECT.md
+@.planning/ROADMAP.md
+@.planning/STATE.md
+@.planning/phases/07-mode-switcher-week-mode/07-CONTEXT.md
+@.planning/phases/07-mode-switcher-week-mode/07-RESEARCH.md
+@.planning/phases/07-mode-switcher-week-mode/07-UI-SPEC.md
+@.planning/phases/06-renderer-architecture/06-01-SUMMARY.md
+@.planning/phases/06-renderer-architecture/06-02-SUMMARY.md
+
+<interfaces>
+<!-- Key types and contracts the executor needs. -->
+
+From assets/src/types.ts:
+```typescript
+export type DisplayMetric = 'hours' | 'count';
+export type HeatmapMode = 'year' | 'week' | 'day' | 'combined';
+```
+
+From assets/src/state.ts:
+```typescript
+export interface HeatmapState {
+  mode: HeatmapMode;
+  metric: DisplayMetric;
+  filters: FilterState;
+  weekStart: string;
+  data: HeatmapData | null;
+}
+export function createInitialState(weekStart: string): HeatmapState;
+```
+
+From assets/src/renderers/registry.ts:
+```typescript
+export function getRenderer(mode: string): ModeRenderer;
+```
+
+From assets/src/shared/stats.ts:
+```typescript
+export function renderStats(container: HTMLElement, days: DayEntry[]): void;
+```
+
+From assets/src/heatmap.ts (current doRender pattern):
+```typescript
+const doRender = () => {
+  if (!state.data) return;
+  const renderer = getRenderer(state.mode);
+  renderer.destroy?.();
+  renderer.render({ container: svgArea, data: state.data, state, config: {...}, onCellClick, emptyMessage: ... });
+  renderStats(container, state.data.days);
+  svgArea.scrollLeft = svgArea.scrollWidth;
+};
+```
+</interfaces>
+</context>
+
+<tasks>
+
+<task type="auto" tdd="true">
+  <name>Task 1: Create UI controls module and wire into heatmap orchestrator</name>
+  <files>
+    assets/src/ui/controls.ts,
+    assets/src/heatmap.ts,
+    Resources/views/widget/heatmap.html.twig,
+    Resources/public/heatmap.css,
+    assets/test/controls.test.ts
+  </files>
+  <read_first>
+    assets/src/heatmap.ts,
+    assets/src/types.ts,
+    assets/src/state.ts,
+    assets/src/shared/stats.ts,
+    Resources/views/widget/heatmap.html.twig,
+    Resources/public/heatmap.css,
+    .planning/phases/07-mode-switcher-week-mode/07-UI-SPEC.md
+  </read_first>
+  <behavior>
+    - createModeControl('year', [{key:'year',label:'Year'},{key:'week',label:'Week'}], cb) returns nav element with class 'nav nav-segmented' and role='tablist'
+    - createModeControl: first button has class 'nav-link active', second has 'nav-link' (no active)
+    - createModeControl: clicking inactive button adds 'active' to it, removes 'active' from previous, calls onChange with key
+    - createMetricControl('hours', cb) returns nav element with class 'nav nav-segmented nav-sm'
+    - createMetricControl: clicking 'Count' calls onChange with 'count'
+    - Both controls have role='tab' on buttons and aria-selected attribute
+  </behavior>
+  <action>
+    **1. Create `assets/src/ui/controls.ts`** with two exported functions:
+
+    `createModeControl(activeMode: string, modes: Array<{key: string; label: string}>, onChange: (mode: string) => void): HTMLElement`
+    - Create `<nav>` with `className = 'nav nav-segmented'` and `role="tablist"`
+    - For each mode, create `<button>` with `className = 'nav-link'` (add ` active` if `m.key === activeMode`)
+    - Set `role="tab"`, `aria-selected` = `"true"/"false"` based on active
+    - On click: remove `active` from all siblings, add `active` to clicked, update `aria-selected`, call `onChange(m.key)`
+    - Return the nav element
+
+    `createMetricControl(activeMetric: string, onChange: (metric: string) => void): HTMLElement`
+    - Same pattern but `className = 'nav nav-segmented nav-sm'`
+    - Two hardcoded options: `{key: 'hours', label: 'Hours'}` and `{key: 'count', label: 'Count'}`
+
+    **2. Modify `Resources/views/widget/heatmap.html.twig`** -- change the `{% block box_title %}` block from:
+    ```
+    {% block box_title %}
+        {{ title }}
+    {% endblock %}
+    ```
+    To:
+    ```
+    {% block box_title %}
+        <div style="display: flex; align-items: center; gap: 12px; flex-wrap: wrap;">
+            {{ title }}
+            <div id="heatmap-controls" style="display: flex; gap: 8px; margin-left: auto;"></div>
+        </div>
+    {% endblock %}
+    ```
+
+    **3. Modify `assets/src/heatmap.ts`** -- in the `init()` function:
+    - Add import: `import { createModeControl, createMetricControl } from './ui/controls';`
+    - After building wrapper and svgArea, before the filter dropdown section, add control wiring:
+    ```typescript
+    const controlsContainer = document.getElementById('heatmap-controls');
+    if (controlsContainer) {
+      const modeControl = createModeControl(state.mode, [
+        { key: 'year', label: 'Year' },
+        { key: 'week', label: 'Week' },
+      ], (mode) => {
+        state.mode = mode as HeatmapMode;
+        doRender();
+      });
+
+      const metricControl = createMetricControl(state.metric, (metric) => {
+        state.metric = metric as DisplayMetric;
+        doRender();
+      });
+
+      controlsContainer.appendChild(modeControl);
+      controlsContainer.appendChild(metricControl);
+    }
+    ```
+    - Modify `doRender()` to conditionally render stats: replace `renderStats(container, state.data.days);` with:
+    ```typescript
+    if (state.mode === 'year') {
+      renderStats(container, state.data.days);
+    } else {
+      const existingStats = container.querySelector('.heatmap-stats');
+      if (existingStats) existingStats.remove();
+    }
+    ```
+    - Modify `doRender()` to only auto-scroll for year mode: wrap `svgArea.scrollLeft = svgArea.scrollWidth;` in `if (state.mode === 'year') { ... }`
+
+    **4. Add to `Resources/public/heatmap.css`:**
+    ```css
+    .heatmap-week-cell {
+      cursor: default;
+    }
+    ```
+
+    **5. Create `assets/test/controls.test.ts`** with tests per the behavior block above. Import from `../src/ui/controls`. Use jsdom to verify DOM output, class names, click handlers, and aria attributes.
+  </action>
+  <verify>
+    <automated>cd /home/toph/code/toph/kimai-heatmap && npx vitest run assets/test/controls.test.ts</automated>
+  </verify>
+  <acceptance_criteria>
+    - assets/src/ui/controls.ts contains `export function createModeControl(`
+    - assets/src/ui/controls.ts contains `export function createMetricControl(`
+    - assets/src/ui/controls.ts contains `nav nav-segmented`
+    - assets/src/ui/controls.ts contains `nav-sm`
+    - assets/src/ui/controls.ts contains `role` and `tablist` and `aria-selected`
+    - assets/src/heatmap.ts contains `import { createModeControl, createMetricControl } from './ui/controls'`
+    - assets/src/heatmap.ts contains `document.getElementById('heatmap-controls')`
+    - assets/src/heatmap.ts contains `state.mode === 'year'` (conditional stats)
+    - Resources/views/widget/heatmap.html.twig contains `id="heatmap-controls"`
+    - Resources/views/widget/heatmap.html.twig contains `display: flex; align-items: center; gap: 12px`
+    - Resources/public/heatmap.css contains `.heatmap-week-cell`
+    - assets/test/controls.test.ts exists and `npx vitest run assets/test/controls.test.ts` exits 0
+    - `npm test` exits 0 (all 62+ tests pass)
+  </acceptance_criteria>
+  <done>Mode switcher and metric toggle controls render with correct Tabler classes, respond to clicks by updating active state and calling callbacks, and are wired into heatmap.ts to update state and trigger doRender. Stats row hidden in non-year modes. All tests pass.</done>
+</task>
+
+</tasks>
+
+<threat_model>
+## Trust Boundaries
+
+No new trust boundaries. Controls are purely client-side UI manipulating existing client state. No new data flows, authentication, or input from users beyond button clicks.
+
+## STRIDE Threat Register
+
+| Threat ID | Category | Component | Disposition | Mitigation Plan |
+|-----------|----------|-----------|-------------|-----------------|
+| T-07-01 | T (Tampering) | mode/metric state | accept | Client-side only; tampering has no security impact (changes own view) |
+</threat_model>
+
+<verification>
+- `npx vitest run assets/test/controls.test.ts` passes
+- `npm test` passes (all existing + new tests)
+- `npm run build:dev` succeeds
+- Twig template contains `#heatmap-controls` div
+</verification>
+
+<success_criteria>
+- Mode switcher with Year/Week buttons renders in widget header using Tabler nav-segmented
+- Metric toggle with Hours/Count buttons renders adjacent to mode switcher using nav-segmented nav-sm
+- Clicking controls updates HeatmapState and calls doRender
+- Stats row conditionally hidden in week mode
+- All tests green
+</success_criteria>
+
+<output>
+After completion, create `.planning/phases/07-mode-switcher-week-mode/07-01-SUMMARY.md`
+</output>

.planning/phases/07-mode-switcher-week-mode/07-01-SUMMARY.md

@@ -0,0 +1,100 @@
+---
+phase: 07-mode-switcher-week-mode
+plan: 01
+subsystem: ui
+tags: [tabler, segmented-control, heatmap, typescript]
+
+requires:
+  - phase: 06-renderer-architecture
+    provides: "Strategy pattern renderer with registry, HeatmapState with mode/metric fields"
+provides:
+  - "createModeControl and createMetricControl UI control functions"
+  - "Twig template heatmap-controls container in card header"
+  - "Conditional stats row display based on mode"
+affects: [07-02, 07-03]
+
+tech-stack:
+  added: []
+  patterns: ["Tabler nav-segmented for mode switching controls"]
+
+key-files:
+  created:
+    - assets/src/ui/controls.ts
+    - assets/test/controls.test.ts
+  modified:
+    - assets/src/heatmap.ts
+    - Resources/views/widget/heatmap.html.twig
+    - Resources/public/heatmap.css
+    - Resources/public/heatmap.js
+
+key-decisions:
+  - "createMetricControl delegates to createModeControl with overridden className for nav-sm"
+
+patterns-established:
+  - "UI controls in assets/src/ui/ directory, tested independently from renderers"
+
+requirements-completed: [VIZ-01, VIZ-05, TEST-01]
+
+duration: 2min
+completed: 2026-04-09
+---
+
+# Phase 7 Plan 1: Mode Switcher & Metric Toggle Summary
+
+**Tabler nav-segmented controls for year/week mode switching and hours/count metric toggle, wired into HeatmapState with conditional stats rendering**
+
+## Performance
+
+- **Duration:** 2 min
+- **Started:** 2026-04-09T09:14:18Z
+- **Completed:** 2026-04-09T09:16:01Z
+- **Tasks:** 1 (TDD: RED + GREEN)
+- **Files modified:** 6
+
+## Accomplishments
+- Mode switcher (Year/Week) and metric toggle (Hours/Count) as Tabler nav-segmented controls with full ARIA support
+- Controls wired into heatmap orchestrator updating HeatmapState and triggering doRender
+- Stats row conditionally hidden in non-year modes
+- Auto-scroll restricted to year mode only
+- 11 new tests (73 total, all passing)
+
+## Task Commits
+
+Each task was committed atomically:
+
+1. **Task 1 (RED): Failing control tests** - `cab07ee` (test)
+2. **Task 1 (GREEN): Controls module + wiring** - `cd1ac52` (feat)
+
+## Files Created/Modified
+- `assets/src/ui/controls.ts` - createModeControl and createMetricControl functions
+- `assets/test/controls.test.ts` - 11 tests for control rendering, click handling, ARIA
+- `assets/src/heatmap.ts` - Import controls, wire to state, conditional stats/scroll
+- `Resources/views/widget/heatmap.html.twig` - heatmap-controls div in card header
+- `Resources/public/heatmap.css` - heatmap-week-cell cursor style
+- `Resources/public/heatmap.js` - Rebuilt bundle
+
+## Decisions Made
+- createMetricControl reuses createModeControl internally, overriding className for nav-sm variant
+
+## Deviations from Plan
+
+None - plan executed exactly as written.
+
+## Issues Encountered
+None.
+
+## User Setup Required
+None - no external service configuration required.
+
+## Next Phase Readiness
+- Controls are in place for 07-02 (week-mode renderer) to use
+- WeekModeRenderer can be registered and will be dispatched when mode is 'week'
+- Metric toggle ready for renderers to read state.metric for color scale selection
+
+## Self-Check: PASSED
+
+All 6 files verified present. Both commits (cab07ee, cd1ac52) found. All 11 acceptance criteria confirmed.
+
+---
+*Phase: 07-mode-switcher-week-mode*
+*Completed: 2026-04-09*

.planning/phases/07-mode-switcher-week-mode/07-02-PLAN.md

@@ -0,0 +1,329 @@
+---
+phase: 07-mode-switcher-week-mode
+plan: 02
+type: execute
+wave: 2
+depends_on: [07-01]
+files_modified:
+  - assets/src/renderers/week.ts
+  - assets/src/heatmap.ts
+  - assets/test/week.test.ts
+autonomous: false
+requirements: [VIZ-02, TEST-01]
+must_haves:
+  truths:
+    - "Switching to week mode renders 7 horizontal cells colored by aggregated metric"
+    - "Day labels (Mon-Sun or Sun-Sat) respect user's start-of-week preference"
+    - "Tooltip on week cell shows full weekday name + aggregated value"
+    - "Weekdays with zero tracked time render as empty cells (not lowest green)"
+    - "Switching back to year mode restores the full calendar heatmap"
+  artifacts:
+    - path: "assets/src/renderers/week.ts"
+      provides: "WeekModeRenderer implementing ModeRenderer"
+      exports: ["WeekModeRenderer"]
+      min_lines: 60
+    - path: "assets/test/week.test.ts"
+      provides: "Tests for week renderer aggregation and rendering"
+      min_lines: 50
+  key_links:
+    - from: "assets/src/heatmap.ts"
+      to: "assets/src/renderers/week.ts"
+      via: "import + registerRenderer"
+      pattern: "registerRenderer.*WeekModeRenderer"
+    - from: "assets/src/renderers/week.ts"
+      to: "assets/src/shared/color-scale.ts"
+      via: "buildColorScale for week cell fill"
+      pattern: "buildColorScale"
+    - from: "assets/src/renderers/week.ts"
+      to: "assets/src/shared/tooltip.ts"
+      via: "createTooltip/showTooltip/hideTooltip"
+      pattern: "createTooltip"
+---
+
+<objective>
+Implement the WeekModeRenderer that aggregates DayEntry data by weekday and renders a 7-cell horizontal heatmap, then wire it into the orchestrator.
+
+Purpose: Delivers the first new visualization mode -- users can see which weekdays are busiest at a glance.
+Output: Working week-mode renderer with tooltip, registered and dispatch-ready, with tests.
+</objective>
+
+<execution_context>
+@/home/toph/code/toph/kimai-heatmap/.claude/get-shit-done/workflows/execute-plan.md
+@/home/toph/code/toph/kimai-heatmap/.claude/get-shit-done/templates/summary.md
+</execution_context>
+
+<context>
+@.planning/PROJECT.md
+@.planning/ROADMAP.md
+@.planning/STATE.md
+@.planning/phases/07-mode-switcher-week-mode/07-CONTEXT.md
+@.planning/phases/07-mode-switcher-week-mode/07-RESEARCH.md
+@.planning/phases/07-mode-switcher-week-mode/07-UI-SPEC.md
+@.planning/phases/07-mode-switcher-week-mode/07-01-SUMMARY.md
+
+<interfaces>
+<!-- Key types and contracts the executor needs. -->
+
+From assets/src/renderers/types.ts:
+```typescript
+export interface RenderContext {
+  container: HTMLElement;
+  data: HeatmapData;
+  state: HeatmapState;
+  config: HeatmapConfig;
+  onCellClick?: (dateStr: string) => void;
+  emptyMessage?: string;
+}
+
+export interface ModeRenderer {
+  readonly mode: string;
+  render(ctx: RenderContext): void;
+  destroy?(): void;
+}
+```
+
+From assets/src/types.ts:
+```typescript
+export interface DayEntry {
+  date: string; // "YYYY-MM-DD"
+  hours: number;
+  count: number;
+}
+export type DisplayMetric = 'hours' | 'count';
+```
+
+From assets/src/state.ts:
+```typescript
+export interface HeatmapState {
+  mode: HeatmapMode;
+  metric: DisplayMetric;
+  filters: FilterState;
+  weekStart: string;
+  data: HeatmapData | null;
+}
+```
+
+From assets/src/shared/color-scale.ts:
+```typescript
+export function buildColorScale(days: DayEntry[], metric?: DisplayMetric): ScaleQuantize<string>;
+```
+
+From assets/src/shared/tooltip.ts:
+```typescript
+export function createTooltip(): HTMLDivElement;
+export function showTooltip(tip: HTMLDivElement, html: string, anchorRect: DOMRect, cellSize: number): void;
+export function hideTooltip(tip: HTMLDivElement): void;
+```
+
+From assets/src/shared/date-utils.ts:
+```typescript
+export function getDayLabels(weekStart: string): string[];
+// DAY_LABELS_MONDAY = ['Mon', '', 'Wed', '', 'Fri', '', '']
+// DAY_LABELS_SUNDAY = ['Sun', '', 'Tue', '', 'Thu', '', 'Sat']
+```
+
+From assets/src/renderers/registry.ts:
+```typescript
+export function registerRenderer(renderer: ModeRenderer): void;
+```
+
+Existing registration pattern in heatmap.ts:
+```typescript
+import { YearModeRenderer } from './renderers/year';
+registerRenderer(new YearModeRenderer());
+```
+</interfaces>
+</context>
+
+<tasks>
+
+<task type="auto" tdd="true">
+  <name>Task 1: Implement WeekModeRenderer and register in orchestrator</name>
+  <files>
+    assets/src/renderers/week.ts,
+    assets/src/heatmap.ts,
+    assets/test/week.test.ts
+  </files>
+  <read_first>
+    assets/src/renderers/year.ts,
+    assets/src/renderers/types.ts,
+    assets/src/renderers/registry.ts,
+    assets/src/shared/color-scale.ts,
+    assets/src/shared/tooltip.ts,
+    assets/src/shared/date-utils.ts,
+    assets/src/heatmap.ts,
+    assets/src/types.ts,
+    assets/src/state.ts,
+    .planning/phases/07-mode-switcher-week-mode/07-UI-SPEC.md
+  </read_first>
+  <behavior>
+    - WeekModeRenderer.mode equals 'week'
+    - render() with 3 DayEntries (Mon, Mon, Wed) aggregates: Monday totalHours = sum of both Mon entries, Wednesday totalHours = Wed entry hours
+    - render() produces an SVG with exactly 7 rect elements
+    - Rect for a weekday with data has a fill color from buildColorScale (not empty fill)
+    - Rect for a weekday with no data has class 'heatmap-empty'
+    - Labels respect weekStart: Monday-start first label is 'Mon', Sunday-start first label is 'Sun'
+    - Tooltip on hover shows full weekday name + aggregated value (e.g. "Monday: 8.5h (4 entries)")
+    - Tooltip for count metric shows "Monday: 4 entries (8.5h)" (count first)
+    - Empty weekday tooltip shows "Tuesday: No tracked time"
+    - destroy() removes tooltip element
+  </behavior>
+  <action>
+    **1. Create `assets/src/renderers/week.ts`:**
+
+    Define a local `WeekdayAggregate` interface:
+    ```typescript
+    interface WeekdayAggregate {
+      dayIndex: number;      // 0-6, relative to weekStart
+      label: string;         // Full name: "Monday", "Tuesday", etc.
+      shortLabel: string;    // Short: "Mon", "Tue", etc.
+      totalHours: number;
+      totalCount: number;
+      dayCount: number;      // number of distinct days with entries
+    }
+    ```
+
+    Weekday name arrays (for tooltip -- full names per D-07):
+    ```typescript
+    const WEEKDAY_NAMES_MONDAY = ['Monday', 'Tuesday', 'Wednesday', 'Thursday', 'Friday', 'Saturday', 'Sunday'];
+    const WEEKDAY_NAMES_SUNDAY = ['Sunday', 'Monday', 'Tuesday', 'Wednesday', 'Thursday', 'Friday', 'Saturday'];
+    const WEEKDAY_SHORT_MONDAY = ['Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat', 'Sun'];
+    const WEEKDAY_SHORT_SUNDAY = ['Sun', 'Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat'];
+    ```
+
+    `aggregateByWeekday(days: DayEntry[], weekStart: string): WeekdayAggregate[]`:
+    - Create 7 buckets, indexed 0-6
+    - For each day entry: parse date, get JS day (`new Date(d.date + 'T00:00:00').getDay()`), compute index using `weekStart === 'sunday' ? jsDay : (jsDay + 6) % 7`
+    - Accumulate totalHours, totalCount, dayCount into bucket
+    - Set label from WEEKDAY_NAMES array by index, shortLabel from WEEKDAY_SHORT array
+    - Return all 7 buckets
+
+    `export class WeekModeRenderer implements ModeRenderer`:
+    - `readonly mode = 'week'`
+    - Private `tooltip: HTMLDivElement | null = null`
+
+    `render(ctx: RenderContext)`:
+    - Clear container: `ctx.container.innerHTML = ''`
+    - Handle empty data (same pattern as YearModeRenderer -- show emptyMessage or "No tracking data available")
+    - Destroy previous tooltip, create new one via `createTooltip()`
+    - Call `aggregateByWeekday(ctx.data.days, ctx.state.weekStart)`
+    - Build color scale: only pass DayEntry items that have data to `buildColorScale()` so scale domain reflects actual values. Create synthetic DayEntry array from aggregates for scale: `aggregates.filter(a => a.dayCount > 0).map(a => ({ date: '', hours: a.totalHours, count: a.totalCount }))`
+    - Then call `buildColorScale(syntheticDays, ctx.state.metric)`
+    - SVG layout constants (per UI-SPEC): cellWidth=60, cellHeight=40, cellGap=4, labelWidth=50
+    - SVG dimensions: width = `labelWidth + 7 * (cellWidth + cellGap)`, height = cellHeight
+    - Create SVG via d3 `select(ctx.container).append('svg')` with computed dimensions, class `heatmap-svg`
+    - Render 7 labels as `<text>` elements: class `heatmap-label`, x=0, y = vertically centered in cell (`cellHeight / 2 + 3`), text = shortLabel for each aggregate. Show ALL 7 labels (not the sparse pattern from year-mode)
+    - Render 7 rects: x = `labelWidth + i * (cellWidth + cellGap)`, y = 0, width = cellWidth, height = cellHeight
+    - Class: `heatmap-week-cell` always, add `heatmap-empty` if `dayCount === 0`
+    - Fill: if `dayCount === 0`, return `''` (CSS handles empty fill). Otherwise, use `colorScale(ctx.state.metric === 'hours' ? agg.totalHours : agg.totalCount)`
+    - rx="2" ry="2" for rounded corners
+    - Tooltip on mouseenter: if `dayCount > 0`:
+      - hours metric: `"<strong>{label}</strong><br>{totalHours.toFixed(1)}h ({totalCount} entries)"`
+      - count metric: `"<strong>{label}</strong><br>{totalCount} entries ({totalHours.toFixed(1)}h)"`
+    - If `dayCount === 0`: `"<strong>{label}</strong><br>No tracked time"`
+    - Use `showTooltip(tooltip, html, rect.getBoundingClientRect(), cellWidth)`
+    - On mouseleave: `hideTooltip(tooltip)`
+    - No click handler on week cells (per discretion -- aggregation has no single-date target)
+
+    `destroy()`:
+    - Remove tooltip if exists, set to null
+
+    Export the class.
+
+    **2. Modify `assets/src/heatmap.ts`:**
+    - Add import: `import { WeekModeRenderer } from './renderers/week';`
+    - Add registration below existing: `registerRenderer(new WeekModeRenderer());`
+    - That's the only change needed in heatmap.ts for this task (controls wiring done in Plan 01)
+
+    **3. Create `assets/test/week.test.ts`:**
+    Test the WeekModeRenderer using the pattern from existing test files. Import the renderer, create a container div, build test DayEntry arrays with known dates and values. Verify:
+    - SVG contains exactly 7 rect elements
+    - Aggregation sums correctly (two entries on same weekday -> combined hours)
+    - Empty weekdays get `heatmap-empty` class
+    - Data weekdays get a fill color (not empty string)
+    - Labels appear in correct weekStart order
+    - destroy() removes tooltip
+    - Test with weekStart='sunday' to verify label order changes
+  </action>
+  <verify>
+    <automated>cd /home/toph/code/toph/kimai-heatmap && npx vitest run assets/test/week.test.ts && npm test</automated>
+  </verify>
+  <acceptance_criteria>
+    - assets/src/renderers/week.ts contains `export class WeekModeRenderer implements ModeRenderer`
+    - assets/src/renderers/week.ts contains `readonly mode = 'week'`
+    - assets/src/renderers/week.ts contains `aggregateByWeekday`
+    - assets/src/renderers/week.ts contains `buildColorScale`
+    - assets/src/renderers/week.ts contains `createTooltip`
+    - assets/src/renderers/week.ts contains `showTooltip` and `hideTooltip`
+    - assets/src/renderers/week.ts contains `No tracked time`
+    - assets/src/renderers/week.ts contains `heatmap-week-cell`
+    - assets/src/renderers/week.ts contains `heatmap-empty`
+    - assets/src/renderers/week.ts contains `(jsDay + 6) % 7` (Monday-start weekday index)
+    - assets/src/heatmap.ts contains `import { WeekModeRenderer } from './renderers/week'`
+    - assets/src/heatmap.ts contains `registerRenderer(new WeekModeRenderer())`
+    - assets/test/week.test.ts exists and `npx vitest run assets/test/week.test.ts` exits 0
+    - `npm test` exits 0 (all tests pass including new week tests)
+    - `npm run build:dev` exits 0 (bundle builds)
+  </acceptance_criteria>
+  <done>WeekModeRenderer aggregates DayEntry data by weekday, renders 7 horizontal SVG cells with color scale and tooltips, respects weekStart preference, and is registered for dispatch. All tests pass.</done>
+</task>
+
+<task type="checkpoint:human-verify" gate="blocking">
+  <name>Task 2: Visual verification of mode switcher and week mode</name>
+  <files>none</files>
+  <action>Human visual verification of the complete Phase 7 feature set in a running Kimai instance. No code changes -- verify that Plan 01 (controls) and Plan 02 Task 1 (week renderer) work correctly together end-to-end.</action>
+  <verify>
+    <automated>cd /home/toph/code/toph/kimai-heatmap && npm test && npm run build:dev</automated>
+  </verify>
+  <done>Human confirms: mode switcher toggles year/week views, metric toggle switches hours/count coloring, week-mode shows 7 cells with correct tooltips, stats row hidden in week mode, no console errors.</done>
+  <what-built>
+    Mode switcher (Year/Week) and metric toggle (Hours/Count) controls in the widget header. Week-mode renderer showing 7 weekday cells with aggregated data. Stats row hidden in week mode, visible in year mode.
+  </what-built>
+  <how-to-verify>
+    1. Start local Kimai dev environment, navigate to dashboard
+    2. Verify the heatmap widget shows two controls in the header: "Year | Week" and "Hours | Count"
+    3. Click "Week" -- should show 7 horizontal cells with weekday labels (Mon-Sun), stats row should disappear
+    4. Hover over a colored cell -- tooltip shows full weekday name + aggregated hours and entry count
+    5. Hover over an empty cell -- tooltip shows "No tracked time"
+    6. Click "Count" -- cell colors should change (re-colored by entry count instead of hours)
+    7. Click "Year" -- should return to full calendar heatmap, stats row reappears
+    8. Click "Count" in year mode -- year cells re-color by count
+    9. Change project filter -- both modes should reflect filtered data
+    10. Check browser console -- no JavaScript errors
+  </how-to-verify>
+  <resume-signal>Type "approved" or describe issues</resume-signal>
+</task>
+
+</tasks>
+
+<threat_model>
+## Trust Boundaries
+
+No new trust boundaries. Week renderer consumes the same authenticated data as year renderer. No new endpoints, inputs, or data flows.
+
+## STRIDE Threat Register
+
+| Threat ID | Category | Component | Disposition | Mitigation Plan |
+|-----------|----------|-----------|-------------|-----------------|
+| T-07-02 | T (Tampering) | weekday aggregation | accept | Client-side aggregation of already-authenticated data; no security impact |
+</threat_model>
+
+<verification>
+- `npx vitest run assets/test/week.test.ts` passes
+- `npm test` passes (full suite)
+- `npm run build:dev` succeeds
+- Human verifies visual output in running Kimai
+</verification>
+
+<success_criteria>
+- Week-mode renders 7 horizontal cells colored by aggregated hours or count
+- Day labels respect start-of-week preference
+- Tooltips show weekday name + value in correct format for hours/count metrics
+- Empty weekdays render as empty cells (not lowest green)
+- Mode switching between year and week works without errors
+- Metric toggle affects both modes
+</success_criteria>
+
+<output>
+After completion, create `.planning/phases/07-mode-switcher-week-mode/07-02-SUMMARY.md`
+</output>

.planning/phases/07-mode-switcher-week-mode/07-02-SUMMARY.md

@@ -0,0 +1,89 @@
+---
+phase: 07-mode-switcher-week-mode
+plan: 02
+subsystem: ui
+tags: [d3, typescript, heatmap, week-mode, aggregation]
+
+requires:
+  - phase: 06-renderer-architecture
+    provides: ModeRenderer interface, registry, shared color-scale/tooltip/date-utils
+  - phase: 07-mode-switcher-week-mode plan 01
+    provides: Mode switcher controls, metric toggle, doRender dispatch
+provides:
+  - WeekModeRenderer aggregating DayEntry data by weekday into 7-cell horizontal heatmap
+  - Week mode registered and dispatch-ready via orchestrator
+affects: [08-day-mode, 09-combined-mode]
+
+tech-stack:
+  added: []
+  patterns: [weekday aggregation with dayCount tracking, synthetic DayEntry for color scale domain]
+
+key-files:
+  created:
+    - assets/src/renderers/week.ts
+    - assets/test/week.test.ts
+  modified:
+    - assets/src/heatmap.ts
+
+key-decisions:
+  - "Labels placed centered above each cell (horizontal layout) rather than in a left column (vertical layout) since week mode is a single horizontal row"
+
+patterns-established:
+  - "Aggregation renderer pattern: aggregate DayEntry[] -> synthetic DayEntry[] for buildColorScale, render cells from aggregates"
+
+requirements-completed: [VIZ-02, TEST-01]
+
+duration: 4min
+completed: 2026-04-09
+---
+
+# Phase 7 Plan 02: Week Mode Renderer Summary
+
+**WeekModeRenderer aggregates time entries by weekday into 7 horizontal SVG cells with color scale, metric toggle, and weekStart-aware ordering**
+
+## Performance
+
+- **Duration:** 4 min
+- **Started:** 2026-04-09T14:29:19Z
+- **Completed:** 2026-04-09T14:33:19Z
+- **Tasks:** 1 of 2 (Task 2 is human-verify checkpoint)
+- **Files modified:** 3
+
+## Accomplishments
+- WeekModeRenderer implements ModeRenderer with aggregateByWeekday logic summing hours/count per weekday
+- 7-cell SVG with color scale from buildColorScale, empty cells get heatmap-empty class
+- Tooltips show full weekday name with hours-first or count-first format depending on metric
+- Labels respect weekStart preference (Monday-first or Sunday-first ordering)
+- Registered in heatmap.ts for dispatch via mode switcher
+- 14 tests covering aggregation, rendering, tooltips, empty state, label ordering
+
+## Task Commits
+
+Each task was committed atomically:
+
+1. **Task 1 RED: Failing tests for week renderer** - `7fba98f` (test)
+2. **Task 1 GREEN+REFACTOR: Week mode renderer implementation** - `9dde529` (feat)
+
+## Files Created/Modified
+- `assets/src/renderers/week.ts` - WeekModeRenderer with aggregateByWeekday, 7-cell SVG, tooltips (149 lines)
+- `assets/test/week.test.ts` - 14 tests covering mode, rendering, aggregation, tooltips, labels, destroy (178 lines)
+- `assets/src/heatmap.ts` - Added WeekModeRenderer import and registration
+
+## Decisions Made
+- Labels placed centered above each cell in horizontal layout rather than in a left column, since the 7-cell week view is a single horizontal row
+- Used synthetic DayEntry array from non-zero aggregates to feed buildColorScale, keeping color domain based on actual data values
+
+## Deviations from Plan
+
+None - plan executed exactly as written.
+
+## Issues Encountered
+None.
+
+## User Setup Required
+None - no external service configuration required.
+
+## Next Phase Readiness
+- Task 2 (human-verify checkpoint) pending -- requires visual verification in running Kimai instance
+- Week mode renderer is code-complete and all tests pass
+- Ready for day-mode renderer (phase 08) once visual verification confirms correctness

.planning/phases/07-mode-switcher-week-mode/07-CONTEXT.md

@@ -0,0 +1,107 @@
+# Phase 7: Mode Switcher + Week Mode - Context
+
+**Gathered:** 2026-04-09
+**Status:** Ready for planning
+
+<domain>
+## Phase Boundary
+
+Users can switch between year and week visualization modes and toggle between hours and entry-count display. This is the first visible v1.1 feature, building on the renderer architecture from Phase 6. Scope: mode switcher UI, week-mode renderer, hours/count toggle. Day-mode and combined-mode renderers belong to Phase 9.
+
+</domain>
+
+<decisions>
+## Implementation Decisions
+
+### Mode Switcher UI
+- **D-01:** Segmented control placed in the widget header row (Kimai Tabler card header area), next to the widget title
+- **D-02:** Shows "Year" and "Week" as the two options for this phase (Day and Combined added in Phase 9)
+- **D-03:** Active mode visually highlighted using Kimai/Tabler CSS conventions (e.g., `btn-group` with active state)
+
+### Week-Mode Visualization
+- **D-04:** Horizontal layout — 7 cells (one per weekday), colored by aggregated metric value for that weekday
+- **D-05:** Day labels shown alongside cells (Mon, Tue, etc.), respecting user's start-of-week preference from `state.weekStart`
+- **D-06:** Aggregation is client-side — sum/average hours or count from existing `DayEntry[]` data grouped by weekday (no backend changes, per STATE.md decision)
+- **D-07:** Tooltip on hover shows weekday name + aggregated value (e.g., "Monday: 42.5h (23 entries)")
+
+### Hours/Count Toggle
+- **D-08:** Separate small segmented control (not merged into mode switcher) — "Hours" / "Count" options
+- **D-09:** Placed adjacent to the mode switcher in the header area
+- **D-10:** Toggles `state.metric` between `'hours'` and `'count'`, triggers re-render without re-fetching data
+- **D-11:** Affects color scale in both year and week modes — year-mode already supports this via metric-aware cell fill from Phase 6
+
+### Claude's Discretion
+- Exact sizing and spacing of week-mode cells (could be larger than year cells since only 7)
+- Whether week-mode cells are clickable (and what click-through would show)
+- Stats row behavior when in week mode — may show week-aggregated stats or hide year-specific stats like streak
+- Exact Tabler CSS classes for segmented controls
+- Animation/transition when switching modes
+
+</decisions>
+
+<canonical_refs>
+## Canonical References
+
+**Downstream agents MUST read these before planning or implementing.**
+
+### Renderer Architecture (Phase 6)
+- `.planning/phases/06-renderer-architecture/06-01-SUMMARY.md` — Type contracts, ModeRenderer interface, registry, shared utilities
+- `.planning/phases/06-renderer-architecture/06-02-SUMMARY.md` — YearModeRenderer implementation, orchestrator dispatch pattern
+
+### Existing Code
+- `assets/src/renderers/types.ts` — ModeRenderer interface and RenderContext contract
+- `assets/src/renderers/registry.ts` — Renderer registration pattern
+- `assets/src/renderers/year.ts` — Reference renderer implementation
+- `assets/src/state.ts` — HeatmapState with mode, metric, weekStart fields
+- `assets/src/types.ts` — HeatmapMode, DisplayMetric, DayEntry types
+- `assets/src/heatmap.ts` — Orchestrator with doRender() dispatch and DOM layout
+
+### Requirements
+- `.planning/REQUIREMENTS.md` — VIZ-01 (mode switcher), VIZ-02 (week-mode), VIZ-05 (hours/count toggle), TEST-01 (tests)
+
+### Widget Template
+- `Resources/views/widget/heatmap.html.twig` — Kimai card embed structure, data attributes
+- `Resources/public/heatmap.css` — Existing styles, Tabler CSS var usage
+
+</canonical_refs>
+
+<code_context>
+## Existing Code Insights
+
+### Reusable Assets
+- `ModeRenderer` interface: new `WeekModeRenderer` implements this and registers via `registerRenderer()`
+- `buildColorScale()` in `shared/color-scale.ts`: already metric-aware, reusable for week cells
+- `createTooltip()/showTooltip()/hideTooltip()` in `shared/tooltip.ts`: reusable for week-mode tooltips
+- `getDayLabels()` in `shared/date-utils.ts`: provides weekday labels respecting start-of-week preference
+
+### Established Patterns
+- Strategy pattern dispatch: `getRenderer(state.mode).render(ctx)` in `doRender()`
+- Module-level registration: `registerRenderer(new WeekModeRenderer())` at import time
+- IIFE bundle via esbuild: `KimaiHeatmap` global, all modules bundled into `Resources/public/heatmap.js`
+- Kimai Tabler card layout: widget header via Twig `@theme/embeds/card.html.twig`
+
+### Integration Points
+- Mode switcher and metric toggle need to be injected into the DOM by `heatmap.ts` init (or via Twig template modification)
+- `state.mode` and `state.metric` changes trigger `doRender()` — existing pattern in `heatmap.ts`
+- Filter dropdown already in header area — new controls should coordinate layout with it
+
+</code_context>
+
+<specifics>
+## Specific Ideas
+
+No specific requirements — open to standard approaches
+
+</specifics>
+
+<deferred>
+## Deferred Ideas
+
+None — discussion stayed within phase scope
+
+</deferred>
+
+---
+
+*Phase: 07-mode-switcher-week-mode*
+*Context gathered: 2026-04-09*

.planning/phases/07-mode-switcher-week-mode/07-DISCUSSION-LOG.md

@@ -0,0 +1,75 @@
+# Phase 7: Mode Switcher + Week Mode - Discussion Log
+
+> **Audit trail only.** Do not use as input to planning, research, or execution agents.
+> Decisions are captured in CONTEXT.md — this log preserves the alternatives considered.
+
+**Date:** 2026-04-09
+**Phase:** 07-mode-switcher-week-mode
+**Areas discussed:** Mode Switcher UI, Week-Mode Visualization, Hours/Count Toggle, Stats Adaptation
+**Mode:** --auto (all decisions auto-selected)
+
+---
+
+## Mode Switcher UI
+
+| Option | Description | Selected |
+|--------|-------------|----------|
+| Segmented control in header | Placed in Tabler card header next to title, btn-group style | ✓ |
+| Dropdown in header | Select element like the project filter | |
+| Tabs below header | Tab bar between header and heatmap content | |
+
+**User's choice:** [auto] Segmented control in header (recommended default — matches SC1 requirement and Tabler card conventions)
+**Notes:** Kimai uses Tabler UI framework. Segmented controls via btn-group are native to the design system.
+
+---
+
+## Week-Mode Visualization
+
+| Option | Description | Selected |
+|--------|-------------|----------|
+| Horizontal heatmap cells | 7 cells (one per weekday), colored by aggregate metric | ✓ |
+| Vertical bar chart | 7 bars showing aggregate values per weekday | |
+| Grid matching year layout | 1-row x 7-col grid reusing year-mode cell styling | |
+
+**User's choice:** [auto] Horizontal heatmap cells (recommended default — simplest visualization revealing weekday patterns, closest to heatmap metaphor)
+**Notes:** Client-side aggregation from existing DayEntry[] data. No backend changes needed per STATE.md decision.
+
+---
+
+## Hours/Count Toggle
+
+| Option | Description | Selected |
+|--------|-------------|----------|
+| Separate segmented control | Small toggle adjacent to mode switcher in header | ✓ |
+| Merged into mode switcher | Combined control (Year-Hours, Year-Count, Week-Hours, etc.) | |
+| Icon toggle button | Single button that cycles between hours/count | |
+
+**User's choice:** [auto] Separate segmented control (recommended default — keeps mode and metric concerns separate, cleaner UX)
+**Notes:** Toggles state.metric, triggers re-render without data re-fetch. Year-mode already supports metric-aware fill from Phase 6.
+
+---
+
+## Stats Adaptation
+
+| Option | Description | Selected |
+|--------|-------------|----------|
+| Claude's Discretion | Stats can adapt per mode or remain consistent | ✓ |
+| Mode-specific stats | Different stat values per visualization mode | |
+| Always show year stats | Keep stats unchanged regardless of mode | |
+
+**User's choice:** [auto] Claude's Discretion (recommended default — secondary concern, implementation can optimize)
+**Notes:** Stats behavior in week-mode is a detail best resolved during implementation.
+
+---
+
+## Claude's Discretion
+
+- Week-mode cell sizing and spacing
+- Week-mode cell click behavior
+- Stats row adaptation per mode
+- Exact Tabler CSS classes for controls
+- Mode switch animation/transitions
+
+## Deferred Ideas
+
+None — discussion stayed within phase scope

.planning/phases/07-mode-switcher-week-mode/07-RESEARCH.md

@@ -0,0 +1,395 @@
+# Phase 7: Mode Switcher + Week Mode - Research
+
+**Researched:** 2026-04-09
+**Domain:** d3.js visualization modes, Tabler UI segmented controls, client-side data aggregation
+**Confidence:** HIGH
+
+## Summary
+
+Phase 7 adds two UI controls (mode switcher and hours/count toggle) and one new renderer (WeekModeRenderer) to the existing strategy-pattern architecture from Phase 6. The infrastructure is solid -- `ModeRenderer` interface, renderer registry, `HeatmapState` with `mode` and `metric` fields, and shared utilities (color scale, tooltip, date-utils) are all in place. The new work is: (1) render two Tabler `nav-segmented` controls in the widget header, (2) wire their click handlers to update `state.mode` and `state.metric` then call `doRender()`, and (3) implement `WeekModeRenderer` that aggregates `DayEntry[]` by weekday and renders 7 colored cells.
+
+Tabler provides a native `nav-segmented` component that matches the "segmented control" design from CONTEXT.md decisions. No custom CSS needed for the control itself -- just Tabler classes. The week-mode renderer is straightforward d3 work: group existing data by day-of-week (0-6), sum hours/count per weekday, render 7 rectangles with the shared `buildColorScale()`. The `getDayLabels()` and weekday-index calculation in `date-utils.ts` already handle start-of-week preference.
+
+**Primary recommendation:** Build controls in JS (not Twig) since they interact with `HeatmapState`; keep the Twig template unchanged. Register `WeekModeRenderer` alongside `YearModeRenderer` at module level.
+
+<user_constraints>
+## User Constraints (from CONTEXT.md)
+
+### Locked Decisions
+- D-01: Segmented control in widget header row (Kimai Tabler card header area), next to title
+- D-02: "Year" and "Week" as the two mode options (Day/Combined in Phase 9)
+- D-03: Active mode highlighted using Kimai/Tabler CSS conventions
+- D-04: Week-mode horizontal layout -- 7 cells, one per weekday, colored by aggregated metric
+- D-05: Day labels alongside cells, respecting user's start-of-week from `state.weekStart`
+- D-06: Client-side aggregation of existing DayEntry[] grouped by weekday (no backend changes)
+- D-07: Tooltip on hover: weekday name + aggregated value
+- D-08: Hours/Count toggle is a separate small segmented control
+- D-09: Placed adjacent to mode switcher in header
+- D-10: Toggles `state.metric` between 'hours' and 'count', triggers re-render without re-fetch
+- D-11: Affects color scale in both year and week modes
+
+### Claude's Discretion
+- Exact sizing/spacing of week-mode cells
+- Whether week-mode cells are clickable (and what click-through shows)
+- Stats row behavior when in week mode
+- Exact Tabler CSS classes for segmented controls
+- Animation/transition when switching modes
+
+### Deferred Ideas (OUT OF SCOPE)
+None
+</user_constraints>
+
+<phase_requirements>
+## Phase Requirements
+
+| ID | Description | Research Support |
+|----|-------------|------------------|
+| VIZ-01 | Mode switcher UI allows toggling between year, week, day, and combined views | Tabler `nav-segmented` component; only Year/Week for this phase per D-02 |
+| VIZ-02 | Week-mode renders day-of-week aggregation showing busiest weekdays | WeekModeRenderer with client-side DayEntry grouping by weekday |
+| VIZ-05 | Hours vs entry-count toggle switches color scale metric across all modes | Separate `nav-segmented` control toggling `state.metric`; `buildColorScale()` already metric-aware |
+| TEST-01 | Vitest tests for mode switcher, each renderer, and display toggle | Test patterns established in existing 9 test files; jsdom environment |
+</phase_requirements>
+
+## Standard Stack
+
+### Core (already installed -- no new packages)
+| Library | Version | Purpose | Why Standard |
+|---------|---------|---------|--------------|
+| d3-selection | ^3.0.0 | DOM manipulation for week cells | Already in use for year renderer |
+| d3-scale | ^4.0.2 | Color scale for week cells | `buildColorScale()` already wraps this |
+| d3-array | ^3.2.4 | `max()` for scale domain | Already in shared/color-scale.ts |
+| vitest | ^4.1.3 | Test runner | Already configured with jsdom |
+
+No new npm packages required. [VERIFIED: package.json in codebase]
+
+### Tabler CSS (bundled with Kimai)
+| Component | Classes | Purpose |
+|-----------|---------|---------|
+| Segmented control | `nav nav-segmented`, `nav-link`, `active` | Mode switcher and metric toggle |
+| Small variant | `nav-sm` | Compact toggle for hours/count |
+
+[CITED: docs.tabler.io/ui/components/segmented-control]
+
+## Architecture Patterns
+
+### Project Structure (new files only)
+```
+assets/
+  src/
+    renderers/
+      week.ts          # NEW: WeekModeRenderer
+    ui/
+      controls.ts      # NEW: mode switcher + metric toggle DOM builders
+  test/
+    week.test.ts       # NEW: WeekModeRenderer tests
+    controls.test.ts   # NEW: UI control interaction tests
+```
+
+### Pattern 1: WeekModeRenderer (Strategy Pattern Extension)
+
+**What:** New renderer implementing `ModeRenderer` interface, registered via `registerRenderer()`.
+
+**When to use:** Rendering the week-mode aggregation view.
+
+**Example:**
+```typescript
+// assets/src/renderers/week.ts
+import type { ModeRenderer, RenderContext } from './types';
+import { registerRenderer } from './registry';
+import { buildColorScale } from '../shared/color-scale';
+import { createTooltip, showTooltip, hideTooltip } from '../shared/tooltip';
+
+interface WeekdayAggregate {
+  dayIndex: number;    // 0-6, relative to weekStart
+  label: string;       // "Mon", "Tue", etc.
+  totalHours: number;
+  totalCount: number;
+  dayCount: number;    // number of occurrences for averaging
+}
+
+export class WeekModeRenderer implements ModeRenderer {
+  readonly mode = 'week';
+  private tooltip: HTMLDivElement | null = null;
+
+  render(ctx: RenderContext): void {
+    // 1. Aggregate DayEntry[] by weekday
+    // 2. Build 7-cell horizontal SVG
+    // 3. Color via buildColorScale() using ctx.state.metric
+    // 4. Attach tooltip handlers
+  }
+
+  destroy(): void {
+    this.tooltip?.remove();
+    this.tooltip = null;
+  }
+}
+
+// Module-level registration
+registerRenderer(new WeekModeRenderer());
+```
+
+### Pattern 2: UI Controls (JS-driven, not Twig)
+
+**What:** Build mode switcher and metric toggle as DOM elements in `heatmap.ts` init, inserted into the widget header area.
+
+**Why JS not Twig:** Controls must interact with `HeatmapState` and call `doRender()`. Putting them in Twig would require a separate event-binding pass and Twig has no knowledge of JS state. Building them in JS during init keeps the coupling clean.
+
+**Example:**
+```typescript
+// assets/src/ui/controls.ts
+export interface ControlCallbacks {
+  onModeChange: (mode: string) => void;
+  onMetricChange: (metric: string) => void;
+}
+
+export function createModeControl(
+  activeMode: string,
+  modes: Array<{ key: string; label: string }>,
+  onChange: (mode: string) => void,
+): HTMLElement {
+  const nav = document.createElement('nav');
+  nav.className = 'nav nav-segmented';
+  nav.setAttribute('role', 'tablist');
+
+  for (const m of modes) {
+    const btn = document.createElement('button');
+    btn.className = 'nav-link' + (m.key === activeMode ? ' active' : '');
+    btn.setAttribute('role', 'tab');
+    btn.textContent = m.label;
+    btn.addEventListener('click', () => {
+      nav.querySelectorAll('.nav-link').forEach(b => b.classList.remove('active'));
+      btn.classList.add('active');
+      onChange(m.key);
+    });
+    nav.appendChild(btn);
+  }
+  return nav;
+}
+
+export function createMetricControl(
+  activeMetric: string,
+  onChange: (metric: string) => void,
+): HTMLElement {
+  // Same pattern, nav-sm for compact size
+  const nav = document.createElement('nav');
+  nav.className = 'nav nav-segmented nav-sm';
+  // ... buttons for 'Hours' and 'Count'
+  return nav;
+}
+```
+
+### Pattern 3: Weekday Aggregation (Client-Side)
+
+**What:** Group `DayEntry[]` by day-of-week index, summing hours and counts.
+
+**Key detail:** Must respect `state.weekStart`. The existing `date-utils.ts` calculates `dayOfWeek` as `(jsDay + 6) % 7` for Monday start and `jsDay` for Sunday start. Reuse the same logic.
+
+```typescript
+function aggregateByWeekday(
+  days: DayEntry[],
+  weekStart: string,
+): WeekdayAggregate[] {
+  const buckets = new Array(7).fill(null).map((_, i) => ({
+    dayIndex: i,
+    label: '', // filled from getDayLabels or full-name variant
+    totalHours: 0,
+    totalCount: 0,
+    dayCount: 0,
+  }));
+
+  for (const d of days) {
+    const jsDay = new Date(d.date + 'T00:00:00').getDay();
+    const idx = weekStart === 'sunday' ? jsDay : (jsDay + 6) % 7;
+    buckets[idx].totalHours += d.hours;
+    buckets[idx].totalCount += d.count;
+    buckets[idx].dayCount += 1;
+  }
+  return buckets;
+}
+```
+
+### Pattern 4: Control Placement in Widget Header
+
+**What:** Insert controls into the card header alongside the existing title.
+
+**Approach:** The Twig template uses `@theme/embeds/card.html.twig`. The `{% block box_title %}` currently holds just `{{ title }}`. Two options:
+
+1. **Modify Twig** to add a placeholder `<div id="heatmap-controls">` in `box_title` block -- then JS populates it.
+2. **Pure JS** -- find the `.card-header` parent of `#heatmap-container` and inject controls.
+
+**Recommendation:** Option 1 -- add a controls placeholder in Twig. This is cleaner because it ensures the layout structure is correct even before JS loads, and avoids fragile DOM traversal.
+
+```twig
+{% block box_title %}
+    <div style="display: flex; align-items: center; gap: 12px; flex-wrap: wrap;">
+        {{ title }}
+        <div id="heatmap-controls" style="display: flex; gap: 8px; margin-left: auto;"></div>
+    </div>
+{% endblock %}
+```
+
+Then in `heatmap.ts`, build controls and append to `#heatmap-controls`.
+
+### Anti-Patterns to Avoid
+- **Merging mode switcher and metric toggle into one control:** CONTEXT.md D-08 explicitly says separate controls.
+- **Re-fetching data on metric toggle:** D-10 says re-render without re-fetch. The data already has both `hours` and `count` fields.
+- **Building week renderer from scratch without shared utilities:** `buildColorScale()`, tooltip helpers, and `getDayLabels()` are all reusable.
+
+## Don't Hand-Roll
+
+| Problem | Don't Build | Use Instead | Why |
+|---------|-------------|-------------|-----|
+| Segmented control UI | Custom toggle buttons with manual styling | Tabler `nav-segmented` classes | Native Kimai theme integration, accessible markup |
+| Color scale | New scale for week cells | `buildColorScale()` from shared/color-scale.ts | Already metric-aware, consistent across modes |
+| Tooltips | New tooltip logic | `createTooltip/showTooltip/hideTooltip` from shared/tooltip.ts | Consistent behavior, already tested |
+| Weekday ordering | Hard-coded day arrays | Reuse `(jsDay + 6) % 7` pattern from date-utils.ts | Already handles Monday/Sunday start |
+
+## Common Pitfalls
+
+### Pitfall 1: Weekday Index Mismatch Between Aggregation and Labels
+**What goes wrong:** Aggregation uses one weekday ordering, labels use another, so Tuesday's data shows on Monday's cell.
+**Why it happens:** JS `Date.getDay()` returns 0=Sunday. The existing code remaps for Monday-start. If aggregation and label generation use different mappings, they desync.
+**How to avoid:** Use the exact same index formula as `generateCells()` in date-utils.ts: `weekStart === 'sunday' ? jsDay : (jsDay + 6) % 7`. Map labels using the same index.
+**Warning signs:** Tests with known weekday data showing wrong labels.
+
+### Pitfall 2: Empty Aggregate Buckets Confuse Color Scale
+**What goes wrong:** Weekdays with zero entries get passed to `buildColorScale()` which sets domain `[0, maxVal]`, and zero values map to the lowest color bucket instead of showing as empty.
+**Why it happens:** `buildColorScale` maps any value in `[0, maxVal]` to a color. Zero is technically in-domain.
+**How to avoid:** Either (a) filter out zero-value weekdays before passing to color scale and render them as empty cells, or (b) treat weekdays with `dayCount === 0` as empty (no fill), similar to how year-mode handles null entries.
+**Warning signs:** All 7 cells colored even when user tracked on only 3 weekdays.
+
+### Pitfall 3: Controls Not Reflecting State After Re-render
+**What goes wrong:** Mode or metric changes correctly, but if `doRender()` rebuilds the entire container, controls get destroyed.
+**Why it happens:** `heatmap.ts`'s `doRender()` calls `renderer.render(ctx)` which does `ctx.container.innerHTML = ''` on the SVG area. If controls are inside the SVG area, they vanish.
+**How to avoid:** Controls live outside the SVG area container (in the card header via `#heatmap-controls`). The renderer only clears `svgArea`, not the card header.
+**Warning signs:** Controls disappear after first interaction.
+
+### Pitfall 4: Stats Row Showing Year-Specific Data in Week Mode
+**What goes wrong:** Streak counter and "busiest day" stats show in week mode where they don't make contextual sense.
+**Why it happens:** `renderStats()` is called unconditionally after every `doRender()`.
+**How to avoid:** Either skip `renderStats()` when mode is 'week', or show week-appropriate stats (e.g., busiest weekday, average per weekday). Simplest: hide stats in week mode for now.
+**Warning signs:** "Busiest: Mon, Jan 13" showing below a weekday aggregation view.
+
+## Code Examples
+
+### Weekday Aggregation with Full Labels
+```typescript
+// Full weekday names for tooltips (D-07 wants "Monday: 42.5h")
+const WEEKDAY_NAMES_MONDAY = ['Monday', 'Tuesday', 'Wednesday', 'Thursday', 'Friday', 'Saturday', 'Sunday'];
+const WEEKDAY_NAMES_SUNDAY = ['Sunday', 'Monday', 'Tuesday', 'Wednesday', 'Thursday', 'Friday', 'Saturday'];
+
+function getWeekdayNames(weekStart: string): string[] {
+  return weekStart === 'sunday' ? WEEKDAY_NAMES_SUNDAY : WEEKDAY_NAMES_MONDAY;
+}
+```
+
+### Week-Mode SVG Layout (7 horizontal cells)
+```typescript
+// Larger cells since only 7 vs 365
+const cellWidth = 60;
+const cellHeight = 40;
+const cellGap = 4;
+const labelWidth = 50; // space for "Mon", "Tue" labels
+const svgWidth = labelWidth + 7 * (cellWidth + cellGap);
+const svgHeight = cellHeight + 20; // room for value text below
+
+// Layout: label | rect | label | rect | ...
+// Or: 7 rects in a row with labels below/beside
+```
+
+### Wiring Controls to State in heatmap.ts
+```typescript
+// In init(), after building wrapper:
+const controlsContainer = document.getElementById('heatmap-controls');
+if (controlsContainer) {
+  const modeControl = createModeControl(state.mode, [
+    { key: 'year', label: 'Year' },
+    { key: 'week', label: 'Week' },
+  ], (mode) => {
+    state.mode = mode as HeatmapMode;
+    doRender();
+  });
+
+  const metricControl = createMetricControl(state.metric, (metric) => {
+    state.metric = metric as DisplayMetric;
+    doRender();
+  });
+
+  controlsContainer.appendChild(modeControl);
+  controlsContainer.appendChild(metricControl);
+}
+```
+
+## Validation Architecture
+
+### Test Framework
+| Property | Value |
+|----------|-------|
+| Framework | Vitest 4.1.3 + jsdom |
+| Config file | `vitest.config.ts` |
+| Quick run command | `npm test` |
+| Full suite command | `npm test` |
+
+### Phase Requirements to Test Map
+| Req ID | Behavior | Test Type | Automated Command | File Exists? |
+|--------|----------|-----------|-------------------|-------------|
+| VIZ-01 | Mode switcher renders Year/Week buttons, click changes active state | unit | `npx vitest run assets/test/controls.test.ts` | Wave 0 |
+| VIZ-02 | Week renderer aggregates by weekday, renders 7 cells with correct colors | unit | `npx vitest run assets/test/week.test.ts` | Wave 0 |
+| VIZ-05 | Metric toggle switches state.metric, re-renders with different color values | unit | `npx vitest run assets/test/controls.test.ts` | Wave 0 |
+| TEST-01 | All mode/renderer/toggle tests pass | suite | `npm test` | Wave 0 |
+
+### Sampling Rate
+- **Per task commit:** `npm test`
+- **Per wave merge:** `npm test` (single suite)
+- **Phase gate:** Full suite green before `/gsd-verify-work`
+
+### Wave 0 Gaps
+- [ ] `assets/test/week.test.ts` -- WeekModeRenderer rendering and aggregation tests
+- [ ] `assets/test/controls.test.ts` -- mode switcher and metric toggle interaction tests
+
+## Security Domain
+
+No security-relevant ASVS categories apply to this phase. It is purely client-side UI rendering with no authentication, input handling from users, cryptography, or access control changes. Data comes from the existing authenticated API endpoint.
+
+## Assumptions Log
+
+| # | Claim | Section | Risk if Wrong |
+|---|-------|---------|---------------|
+| A1 | Tabler `nav-segmented` classes are available in Kimai's bundled Tabler version | Architecture Patterns | Controls would need custom CSS; verify in running Kimai instance |
+| A2 | The `card-header` area in Kimai's card embed template has enough space for controls next to the title | Architecture Patterns | May need to adjust Twig layout or use a different placement |
+
+## Open Questions
+
+1. **Stats row in week mode**
+   - What we know: Year-mode shows streak, total hours, avg hours, busiest day
+   - What's unclear: Whether these make sense in week mode (streak is year-concept)
+   - Recommendation: Hide stats in week mode initially; can add week-specific stats later if wanted
+
+2. **Week-mode cell click behavior**
+   - What we know: Year-mode clicks navigate to timesheet for that date
+   - What's unclear: What clicking "Monday" in week-mode should do (filter timesheet by weekday? no-op?)
+   - Recommendation: No click handler for week cells initially -- the aggregation isn't tied to a single date
+
+## Sources
+
+### Primary (HIGH confidence)
+- Codebase: `assets/src/renderers/types.ts`, `registry.ts`, `year.ts` -- ModeRenderer contract and reference implementation
+- Codebase: `assets/src/state.ts`, `assets/src/types.ts` -- HeatmapState with mode/metric fields already defined
+- Codebase: `assets/src/shared/color-scale.ts` -- buildColorScale already metric-aware
+- Codebase: `assets/src/shared/date-utils.ts` -- weekday index calculation with start-of-week support
+
+### Secondary (MEDIUM confidence)
+- [Tabler segmented control docs](https://docs.tabler.io/ui/components/segmented-control) -- `nav nav-segmented` markup pattern [CITED: docs.tabler.io/ui/components/segmented-control]
+
+### Tertiary (LOW confidence)
+- None
+
+## Metadata
+
+**Confidence breakdown:**
+- Standard stack: HIGH -- no new packages, all already installed and tested
+- Architecture: HIGH -- extends well-established strategy pattern from Phase 6
+- Pitfalls: HIGH -- based on direct codebase analysis of existing patterns
+
+**Research date:** 2026-04-09
+**Valid until:** 2026-05-09 (stable -- no external dependency changes expected)

.planning/phases/07-mode-switcher-week-mode/07-REVIEW.md

@@ -0,0 +1,106 @@
+---
+phase: 07-mode-switcher-week-mode
+reviewed: 2026-04-09T12:00:00Z
+depth: standard
+files_reviewed: 9
+files_reviewed_list:
+  - Resources/public/heatmap.css
+  - Resources/public/heatmap.js
+  - Resources/views/widget/heatmap.html.twig
+  - assets/src/heatmap.ts
+  - assets/src/renderers/week.ts
+  - assets/src/renderers/year.ts
+  - assets/src/ui/controls.ts
+  - assets/test/controls.test.ts
+  - assets/test/week.test.ts
+findings:
+  critical: 0
+  warning: 3
+  info: 2
+  total: 5
+status: issues_found
+---
+
+# Phase 7: Code Review Report
+
+**Reviewed:** 2026-04-09T12:00:00Z
+**Depth:** standard
+**Files Reviewed:** 9
+**Status:** issues_found
+
+## Summary
+
+Phase 7 adds a mode switcher (year/week toggle) and metric toggle (hours/count) to the heatmap widget, plus a new week-mode renderer that aggregates time data by weekday. The code is well-structured: clean renderer registry pattern, good separation of concerns between UI controls and renderers, solid test coverage for the new components.
+
+Three warnings found -- two are potential bugs related to tooltip XSS and missing null safety, one is a subtle interaction issue with the renderer lifecycle. Two minor info items for code quality.
+
+## Warnings
+
+### WR-01: Tooltip innerHTML allows XSS via project/weekday names
+
+**File:** `assets/src/shared/tooltip.ts:18`, `assets/src/renderers/week.ts:134`, `assets/src/renderers/year.ts:114`
+**Issue:** `showTooltip` sets `tip.innerHTML = html`, and the callers build HTML strings by interpolating data values. In week.ts, `agg.label` comes from hardcoded weekday names (safe), but in year.ts line 114, `DISPLAY_FORMAT(d.date)` is also safe since it formats a Date object. However, `showTooltip` itself is a shared utility -- any future caller interpolating user-controlled data (e.g., project names from the server) would be vulnerable to stored XSS. The pattern is fragile.
+**Fix:** Consider using `textContent` for data values and building DOM nodes instead of HTML strings, or at minimum add an escaping utility:
+```typescript
+function escapeHtml(s: string): string {
+  const div = document.createElement('div');
+  div.textContent = s;
+  return div.innerHTML;
+}
+```
+
+### WR-02: Renderer destroy() is optional but called unconditionally
+
+**File:** `assets/src/heatmap.ts:69`
+**Issue:** Line 69 calls `renderer.destroy?.()` on the *new* renderer (just fetched via `getRenderer(state.mode)`), not the *previous* renderer. When switching from year to week mode, the year renderer's tooltip is never cleaned up -- `destroy()` is called on the week renderer instance (which hasn't rendered yet, so it's a no-op). The previous mode's tooltip element leaks in the DOM.
+**Fix:** Track the active renderer and destroy it before switching:
+```typescript
+let activeRenderer: ModeRenderer | null = null;
+
+const doRender = () => {
+  if (!state.data) return;
+  activeRenderer?.destroy?.();
+  activeRenderer = getRenderer(state.mode);
+  activeRenderer.render({ /* ... */ });
+  // ...
+};
+```
+
+### WR-03: Color scale domain starts at 0, producing color for zero-value entries
+
+**File:** `assets/src/shared/color-scale.ts:15`
+**Issue:** The quantize scale domain is `[0, maxVal]`, which means a value of exactly 0 maps to the lightest green (`#9be9a8`). In the week renderer this is mitigated by the `hasData` guard (line 115-118 in week.ts), and in year.ts by the `if (!d.entry)` check (line 107). But if a DayEntry exists with `hours: 0` and `count: 0`, it would render with a green fill rather than appearing empty. This is an edge case but a data-truthfulness issue.
+**Fix:** Either filter zero-value entries in the color-scale builder, or add a guard in the renderers:
+```typescript
+// In year.ts, line 107:
+if (!d.entry || (ctx.state.metric === 'hours' ? d.entry.hours : d.entry.count) === 0) return '';
+```
+
+## Info
+
+### IN-01: Duplicate stats-removal logic in doRender
+
+**File:** `assets/src/heatmap.ts:78-83`
+**Issue:** Lines 78-83 have two consecutive `if (state.mode === 'year')` blocks that could be combined into a single if/else:
+```typescript
+if (state.mode === 'year') {
+  renderStats(container, state.data.days);
+  svgArea.scrollLeft = svgArea.scrollWidth;
+} else {
+  const existingStats = container.querySelector('.heatmap-stats');
+  if (existingStats) existingStats.remove();
+}
+```
+**Fix:** Merge the two conditionals as shown above.
+
+### IN-02: `createMetricControl` is a thin wrapper that adds no value
+
+**File:** `assets/src/ui/controls.ts:33-42`
+**Issue:** `createMetricControl` simply calls `createModeControl` with hardcoded hours/count options. This is fine as a convenience function, but the naming is slightly misleading -- it suggests a different control type when it's really just pre-configured mode buttons. No action needed, just noting for awareness.
+**Fix:** None required. Could add a brief doc comment clarifying it's a convenience wrapper.
+
+---
+
+_Reviewed: 2026-04-09T12:00:00Z_
+_Reviewer: Claude (gsd-code-reviewer)_
+_Depth: standard_

.planning/phases/07-mode-switcher-week-mode/07-UI-SPEC.md

@@ -0,0 +1,263 @@
+---
+phase: 7
+slug: mode-switcher-week-mode
+status: draft
+shadcn_initialized: false
+preset: none
+created: 2026-04-09
+---
+
+# Phase 7 — UI Design Contract
+
+> Visual and interaction contract for the mode switcher, week-mode renderer, and hours/count toggle. Generated by gsd-ui-researcher.
+
+---
+
+## Design System
+
+| Property | Value |
+|----------|-------|
+| Tool | none (Kimai plugin -- no shadcn) |
+| Preset | not applicable |
+| Component library | Tabler UI (bundled with Kimai) |
+| Icon library | none required this phase |
+| Font | `var(--tblr-font-sans-serif)` (inherited from Kimai/Tabler) |
+
+---
+
+## Spacing Scale
+
+Declared values (must be multiples of 4):
+
+| Token | Value | Usage |
+|-------|-------|-------|
+| xs | 4px | Gap between week-mode cells and labels, segmented control internal padding |
+| sm | 8px | Gap between mode switcher and metric toggle controls |
+| md | 16px | Gap between SVG area and filter dropdown (existing), stats row padding-top at 12px is the one exception |
+| lg | 24px | Not used this phase |
+| xl | 32px | Not used this phase |
+
+Exceptions: Stats row uses 12px padding-top (existing convention from `heatmap-stats`). Week-mode cell gap uses 4px between cells.
+
+---
+
+## Typography
+
+| Role | Size | Weight | Line Height | CSS Source |
+|------|------|--------|-------------|------------|
+| Body / Stats | 13px (0.8125rem) | 400 | 1.5 | Existing `.heatmap-stats`, `.heatmap-tooltip` |
+| Label (weekday, axis) | 10px | 400 | 1.2 | Existing `.heatmap-label` |
+| Control text (segmented buttons) | 13px (0.8125rem) | 400 (normal), 600 (active) | 1.5 | Tabler `nav-link` default |
+| Tooltip | 13px (0.8125rem) | 400 | 1.4 | Existing `.heatmap-tooltip` |
+
+All fonts use `var(--tblr-font-sans-serif)`. No custom font declarations.
+
+---
+
+## Color
+
+This phase introduces no new colors. All values come from Kimai's Tabler CSS variables and the existing heatmap color scale.
+
+| Role | Value | Usage |
+|------|-------|-------|
+| Dominant (60%) | `var(--tblr-bg-surface)` | Widget card background, tooltip background |
+| Secondary (30%) | `var(--tblr-bg-surface-secondary)` | Empty heatmap cells (year and week mode) |
+| Accent (10%) | Green scale: `#9be9a8`, `#40c463`, `#30a14e`, `#216e39` | Heatmap cells with data (both year and week modes) |
+| Border | `var(--tblr-border-color)` | Tooltip border |
+| Text primary | `var(--tblr-body-color)` | Weekday labels, stat values, control text |
+| Text secondary | `var(--tblr-secondary)` fallback `#6c757d` | Stats row labels |
+| Active control | Tabler `nav-segmented .active` default styling | Active mode/metric button background highlight |
+
+Accent reserved for: heatmap cells with tracked data only (cells colored by `buildColorScale()` quantize scale across 4 green buckets). Zero-data weekday cells use the secondary empty fill, not the lowest green bucket.
+
+---
+
+## Component Inventory
+
+### 1. Mode Switcher (Segmented Control)
+
+| Property | Value |
+|----------|-------|
+| Element | `<nav>` with Tabler `nav nav-segmented` classes |
+| Placement | Inside `#heatmap-controls` div in card header, right-aligned via `margin-left: auto` |
+| Items | "Year" (key: `year`), "Week" (key: `week`) |
+| Active state | `.active` class on the selected `nav-link` button |
+| ARIA | `role="tablist"` on nav, `role="tab"` on each button, `aria-selected` on active |
+| Behavior | Click sets `state.mode`, calls `doRender()`. Does not re-fetch data. |
+| Default | "Year" active on load (matches `createInitialState`) |
+
+### 2. Metric Toggle (Compact Segmented Control)
+
+| Property | Value |
+|----------|-------|
+| Element | `<nav>` with Tabler `nav nav-segmented nav-sm` classes |
+| Placement | Adjacent to mode switcher inside `#heatmap-controls`, 8px gap |
+| Items | "Hours" (key: `hours`), "Count" (key: `count`) |
+| Active state | `.active` class on selected button |
+| ARIA | Same pattern as mode switcher |
+| Behavior | Click sets `state.metric`, calls `doRender()`. Does not re-fetch data. |
+| Default | "Hours" active on load |
+
+### 3. Controls Container (Twig Template Addition)
+
+| Property | Value |
+|----------|-------|
+| Element | `<div id="heatmap-controls">` |
+| Placement | Inside `{% block box_title %}`, wrapped in a flex container with the title |
+| Layout | `display: flex; align-items: center; gap: 8px; margin-left: auto` |
+| Parent flex | Title wrapper: `display: flex; align-items: center; gap: 12px; flex-wrap: wrap` |
+
+### 4. Week-Mode Renderer (SVG)
+
+| Property | Value |
+|----------|-------|
+| Cell width | 60px |
+| Cell height | 40px |
+| Cell gap | 4px |
+| Cell border radius | `rx="2" ry="2"` (matches `.heatmap-cell`) |
+| Label width | 50px (left of cells, for 3-letter weekday abbreviation) |
+| Total SVG width | `50 + 7 * (60 + 4) = 498px` |
+| Total SVG height | 40px (single row, no extra margin needed) |
+| Cell class | `heatmap-cell` (reuses existing hover/cursor styles) |
+| Empty cell class | `heatmap-empty` (reuses existing empty fill) |
+| Label class | `heatmap-label` (reuses existing 10px label style) |
+| Label position | Vertically centered beside each cell, 50px column left of cells |
+| Day order | Follows `state.weekStart` -- Monday-first or Sunday-first |
+| Click behavior | None for this phase (weekday aggregation has no single-date target) |
+
+### 5. Week-Mode Tooltip
+
+| Property | Value |
+|----------|-------|
+| Trigger | Hover on week-mode cell |
+| Content format (hours metric) | `"Monday: 42.5h (23 entries)"` |
+| Content format (count metric) | `"Monday: 23 entries (42.5h)"` |
+| Styling | Existing `.heatmap-tooltip` class (no changes) |
+| Position | Above cursor, shared `showTooltip`/`hideTooltip` utilities |
+
+### 6. Stats Row Behavior
+
+| Mode | Stats Row |
+|------|-----------|
+| Year | Shown as-is (streak, total, avg, busiest day) |
+| Week | Hidden -- streak and busiest-date are year-specific concepts |
+
+Implementation: `renderStats()` call in `doRender()` is conditional on `state.mode === 'year'`. When mode is `'week'`, remove any existing `.heatmap-stats` element.
+
+---
+
+## Interaction Contracts
+
+### Mode Switch: Year to Week
+
+1. User clicks "Week" in mode switcher
+2. "Week" button gets `.active`, "Year" button loses `.active`
+3. `state.mode` set to `'week'`
+4. `doRender()` dispatches to `WeekModeRenderer`
+5. SVG area clears and renders 7 horizontal weekday cells
+6. Stats row is removed
+7. Scroll position resets (no horizontal scroll needed for 7 cells)
+8. Filter selection preserved (`state.filters` unchanged)
+
+### Mode Switch: Week to Year
+
+1. User clicks "Year" in mode switcher
+2. Active states swap
+3. `state.mode` set to `'year'`
+4. `doRender()` dispatches to `YearModeRenderer`
+5. SVG area clears and renders full year calendar grid
+6. Stats row reappears
+7. SVG area scrolls to right end (existing behavior)
+
+### Metric Toggle
+
+1. User clicks "Count" (or "Hours")
+2. Active state swaps on metric toggle buttons
+3. `state.metric` updated
+4. `doRender()` re-renders current mode with new metric
+5. Color scale recalculated via `buildColorScale(days, state.metric)`
+6. No data re-fetch
+
+### No Transition Animation
+
+Mode switches are instant (clear + re-render). No CSS transitions or d3 transitions between modes. This keeps implementation simple and avoids visual glitches with different SVG structures.
+
+---
+
+## Copywriting Contract
+
+| Element | Copy |
+|---------|------|
+| Mode switcher labels | "Year", "Week" |
+| Metric toggle labels | "Hours", "Count" |
+| Week tooltip (hours mode) | "{Weekday}: {N}h ({N} entries)" -- e.g. "Monday: 42.5h (23 entries)" |
+| Week tooltip (count mode) | "{Weekday}: {N} entries ({N}h)" -- e.g. "Monday: 23 entries (42.5h)" |
+| Week empty cell tooltip | "{Weekday}: No tracked time" |
+| Data load error | "Failed to load heatmap data" (existing, unchanged) |
+| Empty state (no data, week mode) | 7 cells all rendered with `.heatmap-empty` fill, no special empty-state message needed (the empty cells are self-explanatory) |
+| Project filter empty (week mode) | "No tracking data for this project" (existing `emptyMessage`, rendered as text in SVG area) |
+
+No destructive actions in this phase.
+
+---
+
+## Registry Safety
+
+| Registry | Blocks Used | Safety Gate |
+|----------|-------------|-------------|
+| Not applicable | No shadcn, no registries | N/A |
+
+This is a Symfony/Kimai plugin using Tabler CSS bundled with the host application. No component registry applies.
+
+---
+
+## CSS Additions
+
+Only one new CSS rule needed:
+
+```css
+/* Week-mode cells: no pointer cursor since they are not clickable */
+.heatmap-week-cell {
+  cursor: default;
+}
+```
+
+All other styling reuses existing classes: `.heatmap-cell`, `.heatmap-empty`, `.heatmap-label`, `.heatmap-tooltip`. The Tabler `nav-segmented` classes handle control styling with zero custom CSS.
+
+---
+
+## Twig Template Change
+
+The `{% block box_title %}` in `heatmap.html.twig` changes from:
+
+```twig
+{% block box_title %}
+    {{ title }}
+{% endblock %}
+```
+
+To:
+
+```twig
+{% block box_title %}
+    <div style="display: flex; align-items: center; gap: 12px; flex-wrap: wrap;">
+        {{ title }}
+        <div id="heatmap-controls" style="display: flex; gap: 8px; margin-left: auto;"></div>
+    </div>
+{% endblock %}
+```
+
+JS populates `#heatmap-controls` at init time. The inline styles are intentional -- this is a minimal layout wrapper, not a reusable component.
+
+---
+
+## Checker Sign-Off
+
+- [ ] Dimension 1 Copywriting: PASS
+- [ ] Dimension 2 Visuals: PASS
+- [ ] Dimension 3 Color: PASS
+- [ ] Dimension 4 Typography: PASS
+- [ ] Dimension 5 Spacing: PASS
+- [ ] Dimension 6 Registry Safety: PASS
+
+**Approval:** pending

.planning/phases/07-mode-switcher-week-mode/07-VALIDATION.md

@@ -0,0 +1,77 @@
+---
+phase: 07
+slug: mode-switcher-week-mode
+status: draft
+nyquist_compliant: false
+wave_0_complete: false
+created: 2026-04-09
+---
+
+# Phase 07 — Validation Strategy
+
+> Per-phase validation contract for feedback sampling during execution.
+
+---
+
+## Test Infrastructure
+
+| Property | Value |
+|----------|-------|
+| **Framework** | vitest 3.x |
+| **Config file** | vitest.config.ts |
+| **Quick run command** | `npx vitest run --reporter=verbose` |
+| **Full suite command** | `npx vitest run --reporter=verbose` |
+| **Estimated runtime** | ~5 seconds |
+
+---
+
+## Sampling Rate
+
+- **After every task commit:** Run `npx vitest run --reporter=verbose`
+- **After every plan wave:** Run `npx vitest run --reporter=verbose`
+- **Before `/gsd-verify-work`:** Full suite must be green
+- **Max feedback latency:** 5 seconds
+
+---
+
+## Per-Task Verification Map
+
+| Task ID | Plan | Wave | Requirement | Threat Ref | Secure Behavior | Test Type | Automated Command | File Exists | Status |
+|---------|------|------|-------------|------------|-----------------|-----------|-------------------|-------------|--------|
+| 07-01-01 | 01 | 1 | VIZ-01 | — | N/A | unit | `npx vitest run` | ❌ W0 | ⬜ pending |
+| 07-01-02 | 01 | 1 | VIZ-05 | — | N/A | unit | `npx vitest run` | ❌ W0 | ⬜ pending |
+| 07-02-01 | 02 | 1 | VIZ-02 | — | N/A | unit | `npx vitest run` | ❌ W0 | ⬜ pending |
+| 07-02-02 | 02 | 1 | TEST-01 | — | N/A | unit | `npx vitest run` | ❌ W0 | ⬜ pending |
+
+*Status: ⬜ pending / ✅ green / ❌ red / ⚠️ flaky*
+
+---
+
+## Wave 0 Requirements
+
+*Existing infrastructure covers all phase requirements.*
+
+Vitest is already installed and configured. Test files exist in `assets/test/`. No additional setup needed.
+
+---
+
+## Manual-Only Verifications
+
+| Behavior | Requirement | Why Manual | Test Instructions |
+|----------|-------------|------------|-------------------|
+| Segmented control renders in card header | VIZ-01 | Visual layout in Kimai dashboard | Start dev Kimai, verify controls appear in widget header |
+| Week-mode cells colored correctly | VIZ-02 | Visual regression check | Switch to week mode, verify 7 colored cells with correct labels |
+| Mode switch preserves filter | SC-4 | Requires running Kimai with project data | Select a project filter, switch modes, verify filter state retained |
+
+---
+
+## Validation Sign-Off
+
+- [ ] All tasks have `<automated>` verify or Wave 0 dependencies
+- [ ] Sampling continuity: no 3 consecutive tasks without automated verify
+- [ ] Wave 0 covers all MISSING references
+- [ ] No watch-mode flags
+- [ ] Feedback latency < 5s
+- [ ] `nyquist_compliant: true` set in frontmatter
+
+**Approval:** pending

.planning/phases/07-mode-switcher-week-mode/07-VERIFICATION.md

@@ -0,0 +1,115 @@
+---
+phase: 07-mode-switcher-week-mode
+verified: 2026-04-09T17:02:00Z
+status: human_needed
+score: 5/5
+human_verification:
+  - test: "Verify mode switcher and week mode visually in running Kimai"
+    expected: "Year/Week segmented control in header toggles between calendar and 7-cell weekday view. Hours/Count toggle re-colors cells. Stats row hidden in week mode. No console errors."
+    why_human: "Visual rendering, SVG layout, Tabler CSS integration, and tooltip positioning cannot be verified programmatically without a running Kimai instance"
+  - test: "Verify filter preservation across mode switches"
+    expected: "Select a project filter, switch from year to week and back -- filter remains active and data stays filtered"
+    why_human: "Requires live data fetch and DOM interaction sequence"
+---
+
+# Phase 7: Mode Switcher + Week Mode Verification Report
+
+**Phase Goal:** Users can switch between year and week visualization modes and toggle between hours and entry-count display
+**Verified:** 2026-04-09T17:02:00Z
+**Status:** human_needed
+**Re-verification:** No -- initial verification
+
+## Goal Achievement
+
+### Observable Truths
+
+| # | Truth | Status | Evidence |
+|---|-------|--------|----------|
+| 1 | A segmented control in the widget header lets the user switch between year and week views | VERIFIED | `heatmap.html.twig` has `#heatmap-controls` div in card header; `heatmap.ts:49-55` wires `createModeControl` with year/week options; onChange sets `state.mode` and calls `doRender()` |
+| 2 | Week-mode shows a day-of-week aggregation heatmap revealing which weekdays are busiest | VERIFIED | `WeekModeRenderer` in `renderers/week.ts` (155 lines) aggregates DayEntry by weekday, renders 7 SVG rects with `buildColorScale`; registered in `heatmap.ts:12` |
+| 3 | Hours/count toggle switches the color scale metric across both modes without re-fetching data | VERIFIED | `createMetricControl` wired at `heatmap.ts:57-60`; sets `state.metric` and calls `doRender()` with no fetch; week renderer reads `ctx.state.metric` at lines 78 and 118 |
+| 4 | Switching modes preserves the current filter selection | VERIFIED | Mode onChange only mutates `state.mode` (`heatmap.ts:53`); `state.filters` is untouched; no fetch on mode switch |
+| 5 | Vitest tests cover mode switcher interaction, week renderer output, and display toggle behavior | VERIFIED | `controls.test.ts` (11 tests): rendering, click handling, ARIA. `week.test.ts` (14 tests): aggregation, rendering, tooltips, labels, destroy. 174 total tests pass. |
+
+**Score:** 5/5 truths verified
+
+### Required Artifacts
+
+| Artifact | Expected | Status | Details |
+|----------|----------|--------|---------|
+| `assets/src/ui/controls.ts` | createModeControl and createMetricControl functions | VERIFIED | 42 lines, exports both functions, Tabler nav-segmented pattern, ARIA attributes |
+| `assets/src/renderers/week.ts` | WeekModeRenderer implementing ModeRenderer | VERIFIED | 155 lines, aggregateByWeekday, 7-cell SVG, color scale, tooltips, destroy |
+| `assets/test/controls.test.ts` | Tests for mode switcher and metric toggle | VERIFIED | 111 lines, 11 tests covering rendering, click, ARIA |
+| `assets/test/week.test.ts` | Tests for week renderer | VERIFIED | 178 lines, 14 tests covering aggregation, rendering, tooltips, labels |
+| `Resources/views/widget/heatmap.html.twig` | Controls placeholder in card header | VERIFIED | `#heatmap-controls` div in `box_title` block with flex layout |
+| `Resources/public/heatmap.css` | heatmap-week-cell style | VERIFIED | `.heatmap-week-cell { cursor: default; }` at line 97 |
+
+### Key Link Verification
+
+| From | To | Via | Status | Details |
+|------|----|-----|--------|---------|
+| `heatmap.ts` | `ui/controls.ts` | `import { createModeControl, createMetricControl }` | WIRED | Line 8: import; lines 49-63: both controls created and appended to DOM |
+| `heatmap.ts` | `renderers/week.ts` | `import + registerRenderer` | WIRED | Line 6: import WeekModeRenderer; line 12: `registerRenderer(new WeekModeRenderer())` |
+| `ui/controls.ts` | `state.mode / state.metric` | onChange callbacks | WIRED | `heatmap.ts:53`: `state.mode = mode`; line 58: `state.metric = metric`; both call `doRender()` |
+| `renderers/week.ts` | `shared/color-scale.ts` | `buildColorScale` | WIRED | Line 4: import; line 78: `buildColorScale(syntheticDays, ctx.state.metric)` |
+| `renderers/week.ts` | `shared/tooltip.ts` | `createTooltip/showTooltip/hideTooltip` | WIRED | Line 3: imports; line 70: create; line 142: show; line 145: hide |
+
+### Data-Flow Trace (Level 4)
+
+| Artifact | Data Variable | Source | Produces Real Data | Status |
+|----------|---------------|--------|--------------------|--------|
+| `renderers/week.ts` | `ctx.data.days` | Passed from `heatmap.ts` `state.data` | Yes -- fetched from `/heatmap_data` API endpoint | FLOWING |
+| `ui/controls.ts` | `activeMode`, `activeMetric` | Passed from `heatmap.ts` `state.mode`/`state.metric` | Yes -- initialized from `createInitialState` | FLOWING |
+| `heatmap.ts` doRender | `state.data` | `fetch(baseUrl)` at line 145 | Yes -- API fetch with JSON parse | FLOWING |
+
+### Behavioral Spot-Checks
+
+| Behavior | Command | Result | Status |
+|----------|---------|--------|--------|
+| All tests pass | `npm test` | 174 passed, 0 failed | PASS |
+| Build succeeds | `npm run build:dev` | 91.0kb bundle, exit 0 | PASS |
+| controls.ts exports functions | `grep "export function" assets/src/ui/controls.ts` | createModeControl, createMetricControl | PASS |
+| week.ts exports class | `grep "export class" assets/src/renderers/week.ts` | WeekModeRenderer | PASS |
+| WeekModeRenderer registered | `grep "registerRenderer.*WeekModeRenderer" assets/src/heatmap.ts` | Found at line 12 | PASS |
+
+### Requirements Coverage
+
+| Requirement | Source Plan | Description | Status | Evidence |
+|-------------|------------|-------------|--------|----------|
+| VIZ-01 | 07-01 | Mode switcher UI allows toggling between year, week, day, and combined views | SATISFIED (partial -- year/week only) | Controls built for year/week; day/combined modes deferred to Phase 9 per REQUIREMENTS.md traceability |
+| VIZ-02 | 07-02 | Week-mode renders day-of-week aggregation showing which weekdays are busiest | SATISFIED | WeekModeRenderer with aggregateByWeekday, 7-cell SVG, color scale |
+| VIZ-05 | 07-01 | Hours vs entry-count toggle switches color scale metric across all modes | SATISFIED (partial -- current modes) | createMetricControl wired; week renderer reads state.metric for color scale |
+| TEST-01 | 07-01, 07-02 | Vitest tests for mode switcher, each renderer, and display toggle | SATISFIED (partial -- current renderers) | 25 new tests for controls and week renderer; 174 total passing |
+
+### Anti-Patterns Found
+
+| File | Line | Pattern | Severity | Impact |
+|------|------|---------|----------|--------|
+| -- | -- | No anti-patterns found | -- | -- |
+
+Note: `createModeControl` applies `nav-sm` class to both mode and metric controls (plan specified `nav-sm` only for metric). Commit `12e734a` ("uniform control sizing") indicates this was a deliberate design refinement, not a bug.
+
+### Human Verification Required
+
+### 1. Visual Rendering in Kimai Dashboard
+
+**Test:** Start local Kimai, navigate to dashboard. Verify Year/Week segmented control and Hours/Count toggle appear in widget header. Click Week -- verify 7 horizontal cells with weekday labels. Hover cells for tooltips. Click Count -- verify re-coloring. Click Year -- verify calendar returns with stats row.
+**Expected:** Controls render with Tabler styling, mode switching is instant, tooltips show correct aggregated data, stats row toggles visibility.
+**Why human:** SVG layout, Tabler CSS integration, tooltip positioning, and visual polish require a running browser with Kimai's CSS loaded.
+
+### 2. Filter Preservation Across Mode Switches
+
+**Test:** Select a project filter, then switch between Year and Week modes.
+**Expected:** Filter dropdown stays on selected project, heatmap data remains filtered in both modes.
+**Why human:** Requires live data fetch and interactive DOM state observation.
+
+### Gaps Summary
+
+No code-level gaps found. All 5 roadmap success criteria verified in the codebase. All artifacts exist, are substantive, wired, and data flows through. 174 tests pass. Build succeeds.
+
+Two items require human visual verification: (1) the rendered output in a running Kimai instance, and (2) filter preservation during mode switching. These are the plan's own human-verify checkpoint (07-02 Task 2).
+
+---
+
+_Verified: 2026-04-09T17:02:00Z_
+_Verifier: Claude (gsd-verifier)_

.planning/phases/08-backend-aggregation-filtering/08-01-PLAN.md

@@ -0,0 +1,284 @@
+---
+phase: 08-backend-aggregation-filtering
+plan: 01
+type: execute
+wave: 1
+depends_on: []
+files_modified:
+  - Service/HeatmapService.php
+  - Tests/Service/HeatmapServiceTest.php
+autonomous: true
+requirements: [API-01, FILT-02, FILT-03, TEST-03]
+
+must_haves:
+  truths:
+    - "getHourlyAggregation returns hour-of-day aggregation with timezone-correct hour extraction"
+    - "getDayHourAggregation returns 7x24 day/hour matrix with weekStart-relative day index"
+    - "Activity filter narrows all aggregation queries to a specific activity"
+    - "Customer filter narrows all aggregation queries via project->customer join"
+    - "getDailyAggregation accepts optional activity and customer filter params"
+  artifacts:
+    - path: "Service/HeatmapService.php"
+      provides: "Hourly, day/hour aggregation + filter params on all queries"
+      exports: ["getHourlyAggregation", "getDayHourAggregation", "getUserCustomers", "getUserActivities"]
+    - path: "Tests/Service/HeatmapServiceTest.php"
+      provides: "Unit tests for all new service methods"
+  key_links:
+    - from: "Service/HeatmapService.php"
+      to: "DBAL Connection"
+      via: "repository->getEntityManager()->getConnection()"
+      pattern: "executeQuery.*CONVERT_TZ"
+    - from: "Service/HeatmapService.php"
+      to: "TimesheetRepository QueryBuilder"
+      via: "createQueryBuilder for DQL queries"
+      pattern: "createQueryBuilder.*join.*customer"
+---
+
+<objective>
+Extend HeatmapService with hourly and day/hour aggregation methods, cascade entity queries, and activity/customer filter support on all aggregation methods.
+
+Purpose: Backend data layer for Phase 9 renderers (day-mode, combined-mode) and Phase 10 entity pickers. All new queries use parameterized SQL to prevent injection.
+Output: Extended HeatmapService with 4 new public methods + filter params on existing method, fully tested.
+</objective>
+
+<execution_context>
+@/home/toph/code/toph/kimai-heatmap/.claude/get-shit-done/workflows/execute-plan.md
+@/home/toph/code/toph/kimai-heatmap/.claude/get-shit-done/templates/summary.md
+</execution_context>
+
+<context>
+@.planning/PROJECT.md
+@.planning/ROADMAP.md
+@.planning/STATE.md
+@.planning/phases/08-backend-aggregation-filtering/08-CONTEXT.md
+@.planning/phases/08-backend-aggregation-filtering/08-RESEARCH.md
+
+<interfaces>
+<!-- Existing service interface that will be extended -->
+
+From Service/HeatmapService.php:
+```php
+class HeatmapService
+{
+    public function __construct(private readonly TimesheetRepository $repository) {}
+    public function getDailyAggregation(User $user, \DateTimeInterface $begin, \DateTimeInterface $end, ?int $projectId = null): array {}
+    public function getUserProjects(User $user): array {}
+}
+```
+
+From Tests/Service/HeatmapServiceTest.php:
+```php
+// Mock helper creates: AbstractQuery mock, QueryBuilder mock (with select/addSelect/andWhere/setParameter/groupBy/orderBy/expr/getQuery stubs), TimesheetRepository mock
+private function createServiceWithResults(array $results): HeatmapService {}
+```
+
+From 08-RESEARCH.md — Native SQL pattern:
+```php
+$conn = $this->repository->getEntityManager()->getConnection();
+$result = $conn->executeQuery($sql, $params);
+$rows = $result->fetchAllAssociative();
+```
+</interfaces>
+</context>
+
+<tasks>
+
+<task type="auto" tdd="true">
+  <name>Task 1: Add aggregation methods and filter support to HeatmapService</name>
+  <files>Service/HeatmapService.php, Tests/Service/HeatmapServiceTest.php</files>
+  <read_first>
+    - Service/HeatmapService.php (current service with getDailyAggregation and getUserProjects)
+    - Tests/Service/HeatmapServiceTest.php (existing test pattern and createServiceWithResults helper)
+    - .planning/phases/08-backend-aggregation-filtering/08-RESEARCH.md (native SQL patterns, timezone handling, mock patterns)
+  </read_first>
+  <behavior>
+    - Test: getHourlyAggregation returns array of {hour: int (0-23), hours: float, count: int} from mocked native SQL results
+    - Test: getHourlyAggregation converts duration seconds to hours rounded to 2 decimals (e.g., 7200 -> 2.0)
+    - Test: getHourlyAggregation returns empty array when no data
+    - Test: getDayHourAggregation returns array of {day: int (0-6), hour: int (0-23), hours: float, count: int}
+    - Test: getDayHourAggregation remaps MySQL DAYOFWEEK (1=Sun..7=Sat) to 0-6 relative to weekStart='monday' (Mon=0, Tue=1, ..., Sun=6)
+    - Test: getDayHourAggregation remaps correctly for weekStart='sunday' (Sun=0, Mon=1, ..., Sat=6)
+    - Test: getDailyAggregation with activityId param calls andWhere with activity filter
+    - Test: getDailyAggregation with customerId param calls join('t.project','p') and andWhere with customer filter
+    - Test: getUserCustomers returns [{id: int, name: string}] from user's timesheet customers
+    - Test: getUserActivities returns [{id: int, name: string}], optionally scoped by projectId
+  </behavior>
+  <action>
+**Write tests first (RED), then implement (GREEN).**
+
+**Test additions to HeatmapServiceTest.php:**
+
+Add a `createServiceWithNativeResults(array $results)` helper that mocks the DBAL Connection chain:
+```php
+private function createServiceWithNativeResults(array $results): HeatmapService
+{
+    $statement = $this->createMock(\Doctrine\DBAL\Result::class);
+    $statement->method('fetchAllAssociative')->willReturn($results);
+
+    $connection = $this->createMock(\Doctrine\DBAL\Connection::class);
+    $connection->method('executeQuery')->willReturn($statement);
+
+    $em = $this->createMock(\Doctrine\ORM\EntityManagerInterface::class);
+    $em->method('getConnection')->willReturn($connection);
+
+    $repo = $this->createMock(TimesheetRepository::class);
+    $repo->method('getEntityManager')->willReturn($em);
+
+    return new HeatmapService($repo);
+}
+```
+
+Update the existing `createServiceWithResults()` to also stub `join()` on the QueryBuilder mock:
+```php
+$qb->method('join')->willReturnSelf();
+```
+
+Add test methods:
+- `testGetHourlyAggregationReturnsFormattedResults` — mock native SQL returning `[['hour_slot' => 9, 'duration' => 7200, 'count' => 5]]`, assert result is `[['hour' => 9, 'hours' => 2.0, 'count' => 5]]`
+- `testGetHourlyAggregationReturnsEmptyForNoData` — mock empty results, assert empty array
+- `testGetDayHourAggregationReturnsFormattedResults` — mock native SQL returning `[['dow' => 2, 'hour_slot' => 14, 'duration' => 3600, 'count' => 1]]`, with weekStart='monday', assert `[['day' => 0, 'hour' => 14, 'hours' => 1.0, 'count' => 1]]` (MySQL dow=2 is Monday, which is day=0 for monday-start)
+- `testGetDayHourAggregationSundayStart` — same input but weekStart='sunday', assert `[['day' => 1, 'hour' => 14, 'hours' => 1.0, 'count' => 1]]` (Monday is day=1 for sunday-start)
+- `testGetDailyAggregationWithActivityFilter` — verify activity filter is applied (use existing mock pattern, assert service call doesn't throw)
+- `testGetDailyAggregationWithCustomerFilter` — verify customer filter with join is applied
+- `testGetUserCustomersReturnsFormattedResults` — mock QB returning `[['customerId' => 1, 'name' => 'Acme']]`, assert `[['id' => 1, 'name' => 'Acme']]`
+- `testGetUserActivitiesReturnsFormattedResults` — mock QB returning `[['activityId' => 5, 'name' => 'Dev']]`, assert `[['id' => 5, 'name' => 'Dev']]`
+- `testGetUserActivitiesWithProjectScope` — same as above but with projectId param, assert no error
+
+**Service implementation in HeatmapService.php:**
+
+1. **Extend getDailyAggregation signature** — add `?int $customerId = null, ?int $activityId = null` after `$projectId`. Add filter logic:
+   ```php
+   if ($activityId !== null) {
+       $qb->andWhere($qb->expr()->eq('t.activity', ':activity'))
+          ->setParameter('activity', $activityId);
+   }
+   if ($customerId !== null) {
+       $qb->join('t.project', 'p')
+          ->andWhere($qb->expr()->eq('p.customer', ':customer'))
+          ->setParameter('customer', $customerId);
+   }
+   ```
+
+2. **Add getHourlyAggregation** — uses native SQL via DBAL Connection:
+   - Accepts `User $user, \DateTimeInterface $begin, \DateTimeInterface $end, ?int $projectId = null, ?int $customerId = null, ?int $activityId = null`
+   - Compute timezone offset: `$tz = new \DateTimeZone($user->getTimezone()); $offset = $tz->getOffset(new \DateTime('now', new \DateTimeZone('UTC'))); $offsetStr = sprintf('%+03d:%02d', intdiv($offset, 3600), abs(intdiv($offset % 3600, 60)));`
+   - SQL: `SELECT HOUR(CONVERT_TZ(t.start_time, '+00:00', :tz)) as hour_slot, COALESCE(SUM(t.duration), 0) as duration, COUNT(t.id) as count FROM kimai2_timesheet t WHERE t.user = :user AND t.date_tz BETWEEN :begin AND :end AND t.end_time IS NOT NULL`
+   - Append filter clauses: `AND t.project_id = :project` (if projectId), `INNER JOIN kimai2_projects p ON t.project_id = p.id AND p.customer_id = :customer` (if customerId), `AND t.activity_id = :activity` (if activityId)
+   - `GROUP BY hour_slot ORDER BY hour_slot ASC`
+   - Map results: `['hour' => (int)$row['hour_slot'], 'hours' => round((int)$row['duration'] / 3600, 2), 'count' => (int)$row['count']]`
+
+3. **Add getDayHourAggregation** — uses native SQL:
+   - Same signature as getHourlyAggregation plus `string $weekStart = 'monday'`
+   - SQL: `SELECT DAYOFWEEK(t.date_tz) as dow, HOUR(CONVERT_TZ(t.start_time, '+00:00', :tz)) as hour_slot, COALESCE(SUM(t.duration), 0) as duration, COUNT(t.id) as count FROM kimai2_timesheet t WHERE ...`
+   - Same filter append logic as getHourlyAggregation
+   - `GROUP BY dow, hour_slot ORDER BY dow, hour_slot`
+   - Remap MySQL DAYOFWEEK to 0-6 relative to weekStart:
+     ```php
+     $weekStartOffset = ($weekStart === 'sunday') ? 1 : 2;
+     $dayIndex = ($mysqlDow - $weekStartOffset + 7) % 7;
+     ```
+   - Map results: `['day' => $dayIndex, 'hour' => (int)$row['hour_slot'], 'hours' => round((int)$row['duration'] / 3600, 2), 'count' => (int)$row['count']]`
+
+4. **Add getUserCustomers** — DQL via QueryBuilder:
+   ```php
+   public function getUserCustomers(User $user): array
+   {
+       $qb = $this->repository->createQueryBuilder('t');
+       $qb->select('DISTINCT IDENTITY(p.customer) as customerId, c.name')
+          ->join('t.project', 'p')
+          ->join('p.customer', 'c')
+          ->andWhere($qb->expr()->eq('t.user', ':user'))
+          ->andWhere($qb->expr()->isNotNull('t.end'))
+          ->setParameter('user', $user)
+          ->orderBy('c.name', 'ASC');
+       return array_map(fn(array $row) => [
+           'id' => (int) $row['customerId'],
+           'name' => $row['name'],
+       ], $qb->getQuery()->getResult());
+   }
+   ```
+
+5. **Add getUserActivities** — DQL via QueryBuilder:
+   ```php
+   public function getUserActivities(User $user, ?int $projectId = null): array
+   {
+       $qb = $this->repository->createQueryBuilder('t');
+       $qb->select('DISTINCT IDENTITY(t.activity) as activityId, a.name')
+          ->join('t.activity', 'a')
+          ->andWhere($qb->expr()->eq('t.user', ':user'))
+          ->andWhere($qb->expr()->isNotNull('t.end'))
+          ->setParameter('user', $user)
+          ->orderBy('a.name', 'ASC');
+       if ($projectId !== null) {
+           $qb->andWhere($qb->expr()->eq('t.project', ':project'))
+              ->setParameter('project', $projectId);
+       }
+       return array_map(fn(array $row) => [
+           'id' => (int) $row['activityId'],
+           'name' => $row['name'],
+       ], $qb->getQuery()->getResult());
+   }
+   ```
+  </action>
+  <verify>
+    <automated>php dev/kimai/vendor/bin/phpunit --configuration Tests/phpunit.xml --filter "testGetHourly|testGetDayHour|testGetDailyAggregationWith|testGetUserCustomers|testGetUserActivities"</automated>
+  </verify>
+  <acceptance_criteria>
+    - Service/HeatmapService.php contains `public function getHourlyAggregation(`
+    - Service/HeatmapService.php contains `public function getDayHourAggregation(`
+    - Service/HeatmapService.php contains `public function getUserCustomers(`
+    - Service/HeatmapService.php contains `public function getUserActivities(`
+    - Service/HeatmapService.php contains `CONVERT_TZ(t.start_time, '+00:00', :tz)`
+    - Service/HeatmapService.php contains `DAYOFWEEK(t.date_tz)`
+    - Service/HeatmapService.php contains `$weekStartOffset = ($weekStart === 'sunday') ? 1 : 2`
+    - getDailyAggregation signature contains `?int $customerId = null, ?int $activityId = null`
+    - Service/HeatmapService.php contains `->join('t.project', 'p')` for customer filter
+    - Service/HeatmapService.php contains `t.activity_id = :activity` for activity filter in native SQL
+    - Service/HeatmapService.php contains `eq('t.activity', ':activity')` for activity filter in DQL
+    - Tests/Service/HeatmapServiceTest.php contains `testGetHourlyAggregationReturnsFormattedResults`
+    - Tests/Service/HeatmapServiceTest.php contains `testGetDayHourAggregationReturnsFormattedResults`
+    - Tests/Service/HeatmapServiceTest.php contains `testGetDayHourAggregationSundayStart`
+    - Tests/Service/HeatmapServiceTest.php contains `testGetUserCustomersReturnsFormattedResults`
+    - Tests/Service/HeatmapServiceTest.php contains `testGetUserActivitiesReturnsFormattedResults`
+    - Tests/Service/HeatmapServiceTest.php contains `createServiceWithNativeResults`
+    - PHPUnit exits 0 for all new tests
+  </acceptance_criteria>
+  <done>All 4 new service methods implemented with timezone-correct SQL, filter support on all aggregations, and all tests green</done>
+</task>
+
+</tasks>
+
+<threat_model>
+## Trust Boundaries
+
+| Boundary | Description |
+|----------|-------------|
+| HTTP request -> HeatmapService | Query params (mode, project, customer, activity) are untrusted user input |
+| HeatmapService -> Database | SQL queries must use parameterized binding, never string concatenation |
+
+## STRIDE Threat Register
+
+| Threat ID | Category | Component | Disposition | Mitigation Plan |
+|-----------|----------|-----------|-------------|-----------------|
+| T-08-01 | Tampering | Native SQL queries | mitigate | All values passed via DBAL named parameters (:tz, :user, :begin, :end, :project, :customer, :activity) — never concatenated into SQL string |
+| T-08-02 | Information Disclosure | Aggregation queries | mitigate | All queries include `t.user = :user` constraint — user can only see own timesheet data |
+| T-08-03 | Tampering | Filter ID params | mitigate | Integer type enforced via `getInt()` in controller (Plan 02); service accepts `?int` typed params |
+</threat_model>
+
+<verification>
+- `php dev/kimai/vendor/bin/phpunit --configuration Tests/phpunit.xml` exits 0
+- HeatmapService has 6 public methods: getDailyAggregation, getHourlyAggregation, getDayHourAggregation, getUserProjects, getUserCustomers, getUserActivities
+- All native SQL uses parameterized queries (no string interpolation in SQL)
+</verification>
+
+<success_criteria>
+- All new service methods return correctly shaped data per D-06 and D-07 contracts
+- Filter params (activity, customer) narrow results via parameterized WHERE clauses
+- Timezone offset computed from user's timezone setting per D-08
+- Day-of-week index remapped relative to weekStart per 08-RESEARCH.md Pattern 5
+- All PHPUnit tests pass
+</success_criteria>
+
+<output>
+After completion, create `.planning/phases/08-backend-aggregation-filtering/08-01-SUMMARY.md`
+</output>

.planning/phases/08-backend-aggregation-filtering/08-01-SUMMARY.md

@@ -0,0 +1,89 @@
+---
+phase: 08-backend-aggregation-filtering
+plan: 01
+subsystem: backend-service
+tags: [php, aggregation, filtering, timezone, tdd]
+dependency_graph:
+  requires: []
+  provides: [getHourlyAggregation, getDayHourAggregation, getUserCustomers, getUserActivities, filter-params]
+  affects: [Controller/HeatmapController.php, DependencyInjection]
+tech_stack:
+  added: []
+  patterns: [native-sql-dbal, timezone-offset-convert_tz, weekstart-day-remapping, entity-manager-injection]
+key_files:
+  created: []
+  modified:
+    - Service/HeatmapService.php
+    - Tests/Service/HeatmapServiceTest.php
+    - Tests/bootstrap.php
+decisions:
+  - Inject EntityManagerInterface as second constructor param instead of accessing via protected getEntityManager() on TimesheetRepository -- enables clean mocking
+  - Use subquery for customer filter in native SQL instead of JOIN to keep SQL builder logic simple
+metrics:
+  duration_seconds: 466
+  completed: "2026-04-09T19:25:45Z"
+  tasks_completed: 1
+  tasks_total: 1
+  test_count: 13
+  test_pass: 13
+---
+
+# Phase 8 Plan 01: Backend Aggregation + Filter Methods Summary
+
+Extended HeatmapService with hourly/day-hour aggregation via native SQL CONVERT_TZ, cascade entity queries (customers/activities), and activity/customer filter params on all aggregation methods.
+
+## Tasks Completed
+
+| # | Task | Commit | Key Changes |
+|---|------|--------|-------------|
+| 1 | Add aggregation methods and filter support (TDD) | 8a0e5de (RED), c28220c (GREEN) | 4 new service methods, 10 new tests, filter params on getDailyAggregation |
+
+## Implementation Details
+
+### New Service Methods
+
+- **getHourlyAggregation**: Native SQL with `CONVERT_TZ(start_time, '+00:00', :tz)` for timezone-correct hour grouping. Returns `{hour, hours, count}`.
+- **getDayHourAggregation**: Native SQL with `DAYOFWEEK(date_tz)` remapped to 0-6 relative to weekStart preference. Returns `{day, hour, hours, count}`.
+- **getUserCustomers**: DQL via QueryBuilder joining through project to customer. Returns `{id, name}`.
+- **getUserActivities**: DQL via QueryBuilder with optional projectId scope. Returns `{id, name}`.
+
+### Extended Methods
+
+- **getDailyAggregation**: Added `?int $customerId` and `?int $activityId` params with parameterized WHERE clauses.
+
+### Architecture Change
+
+Injected `EntityManagerInterface` as second constructor parameter to HeatmapService. This replaces the previous pattern of calling the protected `getEntityManager()` on TimesheetRepository, which cannot be mocked in PHPUnit. Symfony autowiring handles the injection automatically.
+
+### Test Infrastructure
+
+Added `createServiceWithNativeResults()` helper for mocking DBAL Connection chain (Result -> Connection -> EntityManager). Updated `createServiceWithResults()` to stub `join()` and pass EntityManager mock.
+
+Updated `Tests/bootstrap.php` with a prepended autoloader for worktree contexts.
+
+## Deviations from Plan
+
+### Auto-fixed Issues
+
+**1. [Rule 3 - Blocking] EntityManager access pattern incompatible with PHPUnit mocking**
+- **Found during:** Task 1 (RED phase)
+- **Issue:** `TimesheetRepository::getEntityManager()` is protected in Doctrine's EntityRepository, making it impossible to mock via `createMock()`. Using `getMockBuilder()->onlyMethods()` also failed because the mock's `__call` magic intercepted the call.
+- **Fix:** Added `EntityManagerInterface` as second constructor parameter to HeatmapService. Symfony autowiring handles injection; tests pass a mock directly.
+- **Files modified:** Service/HeatmapService.php, Tests/Service/HeatmapServiceTest.php
+- **Commit:** c28220c
+
+**2. [Rule 3 - Blocking] Worktree autoloader resolving classes from main repo**
+- **Found during:** Task 1 (GREEN phase)
+- **Issue:** Composer's classmap in Kimai's vendor directory resolves plugin classes via the symlink to the main repo, ignoring worktree file changes.
+- **Fix:** Added prepended `spl_autoload_register` in Tests/bootstrap.php that resolves `KimaiPlugin\KimaiHeatmapBundle\` from the current directory before Composer's classmap.
+- **Files modified:** Tests/bootstrap.php
+- **Commit:** c28220c
+
+## Verification
+
+- PHPUnit: 13 tests, 40 assertions, 0 failures
+- All 6 public business methods present on HeatmapService
+- All native SQL uses parameterized queries (no string interpolation)
+- All queries include user scope constraint
+
+## Self-Check: PASSED

.planning/phases/08-backend-aggregation-filtering/08-02-PLAN.md

@@ -0,0 +1,360 @@
+---
+phase: 08-backend-aggregation-filtering
+plan: 02
+type: execute
+wave: 2
+depends_on: ["08-01"]
+files_modified:
+  - Controller/HeatmapController.php
+  - Tests/Controller/HeatmapControllerTest.php
+  - assets/src/types.ts
+autonomous: true
+requirements: [API-01, API-02, FILT-02, FILT-03, TEST-03]
+
+must_haves:
+  truths:
+    - "/heatmap/data?mode=hourly returns hourly aggregation JSON"
+    - "/heatmap/data?mode=dayhour returns day/hour matrix JSON"
+    - "/heatmap/data?activity=N narrows results to that activity"
+    - "/heatmap/data?customer=N narrows results to that customer's projects"
+    - "/heatmap/customers returns user's customer list"
+    - "/heatmap/projects returns user's project list (optionally filtered by customer)"
+    - "/heatmap/activities returns user's activity list (optionally filtered by project)"
+    - "TypeScript types exist for hourly and day/hour response shapes"
+  artifacts:
+    - path: "Controller/HeatmapController.php"
+      provides: "Mode dispatch, filter params, cascade endpoints"
+      exports: ["data", "customers", "projects", "activities"]
+    - path: "Tests/Controller/HeatmapControllerTest.php"
+      provides: "Unit tests for mode dispatch and cascade endpoints"
+    - path: "assets/src/types.ts"
+      provides: "HourEntry, DayHourEntry, HourlyData, DayHourData types"
+  key_links:
+    - from: "Controller/HeatmapController.php"
+      to: "Service/HeatmapService.php"
+      via: "Symfony DI injection"
+      pattern: "service->getHourlyAggregation|service->getDayHourAggregation|service->getUserCustomers|service->getUserActivities"
+---
+
+<objective>
+Extend HeatmapController with mode dispatch, filter parameters, and cascade entity endpoints. Add TypeScript types for new response shapes.
+
+Purpose: Wire the service methods from Plan 01 to HTTP endpoints, making aggregation data and entity lists available to the frontend. Cascade endpoints serve Phase 10 pickers.
+Output: Extended controller with 4 actions (data with mode/filters, customers, projects, activities), tests, and TS types.
+</objective>
+
+<execution_context>
+@/home/toph/code/toph/kimai-heatmap/.claude/get-shit-done/workflows/execute-plan.md
+@/home/toph/code/toph/kimai-heatmap/.claude/get-shit-done/templates/summary.md
+</execution_context>
+
+<context>
+@.planning/PROJECT.md
+@.planning/ROADMAP.md
+@.planning/STATE.md
+@.planning/phases/08-backend-aggregation-filtering/08-CONTEXT.md
+@.planning/phases/08-backend-aggregation-filtering/08-RESEARCH.md
+@.planning/phases/08-backend-aggregation-filtering/08-UI-SPEC.md
+@.planning/phases/08-backend-aggregation-filtering/08-01-SUMMARY.md
+
+<interfaces>
+<!-- From Plan 01 — new service methods available -->
+
+From Service/HeatmapService.php (after Plan 01):
+```php
+public function getDailyAggregation(User $user, \DateTimeInterface $begin, \DateTimeInterface $end, ?int $projectId = null, ?int $customerId = null, ?int $activityId = null): array;
+public function getHourlyAggregation(User $user, \DateTimeInterface $begin, \DateTimeInterface $end, ?int $projectId = null, ?int $customerId = null, ?int $activityId = null): array;
+public function getDayHourAggregation(User $user, \DateTimeInterface $begin, \DateTimeInterface $end, ?int $projectId = null, ?int $customerId = null, ?int $activityId = null, string $weekStart = 'monday'): array;
+public function getUserProjects(User $user): array;
+public function getUserCustomers(User $user): array;
+public function getUserActivities(User $user, ?int $projectId = null): array;
+```
+
+From Controller/HeatmapController.php (current):
+```php
+#[Route(path: '/heatmap')]
+#[IsGranted('IS_AUTHENTICATED_REMEMBERED')]
+class HeatmapController extends AbstractController
+{
+    #[Route(path: '/data', name: 'heatmap_data', methods: ['GET'])]
+    #[IsGranted('view_own_timesheet')]
+    public function data(Request $request, HeatmapService $service): JsonResponse
+}
+```
+
+From assets/src/types.ts (current):
+```typescript
+export interface DayEntry { date: string; hours: number; count: number; }
+export interface HeatmapData { days: DayEntry[]; range: { begin: string; end: string; }; }
+export interface ProjectOption { id: number; name: string; }
+export type DisplayMetric = 'hours' | 'count';
+export type HeatmapMode = 'year' | 'week' | 'day' | 'combined';
+export interface FilterState { projectId: number | null; customerId: number | null; activityId: number | null; }
+```
+
+From Tests/Controller/HeatmapControllerTest.php (current mock pattern):
+```php
+// Mock user via container/tokenStorage pattern
+$container->method('has')->willReturn(true);
+$container->method('get')->willReturn($tokenStorage);
+$controller->setContainer($container);
+```
+</interfaces>
+</context>
+
+<tasks>
+
+<task type="auto" tdd="true">
+  <name>Task 1: Extend HeatmapController with mode dispatch and cascade endpoints</name>
+  <files>Controller/HeatmapController.php, Tests/Controller/HeatmapControllerTest.php</files>
+  <read_first>
+    - Controller/HeatmapController.php (current data action)
+    - Tests/Controller/HeatmapControllerTest.php (existing mock pattern)
+    - Service/HeatmapService.php (Plan 01 output — verify new method signatures)
+    - .planning/phases/08-backend-aggregation-filtering/08-RESEARCH.md (Pattern 1: Mode Dispatch, Pattern 4: Cascade)
+    - .planning/phases/08-backend-aggregation-filtering/08-01-SUMMARY.md (confirm service method signatures)
+  </read_first>
+  <behavior>
+    - Test: data() with mode=hourly calls getHourlyAggregation and returns JSON with 'hours' key
+    - Test: data() with mode=dayhour calls getDayHourAggregation and returns JSON with 'matrix' key
+    - Test: data() with no mode (default) calls getDailyAggregation and returns JSON with 'days' key
+    - Test: data() passes activity and customer params to service method
+    - Test: customers() returns JSON array from getUserCustomers
+    - Test: projects() returns JSON array from getUserProjects (existing method)
+    - Test: projects() with customer param passes it to the service (filtered query would be in service)
+    - Test: activities() returns JSON array from getUserActivities
+    - Test: activities() with project param passes it to getUserActivities
+  </behavior>
+  <action>
+**Write tests first (RED), then implement (GREEN).**
+
+**Test additions to HeatmapControllerTest.php:**
+
+Add a helper method to create controller with mocked user (extract from existing test):
+```php
+private function createControllerWithUser(): array
+{
+    $user = $this->createMock(User::class);
+    $user->method('getTimezone')->willReturn('Europe/Berlin');
+    // Kimai's User has getFirstDayOfWeek() returning 'monday' or 'sunday'
+    $user->method('getFirstDayOfWeek')->willReturn('monday');
+
+    $controller = new HeatmapController();
+    $container = $this->createMock(\Symfony\Component\DependencyInjection\ContainerInterface::class);
+    $tokenStorage = $this->createMock(\Symfony\Component\Security\Core\Authentication\Token\Storage\TokenStorageInterface::class);
+    $token = $this->createMock(\Symfony\Component\Security\Core\Authentication\Token\TokenInterface::class);
+    $token->method('getUser')->willReturn($user);
+    $tokenStorage->method('getToken')->willReturn($token);
+    $container->method('has')->willReturn(true);
+    $container->method('get')->willReturn($tokenStorage);
+    $controller->setContainer($container);
+
+    return [$controller, $user];
+}
+```
+
+Add test methods:
+- `testDataReturnsHourlyMode` — create service mock where `getHourlyAggregation` returns `[['hour' => 9, 'hours' => 2.0, 'count' => 5]]`, request with `?mode=hourly`, assert response JSON has `hours` key with that array and `range` key
+- `testDataReturnsDayHourMode` — service mock where `getDayHourAggregation` returns `[['day' => 0, 'hour' => 9, 'hours' => 1.0, 'count' => 1]]`, request with `?mode=dayhour`, assert response JSON has `matrix` key
+- `testDataDefaultsToDailyMode` — service mock `getDailyAggregation` returns mock days, request with no mode param, assert `days` key present
+- `testDataPassesFilterParams` — request with `?activity=5&customer=3`, verify service method receives these values (use `$service->expects($this->once())->method('getDailyAggregation')->with(...)`)
+- `testCustomersEndpoint` — service mock `getUserCustomers` returns `[['id' => 1, 'name' => 'Acme']]`, call customers(), assert JSON response matches
+- `testProjectsEndpoint` — service mock `getUserProjects` returns `[['id' => 1, 'name' => 'Web']]`, call projects(), assert JSON matches
+- `testActivitiesEndpoint` — service mock `getUserActivities` returns `[['id' => 1, 'name' => 'Dev']]`, call activities(), assert JSON matches
+- `testActivitiesWithProjectParam` — request with `?project=3`, verify `getUserActivities` called with projectId=3
+
+**Controller implementation in HeatmapController.php:**
+
+1. **Rewrite the `data()` action** with mode dispatch and filter params per D-02, D-03:
+   ```php
+   #[Route(path: '/data', name: 'heatmap_data', methods: ['GET'])]
+   #[IsGranted('view_own_timesheet')]
+   public function data(Request $request, HeatmapService $service): JsonResponse
+   {
+       $user = $this->getUser();
+       $end = new \DateTimeImmutable('today');
+       $begin = $end->modify('-1 year');
+
+       $mode = $request->query->getString('mode', 'daily');
+       $projectId = $request->query->getInt('project') ?: null;
+       $customerId = $request->query->getInt('customer') ?: null;
+       $activityId = $request->query->getInt('activity') ?: null;
+
+       $range = ['begin' => $begin->format('Y-m-d'), 'end' => $end->format('Y-m-d')];
+
+       return match ($mode) {
+           'hourly' => new JsonResponse([
+               'hours' => $service->getHourlyAggregation($user, $begin, $end, $projectId, $customerId, $activityId),
+               'range' => $range,
+           ]),
+           'dayhour' => new JsonResponse([
+               'matrix' => $service->getDayHourAggregation($user, $begin, $end, $projectId, $customerId, $activityId, $user->getFirstDayOfWeek()),
+               'range' => $range,
+           ]),
+           default => new JsonResponse([
+               'days' => $service->getDailyAggregation($user, $begin, $end, $projectId, $customerId, $activityId),
+               'range' => $range,
+           ]),
+       };
+   }
+   ```
+
+2. **Add customers() action** per D-04:
+   ```php
+   #[Route(path: '/customers', name: 'heatmap_customers', methods: ['GET'])]
+   #[IsGranted('view_own_timesheet')]
+   public function customers(HeatmapService $service): JsonResponse
+   {
+       return new JsonResponse($service->getUserCustomers($this->getUser()));
+   }
+   ```
+
+3. **Add projects() action** — extend existing getUserProjects with optional customer filter. NOTE: the existing `getUserProjects()` method takes only User. For customer-scoped project filtering, add a `?int $customerId = null` param to the service method signature if not already done, OR query projects from timesheets filtered by customer. Since D-04 says `/heatmap/projects?customer={id}`, add customer filtering:
+   ```php
+   #[Route(path: '/projects', name: 'heatmap_projects', methods: ['GET'])]
+   #[IsGranted('view_own_timesheet')]
+   public function projects(Request $request, HeatmapService $service): JsonResponse
+   {
+       $customerId = $request->query->getInt('customer') ?: null;
+       return new JsonResponse($service->getUserProjects($this->getUser(), $customerId));
+   }
+   ```
+   IMPORTANT: This requires extending `getUserProjects(User $user, ?int $customerId = null)` in the service. Add the optional customer filter to getUserProjects:
+   ```php
+   if ($customerId !== null) {
+       $qb->join('p.customer', 'c')
+          ->andWhere($qb->expr()->eq('c.id', ':customer'))
+          ->setParameter('customer', $customerId);
+   }
+   ```
+
+4. **Add activities() action** per D-04:
+   ```php
+   #[Route(path: '/activities', name: 'heatmap_activities', methods: ['GET'])]
+   #[IsGranted('view_own_timesheet')]
+   public function activities(Request $request, HeatmapService $service): JsonResponse
+   {
+       $projectId = $request->query->getInt('project') ?: null;
+       return new JsonResponse($service->getUserActivities($this->getUser(), $projectId));
+   }
+   ```
+  </action>
+  <verify>
+    <automated>php dev/kimai/vendor/bin/phpunit --configuration Tests/phpunit.xml --filter "testDataReturnsHourly|testDataReturnsDayHour|testDataDefaultsToDaily|testDataPassesFilter|testCustomersEndpoint|testProjectsEndpoint|testActivitiesEndpoint|testActivitiesWithProject"</automated>
+  </verify>
+  <acceptance_criteria>
+    - Controller/HeatmapController.php contains `$mode = $request->query->getString('mode', 'daily')`
+    - Controller/HeatmapController.php contains `return match ($mode)`
+    - Controller/HeatmapController.php contains `'hourly' => new JsonResponse`
+    - Controller/HeatmapController.php contains `'dayhour' => new JsonResponse`
+    - Controller/HeatmapController.php contains `$request->query->getInt('customer')`
+    - Controller/HeatmapController.php contains `$request->query->getInt('activity')`
+    - Controller/HeatmapController.php contains `public function customers(`
+    - Controller/HeatmapController.php contains `public function projects(`
+    - Controller/HeatmapController.php contains `public function activities(`
+    - Controller/HeatmapController.php contains `#[Route(path: '/customers'`
+    - Controller/HeatmapController.php contains `#[Route(path: '/projects'`
+    - Controller/HeatmapController.php contains `#[Route(path: '/activities'`
+    - All 4 actions have `#[IsGranted('view_own_timesheet')]`
+    - Tests/Controller/HeatmapControllerTest.php contains `testDataReturnsHourlyMode`
+    - Tests/Controller/HeatmapControllerTest.php contains `testDataReturnsDayHourMode`
+    - Tests/Controller/HeatmapControllerTest.php contains `testCustomersEndpoint`
+    - Tests/Controller/HeatmapControllerTest.php contains `testActivitiesEndpoint`
+    - PHPUnit exits 0 for all controller tests
+  </acceptance_criteria>
+  <done>Controller dispatches by mode, passes filters, serves cascade endpoints, all tests green</done>
+</task>
+
+<task type="auto">
+  <name>Task 2: Add TypeScript types for new API response shapes</name>
+  <files>assets/src/types.ts</files>
+  <read_first>
+    - assets/src/types.ts (current types)
+    - .planning/phases/08-backend-aggregation-filtering/08-UI-SPEC.md (TypeScript Type Extensions section)
+  </read_first>
+  <action>
+Add the following interfaces to `assets/src/types.ts` after the existing `HeatmapData` interface, per the UI-SPEC contract:
+
+```typescript
+export interface HourEntry {
+  hour: number;   // 0-23
+  hours: number;
+  count: number;
+}
+
+export interface DayHourEntry {
+  day: number;    // 0-6, relative to weekStart
+  hour: number;   // 0-23
+  hours: number;
+  count: number;
+}
+
+export interface HourlyData {
+  hours: HourEntry[];
+  range: { begin: string; end: string };
+}
+
+export interface DayHourData {
+  matrix: DayHourEntry[];
+  range: { begin: string; end: string };
+}
+```
+
+These types are consumed by Phase 9 renderers. They match the JSON response contracts from the controller (mode=hourly returns HourlyData, mode=dayhour returns DayHourData).
+  </action>
+  <verify>
+    <automated>cd /home/toph/code/toph/kimai-heatmap && npx tsc --noEmit --project assets/tsconfig.json 2>&1 || echo "TS check done"</automated>
+  </verify>
+  <acceptance_criteria>
+    - assets/src/types.ts contains `export interface HourEntry`
+    - assets/src/types.ts contains `export interface DayHourEntry`
+    - assets/src/types.ts contains `export interface HourlyData`
+    - assets/src/types.ts contains `export interface DayHourData`
+    - assets/src/types.ts contains `hours: HourEntry[]`
+    - assets/src/types.ts contains `matrix: DayHourEntry[]`
+    - TypeScript compilation passes without errors (or no tsconfig exists, which is fine)
+  </acceptance_criteria>
+  <done>TypeScript types for hourly and day/hour API responses exist in types.ts</done>
+</task>
+
+</tasks>
+
+<threat_model>
+## Trust Boundaries
+
+| Boundary | Description |
+|----------|-------------|
+| HTTP query params -> Controller | mode, project, customer, activity params are untrusted |
+| Controller -> Service | Integer IDs type-cast via getInt(), mode validated via match() default |
+
+## STRIDE Threat Register
+
+| Threat ID | Category | Component | Disposition | Mitigation Plan |
+|-----------|----------|-----------|-------------|-----------------|
+| T-08-04 | Tampering | mode query param | mitigate | `match($mode)` with `default` case falls through to daily — invalid modes cannot reach aggregation queries |
+| T-08-05 | Tampering | filter ID params | mitigate | `$request->query->getInt()` returns 0 for non-integer input, converted to null via `?: null` — no string injection possible |
+| T-08-06 | Elevation of Privilege | cascade endpoints | mitigate | All endpoints have `#[IsGranted('view_own_timesheet')]` + queries scoped to `t.user = :user` |
+| T-08-07 | Information Disclosure | cascade entity lists | mitigate | getUserCustomers/Activities/Projects all filter by user's own timesheets — cannot enumerate other users' entities |
+</threat_model>
+
+<verification>
+- `php dev/kimai/vendor/bin/phpunit --configuration Tests/phpunit.xml` exits 0 (full suite)
+- Controller has 4 public action methods: data, customers, projects, activities
+- All routes use `#[IsGranted('view_own_timesheet')]`
+- All query params use type-safe `getInt()` or `getString()`
+- TypeScript types compile without errors
+</verification>
+
+<success_criteria>
+- mode=hourly returns `{hours: [...], range: {...}}` per D-02, D-06
+- mode=dayhour returns `{matrix: [...], range: {...}}` per D-02, D-07
+- Default mode returns existing daily format (backward compatible)
+- activity and customer params passed through to service per D-03
+- Cascade endpoints return `[{id, name}]` per D-04, D-05
+- TypeScript types match API response contracts per D-09
+- All PHPUnit tests pass
+</success_criteria>
+
+<output>
+After completion, create `.planning/phases/08-backend-aggregation-filtering/08-02-SUMMARY.md`
+</output>

.planning/phases/08-backend-aggregation-filtering/08-02-SUMMARY.md

@@ -0,0 +1,112 @@
+---
+phase: 08-backend-aggregation-filtering
+plan: 02
+subsystem: api
+tags: [symfony, controller, php, typescript, rest-api]
+
+requires:
+  - phase: 08-backend-aggregation-filtering-01
+    provides: "HeatmapService with hourly, day/hour aggregation and entity list methods"
+provides:
+  - "Controller mode dispatch (daily/hourly/dayhour) with filter params"
+  - "Cascade endpoints: /customers, /projects, /activities"
+  - "TypeScript types for HourlyData and DayHourData response shapes"
+affects: [09-renderer-modes, 10-entity-pickers]
+
+tech-stack:
+  added: []
+  patterns: ["match() dispatch for API mode selection", "cascade entity endpoints for picker data"]
+
+key-files:
+  created: []
+  modified:
+    - Controller/HeatmapController.php
+    - Service/HeatmapService.php
+    - Tests/Controller/HeatmapControllerTest.php
+    - assets/src/types.ts
+
+key-decisions:
+  - "Extended getUserProjects with optional customerId param for cascade filtering"
+
+patterns-established:
+  - "Mode dispatch via match() on query string param with safe default"
+  - "Filter params use getInt() with ?: null for type-safe nullable integers"
+
+requirements-completed: [API-01, API-02, FILT-02, FILT-03, TEST-03]
+
+duration: 4min
+completed: 2026-04-09
+---
+
+# Phase 8 Plan 02: Controller Mode Dispatch & Cascade Endpoints Summary
+
+**Controller mode dispatch (daily/hourly/dayhour), filter param passthrough, and cascade entity endpoints for customer/project/activity pickers**
+
+## Performance
+
+- **Duration:** 4 min
+- **Started:** 2026-04-09T19:41:25Z
+- **Completed:** 2026-04-09T19:45:20Z
+- **Tasks:** 2
+- **Files modified:** 4
+
+## Accomplishments
+- Extended data() action with mode dispatch (daily/hourly/dayhour) via match() expression
+- Added customer, activity filter params alongside existing project filter
+- Added cascade endpoints: /customers, /projects (with customer filter), /activities (with project filter)
+- Added TypeScript types HourEntry, DayHourEntry, HourlyData, DayHourData matching API contracts
+- 9 controller tests all passing (21 total suite)
+
+## Task Commits
+
+Each task was committed atomically:
+
+1. **Task 1: Extend HeatmapController with mode dispatch and cascade endpoints**
+   - `86e7d5f` (test: failing tests for mode dispatch and cascade endpoints)
+   - `f8b22da` (feat: mode dispatch, filter params, and cascade endpoints)
+2. **Task 2: Add TypeScript types for new API response shapes** - `0691567` (feat)
+
+## Files Created/Modified
+- `Controller/HeatmapController.php` - Mode dispatch, filter params, 3 new cascade actions
+- `Service/HeatmapService.php` - Extended getUserProjects with optional customerId param
+- `Tests/Controller/HeatmapControllerTest.php` - 8 new tests for mode dispatch and cascade endpoints
+- `assets/src/types.ts` - HourEntry, DayHourEntry, HourlyData, DayHourData interfaces
+
+## Decisions Made
+- Extended getUserProjects(User, ?int customerId) rather than adding a separate method -- keeps cascade filtering consistent with how getUserActivities already accepts projectId
+
+## Deviations from Plan
+
+### Auto-fixed Issues
+
+**1. [Rule 3 - Blocking] Extended getUserProjects with optional customerId parameter**
+- **Found during:** Task 1 (controller projects() endpoint)
+- **Issue:** Plan's projects() action passes customerId to getUserProjects, but service method only accepted User
+- **Fix:** Added optional `?int $customerId = null` param with customer join/filter when non-null
+- **Files modified:** Service/HeatmapService.php
+- **Verification:** Full test suite passes (21 tests, 56 assertions)
+- **Committed in:** f8b22da (Task 1 commit)
+
+---
+
+**Total deviations:** 1 auto-fixed (1 blocking)
+**Impact on plan:** Necessary service extension to support cascade project filtering. No scope creep.
+
+## Issues Encountered
+None
+
+## User Setup Required
+None - no external service configuration required.
+
+## Next Phase Readiness
+- All mode dispatch and cascade endpoints ready for Phase 9 renderer consumption
+- TypeScript types ready for Phase 9 frontend integration
+- Phase 10 entity pickers can consume /customers, /projects, /activities endpoints
+
+## Self-Check: PASSED
+
+All 4 files verified present. All 3 commits verified in history. All acceptance criteria spot checks passed.
+
+---
+*Phase: 08-backend-aggregation-filtering*
+*Completed: 2026-04-09*

.planning/phases/08-backend-aggregation-filtering/08-CONTEXT.md

@@ -0,0 +1,94 @@
+# Phase 8: Backend Aggregation + Filtering - Context
+
+**Gathered:** 2026-04-09
+**Status:** Ready for planning
+
+<domain>
+## Phase Boundary
+
+Backend serves hour-level and day/hour aggregation data for day-mode and combined-mode renderers (Phase 9), plus activity and customer filter params on the existing data endpoint, and cascade entity endpoints for the TomSelect pickers (Phase 10). No frontend rendering changes — this phase builds the data layer.
+
+</domain>
+
+<decisions>
+## Implementation Decisions
+
+### Claude's Discretion
+User deferred all decisions to Claude. The following defaults are based on existing codebase patterns:
+
+- **D-01:** Extend `HeatmapService` with `getHourlyAggregation()` and `getDayHourAggregation()` methods alongside the existing `getDailyAggregation()` — separate methods, not one flexible method, matching the existing service pattern
+- **D-02:** Extend the existing `/heatmap/data` endpoint with optional `mode` query param (`daily` default, `hourly`, `dayhour`) rather than separate endpoints per mode — keeps frontend fetch logic simple (one URL, add `?mode=X`)
+- **D-03:** Add `activity` and `customer` query params to the existing `/heatmap/data` endpoint — additive AND logic with existing `project` filter. Customer filter queries all projects under that customer.
+- **D-04:** Cascade endpoints: `/heatmap/customers`, `/heatmap/projects?customer={id}`, `/heatmap/activities?project={id}` — session auth (same as existing), scoped to user's own entities (timesheets they've created)
+- **D-05:** Cascade endpoint response format: `[{id: number, name: string}]` — matches existing `getUserProjects()` return shape
+- **D-06:** Hourly aggregation returns `{hour: number (0-23), hours: float, count: int}` — groups by hour-of-day across entire date range
+- **D-07:** Day/hour aggregation returns `{day: number (0-6), hour: number (0-23), hours: float, count: int}` — 7x24 matrix data, day index relative to weekStart
+- **D-08:** Timezone handling: use Kimai's user timezone setting (available via `$user->getTimezone()`) for hour grouping — entries are stored UTC, grouping must respect user's local time
+- **D-09:** Frontend extends the existing fetch call with mode/filter params — no new fetch functions, just URL parameter construction
+
+</decisions>
+
+<canonical_refs>
+## Canonical References
+
+**Downstream agents MUST read these before planning or implementing.**
+
+### Existing Backend
+- `Controller/HeatmapController.php` — Current `/heatmap/data` endpoint with project filter
+- `Service/HeatmapService.php` — `getDailyAggregation()` and `getUserProjects()` query patterns
+- `Tests/Controller/HeatmapControllerTest.php` — Existing controller test pattern with mock service
+
+### Renderer Architecture (for understanding data consumers)
+- `assets/src/types.ts` — HeatmapData, DayEntry types that backend produces
+- `assets/src/heatmap.ts` — Frontend fetch and state management
+
+### Requirements
+- `.planning/REQUIREMENTS.md` — API-01 (mode param), API-02 (filter params), FILT-02 (activity filter), FILT-03 (customer filter), TEST-03 (PHPUnit tests)
+
+### Kimai Internals
+- Kimai's `TimesheetRepository` — base for all queries (injected into HeatmapService)
+- Kimai's entity relationships: Timesheet → Project → Customer, Timesheet → Activity
+- `App\Entity\User::getTimezone()` — user timezone for hour grouping
+
+</canonical_refs>
+
+<code_context>
+## Existing Code Insights
+
+### Reusable Assets
+- `HeatmapService`: extend with new aggregation methods — same QueryBuilder pattern
+- `HeatmapController`: extend with new action methods and filter params
+- `getUserProjects()`: reference for cascade endpoint response shape
+- Existing test pattern: mock service, mock user via container/tokenStorage
+
+### Established Patterns
+- Symfony route attributes (`#[Route]`, `#[IsGranted]`)
+- QueryBuilder with parameter binding for SQL injection safety
+- JSON response with simple array structure
+- Session auth via `IS_AUTHENTICATED_REMEMBERED` (not API auth)
+
+### Integration Points
+- New controller actions register automatically via Symfony routing
+- Frontend fetch adds query params to existing `data-url` base URL
+- Cascade endpoints consumed by TomSelect pickers in Phase 10
+
+</code_context>
+
+<specifics>
+## Specific Ideas
+
+No specific requirements — open to standard approaches
+
+</specifics>
+
+<deferred>
+## Deferred Ideas
+
+None — discussion stayed within phase scope
+
+</deferred>
+
+---
+
+*Phase: 08-backend-aggregation-filtering*
+*Context gathered: 2026-04-09*

.planning/phases/08-backend-aggregation-filtering/08-DISCUSSION-LOG.md

@@ -0,0 +1,34 @@
+# Phase 8: Backend Aggregation + Filtering - Discussion Log
+
+> **Audit trail only.** Do not use as input to planning, research, or execution agents.
+> Decisions are captured in CONTEXT.md — this log preserves the alternatives considered.
+
+**Date:** 2026-04-09
+**Phase:** 08-backend-aggregation-filtering
+**Areas discussed:** None (user deferred all to Claude's discretion)
+
+---
+
+## Gray Areas Presented
+
+| Area | Description | Selected |
+|------|-------------|----------|
+| Aggregation query design | Query structure, timezone handling | |
+| Filter param handling | Activity + customer filter integration | |
+| Cascade endpoints | Entity list endpoints shape and scoping | |
+| Frontend data flow | Fetch URL extension vs separate endpoints | |
+
+**User's choice:** "Nothing" — deferred all areas to Claude's discretion
+**Notes:** All decisions made by Claude based on existing codebase patterns (HeatmapService, HeatmapController)
+
+## Claude's Discretion
+
+All 4 areas deferred. Decisions D-01 through D-09 in CONTEXT.md are Claude's defaults based on:
+- Existing `getDailyAggregation()` query pattern
+- Existing controller route/auth pattern
+- Existing `getUserProjects()` response shape
+- Requirements constraints (session auth, own endpoints)
+
+## Deferred Ideas
+
+None

.planning/phases/08-backend-aggregation-filtering/08-RESEARCH.md

@@ -0,0 +1,443 @@
+# Phase 8: Backend Aggregation + Filtering - Research
+
+**Researched:** 2026-04-09
+**Domain:** Symfony/Doctrine PHP backend, SQL aggregation, timezone handling
+**Confidence:** HIGH
+
+## Summary
+
+Phase 8 extends the existing `HeatmapService` and `HeatmapController` with two new aggregation modes (hourly, day/hour) and three filter parameters (activity, customer, plus existing project). It also adds three cascade entity endpoints for the Phase 10 TomSelect pickers. All changes are backend PHP + PHPUnit tests with minimal frontend touch (URL parameter construction only).
+
+The critical technical challenge is **timezone-correct hour extraction**. Kimai stores `start_time` in UTC but users operate in local timezones. MariaDB's `CONVERT_TZ` with numeric offsets (e.g., `'+02:00'`) is the most reliable approach -- it does not depend on MySQL timezone tables being loaded. The `date_tz` column (already in user timezone) can be used for day-of-week grouping.
+
+**Primary recommendation:** Use native SQL queries (via DBAL Connection) for the hourly and day/hour aggregations since Kimai only registers DATE/DAY/MONTH/YEAR as custom DQL functions -- there is no HOUR function. Keep the existing DQL QueryBuilder pattern for the daily aggregation and cascade endpoints.
+
+<user_constraints>
+## User Constraints (from CONTEXT.md)
+
+### Locked Decisions
+No locked decisions -- user deferred all to Claude's discretion.
+
+### Claude's Discretion
+- D-01: Extend HeatmapService with separate getHourlyAggregation() and getDayHourAggregation() methods
+- D-02: Extend existing /heatmap/data endpoint with optional mode query param (daily/hourly/dayhour)
+- D-03: Add activity and customer query params to /heatmap/data endpoint with AND logic
+- D-04: Cascade endpoints: /heatmap/customers, /heatmap/projects?customer={id}, /heatmap/activities?project={id}
+- D-05: Cascade response format: [{id: number, name: string}]
+- D-06: Hourly aggregation returns {hour: 0-23, hours: float, count: int}
+- D-07: Day/hour aggregation returns {day: 0-6, hour: 0-23, hours: float, count: int}
+- D-08: Use Kimai user timezone for hour grouping
+- D-09: Frontend extends existing fetch with mode/filter params
+
+### Deferred Ideas (OUT OF SCOPE)
+None.
+</user_constraints>
+
+<phase_requirements>
+## Phase Requirements
+
+| ID | Description | Research Support |
+|----|-------------|------------------|
+| API-01 | API endpoint accepts mode param returning hour-level and day/hour aggregation data | New service methods + mode param dispatch in controller (see Architecture Patterns) |
+| API-02 | API endpoint accepts activity and customer filter params with own controller endpoints | Filter params on /heatmap/data + 3 cascade endpoints (see Cascade Endpoints pattern) |
+| FILT-02 | Activity filtering narrows heatmap data to a specific activity | QueryBuilder WHERE on t.activity (see Filter Implementation pattern) |
+| FILT-03 | Customer filtering narrows heatmap data to all projects under a customer | JOIN through t.project -> p.customer (see Filter Implementation pattern) |
+| TEST-03 | PHPUnit tests for hour-level and day/hour aggregation queries | Extend existing mock pattern from HeatmapServiceTest (see Validation Architecture) |
+</phase_requirements>
+
+## Architecture Patterns
+
+### Recommended Changes Structure
+
+```
+Controller/HeatmapController.php   # extend with mode dispatch + cascade actions
+Service/HeatmapService.php         # add 3 new methods + extend existing with filters
+Tests/Controller/HeatmapControllerTest.php  # extend with new action tests
+Tests/Service/HeatmapServiceTest.php        # extend with new method tests
+assets/src/types.ts                 # add HourEntry, DayHourEntry, HourlyData, DayHourData types
+```
+
+### Pattern 1: Mode Dispatch in Controller
+
+**What:** The existing `data()` action reads a `mode` query param and dispatches to the appropriate service method. [VERIFIED: existing controller code]
+
+**Example:**
+```php
+// Source: extending existing HeatmapController.php
+#[Route(path: '/data', name: 'heatmap_data', methods: ['GET'])]
+#[IsGranted('view_own_timesheet')]
+public function data(Request $request, HeatmapService $service): JsonResponse
+{
+    $user = $this->getUser();
+    $end = new \DateTimeImmutable('today');
+    $begin = $end->modify('-1 year');
+
+    $mode = $request->query->getString('mode', 'daily');
+    $projectId = $request->query->getInt('project') ?: null;
+    $customerId = $request->query->getInt('customer') ?: null;
+    $activityId = $request->query->getInt('activity') ?: null;
+
+    return match ($mode) {
+        'hourly' => new JsonResponse([
+            'hours' => $service->getHourlyAggregation($user, $begin, $end, $projectId, $customerId, $activityId),
+            'range' => ['begin' => $begin->format('Y-m-d'), 'end' => $end->format('Y-m-d')],
+        ]),
+        'dayhour' => new JsonResponse([
+            'matrix' => $service->getDayHourAggregation($user, $begin, $end, $projectId, $customerId, $activityId),
+            'range' => ['begin' => $begin->format('Y-m-d'), 'end' => $end->format('Y-m-d')],
+        ]),
+        default => new JsonResponse([
+            'days' => $service->getDailyAggregation($user, $begin, $end, $projectId, $customerId, $activityId),
+            'range' => ['begin' => $begin->format('Y-m-d'), 'end' => $end->format('Y-m-d')],
+        ]),
+    };
+}
+```
+
+### Pattern 2: Timezone-Correct Hour Extraction via Native SQL
+
+**What:** Use DBAL native SQL with `CONVERT_TZ` for hour grouping since Kimai has no HOUR DQL function registered. [VERIFIED: doctrine.yaml only registers DATE/DAY/MONTH/YEAR]
+
+**Why native SQL:** Kimai's custom DQL functions (in `App\Doctrine\Extensions\`) only cover DATE, DAY, MONTH, YEAR. Adding a plugin-level DQL function would require modifying Kimai's Doctrine config, which plugins should not do. Native SQL via DBAL Connection is clean and explicit.
+
+**Critical timezone detail:** `start_time` is stored in UTC. Each timesheet has a `timezone` column. The user's current timezone is available via `$user->getTimezone()`. We compute a numeric offset string (e.g., `'+02:00'`) from the user timezone and use `CONVERT_TZ(t.start_time, '+00:00', :tz_offset)`. This avoids requiring MySQL timezone tables. [VERIFIED: UTCDateTimeType.php confirms UTC storage; Timesheet entity confirms timezone column]
+
+**Example:**
+```php
+// Source: pattern derived from existing codebase analysis
+public function getHourlyAggregation(User $user, \DateTimeInterface $begin, \DateTimeInterface $end, ?int $projectId = null, ?int $customerId = null, ?int $activityId = null): array
+{
+    $tz = new \DateTimeZone($user->getTimezone());
+    $offset = $tz->getOffset(new \DateTime('now', $tz));
+    $offsetStr = sprintf('%+03d:%02d', intdiv($offset, 3600), abs($offset % 3600) / 60);
+
+    $conn = $this->repository->getEntityManager()->getConnection();
+    $sql = 'SELECT HOUR(CONVERT_TZ(t.start_time, \'+00:00\', :tz)) as hour_slot,
+                   COALESCE(SUM(t.duration), 0) as duration,
+                   COUNT(t.id) as count
+            FROM kimai2_timesheet t
+            WHERE t.user = :user
+              AND t.date_tz BETWEEN :begin AND :end
+              AND t.end_time IS NOT NULL';
+
+    $params = [
+        'tz' => $offsetStr,
+        'user' => $user->getId(),
+        'begin' => $begin->format('Y-m-d'),
+        'end' => $end->format('Y-m-d'),
+    ];
+
+    // append optional filters...
+    // $sql .= ' GROUP BY hour_slot ORDER BY hour_slot ASC';
+
+    $results = $conn->executeQuery($sql, $params)->fetchAllAssociative();
+    // map to response format
+}
+```
+
+**Offset caveat:** A single offset computed at request time is correct for users in fixed-offset timezones. For DST timezones, entries created during summer will be off by 1 hour when viewed in winter (and vice versa). This is an acceptable tradeoff for an aggregation heatmap -- Kimai's own `date_tz` column has the same limitation (stores the date at creation time, not retroactively adjusted). [ASSUMED]
+
+### Pattern 3: Filter Implementation
+
+**What:** Activity and customer filters are additive WHERE clauses on all aggregation queries. [VERIFIED: existing project filter pattern in HeatmapService]
+
+**Customer filter requires a JOIN** since timesheets reference projects, and projects reference customers:
+```sql
+-- Activity filter (direct relation)
+AND t.activity_id = :activity
+
+-- Customer filter (through project)
+INNER JOIN kimai2_projects p ON t.project_id = p.id
+AND p.customer_id = :customer
+```
+
+For DQL (daily aggregation extending existing QueryBuilder):
+```php
+if ($activityId !== null) {
+    $qb->andWhere($qb->expr()->eq('t.activity', ':activity'))
+       ->setParameter('activity', $activityId);
+}
+if ($customerId !== null) {
+    $qb->join('t.project', 'p')
+       ->andWhere($qb->expr()->eq('p.customer', ':customer'))
+       ->setParameter('customer', $customerId);
+}
+```
+
+### Pattern 4: Cascade Entity Endpoints
+
+**What:** Three new controller actions returning entity lists scoped to user's own timesheets. [VERIFIED: getUserProjects() pattern in HeatmapService]
+
+```php
+#[Route(path: '/customers', name: 'heatmap_customers', methods: ['GET'])]
+#[IsGranted('view_own_timesheet')]
+public function customers(HeatmapService $service): JsonResponse
+{
+    return new JsonResponse($service->getUserCustomers($this->getUser()));
+}
+```
+
+Service methods follow the existing `getUserProjects()` pattern -- query timesheets, join to related entity, select distinct, return `[{id, name}]`.
+
+### Pattern 5: Day/Hour Aggregation with weekStart
+
+**What:** The day/hour (punchcard) mode groups by day-of-week AND hour-of-day. Day index is relative to user's `weekStart` preference.
+
+**Day-of-week from `date_tz`:** Since `date_tz` already stores the date in user timezone, `DAYOFWEEK(date_tz)` gives the correct day. MySQL's DAYOFWEEK returns 1=Sunday through 7=Saturday. We need to remap to 0-6 relative to weekStart in PHP. [VERIFIED: Timesheet entity doc comment confirms date_tz is in user timezone]
+
+```sql
+SELECT DAYOFWEEK(t.date_tz) as dow,
+       HOUR(CONVERT_TZ(t.start_time, '+00:00', :tz)) as hour_slot,
+       COALESCE(SUM(t.duration), 0) as duration,
+       COUNT(t.id) as count
+FROM kimai2_timesheet t
+WHERE ...
+GROUP BY dow, hour_slot
+ORDER BY dow, hour_slot
+```
+
+Then in PHP, remap MySQL's DAYOFWEEK (1=Sun,2=Mon,...,7=Sat) to 0-6 relative to weekStart:
+```php
+// MySQL DAYOFWEEK: 1=Sun, 2=Mon, ... 7=Sat
+// If weekStart=monday: Mon=0, Tue=1, ..., Sun=6
+// If weekStart=sunday: Sun=0, Mon=1, ..., Sat=6
+$weekStartOffset = ($weekStart === 'sunday') ? 1 : 2;
+$dayIndex = ($mysqlDow - $weekStartOffset + 7) % 7;
+```
+
+### Anti-Patterns to Avoid
+
+- **Registering custom DQL functions from a plugin:** Plugins should not modify Kimai's Doctrine configuration. Use native SQL instead. [VERIFIED: plugin architecture does not support custom DQL registration]
+- **Using `CONVERT_TZ` with named timezones:** Requires MySQL `mysql.time_zone_name` table to be populated (often empty in Docker/dev setups). Use numeric offsets only. [ASSUMED]
+- **Ignoring the `end IS NOT NULL` filter:** Running timesheets have no duration. Existing code correctly filters these. New queries must too. [VERIFIED: existing service code]
+
+## Don't Hand-Roll
+
+| Problem | Don't Build | Use Instead | Why |
+|---------|-------------|-------------|-----|
+| Timezone offset calculation | Manual hour math | PHP DateTimeZone::getOffset() | Handles DST transitions correctly |
+| Day-of-week calculation | PHP date() on each row | MySQL DAYOFWEEK() on date_tz | Database-side grouping is faster |
+| SQL injection protection | String concatenation | Parameterized queries (DBAL params) | Standard security practice |
+| JSON serialization | Manual json_encode | Symfony JsonResponse | Handles encoding, content-type headers |
+
+## Common Pitfalls
+
+### Pitfall 1: CONVERT_TZ Returns NULL
+**What goes wrong:** `CONVERT_TZ` returns NULL when using named timezones (e.g., 'Europe/Berlin') and MySQL timezone tables are not loaded.
+**Why it happens:** MariaDB/MySQL ship with empty timezone tables by default. Named timezone lookups fail silently.
+**How to avoid:** Always use numeric offset format (`'+02:00'`), never named timezones.
+**Warning signs:** Aggregation returns zero/empty results when data exists. [ASSUMED]
+
+### Pitfall 2: DST Offset Mismatch
+**What goes wrong:** A single offset computed at request time doesn't match offsets at the time entries were created. Summer entries shift by 1 hour when viewed in winter.
+**Why it happens:** Timezones with DST have different UTC offsets at different times of year.
+**How to avoid:** For a heatmap aggregation, this 1-hour shift is acceptable. If precision is needed later, each timesheet's own `timezone` column could be used per-row (expensive).
+**Warning signs:** Hour bins near DST transitions show unexpected clustering. [ASSUMED]
+
+### Pitfall 3: Table Name Mismatch
+**What goes wrong:** Native SQL uses actual database table names, not Doctrine entity names.
+**Why it happens:** DQL uses entity names (`Timesheet`, `Project`), but raw SQL needs table names (`kimai2_timesheet`, `kimai2_projects`).
+**How to avoid:** Check the `@ORM\Table` annotation or use `$em->getClassMetadata(Timesheet::class)->getTableName()` to resolve dynamically.
+**Warning signs:** "Table doesn't exist" SQL errors. [VERIFIED: Timesheet entity uses kimai2_timesheet table]
+
+### Pitfall 4: Customer Filter Without Project Join
+**What goes wrong:** Trying to filter by customer directly on the timesheet table fails -- there is no customer_id column on kimai2_timesheet.
+**Why it happens:** Kimai's entity model is Timesheet -> Project -> Customer (no direct Timesheet -> Customer relation).
+**How to avoid:** Always JOIN kimai2_projects when filtering by customer.
+**Warning signs:** SQL column not found error. [VERIFIED: Timesheet entity has project and activity relations only]
+
+### Pitfall 5: Missing Query Builder Methods in Mock
+**What goes wrong:** PHPUnit tests fail because the mock QueryBuilder doesn't stub new chained methods (e.g., `join()`).
+**Why it happens:** Existing test helper `createServiceWithResults()` stubs a fixed set of QB methods. New filter logic adds `join()`.
+**How to avoid:** Add `$qb->method('join')->willReturnSelf()` to the test helper. For native SQL tests, mock the DBAL Connection instead.
+**Warning signs:** "Call to undefined method" in test output. [VERIFIED: existing test mock pattern]
+
+## Code Examples
+
+### Native SQL Query with DBAL Connection
+
+```php
+// Source: Doctrine DBAL pattern [VERIFIED: TimesheetRepository uses getEntityManager()]
+$conn = $this->repository->getEntityManager()->getConnection();
+$result = $conn->executeQuery($sql, $params);
+$rows = $result->fetchAllAssociative();
+```
+
+### Timezone Offset from User
+
+```php
+// Source: PHP DateTimeZone API [VERIFIED: User::getTimezone() returns timezone string]
+$tz = new \DateTimeZone($user->getTimezone());
+$offset = $tz->getOffset(new \DateTime('now', new \DateTimeZone('UTC')));
+$hours = intdiv($offset, 3600);
+$minutes = abs(intdiv($offset % 3600, 60));
+$offsetStr = sprintf('%+03d:%02d', $hours, $minutes);
+// e.g., "Europe/Berlin" in summer -> "+02:00"
+```
+
+### Cascade Query (getUserCustomers example)
+
+```php
+// Source: extending existing getUserProjects() pattern [VERIFIED: HeatmapService.php]
+public function getUserCustomers(User $user): array
+{
+    $qb = $this->repository->createQueryBuilder('t');
+    $qb->select('DISTINCT IDENTITY(p.customer) as customerId, c.name')
+       ->join('t.project', 'p')
+       ->join('p.customer', 'c')
+       ->andWhere($qb->expr()->eq('t.user', ':user'))
+       ->andWhere($qb->expr()->isNotNull('t.end'))
+       ->setParameter('user', $user)
+       ->orderBy('c.name', 'ASC');
+
+    return array_map(fn(array $row) => [
+        'id' => (int) $row['customerId'],
+        'name' => $row['name'],
+    ], $qb->getQuery()->getResult());
+}
+```
+
+### getUserActivities with Optional Project Scope
+
+```php
+// Source: extending getUserProjects() pattern [VERIFIED: HeatmapService.php]
+public function getUserActivities(User $user, ?int $projectId = null): array
+{
+    $qb = $this->repository->createQueryBuilder('t');
+    $qb->select('DISTINCT IDENTITY(t.activity) as activityId, a.name')
+       ->join('t.activity', 'a')
+       ->andWhere($qb->expr()->eq('t.user', ':user'))
+       ->andWhere($qb->expr()->isNotNull('t.end'))
+       ->setParameter('user', $user)
+       ->orderBy('a.name', 'ASC');
+
+    if ($projectId !== null) {
+        $qb->andWhere($qb->expr()->eq('t.project', ':project'))
+           ->setParameter('project', $projectId);
+    }
+
+    return array_map(fn(array $row) => [
+        'id' => (int) $row['activityId'],
+        'name' => $row['name'],
+    ], $qb->getQuery()->getResult());
+}
+```
+
+### Testing Native SQL with Mocked Connection
+
+```php
+// Source: PHPUnit mock pattern for DBAL [ASSUMED]
+private function createServiceWithNativeResults(array $results): HeatmapService
+{
+    // For native SQL methods, mock the DBAL connection
+    $statement = $this->createMock(\Doctrine\DBAL\Result::class);
+    $statement->method('fetchAllAssociative')->willReturn($results);
+
+    $connection = $this->createMock(\Doctrine\DBAL\Connection::class);
+    $connection->method('executeQuery')->willReturn($statement);
+
+    $em = $this->createMock(\Doctrine\ORM\EntityManagerInterface::class);
+    $em->method('getConnection')->willReturn($connection);
+
+    $repo = $this->createMock(TimesheetRepository::class);
+    $repo->method('getEntityManager')->willReturn($em);
+    // Also set up createQueryBuilder for DQL methods
+    // ...
+
+    return new HeatmapService($repo);
+}
+```
+
+## Validation Architecture
+
+### Test Framework
+| Property | Value |
+|----------|-------|
+| Framework | PHPUnit 10.5 |
+| Config file | `Tests/phpunit.xml` |
+| Quick run command | `php dev/kimai/vendor/bin/phpunit --configuration Tests/phpunit.xml` |
+| Full suite command | `php dev/kimai/vendor/bin/phpunit --configuration Tests/phpunit.xml` |
+
+### Phase Requirements -> Test Map
+| Req ID | Behavior | Test Type | Automated Command | File Exists? |
+|--------|----------|-----------|-------------------|-------------|
+| API-01 | Mode param dispatches to correct service method | unit | `php dev/kimai/vendor/bin/phpunit --configuration Tests/phpunit.xml --filter testDataReturnsHourly` | Wave 0 |
+| API-01 | Hourly aggregation groups by hour, returns correct shape | unit | `php dev/kimai/vendor/bin/phpunit --configuration Tests/phpunit.xml --filter testGetHourlyAggregation` | Wave 0 |
+| API-01 | Day/hour aggregation groups by day+hour, returns correct shape | unit | `php dev/kimai/vendor/bin/phpunit --configuration Tests/phpunit.xml --filter testGetDayHourAggregation` | Wave 0 |
+| API-02 | Activity filter param narrows results | unit | `php dev/kimai/vendor/bin/phpunit --configuration Tests/phpunit.xml --filter testActivityFilter` | Wave 0 |
+| API-02 | Customer filter param narrows results via project join | unit | `php dev/kimai/vendor/bin/phpunit --configuration Tests/phpunit.xml --filter testCustomerFilter` | Wave 0 |
+| API-02 | Cascade endpoints return entity lists | unit | `php dev/kimai/vendor/bin/phpunit --configuration Tests/phpunit.xml --filter testCustomersEndpoint` | Wave 0 |
+| FILT-02 | Activity filter applied to all aggregation modes | unit | covered by API-02 activity filter tests | Wave 0 |
+| FILT-03 | Customer filter applied to all aggregation modes | unit | covered by API-02 customer filter tests | Wave 0 |
+| TEST-03 | PHPUnit tests for aggregation queries | unit | full suite command | Wave 0 |
+
+### Sampling Rate
+- **Per task commit:** `php dev/kimai/vendor/bin/phpunit --configuration Tests/phpunit.xml`
+- **Per wave merge:** same (single test suite)
+- **Phase gate:** Full suite green before `/gsd-verify-work`
+
+### Wave 0 Gaps
+None -- existing test infrastructure (`Tests/phpunit.xml`, `Tests/bootstrap.php`, mock helpers in `HeatmapServiceTest.php`) covers all needs. New test methods extend existing test classes.
+
+## Security Domain
+
+### Applicable ASVS Categories
+
+| ASVS Category | Applies | Standard Control |
+|---------------|---------|-----------------|
+| V2 Authentication | no | Handled by Kimai (session auth) |
+| V3 Session Management | no | Handled by Kimai |
+| V4 Access Control | yes | `#[IsGranted('view_own_timesheet')]` + user-scoped queries |
+| V5 Input Validation | yes | Query param type casting (`getInt()`, `getString()`) + parameterized SQL |
+| V6 Cryptography | no | No crypto in this phase |
+
+### Known Threat Patterns
+
+| Pattern | STRIDE | Standard Mitigation |
+|---------|--------|---------------------|
+| SQL injection via filter params | Tampering | Parameterized queries (DBAL params for native SQL, QueryBuilder setParameter for DQL) |
+| IDOR on customer/project/activity IDs | Information Disclosure | All queries scoped to `t.user = :user` -- user can only see their own entities |
+| Mode param injection | Tampering | `match()` with `default` case prevents invalid modes from reaching queries |
+
+## Assumptions Log
+
+| # | Claim | Section | Risk if Wrong |
+|---|-------|---------|---------------|
+| A1 | CONVERT_TZ with numeric offsets works without timezone tables loaded | Pitfall 1 | Hour grouping returns NULL; fallback would be PHP-side processing |
+| A2 | Single offset for DST timezones is acceptable for heatmap aggregation | Pitfall 2 | 1-hour shift in some entries; low visual impact |
+| A3 | DBAL Result::fetchAllAssociative() is mockable in PHPUnit | Code Examples | Tests need different mock approach if class is final |
+
+## Open Questions
+
+1. **Table name resolution in native SQL**
+   - What we know: Timesheet table is `kimai2_timesheet`, projects is `kimai2_projects`, customers is `kimai2_customers`, activities is `kimai2_activities`
+   - What's unclear: Whether these names are configurable via Doctrine prefix
+   - Recommendation: Use `$em->getClassMetadata(Timesheet::class)->getTableName()` for safety, or hardcode since Kimai's table names are stable [ASSUMED]
+
+## Sources
+
+### Primary (HIGH confidence)
+- `Controller/HeatmapController.php` -- existing endpoint pattern, route attributes, auth checks
+- `Service/HeatmapService.php` -- existing QueryBuilder pattern, getUserProjects() shape
+- `Tests/Service/HeatmapServiceTest.php` -- existing mock pattern for service tests
+- `dev/kimai/config/packages/doctrine.yaml` -- confirmed DQL functions limited to DATE/DAY/MONTH/YEAR
+- `dev/kimai/src/Doctrine/UTCDateTimeType.php` -- confirmed UTC storage
+- `dev/kimai/src/Entity/Timesheet.php` -- confirmed entity relations, date_tz column, timezone column
+- `dev/kimai/src/Entity/User.php` -- confirmed getTimezone() and getFirstDayOfWeek() APIs
+- `dev/kimai/src/Entity/Project.php` -- confirmed customer relation
+
+### Secondary (MEDIUM confidence)
+- UI-SPEC (`08-UI-SPEC.md`) -- API response contracts for downstream phases
+
+### Tertiary (LOW confidence)
+- MariaDB CONVERT_TZ behavior with numeric offsets (not verified against running instance)
+
+## Metadata
+
+**Confidence breakdown:**
+- Standard stack: HIGH -- extending existing PHP patterns, no new libraries
+- Architecture: HIGH -- all patterns verified against existing codebase
+- Pitfalls: MEDIUM -- timezone handling assumptions need runtime validation
+
+**Research date:** 2026-04-09
+**Valid until:** 2026-05-09 (stable -- Kimai internals unlikely to change)

.planning/phases/08-backend-aggregation-filtering/08-REVIEW.md

@@ -0,0 +1,91 @@
+---
+phase: 08-backend-aggregation-filtering
+reviewed: 2026-04-09T12:00:00Z
+depth: standard
+files_reviewed: 6
+files_reviewed_list:
+  - Controller/HeatmapController.php
+  - Service/HeatmapService.php
+  - Tests/Controller/HeatmapControllerTest.php
+  - Tests/Service/HeatmapServiceTest.php
+  - Tests/bootstrap.php
+  - assets/src/types.ts
+findings:
+  critical: 0
+  warning: 2
+  info: 2
+  total: 4
+status: issues_found
+---
+
+# Phase 8: Code Review Report
+
+**Reviewed:** 2026-04-09T12:00:00Z
+**Depth:** standard
+**Files Reviewed:** 6
+**Status:** issues_found
+
+## Summary
+
+The backend aggregation and filtering implementation is solid overall. The controller uses proper Symfony auth guards and parameterized queries throughout, so there are no injection or auth bypass risks. The main concern is a DST-related logic bug in the timezone offset calculation for hourly aggregations, and a type naming mismatch between the TypeScript frontend types and the backend API modes.
+
+## Warnings
+
+### WR-01: Static timezone offset ignores DST transitions
+
+**File:** `Service/HeatmapService.php:236-244`
+**Issue:** `computeTimezoneOffset()` calculates the UTC offset at the current moment (`new \DateTime('now')`), then uses that fixed offset string in `CONVERT_TZ()` for queries spanning an entire year. For any timezone with daylight saving time (e.g., Europe/Berlin which shifts between +01:00 and +02:00), entries on the "wrong" side of the DST boundary will have their hour slot shifted by one. This means hourly and day-hour aggregations will misattribute hours near the DST transition periods.
+**Fix:** Pass the timezone name string directly to `CONVERT_TZ()` instead of a computed offset. MySQL supports named timezones if the `mysql.time_zone_name` table is populated (which it is on most installations):
+```php
+// Instead of computing offset, pass the IANA timezone name directly:
+$sql = 'SELECT HOUR(CONVERT_TZ(t.start_time, \'+00:00\', :tz)) as hour_slot, ...';
+// where :tz = 'Europe/Berlin' instead of '+02:00'
+```
+If the MySQL timezone tables aren't guaranteed to be populated, an alternative is to compute the offset per-row using the row's own date, but the named timezone approach is cleaner.
+
+### WR-02: Frontend TypeScript mode enum does not match backend API values
+
+**File:** `assets/src/types.ts:52`
+**Issue:** `HeatmapMode` is defined as `'year' | 'week' | 'day' | 'combined'`, but the controller's `mode` query parameter expects `'daily'`, `'hourly'`, or `'dayhour'` (line 31-43 of `HeatmapController.php`). If the frontend sends the TypeScript enum values, the backend will fall through to the `default` branch and always return daily data regardless of the intended mode. This is either a naming mismatch that needs reconciling, or the TypeScript type represents a UI-layer concept that maps to the API values elsewhere -- but as written, using `HeatmapMode` as the API parameter value would be a bug.
+**Fix:** Either align the TypeScript type with the API:
+```typescript
+export type HeatmapMode = 'daily' | 'hourly' | 'dayhour';
+```
+Or keep the UI-facing names and add an explicit mapping layer in the frontend fetch code that converts `'year' -> 'daily'`, `'day' -> 'hourly'`, `'combined' -> 'dayhour'`, etc.
+
+## Info
+
+### IN-01: Duplicated SQL filter clause construction
+
+**File:** `Service/HeatmapService.php:88-101` and `Service/HeatmapService.php:138-151`
+**Issue:** The project/activity/customer filter SQL clauses are identical between `getHourlyAggregation()` and `getDayHourAggregation()`. This duplication means filter logic changes must be applied in two places.
+**Fix:** Extract a private helper method:
+```php
+private function applyNativeFilters(string &$sql, array &$params, ?int $projectId, ?int $customerId, ?int $activityId): void
+{
+    if ($projectId !== null) {
+        $sql .= ' AND t.project_id = :project';
+        $params['project'] = $projectId;
+    }
+    if ($activityId !== null) {
+        $sql .= ' AND t.activity_id = :activity';
+        $params['activity'] = $activityId;
+    }
+    if ($customerId !== null) {
+        $sql .= ' AND t.project_id IN (SELECT p.id FROM kimai2_projects p WHERE p.customer_id = :customer)';
+        $params['customer'] = $customerId;
+    }
+}
+```
+
+### IN-02: Unused variable in test helper
+
+**File:** `Tests/Controller/HeatmapControllerTest.php:30`
+**Issue:** `createControllerWithUser()` returns `[$controller, $user]` and most callers destructure both, but in several tests (lines 42, 80, 98, 123, 136, 148, 168, 188) the `$user` variable is assigned but never used.
+**Fix:** Use `[$controller]` or `[$controller, $_]` in tests that don't need the user. This is a minor readability issue -- no functional impact.
+
+---
+
+_Reviewed: 2026-04-09T12:00:00Z_
+_Reviewer: Claude (gsd-code-reviewer)_
+_Depth: standard_

.planning/phases/08-backend-aggregation-filtering/08-UI-SPEC.md

@@ -0,0 +1,207 @@
+---
+phase: 8
+slug: backend-aggregation-filtering
+status: draft
+shadcn_initialized: false
+preset: none
+created: 2026-04-09
+---
+
+# Phase 8 — UI Design Contract
+
+> Visual and interaction contract for Phase 8. This phase is backend-only: new PHP endpoints, service methods, and PHPUnit tests. No new visual components, no CSS changes, no rendering changes.
+
+---
+
+## Design System
+
+| Property | Value |
+|----------|-------|
+| Tool | none |
+| Preset | not applicable |
+| Component library | none (Kimai Tabler theme) |
+| Icon library | none (no new icons this phase) |
+| Font | inherited from Kimai/Tabler |
+
+---
+
+## Phase UI Surface
+
+**This phase has no visual changes.** It builds the data layer consumed by Phase 9 (Day + Combined Modes) and Phase 10 (Entity Pickers).
+
+Frontend touch is limited to extending the existing `fetch()` call with additional URL query parameters (mode, customer, activity). No new DOM elements, no new CSS classes, no layout changes.
+
+### What This Phase Does NOT Add
+- No new visualization renderers
+- No new filter UI elements (pickers come in Phase 10)
+- No new CSS rules
+- No Twig template changes
+- No new user-visible states
+
+---
+
+## Spacing Scale
+
+Not applicable -- no new visual elements in this phase.
+
+Existing spacing from `heatmap.css` remains unchanged:
+- Wrapper gap: 16px
+- Stats padding-top: 12px
+- Filter select min-width: 140px, max-width: 200px
+
+---
+
+## Typography
+
+Not applicable -- no new text elements in this phase.
+
+---
+
+## Color
+
+Not applicable -- no new color usage in this phase.
+
+---
+
+## Copywriting Contract
+
+No new user-facing copy in this phase. The only text change is extending the existing error console message pattern.
+
+| Element | Copy |
+|---------|------|
+| Fetch error (console) | `KimaiHeatmap: failed to load filtered data` (existing pattern, no change) |
+| Empty state | Handled by renderer layer (Phase 9), not this phase |
+
+---
+
+## API Response Contracts
+
+These are the data contracts downstream phases depend on. Source: 08-CONTEXT.md decisions D-01 through D-09.
+
+### Existing Endpoint Extension: `/heatmap/data`
+
+New query parameters (all optional, additive AND logic):
+
+| Param | Type | Default | Purpose |
+|-------|------|---------|---------|
+| `mode` | `daily` \| `hourly` \| `dayhour` | `daily` | Aggregation mode |
+| `project` | integer | null | Filter by project (existing) |
+| `customer` | integer | null | Filter by customer (all projects under customer) |
+| `activity` | integer | null | Filter by activity |
+
+### Response: mode=daily (existing, unchanged)
+
+```json
+{
+  "days": [{"date": "2026-01-15", "hours": 4.5, "count": 3}],
+  "range": {"begin": "2025-04-09", "end": "2026-04-09"}
+}
+```
+
+### Response: mode=hourly (new -- consumed by Phase 9 day-mode)
+
+```json
+{
+  "hours": [{"hour": 9, "hours": 12.5, "count": 8}],
+  "range": {"begin": "2025-04-09", "end": "2026-04-09"}
+}
+```
+
+- `hour`: 0-23, hour-of-day in user's timezone
+- `hours`: total tracked hours in that hour slot across the date range
+- `count`: total timesheet entries in that hour slot
+
+### Response: mode=dayhour (new -- consumed by Phase 9 combined-mode)
+
+```json
+{
+  "matrix": [{"day": 0, "hour": 9, "hours": 3.2, "count": 2}],
+  "range": {"begin": "2025-04-09", "end": "2026-04-09"}
+}
+```
+
+- `day`: 0-6, day-of-week relative to user's weekStart preference
+- `hour`: 0-23, hour-of-day in user's timezone
+- `hours`: total tracked hours for that day/hour combination
+- `count`: total entries for that day/hour combination
+
+### Cascade Endpoints (new -- consumed by Phase 10 pickers)
+
+| Endpoint | Params | Response |
+|----------|--------|----------|
+| `/heatmap/customers` | none | `[{"id": 1, "name": "Acme Corp"}]` |
+| `/heatmap/projects` | `customer={id}` (optional) | `[{"id": 1, "name": "Website"}]` |
+| `/heatmap/activities` | `project={id}` (optional) | `[{"id": 1, "name": "Development"}]` |
+
+All cascade endpoints:
+- Use session auth (`IS_AUTHENTICATED_REMEMBERED`), not API auth
+- Scoped to entities the current user has timesheets for
+- Return `[{id: number, name: string}]` matching existing `ProjectOption` type
+
+---
+
+## Frontend Fetch Integration
+
+The existing fetch in `heatmap.ts` (lines 113-127, 145-157) will be extended to construct URLs with the new params. Pattern:
+
+```
+${baseUrl}?mode=${state.mode}&project=${id}&customer=${id}&activity=${id}
+```
+
+Only non-null filter values are appended. The `mode` param maps from `HeatmapMode` to API mode:
+- `year` -> `daily` (or omit, it's the default)
+- `week` -> `daily` (client-side aggregation, no backend change)
+- `day` -> `hourly`
+- `combined` -> `dayhour`
+
+---
+
+## TypeScript Type Extensions
+
+New types to add to `assets/src/types.ts` for Phase 9 consumption:
+
+```typescript
+export interface HourEntry {
+  hour: number;   // 0-23
+  hours: number;
+  count: number;
+}
+
+export interface DayHourEntry {
+  day: number;    // 0-6, relative to weekStart
+  hour: number;   // 0-23
+  hours: number;
+  count: number;
+}
+
+export interface HourlyData {
+  hours: HourEntry[];
+  range: { begin: string; end: string };
+}
+
+export interface DayHourData {
+  matrix: DayHourEntry[];
+  range: { begin: string; end: string };
+}
+```
+
+---
+
+## Registry Safety
+
+| Registry | Blocks Used | Safety Gate |
+|----------|-------------|-------------|
+| none | none | not applicable |
+
+---
+
+## Checker Sign-Off
+
+- [ ] Dimension 1 Copywriting: N/A (no new user-facing copy)
+- [ ] Dimension 2 Visuals: N/A (no visual changes)
+- [ ] Dimension 3 Color: N/A (no color changes)
+- [ ] Dimension 4 Typography: N/A (no text changes)
+- [ ] Dimension 5 Spacing: N/A (no layout changes)
+- [ ] Dimension 6 Registry Safety: PASS (no registries used)
+
+**Approval:** pending

.planning/phases/08-backend-aggregation-filtering/08-VALIDATION.md

@@ -0,0 +1,77 @@
+---
+phase: 8
+slug: backend-aggregation-filtering
+status: draft
+nyquist_compliant: false
+wave_0_complete: false
+created: 2026-04-09
+---
+
+# Phase 8 — Validation Strategy
+
+> Per-phase validation contract for feedback sampling during execution.
+
+---
+
+## Test Infrastructure
+
+| Property | Value |
+|----------|-------|
+| **Framework** | PHPUnit 10.x |
+| **Config file** | phpunit.xml.dist |
+| **Quick run command** | `vendor/bin/phpunit --filter HeatmapControllerTest` |
+| **Full suite command** | `vendor/bin/phpunit` |
+| **Estimated runtime** | ~5 seconds |
+
+---
+
+## Sampling Rate
+
+- **After every task commit:** Run `vendor/bin/phpunit --filter HeatmapControllerTest`
+- **After every plan wave:** Run `vendor/bin/phpunit`
+- **Before `/gsd-verify-work`:** Full suite must be green
+- **Max feedback latency:** 5 seconds
+
+---
+
+## Per-Task Verification Map
+
+| Task ID | Plan | Wave | Requirement | Threat Ref | Secure Behavior | Test Type | Automated Command | File Exists | Status |
+|---------|------|------|-------------|------------|-----------------|-----------|-------------------|-------------|--------|
+| 8-01-01 | 01 | 1 | API-01 | — | N/A | unit | `vendor/bin/phpunit --filter testHourlyAggregation` | ❌ W0 | ⬜ pending |
+| 8-01-02 | 01 | 1 | API-01 | — | N/A | unit | `vendor/bin/phpunit --filter testDayHourAggregation` | ❌ W0 | ⬜ pending |
+| 8-02-01 | 02 | 1 | FILT-02, FILT-03 | — | N/A | unit | `vendor/bin/phpunit --filter testActivityFilter` | ❌ W0 | ⬜ pending |
+| 8-02-02 | 02 | 1 | FILT-03 | — | N/A | unit | `vendor/bin/phpunit --filter testCustomerFilter` | ❌ W0 | ⬜ pending |
+| 8-03-01 | 03 | 1 | API-02 | — | N/A | unit | `vendor/bin/phpunit --filter testCascadeCustomers` | ❌ W0 | ⬜ pending |
+| 8-03-02 | 03 | 1 | API-02 | — | N/A | unit | `vendor/bin/phpunit --filter testCascadeProjects` | ❌ W0 | ⬜ pending |
+| 8-03-03 | 03 | 1 | API-02 | — | N/A | unit | `vendor/bin/phpunit --filter testCascadeActivities` | ❌ W0 | ⬜ pending |
+
+*Status: ⬜ pending · ✅ green · ❌ red · ⚠️ flaky*
+
+---
+
+## Wave 0 Requirements
+
+- [ ] `Tests/Controller/HeatmapControllerTest.php` — extend with test stubs for hourly, dayhour, filters, cascade endpoints
+- [ ] `Tests/Service/HeatmapServiceTest.php` — stubs for aggregation methods (if unit testing service separately)
+
+*Existing PHPUnit infrastructure covers framework needs.*
+
+---
+
+## Manual-Only Verifications
+
+*All phase behaviors have automated verification.*
+
+---
+
+## Validation Sign-Off
+
+- [ ] All tasks have `<automated>` verify or Wave 0 dependencies
+- [ ] Sampling continuity: no 3 consecutive tasks without automated verify
+- [ ] Wave 0 covers all MISSING references
+- [ ] No watch-mode flags
+- [ ] Feedback latency < 5s
+- [ ] `nyquist_compliant: true` set in frontmatter
+
+**Approval:** pending

.planning/phases/08-backend-aggregation-filtering/08-VERIFICATION.md

@@ -0,0 +1,91 @@
+---
+phase: 08-backend-aggregation-filtering
+verified: 2026-04-09T20:15:00Z
+status: passed
+score: 5/5 must-haves verified
+---
+
+# Phase 8: Backend Aggregation + Filtering Verification Report
+
+**Phase Goal:** Backend serves hour-level and day/hour aggregation data and accepts activity and customer filter params via custom endpoints
+**Verified:** 2026-04-09T20:15:00Z
+**Status:** passed
+**Re-verification:** No -- initial verification
+
+## Goal Achievement
+
+### Observable Truths
+
+| # | Truth | Status | Evidence |
+|---|-------|--------|----------|
+| 1 | API endpoint accepts mode param returning hourly and day/hour aggregation data | VERIFIED | Controller `data()` uses `match($mode)` dispatching to `getHourlyAggregation` (mode=hourly) and `getDayHourAggregation` (mode=dayhour), with default falling through to daily. Response shapes: `{hours: [...], range}` and `{matrix: [...], range}`. |
+| 2 | Activity filter param narrows heatmap data to entries matching a specific activity | VERIFIED | Controller extracts `$activityId = $request->query->getInt('activity') ?: null` and passes to all service methods. Service applies `AND t.activity_id = :activity` (native SQL) or `eq('t.activity', ':activity')` (DQL) with parameterized binding. |
+| 3 | Customer filter param narrows heatmap data to all projects under a selected customer | VERIFIED | Controller extracts `$customerId` via `getInt('customer')` and passes to service. Native SQL uses subquery `t.project_id IN (SELECT p.id FROM kimai2_projects p WHERE p.customer_id = :customer)`. DQL uses `join('t.project', 'p')` + `eq('p.customer', ':customer')`. |
+| 4 | Custom cascade endpoints (/heatmap/customers, /heatmap/projects, /heatmap/activities) return entity lists using session auth | VERIFIED | Three separate controller actions with `#[Route]` attributes at `/customers`, `/projects`, `/activities`. All use `#[IsGranted('view_own_timesheet')]` (session auth, not API auth). Projects accepts optional `?customer` param for cascade filtering; activities accepts optional `?project` param. All 4 actions (data + 3 cascade) have the `view_own_timesheet` guard. |
+| 5 | PHPUnit tests cover hourly aggregation, day/hour aggregation, and filter parameter handling | VERIFIED | 21 tests, 56 assertions, all passing. Service tests: `testGetHourlyAggregationReturnsFormattedResults`, `testGetHourlyAggregationReturnsEmptyForNoData`, `testGetDayHourAggregationReturnsFormattedResults`, `testGetDayHourAggregationSundayStart`, `testGetDailyAggregationWithActivityFilter`, `testGetDailyAggregationWithCustomerFilter`. Controller tests: `testDataReturnsHourlyMode`, `testDataReturnsDayHourMode`, `testDataDefaultsToDailyMode`, `testDataPassesFilterParams`, `testCustomersEndpoint`, `testProjectsEndpoint`, `testActivitiesEndpoint`, `testActivitiesWithProjectParam`. |
+
+**Score:** 5/5 truths verified
+
+### Required Artifacts
+
+| Artifact | Expected | Status | Details |
+|----------|----------|--------|---------|
+| `Service/HeatmapService.php` | Hourly, day/hour aggregation + filter params on all queries | VERIFIED | 7 methods total (6 public + 1 private helper). `getHourlyAggregation`, `getDayHourAggregation`, `getUserCustomers`, `getUserActivities` all implemented with real SQL/DQL. `getDailyAggregation` extended with `$customerId` and `$activityId` params. `getUserProjects` extended with optional `$customerId`. |
+| `Tests/Service/HeatmapServiceTest.php` | Unit tests for all new service methods | VERIFIED | 13 tests covering hourly, day/hour, filter params, customer/activity entity queries, sunday/monday weekStart remapping. Both `createServiceWithResults` and `createServiceWithNativeResults` helpers present. |
+| `Controller/HeatmapController.php` | Mode dispatch, filter params, cascade endpoints | VERIFIED | 4 actions: `data` (mode dispatch + filters), `customers`, `projects` (with customer cascade), `activities` (with project cascade). All routes annotated with `IsGranted`. |
+| `Tests/Controller/HeatmapControllerTest.php` | Unit tests for mode dispatch and cascade endpoints | VERIFIED | 9 tests covering hourly mode, dayhour mode, daily default, filter passthrough, customers/projects/activities endpoints, activities with project param. |
+| `assets/src/types.ts` | HourEntry, DayHourEntry, HourlyData, DayHourData types | VERIFIED | All 4 interfaces present with correct shapes matching API response contracts. |
+
+### Key Link Verification
+
+| From | To | Via | Status | Details |
+|------|----|-----|--------|---------|
+| Controller data() | Service getHourlyAggregation | `$service->getHourlyAggregation(...)` | WIRED | Called in match 'hourly' branch with all 6 params |
+| Controller data() | Service getDayHourAggregation | `$service->getDayHourAggregation(...)` | WIRED | Called in match 'dayhour' branch with 7 params including weekStart |
+| Controller customers() | Service getUserCustomers | `$service->getUserCustomers(...)` | WIRED | Direct call with user |
+| Controller activities() | Service getUserActivities | `$service->getUserActivities(...)` | WIRED | Called with user and optional projectId |
+| Service native SQL | DBAL Connection | `$this->entityManager->getConnection()` | WIRED | Used in getHourlyAggregation and getDayHourAggregation |
+| Service DQL queries | TimesheetRepository QueryBuilder | `$this->repository->createQueryBuilder('t')` | WIRED | Used in getDailyAggregation, getUserProjects, getUserCustomers, getUserActivities |
+
+### Data-Flow Trace (Level 4)
+
+Not applicable -- these are backend service/controller methods returning data from DB queries. No rendering of dynamic data occurs in this phase.
+
+### Behavioral Spot-Checks
+
+| Behavior | Command | Result | Status |
+|----------|---------|--------|--------|
+| PHPUnit full suite passes | `php dev/kimai/vendor/bin/phpunit --configuration Tests/phpunit.xml` | 21 tests, 56 assertions, 0 failures | PASS |
+
+### Requirements Coverage
+
+| Requirement | Source Plan | Description | Status | Evidence |
+|-------------|------------|-------------|--------|----------|
+| API-01 | 08-01, 08-02 | API endpoint accepts mode param returning hour-level and day/hour aggregation data | SATISFIED | Controller mode dispatch + service aggregation methods |
+| API-02 | 08-02 | API endpoint accepts activity and customer filter params with own controller endpoints | SATISFIED | Filter params on data(), plus cascade endpoints /customers, /projects, /activities |
+| FILT-02 | 08-01 | Activity filtering narrows heatmap data to a specific activity | SATISFIED | `activityId` param on all aggregation methods with parameterized WHERE |
+| FILT-03 | 08-01 | Customer filtering narrows heatmap data to all projects under a customer | SATISFIED | `customerId` param with subquery/join filtering on all aggregation methods |
+| TEST-03 | 08-01, 08-02 | PHPUnit tests for hour-level and day/hour aggregation queries | SATISFIED | 13 service tests + 9 controller tests, all passing |
+
+No orphaned requirements found -- all 5 requirement IDs mapped to this phase appear in plan frontmatter.
+
+### Anti-Patterns Found
+
+| File | Line | Pattern | Severity | Impact |
+|------|------|---------|----------|--------|
+| None | - | - | - | - |
+
+No TODOs, FIXMEs, placeholders, empty returns, or stub patterns found in any phase files.
+
+### Human Verification Required
+
+No human verification items needed. All truths are verifiable through code inspection and automated tests.
+
+### Gaps Summary
+
+No gaps found. All 5 roadmap success criteria verified against actual codebase artifacts. All requirement IDs satisfied. All tests passing.
+
+---
+
+_Verified: 2026-04-09T20:15:00Z_
+_Verifier: Claude (gsd-verifier)_

.planning/research/ARCHITECTURE.md

@@ -1,467 +1,376 @@
-# Architecture Patterns
+# Architecture: v1.1 Integration
 
-**Domain:** Kimai dashboard widget plugin (Symfony bundle + d3.js)
+**Domain:** Kimai heatmap plugin -- visualization modes, TomSelect pickers, display toggle
 **Researched:** 2026-04-08
-**Confidence:** MEDIUM (based on training knowledge of Kimai 2.x plugin system; no live doc verification possible)
+**Confidence:** HIGH (based on reading existing codebase + Kimai source in dev/)
 
-## Recommended Architecture
-
-### High-Level Overview
+## Current Architecture Summary
 
 ```
-+------------------------------------------+
-|  Kimai Dashboard (Twig)                  |
-|  +------------------------------------+  |
-|  |  HeatmapWidget (registered via     |  |
-|  |  WidgetInterface + DI tag)         |  |
-|  |  +------------------------------+ |  |
-|  |  | Twig template renders        | |  |
-|  |  | <div id="heatmap-widget">    | |  |
-|  |  | + inline d3.js bundle        | |  |
-|  |  +------------------------------+ |  |
-|  +------------------------------------+  |
-+------------------------------------------+
-         |                    ^
-         | XHR/fetch          | JSON
-         v                    |
-+------------------------------------------+
-|  HeatmapController (Symfony)             |
-|  GET /api/heatmap?range=&project=        |
-|  - Queries TimesheetRepository           |
-|  - Aggregates hours/counts per day       |
-|  - Returns JSON                          |
-+------------------------------------------+
+Twig template (heatmap.html.twig)
+  -- data attributes: data-url, data-projects, data-timesheet-url, data-week-start
+  -- loads heatmap.js (IIFE, KimaiHeatmap global)
+  -- calls KimaiHeatmap.init(container)
+
+TypeScript (heatmap.ts)
+  init() -- reads data attrs, builds DOM, creates plain <select>, fetches data
+  renderHeatmap() -- d3 year-view calendar grid (single mode)
+  renderStats() -- streak/total/avg/busiest stats row
+  calculateStreak(), calculateStats() -- pure functions
+
+PHP
+  HeatmapController -- GET /heatmap/data?project=N -> JSON {days, range}
+  HeatmapService -- getDailyAggregation(user, begin, end, projectId) GROUP BY DATE
+  HeatmapWidget -- getData() returns {projects, weekStart}
+  DashboardSubscriber -- registers widget on dashboard
+```
+
+## What Needs to Change
+
+### New Features Mapped to Components
+
+| Feature | Backend Changes | Frontend Changes | New Components |
+|---------|----------------|-----------------|----------------|
+| Visualization modes (year/week/day/combined) | New aggregation queries in HeatmapService | Mode switcher UI, new render functions per mode | `renderers/*.ts` modules |
+| TomSelect entity pickers | New API endpoints or reuse Kimai's existing `/api/customers`, `/api/projects`, `/api/activities` | Replace plain `<select>` with TomSelect-enhanced selects, cascading logic | Filter bar component in TS |
+| Activity filtering | Add `activityId` param to controller + service query | Activity picker in cascade after project | None (extends existing) |
+| Hours/count toggle | None (data already includes both `hours` and `count`) | Toggle button, pass display mode to renderer | None (extends existing) |
+
+## Integration Architecture
+
+### 1. Visualization Mode System
+
+**Current state:** `renderHeatmap()` is a monolithic function that only renders the year-view calendar grid. It handles cells, tooltips, month labels, day labels, and click handlers in one function.
+
+**Target state:** A mode dispatcher that delegates to mode-specific renderers sharing common infrastructure (tooltip, color scale, click handler).
+
+```
+heatmap.ts
+  init()
     |
     v
-+------------------------------------------+
-|  Kimai Database (timesheet table)        |
-|  - begin, end, duration, project_id,     |
-|    activity_id, user_id                  |
-+------------------------------------------+
+  ModeController (new)
+    - activeMode: 'year' | 'week' | 'day' | 'combined'
+    - switchMode(mode) -> fetches appropriate data, calls renderer
+    |
+    +-- renderers/year.ts     (refactored from current renderHeatmap)
+    +-- renderers/week.ts     (new: 7-column day-of-week aggregation)
+    +-- renderers/day.ts      (new: 24-row hour-of-day heatmap)
+    +-- renderers/combined.ts (new: 7x24 matrix, day-of-week x hour)
+    |
+    +-- shared/
+        +-- tooltip.ts        (extracted from renderHeatmap)
+        +-- colorScale.ts     (extracted from renderHeatmap)
+        +-- types.ts          (extended with new data shapes)
 ```
 
-### Component Boundaries
+**Renderer interface:**
 
-| Component | Responsibility | Communicates With |
-|-----------|---------------|-------------------|
-| `KimaiHeatmapBundle` | Bundle class, DI registration | Symfony kernel |
-| `HeatmapWidget` | Implements `WidgetInterface`, provides widget metadata and Twig rendering | Dashboard renderer, Twig |
-| `HeatmapController` | API endpoint serving aggregated time data as JSON | Widget frontend (JS), `HeatmapService` |
-| `HeatmapService` | Data aggregation logic (hours/counts per day) | Kimai's `TimesheetRepository` / Doctrine |
-| `d3 heatmap module` | Client-side calendar heatmap rendering | HeatmapController API (fetch), DOM |
-| Twig template | Widget HTML shell + d3 script inclusion | HeatmapWidget, Encore/Webpack assets |
-
-## Kimai Plugin Bundle Structure
-
-Kimai plugins are standard Symfony bundles placed in `var/plugins/` (for local install) or loaded via Composer. The canonical directory layout:
-
-```
-KimaiHeatmapBundle/
-  KimaiHeatmapBundle.php         # Bundle class (extends PluginInterface)
-  DependencyInjection/
-    KimaiHeatmapExtension.php    # Loads services.yaml
-  Resources/
-    config/
-      services.yaml              # Service definitions + DI tags
-      routes.yaml                # Plugin routes (controller endpoints)
-    views/
-      widget/
-        heatmap.html.twig        # Widget Twig template
-    public/
-      heatmap.js                 # Compiled d3 heatmap script
-      heatmap.css                # Widget styles
-  Widget/
-    HeatmapWidget.php            # WidgetInterface implementation
-  Controller/
-    HeatmapController.php        # API controller
-  Service/
-    HeatmapService.php           # Data aggregation
-  EventSubscriber/               # Optional: hook into Kimai events
-  composer.json                  # Package metadata, autoload config
-```
-
-### Bundle Class
-
-```php
-// KimaiHeatmapBundle.php
-namespace KimaiPlugin\KimaiHeatmapBundle;
-
-use App\Plugin\PluginInterface;
-use Symfony\Component\DependencyInjection\ContainerBuilder;
-use Symfony\Component\HttpKernel\Bundle\Bundle;
-
-class KimaiHeatmapBundle extends Bundle implements PluginInterface
-{
-    public function build(ContainerBuilder $container): void
-    {
-        parent::build($container);
-    }
+```typescript
+interface ModeRenderer {
+  render(
+    container: HTMLElement,
+    data: ModeData,
+    config: HeatmapConfig,
+    onCellClick?: (context: CellClickContext) => void,
+    weekStart?: string,
+  ): void;
 }
 ```
 
-**Key point:** Kimai plugins implement `App\Plugin\PluginInterface` which extends Symfony's `BundleInterface`. The namespace MUST be `KimaiPlugin\<BundleName>` for Kimai's plugin loader to discover it.
+Each renderer is a pure function (no shared mutable state). The mode controller manages which one is active and handles data fetching.
 
-### DependencyInjection Extension
+**Backend data requirements per mode:**
 
-```php
-// DependencyInjection/KimaiHeatmapExtension.php
-namespace KimaiPlugin\KimaiHeatmapBundle\DependencyInjection;
+| Mode | Aggregation | Existing? | API Change |
+|------|------------|-----------|------------|
+| Year | GROUP BY DATE | Yes (`getDailyAggregation`) | None |
+| Week | GROUP BY DAYOFWEEK | No | New method + new `mode=week` param |
+| Day | GROUP BY HOUR | No | New method + new `mode=day` param |
+| Combined | GROUP BY DAYOFWEEK, HOUR | No | New method + new `mode=combined` param |
 
-use Symfony\Component\Config\FileLocator;
-use Symfony\Component\DependencyInjection\ContainerBuilder;
-use Symfony\Component\DependencyInjection\Extension\PrependExtensionInterface;
-use Symfony\Component\DependencyInjection\Loader\YamlFileLoader;
-use Symfony\Component\HttpKernel\DependencyInjection\Extension;
+**API endpoint evolution:**
 
-class KimaiHeatmapExtension extends Extension implements PrependExtensionInterface
-{
-    public function load(array $configs, ContainerBuilder $container): void
-    {
-        $loader = new YamlFileLoader($container, new FileLocator(__DIR__ . '/../Resources/config'));
-        $loader->load('services.yaml');
-    }
+```
+Current:  GET /heatmap/data?project=N
+                            -> {days: [{date, hours, count}], range: {begin, end}}
 
-    public function prepend(ContainerBuilder $container): void
-    {
-        // Prepend route config so Kimai loads our routes
-        $container->prependExtensionConfig('kimai', [
-            'plugin' => [
-                'heatmap' => [
-                    'routes' => '@KimaiHeatmapBundle/Resources/config/routes.yaml',
-                ],
-            ],
-        ]);
-    }
+Proposed: GET /heatmap/data?project=N&activity=M&mode=year
+                            -> {days: [{date, hours, count}], range: {begin, end}}
+          GET /heatmap/data?project=N&activity=M&mode=week
+                            -> {buckets: [{dayOfWeek: 0-6, hours, count}]}
+          GET /heatmap/data?project=N&activity=M&mode=day
+                            -> {buckets: [{hour: 0-23, hours, count}]}
+          GET /heatmap/data?project=N&activity=M&mode=combined
+                            -> {buckets: [{dayOfWeek: 0-6, hour: 0-23, hours, count}]}
+```
+
+The `mode` parameter defaults to `year` for backward compatibility. Different modes return different response shapes via a discriminated union keyed on `mode`.
+
+### 2. TomSelect Integration
+
+**The key decision: Don't use Kimai's KimaiFormSelect.js directly.**
+
+Kimai's `KimaiFormSelect` is deeply coupled to Kimai's plugin container system (`this.getContainer().getPlugin('api')`) and Symfony form rendering. It expects:
+- A `KimaiContainer` instance providing API, date utils, and translation plugins
+- Form elements rendered by Symfony with specific `data-*` attributes
+- Global `document` change event delegation for cascading
+
+Our widget builds its DOM in JS (not Symfony forms), runs outside Kimai's form lifecycle, and ships as an IIFE bundle. Trying to hook into `KimaiFormSelect` would require either:
+1. Importing TomSelect + reimplementing cascade logic (the sensible path)
+2. Somehow accessing Kimai's JS plugin container from our IIFE scope (fragile, undocumented)
+
+**Recommendation: Import tom-select directly and implement cascade logic ourselves.**
+
+The cascade pattern from `KimaiFormSelect._activateApiSelects()` is straightforward: on parent change, fetch child options from API, update child select. We can replicate the essential behavior in ~50 lines without the form framework coupling.
+
+**Implementation:**
+
+```typescript
+// filters/EntityPicker.ts
+import TomSelect from 'tom-select';
+
+interface PickerConfig {
+  element: HTMLSelectElement;
+  apiUrl: string;
+  placeholder: string;
+  onChange: (value: string | null) => void;
+  dependsOn?: EntityPicker;  // cascade parent
 }
 ```
 
-## Dashboard Widget System
+**Cascade flow:**
+```
+Customer picker (optional, loads from /api/customers)
+  |-- on change -> reload Project picker from /api/projects?customer=X
+        |-- on change -> reload Activity picker from /api/activities?project=Y
+              |-- on change -> refetch heatmap data with all filters
+```
 
-Kimai's dashboard renders widgets that implement `App\Widget\WidgetInterface`. Widgets are registered via Symfony DI tags.
+**API endpoints to use:** Kimai's existing REST API routes (`get_customers`, `get_projects`, `get_activities`) already exist and return data in the format TomSelect expects. No new backend endpoints needed for the pickers themselves.
 
-### Widget Interface
+**Bundle size concern:** tom-select is ~30KB minified+gzipped. Since Kimai already loads it globally (it's in Kimai's own webpack bundle), we should NOT bundle it into our IIFE. Instead, reference the global `TomSelect` that Kimai already provides.
 
-```php
-// Widget/HeatmapWidget.php
-namespace KimaiPlugin\KimaiHeatmapBundle\Widget;
+**Verification needed:** Check whether `window.TomSelect` or `TomSelect` is available globally in the Kimai dashboard page. If Kimai's webpack build exposes it, we use it. If not, we bundle our own copy.
 
-use App\Widget\WidgetInterface;
-use App\Widget\Type\AbstractWidgetType;
-use App\Repository\TimesheetRepository;
+### 3. Display Toggle (Hours vs Count)
 
-class HeatmapWidget extends AbstractWidgetType
-{
-    public function __construct(
-        private TimesheetRepository $timesheetRepository
-    ) {}
+**This is the simplest change.** The data already contains both `hours` and `count` per day entry. The toggle is purely a frontend concern:
 
-    public function getWidth(): int
-    {
-        return WidgetInterface::WIDTH_FULL;  // Full-width dashboard widget
-    }
+- Add a segmented control or toggle button to the UI
+- Pass `displayMode: 'hours' | 'count'` to the renderer
+- Renderer uses `entry.hours` or `entry.count` for the color scale domain
+- Tooltip text adjusts accordingly
 
-    public function getHeight(): int
-    {
-        return WidgetInterface::HEIGHT_LARGE;
-    }
+**No backend changes needed.** The year-mode API already returns both fields. For new modes (week/day/combined), the aggregation queries should also return both.
 
-    public function getTitle(): string
-    {
-        return 'Activity Heatmap';
-    }
+### 4. Filter Bar Layout
 
-    public function getTemplateName(): string
-    {
-        return '@KimaiHeatmap/widget/heatmap.html.twig';
-    }
+**Current layout:** Heatmap SVG area + project dropdown in a flex row, stats below.
 
-    public function getId(): string
-    {
-        return 'HeatmapWidget';
-    }
+**New layout:**
 
-    public function getData(array $options = []): mixed
-    {
-        // Initial data can be passed to Twig, or widget
-        // can fetch data via XHR from the API endpoint
-        return [];
-    }
+```
++------------------------------------------------------------------+
+| Filter bar: [Customer v] [Project v] [Activity v]  [Year|Week|Day|Combined]  [Hours|Count] |
++------------------------------------------------------------------+
+| Heatmap SVG area (mode-dependent)                                |
++------------------------------------------------------------------+
+| Stats row: streak | total | avg | busiest                       |
++------------------------------------------------------------------+
+```
 
-    public function getPermissions(): array
-    {
-        return ['view_own_timesheet'];
-    }
+The filter bar replaces the current `heatmap-filter` div. It should use Tabler's form layout classes (`row`, `col-auto`) for alignment with the rest of the Kimai dashboard.
+
+## Component Inventory
+
+### New TypeScript Files
+
+| File | Purpose | Depends On |
+|------|---------|-----------|
+| `renderers/year.ts` | Refactored year-view (extracted from renderHeatmap) | shared/tooltip, shared/colorScale |
+| `renderers/week.ts` | Day-of-week aggregation heatmap | shared/tooltip, shared/colorScale |
+| `renderers/day.ts` | Hour-of-day heatmap | shared/tooltip, shared/colorScale |
+| `renderers/combined.ts` | 7x24 day/hour matrix | shared/tooltip, shared/colorScale |
+| `shared/tooltip.ts` | Tooltip creation and positioning (extracted) | None |
+| `shared/colorScale.ts` | Color scale factory (extracted) | None |
+| `filters.ts` | TomSelect entity pickers with cascade | tom-select (global or bundled) |
+| `modeController.ts` | Mode switching, data fetching orchestration | renderers/*, filters |
+
+### Modified TypeScript Files
+
+| File | Changes |
+|------|---------|
+| `heatmap.ts` | `init()` refactored to use ModeController and Filters instead of inline DOM building |
+| `types.ts` | New interfaces: `WeekBucket`, `HourBucket`, `CombinedBucket`, `ModeData` union type, `FilterState` |
+
+### New PHP Files
+
+None needed -- extend existing files.
+
+### Modified PHP Files
+
+| File | Changes |
+|------|---------|
+| `HeatmapService.php` | Add `getWeekdayAggregation()`, `getHourlyAggregation()`, `getCombinedAggregation()`, add `activityId` param to all methods |
+| `HeatmapController.php` | Add `mode` and `activity` query params, dispatch to appropriate service method |
+| `HeatmapWidget.php` | No changes (pickers load via API, not server-side data) |
+| `heatmap.html.twig` | Add data attributes for API URLs (`data-customers-url`, `data-projects-url`, `data-activities-url`), remove `data-projects` (no longer server-rendered) |
+
+### New CSS
+
+| Addition | Purpose |
+|---------|---------|
+| `.heatmap-toolbar` | Filter bar layout (flex, gap, wrapping) |
+| `.heatmap-mode-switcher` | Segmented control for mode tabs |
+| `.heatmap-display-toggle` | Hours/count toggle button |
+| TomSelect overrides | Match Kimai's existing TomSelect styling (should inherit, may need minor tweaks) |
+
+## Data Flow Changes
+
+### Current
+
+```
+init() -> fetch(/heatmap/data) -> renderHeatmap(yearData) -> renderStats()
+filter change -> fetch(/heatmap/data?project=N) -> renderHeatmap(yearData)
+```
+
+### New
+
+```
+init()
+  -> build filter bar (TomSelect pickers, mode tabs, display toggle)
+  -> fetch(/heatmap/data?mode=year) -> yearRenderer.render()
+  -> renderStats()
+
+customer change -> cascade: reload projects -> reload activities -> refetch
+project change -> cascade: reload activities -> refetch
+activity change -> refetch
+mode change -> refetch with new mode param -> modeRenderer.render()
+display toggle -> re-render with same data, different value accessor (no fetch)
+```
+
+**Key insight:** The display toggle (hours/count) does NOT require a new fetch. It re-renders the current data with a different accessor. All other changes (filter, mode) trigger a new fetch.
+
+### State Management
+
+Current state is implicit (closure variables in `init()`). With more state dimensions, formalize it:
+
+```typescript
+interface HeatmapState {
+  mode: 'year' | 'week' | 'day' | 'combined';
+  display: 'hours' | 'count';
+  filters: {
+    customerId: number | null;
+    projectId: number | null;
+    activityId: number | null;
+  };
+  data: ModeData | null;
 }
 ```
 
-### Service Registration (services.yaml)
-
-```yaml
-services:
-    KimaiPlugin\KimaiHeatmapBundle\Widget\HeatmapWidget:
-        arguments:
-            $timesheetRepository: '@App\Repository\TimesheetRepository'
-        tags:
-            - { name: 'kimai.widget', priority: 50 }
-
-    KimaiPlugin\KimaiHeatmapBundle\Controller\HeatmapController:
-        tags: ['controller.service_arguments']
-
-    KimaiPlugin\KimaiHeatmapBundle\Service\HeatmapService:
-        arguments:
-            $timesheetRepository: '@App\Repository\TimesheetRepository'
-```
-
-The `kimai.widget` tag is how the widget gets discovered and rendered on the dashboard. The `priority` controls ordering (higher = appears earlier).
-
-## API Endpoint for Heatmap Data
-
-### Controller
-
-```php
-// Controller/HeatmapController.php
-namespace KimaiPlugin\KimaiHeatmapBundle\Controller;
-
-use App\Controller\AbstractController;
-use Symfony\Component\HttpFoundation\JsonResponse;
-use Symfony\Component\HttpFoundation\Request;
-use Symfony\Component\Routing\Annotation\Route;
-use Symfony\Component\Security\Http\Attribute\IsGranted;
-
-#[Route(path: '/api/heatmap')]
-#[IsGranted('view_own_timesheet')]
-class HeatmapController extends AbstractController
-{
-    #[Route(path: '/data', name: 'heatmap_data', methods: ['GET'])]
-    public function getData(Request $request, HeatmapService $service): JsonResponse
-    {
-        $begin = new \DateTime($request->query->get('begin', '-1 year'));
-        $end = new \DateTime($request->query->get('end', 'now'));
-        $projectId = $request->query->getInt('project', 0);
-
-        $data = $service->getAggregatedData(
-            user: $this->getUser(),
-            begin: $begin,
-            end: $end,
-            projectId: $projectId ?: null
-        );
-
-        return new JsonResponse($data);
-    }
-}
-```
-
-### Route Registration (routes.yaml)
-
-```yaml
-heatmap_api:
-    resource: '../../Controller/'
-    type: annotation  # or attribute for PHP 8+
-    prefix: /api/plugins/heatmap
-```
-
-### JSON Response Shape
-
-```json
-{
-  "days": [
-    { "date": "2026-01-15", "hours": 7.5, "count": 3 },
-    { "date": "2026-01-16", "hours": 4.25, "count": 2 }
-  ],
-  "range": { "begin": "2025-04-08", "end": "2026-04-08" },
-  "maxHours": 12.0,
-  "projects": [
-    { "id": 1, "name": "Aitia" },
-    { "id": 2, "name": "Aleph Garden" }
-  ]
-}
-```
-
-## d3.js Integration in Symfony/Twig
-
-### Strategy: Standalone JS file loaded in Twig template
-
-Kimai uses Webpack Encore for asset management, but plugins typically ship prebuilt JS/CSS in `Resources/public/`. Kimai copies these to `public/bundles/<bundlename>/` via `assets:install`.
-
-**Recommendation:** Ship a self-contained d3 heatmap script rather than integrating with Kimai's Webpack build. This avoids coupling to Kimai's internal build pipeline.
-
-### Twig Template
-
-```twig
-{# Resources/views/widget/heatmap.html.twig #}
-{% block widget_content %}
-<div class="heatmap-widget" id="heatmap-container"
-     data-url="{{ path('heatmap_data') }}"
-     data-mode="hours"
-     data-range="365">
-    <div class="heatmap-controls">
-        <select id="heatmap-mode">
-            <option value="hours">Hours per day</option>
-            <option value="count">Entry count</option>
-        </select>
-        <select id="heatmap-project">
-            <option value="">All projects</option>
-        </select>
-    </div>
-    <div id="heatmap-chart"></div>
-</div>
-{% endblock %}
-
-{% block widget_javascript %}
-<script src="{{ asset('bundles/kimaiheatmap/heatmap.js') }}"></script>
-{% endblock %}
-```
-
-### d3 Module Design
-
-```
-assets/
-  src/
-    heatmap.ts              # Entry point, initializes widget
-    calendar-heatmap.ts     # d3 calendar heatmap rendering
-    data-fetcher.ts         # Fetch API wrapper for controller endpoint
-    color-scale.ts          # CSS variable-aware color scaling
-    types.ts                # TypeScript interfaces
-  package.json              # d3 + build deps
-  tsconfig.json
-  rollup.config.js          # Bundle to single file for Resources/public/
-```
-
-The JS gets bundled (via rollup or esbuild) into a single `heatmap.js` that ships in `Resources/public/`. d3 is bundled in (tree-shaken to only calendar/scale modules).
-
-### CSS Variable Integration
-
-```css
-/* Use Kimai's theme CSS custom properties */
-.heatmap-cell {
-    fill: var(--chart-color-empty, #ebedf0);
-}
-.heatmap-cell[data-level="1"] { fill: var(--chart-color-low, #9be9a8); }
-.heatmap-cell[data-level="2"] { fill: var(--chart-color-medium, #40c463); }
-.heatmap-cell[data-level="3"] { fill: var(--chart-color-high, #30a14e); }
-.heatmap-cell[data-level="4"] { fill: var(--chart-color-max, #216e39); }
-```
-
-**Note:** Kimai uses AdminLTE / Tabler themes. The actual CSS variable names need to be verified against the running Kimai instance. Fallback values ensure the heatmap works even if variables are missing.
-
-## Data Flow
-
-```
-1. User loads Kimai dashboard
-2. Symfony renders dashboard, includes HeatmapWidget
-3. HeatmapWidget renders Twig template (empty chart container + controls)
-4. heatmap.js initializes on DOMContentLoaded
-5. JS reads data-url attribute, fetches /api/plugins/heatmap/data?range=365
-6. HeatmapController receives request, delegates to HeatmapService
-7. HeatmapService queries TimesheetRepository with DQL/QueryBuilder
-   - GROUP BY DATE(begin), SUM(duration), COUNT(*)
-   - Filtered by user, date range, optional project
-8. Controller returns JSON response
-9. d3.js receives JSON, builds calendar heatmap SVG
-10. User interactions (mode toggle, project filter, day click) handled client-side
-    - Mode toggle: re-renders with different data key (hours vs count)
-    - Project filter: new fetch with ?project=ID parameter
-    - Day click: window.location to /en/timesheet/?daterange=YYYY-MM-DD
-```
-
-## Patterns to Follow
-
-### Pattern 1: Widget Data via Dedicated API
-
-**What:** Widget template is a thin shell; data fetching happens via XHR to a dedicated controller endpoint.
-**Why:** Separates rendering from data. Widget loads fast (empty shell), data arrives async. Enables filtering/re-fetching without page reload.
-**When:** Always for data-heavy widgets.
-
-### Pattern 2: Permission-Gated Everything
-
-**What:** Both the widget visibility and the API endpoint check `view_own_timesheet` permission.
-**Why:** Kimai has a role-based permission system. Widget should only appear for users with timesheet access, and the API must independently verify permissions (defense in depth).
-
-### Pattern 3: User-Scoped Queries
-
-**What:** Always filter by `$this->getUser()` in queries.
-**Why:** Personal time tracking -- users should only see their own data. Even if Kimai handles this at the repository level, be explicit.
-
-## Anti-Patterns to Avoid
-
-### Anti-Pattern 1: Embedding Data in Twig
-
-**What:** Passing all heatmap data through `getData()` into Twig as PHP arrays.
-**Why bad:** Large datasets (365 days of data) bloat the HTML. Cannot update without page reload. Makes filtering require full page requests.
-**Instead:** Thin Twig template + XHR data fetching.
-
-### Anti-Pattern 2: Hooking into Kimai's Webpack Build
-
-**What:** Requiring the plugin user to rebuild Kimai's assets.
-**Why bad:** Kimai's internal asset pipeline is not a public API. Updates can break your build. Extra install step for users.
-**Instead:** Ship prebuilt JS/CSS in `Resources/public/`.
-
-### Anti-Pattern 3: Raw SQL Queries
-
-**What:** Writing raw SQL instead of using Doctrine QueryBuilder or DQL.
-**Why bad:** Breaks database portability (Kimai supports MySQL and SQLite). Harder to test.
-**Instead:** Use Doctrine QueryBuilder with Kimai's existing repository patterns.
+Keep it simple -- a plain object in `init()` closure, not a state management library. When any filter/mode changes, build the fetch URL from state and re-render. When display changes, re-render from cached `state.data`.
 
 ## Suggested Build Order
 
-The components have clear dependencies that dictate implementation order:
+Dependencies dictate this sequence:
 
-```
-Phase 1: Plugin Scaffold
-  - Bundle class, DI extension, services.yaml, routes.yaml
-  - Empty widget registered on dashboard (renders "Hello Heatmap")
-  - Nix devshell with local Kimai instance
-  Validates: Plugin loads, widget appears, dev env works
+### Phase 1: Refactor Existing Code (Foundation)
 
-Phase 2: Data Layer
-  - HeatmapService with aggregation queries
-  - HeatmapController returning JSON
-  - PHPUnit tests for service + controller
-  Validates: API returns correct aggregated data
-  Depends on: Phase 1 (routing, DI)
+Extract shared utilities from `renderHeatmap()` -- tooltip, color scale, cell click handler. Create the renderer interface. Refactor year-view into `renderers/year.ts` that implements it. Create `types.ts` extensions.
 
-Phase 3: Heatmap Visualization
-  - d3.js calendar heatmap module (TypeScript)
-  - Build pipeline (rollup/esbuild -> single bundle)
-  - Twig template integration
-  - JS tests for rendering logic
-  Validates: Heatmap renders from API data
-  Depends on: Phase 2 (API endpoint exists)
+**Why first:** Everything else depends on the renderer abstraction. This phase changes no behavior -- existing tests should still pass (or need minor import path updates).
 
-Phase 4: Interactivity
-  - Mode toggle (hours vs count)
-  - Project/activity filter dropdowns
-  - Day-click navigation to timesheet
-  - Kimai theme CSS variable integration
-  Validates: Full feature set works
-  Depends on: Phase 3 (heatmap renders)
+**Validates:** Year-view still works identically after refactor.
+
+### Phase 2: Display Toggle + Mode Switcher UI
+
+Add the hours/count toggle (purely frontend, uses existing data). Add the mode switcher UI (tabs/segmented control) but only year mode works initially.
+
+**Why second:** Low risk, immediate visible result, validates the UI shell before adding complex renderers.
+
+**Validates:** Toggle switches between hours and count display. Mode tabs render but only year works.
+
+### Phase 3: Backend Aggregation Modes + Activity Filtering
+
+Add `getWeekdayAggregation()`, `getHourlyAggregation()`, `getCombinedAggregation()` to HeatmapService. Add `mode` and `activity` params to controller. PHPUnit tests for all new queries.
+
+**Why third:** Renderers need data to render. Get the API right before building the visualizations.
+
+**Validates:** API returns correct data for all modes. Activity filter works.
+
+### Phase 4: New Visualization Renderers
+
+Implement `renderers/week.ts`, `renderers/day.ts`, `renderers/combined.ts`. Wire mode switcher to actually switch renderers.
+
+**Why fourth:** Backend data is ready, UI shell exists, just fill in the renderers.
+
+**Validates:** All four modes render correctly with real data.
+
+### Phase 5: TomSelect Entity Pickers
+
+Replace plain `<select>` with TomSelect-enhanced pickers. Implement customer -> project -> activity cascade. Update Twig template with API URL data attributes.
+
+**Why last:** Most complex integration point (TomSelect availability, cascade logic, API compatibility). Everything else works with the existing project dropdown. This phase upgrades the filtering UX without blocking other features.
+
+**Validates:** Cascade works, filtering triggers data refetch, TomSelect styling matches Kimai.
+
+## Anti-Patterns to Avoid
+
+### Anti-Pattern: Giant Switch Statement in renderHeatmap()
+
+**What:** Adding `if (mode === 'week') { ... } else if (mode === 'day') { ... }` branches to the existing function.
+**Why bad:** The function is already 120+ lines. Adding 3 more modes would make it unmaintainable.
+**Instead:** Separate renderer modules with a shared interface.
+
+### Anti-Pattern: Importing Kimai's KimaiFormSelect.js
+
+**What:** Trying to use Kimai's internal form select system for TomSelect.
+**Why bad:** Coupled to Kimai's JS plugin container, Symfony form lifecycle, and internal APIs. Would break on Kimai updates.
+**Instead:** Import tom-select directly (or use Kimai's global). Implement cascade in ~50 lines.
+
+### Anti-Pattern: Separate API Endpoints per Mode
+
+**What:** Creating `/heatmap/data/week`, `/heatmap/data/day`, etc.
+**Why bad:** Multiplies routes and controllers unnecessarily.
+**Instead:** Single endpoint with `mode` query parameter. One controller method dispatches to the right service method.
+
+### Anti-Pattern: Bundling TomSelect into IIFE
+
+**What:** Including tom-select in the esbuild bundle.
+**Why bad:** Kimai already loads tom-select globally. Bundling a duplicate wastes ~30KB and may cause version conflicts.
+**Instead:** Declare tom-select as external in esbuild config, reference the global. Fall back to bundled copy only if global isn't available.
+
+## TomSelect Global Availability -- Verification Plan
+
+Before implementing Phase 5, verify in the dev environment:
+
+```javascript
+// In browser console on Kimai dashboard:
+typeof TomSelect !== 'undefined'  // Check global
+document.querySelector('[data-renderer]')  // Check if Kimai's selects use TomSelect
 ```
 
-## Scalability Considerations
+If TomSelect is NOT globally available (Kimai bundles it but doesn't expose it), options are:
+1. Add `tom-select` to our npm dependencies and bundle it (adds ~30KB)
+2. Use `esbuild --external:tom-select` and add a shim that extracts it from Kimai's bundle
 
-| Concern | Personal use (1 user) | Team (10 users) |
-|---------|----------------------|-----------------|
-| Query performance | Fine, single GROUP BY | Add DB index on `timesheet.begin` if slow |
-| Data payload size | ~365 rows, trivial | Same per user (user-scoped) |
-| Widget rendering | Instant | Instant (client-side d3) |
-| Caching | Not needed | Consider HTTP cache headers on API |
-
-For personal use (the stated scope), performance is a non-concern. The timesheet table query with a GROUP BY date, filtered to one user and one year, will return at most 365 rows.
+Option 1 is the safe default. Option 2 is fragile.
 
 ## Sources
 
-- Kimai plugin development documentation (kimai.org/documentation/plugin-development.html) -- referenced from training data, MEDIUM confidence
-- Symfony Bundle system documentation (symfony.com/doc/current/bundles.html) -- HIGH confidence, stable API
-- Kimai source code patterns (github.com/kimai/kimai) -- referenced from training data, MEDIUM confidence
-- d3.js calendar heatmap patterns -- HIGH confidence, well-established pattern
+- Kimai source: `dev/kimai/assets/js/forms/KimaiFormSelect.js` (cascade logic, lines 386-447)
+- Kimai source: `dev/kimai/src/Form/Extension/SelectWithApiDataExtension.php` (API data attributes)
+- Kimai API routes: `get_customers`, `get_projects`, `get_activities` (existing REST endpoints)
+- Existing codebase: all files read from `src/`, `assets/src/`, `Resources/`
 
-## Confidence Notes
+## Confidence Assessment
 
 | Area | Confidence | Notes |
 |------|------------|-------|
-| Bundle structure | MEDIUM | Based on Kimai 2.x patterns from training data. Namespace `KimaiPlugin\` and `PluginInterface` need verification against current Kimai release. |
-| Widget registration | MEDIUM | `kimai.widget` DI tag and `WidgetInterface` / `AbstractWidgetType` hierarchy from training data. Widget interface methods may differ in current release. |
-| API controller pattern | HIGH | Standard Symfony controller patterns. Route prefix and permission attribute names should be verified. |
-| d3.js integration | HIGH | Self-contained JS bundle in `Resources/public/` is the standard Kimai plugin asset approach. |
-| Data flow | HIGH | Symfony controller -> Doctrine query -> JSON -> client JS is textbook. |
-| CSS theme variables | LOW | Actual Kimai CSS variable names need verification against running instance. Fallback values mitigate risk. |
+| Renderer refactor pattern | HIGH | Standard strategy pattern, well-understood |
+| Backend aggregation queries | HIGH | Simple SQL GROUP BY variations on existing working query |
+| Display toggle | HIGH | Pure frontend, data already present |
+| TomSelect integration approach | MEDIUM | Need to verify global availability; cascade logic is clear from reading KimaiFormSelect source |
+| Mode switcher UI | HIGH | Tabler provides segmented controls out of the box |
+| API backward compatibility | HIGH | Adding optional `mode` param with `year` default preserves existing behavior |

.planning/research/FEATURES.md

@@ -1,130 +1,138 @@
 # Feature Landscape
 
-**Domain:** Time-tracking activity heatmap dashboard widget (Kimai plugin)
+**Domain:** Time-tracking heatmap dashboard widget (v1.1 milestone -- modes, filtering, toggles)
 **Researched:** 2026-04-08
-**Overall confidence:** MEDIUM (based on training data knowledge of GitHub, GitLab, WakaTime, RescueTime, Toggl, and open-source heatmap libraries; no live verification available)
-
-## Reference Products Analyzed
-
-| Product | Heatmap Style | Key Insight |
-|---------|--------------|-------------|
-| GitHub contribution graph | Year-long calendar grid, 5 color levels, tooltips | The gold standard UX -- simple, instantly understood, no configuration needed |
-| GitLab activity calendar | Same layout as GitHub, slightly different color scheme | Proves the pattern is universal for developer audiences |
-| WakaTime | Calendar heatmap + line charts + breakdowns by language/project | Heavier analytics layer on top of the basic heatmap |
-| RescueTime | Daily productivity scores, category breakdowns, hour-of-day patterns | Focus on productivity categorization, not raw activity |
-| Toggl Track insights | Weekly/monthly bar charts, project pie charts, calendar view | More report-centric than heatmap-centric |
-| cal-heatmap (JS library) | Configurable calendar heatmap, multiple layouts | Popular open-source implementation, good API reference |
 
 ## Table Stakes
 
-Features users expect from any calendar heatmap. Missing any of these makes the widget feel broken or incomplete.
+Features that users of a multi-mode heatmap widget would expect once modes are advertised. Missing any of these makes the feature set feel unfinished.
 
 | Feature | Why Expected | Complexity | Notes |
 |---------|--------------|------------|-------|
-| Calendar grid layout (weeks x days) | This IS the product -- the GitHub-style grid is the universally recognized pattern | Medium | d3.js renders SVG grid; each cell = one day |
-| Color intensity mapping | Users expect darker = more activity, lighter = less; this is how every heatmap works | Low | 4-5 discrete color levels (empty, low, medium, high, very high) |
-| Tooltip on hover | Every reference product shows exact values on hover; without it users stare at colors guessing | Low | Show date, hours tracked, entry count |
-| Sensible default time range | GitHub shows 1 year; users expect to see something useful without configuration | Low | Default to trailing 12 months |
-| Day-of-week labels | Mon/Wed/Fri labels on the Y-axis for orientation | Low | Standard in GitHub/GitLab graphs |
-| Month labels | Column headers showing month boundaries | Low | Standard in all calendar heatmaps |
-| Empty state | Days with no entries should render as a distinct "no data" color, not be invisible | Low | Light gray or the theme's muted background color |
-| Click-through to detail | Clicking a day should take you somewhere useful | Low | Navigate to Kimai timesheet view filtered to that date (already in PROJECT.md requirements) |
-| Theme integration | Must not look like a foreign element glued onto the dashboard | Low | Use Kimai CSS variables for colors |
+| Mode switcher UI | Users need a way to switch views. Without it, modes are invisible. | Low | Use Tabler's `nav-segmented` component -- it exists specifically for toggling views within the same context. Maps to `data-bs-toggle="tab"`. Max 4-5 segments. |
+| Year-view heatmap (existing) | Already shipped in v1.0. Must remain default mode. | Done | Existing `renderHeatmap()` in `heatmap.ts` |
+| Day-of-week aggregation (week mode) | Standard "punchcard" analysis -- which weekdays are busiest. Every time-tracking analytics tool offers this. | Medium | Aggregate existing `DayEntry[]` client-side by `Date.getDay()`. No new backend query needed -- sum/average existing daily data by weekday. 7-row or 7-column chart with color intensity. |
+| Hours vs entry-count toggle | The data already has both `hours` and `count` fields. Users expect to choose which metric colors the heatmap. | Low | Toggle the `colorScale` domain between `hours` and `count`. A small segmented control or pair of radio buttons. Applies to all modes. |
+| Cascading entity pickers (customer -> project -> activity) | Kimai users see TomSelect pickers everywhere else in the app. A plain `<select>` feels foreign. Once activity filtering is promised, the cascade is expected. | Medium-High | See Complexity Notes below for full analysis of integration approach. |
+| Activity filtering | Descoped from v1.0. Now the primary reason for the entity picker upgrade. Users who filter by project will expect activity filtering too. | Medium | Backend: add `?activity=N` param to `HeatmapController::data()`, add `AND t.activity = :activity` clause to `HeatmapService::getDailyAggregation()`. Frontend: wire activity picker into fetch URL. Kimai API route `get_activities` already accepts `?project=N` for cascading. |
+| Persistent filter/mode state | Switching modes or filters then refreshing should not reset everything. | Low | Use URL query params (shareable, bookmarkable) or `localStorage`. URL params preferred. |
 
 ## Differentiators
 
-Features that elevate the widget beyond a static pretty picture. Not expected by default, but each adds meaningful value for a personal time-tracking use case.
+Features that elevate this from "yet another heatmap" to a genuinely useful time-analysis tool. Not expected, but valued.
 
 | Feature | Value Proposition | Complexity | Notes |
 |---------|-------------------|------------|-------|
-| Toggle between hours and entry count | Different questions: "how much did I work?" vs "how consistently did I track?" -- GitHub only shows one metric | Low | Button or toggle in widget header; already in PROJECT.md requirements |
-| Project/activity filter | Focus on one project at a time to see its cadence | Medium | Dropdown populated from Kimai data; re-renders heatmap on change |
-| Configurable time range | See last 3 months, 6 months, full year, or custom range | Medium | Range selector in widget header; affects data query and grid size |
-| Streak indicator | "Current streak: 12 days" -- gamification that motivates consistency | Low | Simple calculation: count consecutive non-zero days ending at today |
-| Summary stats row | Total hours, average hours/day, busiest day -- quick numbers alongside the visual | Low | Small text row below or above the heatmap |
-| Weekend vs weekday distinction | Subtle visual indicator (border, opacity) for weekends | Low | Helps distinguish work patterns from weekend work |
-| Responsive widget sizing | Widget that adapts if Kimai dashboard column width changes | Medium | SVG viewBox scaling; cell size calculation based on container width |
+| Time-of-day heatmap (day mode) | Shows *when during the day* work happens. Reveals morning-person vs night-owl patterns. Uncommon in time-tracking tools. | High | Requires new backend query: `GROUP BY HOUR(t.begin)` for hour-level aggregation. New data shape: `HourEntry { hour: number, hours: number, count: number }`. New d3 layout: 24-row/column grid. Needs new API response format or a `mode` query param. |
+| Combined day/hour matrix | Full punchcard: 7 rows (days) x 24 cols (hours). The GitHub punchcard view. Shows exactly when work happens across the week. | High | Backend: `GROUP BY DAYOFWEEK(t.begin), HOUR(t.begin)`. New data shape: `PunchcardEntry { day: number, hour: number, hours: number, count: number }`. d3 layout: 7x24 grid with circle sizes or color intensity. Most complex visualization but highest insight value. |
+| Customer-level filtering | Filter heatmap by customer (one level above project). Useful for seeing client-specific patterns. | Low | The cascade handles this naturally: customer picker drives project picker via `get_projects?customer=N`. Backend `HeatmapService` needs `?customer=N` param that joins through `t.project.customer`. |
+| Color scale legend | Small gradient bar showing what colors mean (0h to Xh). | Low | Standard d3 pattern. Horizontal gradient with tick labels. Applies to all modes. |
+| Animated transitions between modes | Smooth morphing when switching views (cells rearrange, fade, resize). | Medium | d3 `transition()` API. Key: use consistent `key` functions in `.join()` so d3 matches elements across renders. Polish, not critical. |
 
 ## Anti-Features
 
-Things to deliberately NOT build. Each would add complexity without serving the core "at a glance, see where your time went" purpose.
+Things to explicitly NOT build in v1.1.
 
 | Anti-Feature | Why Avoid | What to Do Instead |
 |--------------|-----------|-------------------|
-| Real-time updates / live refresh | Overengineered for a dashboard widget; page reload is fine for daily granularity data | Refresh data on page load only |
-| Billable vs non-billable split | Out of scope per PROJECT.md; this is personal tracking, not client billing | Single aggregate view |
-| Export/share heatmap as image | Out of scope per PROJECT.md; no audience to share with for personal use | Users can screenshot if needed |
-| Hour-of-day heatmap (2D matrix) | Different visualization entirely; scope creep that doubles the frontend work | Stick to the calendar grid; could be a separate widget later |
-| Drill-down charts within the widget | Clicking a day to show a pie chart of projects within the widget adds major complexity | Click-through to Kimai's existing timesheet/report views instead |
-| Multi-user comparison | Personal tracking tool, not a team dashboard | Single-user view only |
-| Goal setting / targets | Adds state management, settings UI, persistence -- a separate feature domain | Streak indicator covers the motivational angle simply |
-| Animated transitions on data change | Cool but adds JS complexity for near-zero utility on a dashboard widget | Instant re-render on filter change |
-| Mobile-specific layout | Out of scope per PROJECT.md; Kimai dashboard is a desktop experience | Standard responsive SVG is sufficient |
-| Custom color theme picker | Theme integration with Kimai variables is sufficient; custom palettes add a settings UI nobody needs | Use Kimai theme variables, pick a single well-tested palette |
+| Configurable date range selector | Adds significant UI complexity (date pickers, presets). The fixed 1-year window works for personal use. | Defer to v1.2+. If needed later, a simple "6mo / 1yr / 2yr" segmented control is sufficient. |
+| Multi-user comparison | This is a personal tracking tool, not a team dashboard. | Out of scope per PROJECT.md. |
+| Export/share heatmap as image | No audience for a personal tool. SVG-to-PNG is fragile. | Out of scope per PROJECT.md. |
+| Custom color theme picker | Kimai theme integration is sufficient. Adding a color picker adds options without insight. | Keep hardcoded green scale (matches GitHub convention). |
+| Real-time / auto-refresh | Refresh-on-load is fine. WebSocket or polling adds complexity for no gain. | Out of scope per PROJECT.md. |
+| Full Kimai form plugin integration | Kimai's `KimaiFormPlugin` lifecycle (`activateForm`/`destroyForm`) is designed for Symfony form pages, not standalone widgets. Coupling to it means depending on Kimai's internal JS architecture. | Use TomSelect directly. Replicate only the cascading pattern. Style with Kimai's existing TomSelect CSS (already loaded globally). See Complexity Notes. |
+| Drag-to-select date ranges | Complex interaction, ambiguous purpose (filter? zoom? export?). | Click-to-navigate to timesheet (existing) is sufficient. |
+| Drill-down charts within widget | Clicking a day to show a pie chart of projects adds major complexity. | Click-through to Kimai's existing timesheet/report views instead. |
 
 ## Feature Dependencies
 
 ```
-Calendar grid layout
-  --> Color intensity mapping (needs the grid to color)
-  --> Tooltip on hover (needs cells to attach to)
-  --> Click-through to detail (needs cells to click)
-  --> Empty state (needs grid cells for empty days)
-  --> Day/Month labels (needs the grid structure)
-
-Toggle hours/count
-  --> Requires backend to return BOTH hours and count per day
-  --> Re-maps color intensity without re-fetching data
-
-Project/activity filter
-  --> Requires backend filter parameter in data API
-  --> Dropdown populated via separate Kimai API call (projects list)
-  --> Triggers data re-fetch + full heatmap re-render
-
-Configurable time range
-  --> Requires backend date range parameter in data API
-  --> Affects grid dimensions (fewer weeks = smaller grid)
-  --> Triggers data re-fetch + full heatmap re-render
-
-Streak indicator
-  --> Depends on the same daily aggregation data as the heatmap
-  --> No additional backend work if heatmap data is already loaded
-
-Summary stats
-  --> Depends on the same daily aggregation data as the heatmap
-  --> Pure frontend calculation from existing data
+Customer picker -> Project picker -> Activity picker (cascade chain)
+Activity picker -> Activity filter param in API (backend support)
+Mode switcher UI -> All visualization modes (renders)
+Hours/count toggle -> Color scale recalculation (applies to all modes)
+Day mode (time-of-day) -> New backend aggregation query (HOUR grouping)
+Combined matrix -> New backend aggregation query (DAY + HOUR grouping)
+Week mode (day-of-week) -> NO new backend query (aggregate DayEntry[] client-side)
 ```
 
 ## MVP Recommendation
 
-**Phase 1 -- Core heatmap (all table stakes):**
-1. Calendar grid with color intensity (the product itself)
-2. Tooltips on hover
-3. Day/month labels and empty state
-4. Click-through to Kimai timesheet view
-5. Kimai theme integration
+**Phase structure for v1.1:**
 
-**Phase 2 -- Interactivity (high-value differentiators):**
-1. Toggle between hours and entry count
-2. Project/activity filter dropdown
-3. Configurable time range
+Phase 1 -- Mode Switcher + Week Mode + Toggle:
+1. **Mode switcher UI** -- Tabler `nav-segmented`, initially Year (existing) + Week modes
+2. **Week-mode (day-of-week)** -- Client-side aggregation of existing daily data, no backend changes, proves the multi-mode rendering architecture
+3. **Hours/count toggle** -- Small segmented control, applies to all modes, low effort
+4. **Rendering refactor** -- Extract shared concerns (SVG container, color scale, tooltip) into base; modes provide layout strategy
 
-**Phase 3 -- Polish (low-effort differentiators):**
-1. Streak indicator
-2. Summary stats row
-3. Weekend distinction
+Phase 2 -- Entity Pickers + Activity Filtering:
+5. **TomSelect entity pickers** -- Replace plain `<select>` with TomSelect instances, wire cascading via Kimai's API routes (`get_projects?customer=N`, `get_activities?project=N`)
+6. **Activity filtering** -- Backend `?activity=N` param + frontend wiring
+7. **Customer filtering** -- Backend `?customer=N` param (join through project.customer)
 
-**Defer indefinitely:**
-- Hour-of-day matrix, export, goals, animations, multi-user -- all anti-features for this context.
+Phase 3 -- Advanced Modes (defer or stretch):
+8. **Day mode (time-of-day)** -- Needs new backend query + new data shape
+9. **Combined day/hour matrix** -- Most complex layout, depends on hour-level backend data
+10. **Color scale legend** -- Nice polish, do alongside advanced modes
 
-**Rationale:** Phase 1 delivers a complete, useful widget. Phase 2 adds the interactivity that makes it genuinely better than just looking at Kimai's existing reports. Phase 3 is cheap polish that improves daily experience but isn't blocking.
+**Rationale:** Phase 1 proves the multi-mode rendering architecture with zero backend changes. Phase 2 improves filtering UX with Kimai-native patterns and enables activity filtering. Phase 3 adds the data-intensive visualizations requiring new queries. Each phase delivers user-visible value independently.
+
+## Complexity Notes
+
+### TomSelect Integration (the hardest part that looks easy)
+
+Kimai's TomSelect integration runs through a plugin lifecycle: `KimaiFormPlugin` -> `KimaiFormTomselectPlugin` -> `KimaiFormSelect`. The cascading logic in `_activateApiSelects()` (line 386-447 of `KimaiFormSelect.js`) listens for `change` events on selects with `data-related-select` attributes, fetches from `data-api-url` with form field interpolation (`%fieldname%` patterns), and updates the target select via `_updateOptions()` which dispatches `data-reloaded` events.
+
+**Why the plugin cannot use Kimai's system directly:**
+- Requires Kimai's `KimaiContainer` DI (for `getPlugin('api')`)
+- Requires `KimaiFormPlugin` base class registration
+- URL interpolation (`%fieldname%`) assumes Symfony form field naming conventions
+- Lifecycle hooks (`activateForm`/`destroyForm`) expect to be called by Kimai's page init
+
+**Two integration approaches:**
+
+**(a) Direct TomSelect instantiation (recommended):**
+- Import TomSelect standalone (already loaded in Kimai's global JS)
+- Create `<select>` elements styled with Kimai's TomSelect CSS classes
+- Implement simplified cascading: on customer change, `fetch('/api/projects?customer=N')`, rebuild project options, trigger activity reload
+- Use same option grouping pattern (`parentTitle` for optgroups) as Kimai API responses
+- ~100-150 lines of cascading logic, much simpler than Kimai's generic system
+
+**(b) Symfony form fields in Twig template:**
+- Render actual `CustomerType`/`ProjectType`/`ActivityType` form fields in the widget's Twig template
+- Let Kimai's existing JS auto-enhance them with TomSelect
+- Cleaner integration but requires investigation: do Kimai's form plugins activate inside widget Twig blocks?
+- Risk: widget Twig templates may not trigger Kimai's form initialization JS
+
+### Rendering Architecture Refactor
+
+Current `renderHeatmap()` is tightly coupled to the year-view grid layout. Adding modes requires a strategy pattern:
+
+- **Shared infrastructure:** SVG container creation, color scale, tooltip, empty state, resize handler
+- **Mode-specific:** `generateCells()` / layout function, axis labels, dimensions
+- Extract into: `createRenderer(mode)` that returns the appropriate layout strategy
+- Each mode is a self-contained module: `yearMode.ts`, `weekMode.ts`, `dayMode.ts`, `combinedMode.ts`
+
+### Backend Aggregation Queries
+
+| Mode | SQL Aggregation | New Backend Code? |
+|------|-----------------|-------------------|
+| Year (existing) | `GROUP BY DATE(t.date)` | No |
+| Week (day-of-week) | Client-side aggregation of daily data | No |
+| Day (time-of-day) | `GROUP BY HOUR(t.begin)` | Yes -- new method in `HeatmapService` |
+| Combined | `GROUP BY DAYOFWEEK(t.begin), HOUR(t.begin)` | Yes -- new method in `HeatmapService` |
+
+Note: day and combined modes need `t.begin` (timesheet start datetime), not `t.date`. Verify `t.begin` is available and contains time component in Kimai's Timesheet entity.
 
 ## Sources
 
-- GitHub contribution graph: well-known UX pattern (5 color levels, year grid, tooltips, contribution count)
-- GitLab activity calendar: same pattern, confirms universality
-- WakaTime dashboard: adds analytics layer (coding time heatmap, project breakdowns, streak tracking)
-- RescueTime: productivity scoring approach, hour-of-day patterns
-- Toggl Track insights: report-centric visualizations, project breakdowns
-- cal-heatmap.com: popular open-source JS calendar heatmap library, API design reference
-- All sourced from training data (no live verification available) -- MEDIUM confidence
+- Tabler segmented control: https://docs.tabler.io/ui/components/segmented-control
+- GitHub PunchCard visualization: https://github.com/vnau/punchcard
+- Segmented control UX best practices: https://mobbin.com/glossary/segmented-control
+- Apple HIG segmented controls: https://developer.apple.com/design/human-interface-guidelines/segmented-controls
+- d3 heatmap patterns: https://d3-graph-gallery.com/heatmap.html
+- Kimai form select cascading: local `dev/kimai/assets/js/forms/KimaiFormSelect.js` (lines 386-447)
+- Kimai API routes: `get_projects` at `src/API/ProjectController.php:56`, `get_activities` at `src/API/ActivityController.php:54`
+- Kimai SelectWithApiDataExtension: local `dev/kimai/src/Form/Extension/SelectWithApiDataExtension.php`
+- TomSelect: https://tom-select.js.org/

.planning/research/PITFALLS.md

@@ -1,178 +1,162 @@
 # Domain Pitfalls
 
-**Domain:** Kimai dashboard widget plugin (Symfony bundle + d3.js heatmap)
+**Domain:** Kimai heatmap plugin v1.1 -- visualization modes, TomSelect entity pickers, cascading filters, display toggle
 **Researched:** 2026-04-08
-**Note:** Web search/fetch tools were unavailable. Findings are based on training data knowledge of Kimai, Symfony bundles, d3.js, and Nix+PHP environments. All findings marked with confidence levels accordingly.
+**Confidence:** HIGH (based on direct source analysis of existing plugin code and Kimai's KimaiFormSelect internals)
 
 ## Critical Pitfalls
 
 Mistakes that cause rewrites or major issues.
 
-### Pitfall 1: Kimai Major Version Breaking Changes in Plugin API
+### Pitfall 1: KimaiFormSelect Depends on Kimai's Plugin Container -- Cannot Use It Standalone
+
+**What goes wrong:** SEED-001 suggests using Kimai's `KimaiFormSelect.js` with `data-api-url`, `data-related-select`, and `data-empty-url` attributes to get cascading for free. But `KimaiFormSelect._activateApiSelects()` calls `this.getContainer().getPlugin('api')` to make API requests (line 433-435). This requires the select to be inside a form that Kimai's JS plugin system initialized via `activateForm()`. The heatmap widget is a dashboard card, not a Symfony form.
+
+**Why it happens:** Kimai's form system (`KimaiFormSelect`, `KimaiFormPlugin`) is tightly coupled to Kimai's JS plugin container and form lifecycle. The cascading logic in `_activateApiSelects` registers a delegated `change` event listener on `document`, but the handler calls `this.getContainer().getPlugin('api')` which requires the KimaiFormSelect instance to have been created by Kimai's app initialization. Our widget's IIFE bundle runs independently.
+
+**Consequences:** Adding `data-api-url` and `data-related-select` attributes to `<select>` elements in the widget card will silently fail. No errors, just dead selects that do not cascade.
+
+**Prevention:** Roll your own cascade with plain `fetch()` calls to Kimai's API routes or (better) custom controller endpoints. The widget is already fetch-driven. Three more fetch-based selects is consistent with the existing pattern. Use plain `<select>` elements styled with Tabler CSS. Add TomSelect only if the UX demands it.
+
+**Detection:** Change the customer picker and observe whether the project picker updates. If it does not, you hit this.
+
+### Pitfall 2: Destroying and Recreating SVG Without Cleaning Up Tooltips
+
+**What goes wrong:** The current `renderHeatmap()` starts with `container.innerHTML = ''` (line 184) but tooltips are appended to `document.body` (line 267). When switching visualization modes (year -> week -> day), each render creates a new tooltip. The existing cleanup at line 263 (`document.querySelectorAll('.heatmap-tooltip').forEach(el => el.remove())`) only runs inside `renderHeatmap` -- if new modes have their own render functions without this cleanup, tooltips accumulate.
+
+**Why it happens:** The tooltip is necessarily outside the SVG container (fixed positioning to escape overflow clipping). Each render function must know to clean up the shared tooltip.
+
+**Consequences:** Multiple `.heatmap-tooltip` divs on the page. Stale tooltip positioning. Memory leaks on repeated mode switches.
+
+**Prevention:** Extract tooltip into a shared module that all visualization modes import. One tooltip div, created on first use, reused across mode switches. A single `cleanup()` function that any render path calls before rebuilding.
+
+**Detection:** Switch modes 5+ times, inspect `document.body` children for orphaned `.heatmap-tooltip` elements.
+
+### Pitfall 3: Hour-Level Aggregation Query Performance
+
+**What goes wrong:** Day-mode and combined day/hour views need time-of-day data. The current `getDailyAggregation()` groups by `DATE(t.date)` which benefits from Kimai's date index. An hour-level query (`HOUR(t.begin)` or `EXTRACT(HOUR FROM t.begin)`) applies a function to the column, defeating index usage. GROUP BY HOUR over a full year of data scans every row for that user.
+
+**Why it happens:** MySQL/MariaDB cannot use an index when a function wraps the indexed column.
+
+**Consequences:** Slow queries for users with thousands of entries. For personal use (likely <10K entries) it is noticeable latency (~200-500ms), not catastrophic. But it makes mode switching feel sluggish.
 
-**What goes wrong:** Kimai 2.x has changed its internal plugin API, event system, and widget rendering between releases without a formal deprecation cycle. A plugin built against one version silently breaks on the next. The `WidgetInterface`, dashboard rendering hooks, and Twig extensions have all shifted.
-**Why it happens:** Kimai is maintained primarily by one developer (Kevin Papst). The plugin API is not versioned independently from the application -- it evolves with Kimai core.
-**Consequences:** Plugin stops rendering, throws Symfony container errors, or silently disappears from the dashboard after a Kimai update.
 **Prevention:**
-- Pin to a specific Kimai version in composer.json (`"kimai/kimai": "^2.x"` with a tight constraint)
-- Read UPGRADING.md in the Kimai repo before each Kimai update
-- Write an integration test that boots the Symfony kernel with the plugin loaded -- this catches container/DI breakage immediately
-- Subscribe to Kimai releases (GitHub watch) for breaking change awareness
-**Detection:** Dashboard widget silently missing after update. Symfony cache clear errors. DI container compilation failures.
-**Confidence:** MEDIUM (based on Kimai's development history through early 2025)
-**Phase relevance:** Phase 1 (scaffold) -- lock version constraints early.
+1. Limit hour-level queries to a narrow date range (one week or one month, not a full year). The UI for day-mode should show a specific date range anyway.
+2. For the combined matrix, fetch raw timesheet entries for the selected range and aggregate in PHP rather than doing a complex GROUP BY.
+3. Profile with `EXPLAIN` on the actual query against the dev database.
 
-### Pitfall 2: Timezone Mismatch Between PHP and JavaScript
-
-**What goes wrong:** Kimai stores timestamps in UTC in the database. The PHP backend converts to the user's configured timezone for display. If your d3.js heatmap receives raw UTC timestamps and bins them into days client-side, days land in the wrong cells. A session logged at 23:30 Berlin time (21:30 UTC) shows up on the correct day in Kimai's timesheet but the previous day in your heatmap.
-**Why it happens:** The boundary between "server renders timezone-aware data" and "client renders timezone-aware data" is easy to get wrong, especially when aggregating by day.
-**Consequences:** Hours appear on wrong days. Totals per day are wrong. User loses trust in the widget immediately.
-**Prevention:**
-- Aggregate by day on the PHP side using the user's configured Kimai timezone (`$user->getTimezone()`)
-- Send pre-aggregated `{date: "2026-04-08", hours: 5.5, count: 3}` to the frontend -- never raw timestamps
-- The d3 heatmap should receive date strings (not timestamps) so no further timezone conversion happens client-side
-**Detection:** Compare heatmap day totals against Kimai's built-in weekly/monthly reports. Discrepancies = timezone bug.
-**Confidence:** HIGH (this is a universal time-tracking visualization issue, well-documented across domains)
-**Phase relevance:** Phase 1 (data layer) -- get the aggregation right before building the visualization.
-
-### Pitfall 3: Kimai Widget System Assumptions
-
-**What goes wrong:** Kimai's dashboard widget system expects widgets to implement specific interfaces and register via Symfony service tags. Developers coming from generic Symfony bundle development wire things up as controllers/routes instead of using the widget system, resulting in a working page but not a dashboard widget.
-**Why it happens:** Kimai's widget system is Kimai-specific, not standard Symfony. Documentation is sparse. Developers cargo-cult from Symfony controller tutorials instead of studying existing Kimai plugins.
-**Consequences:** You build a standalone page that works at `/my-heatmap` but cannot embed in the Kimai dashboard. Rework required to fit the widget interface.
-**Prevention:**
-- Study existing Kimai plugins that provide dashboard widgets (e.g., `kimai/CalendarBundle`, built-in widgets in `src/Widget/`)
-- Implement `WidgetInterface` (or extend `AbstractWidget`) from the start
-- Register as a tagged Symfony service: `kimai.widget`
-- Do not create a standalone controller -- the widget renders within the dashboard's Twig template
-**Detection:** Widget does not appear on the dashboard. No errors, just absent.
-**Confidence:** MEDIUM (based on Kimai source structure through 2024-2025)
-**Phase relevance:** Phase 1 (scaffold) -- get the widget rendering on the dashboard before writing any d3 code.
+**Detection:** Mode switch to day-view takes noticeably longer than year-view load.
 
 ## Moderate Pitfalls
 
-### Pitfall 4: d3.js Bundle Size in Kimai's Asset Pipeline
+### Pitfall 4: Mode State Lost on Filter Change
 
-**What goes wrong:** Including all of d3.js (~500KB minified) for a calendar heatmap that only needs `d3-scale`, `d3-selection`, `d3-time`, and `d3-time-format`. Kimai uses Webpack Encore for asset compilation, and a full d3 import bloats the plugin's JS bundle unnecessarily.
-**Why it happens:** `import * as d3 from 'd3'` is the most common tutorial pattern.
-**Prevention:**
-- Import only needed d3 modules: `import { select } from 'd3-selection'; import { scaleQuantize } from 'd3-scale';`
-- This reduces the d3 footprint to ~50-80KB
-- Verify with Webpack Bundle Analyzer that tree-shaking works
-**Confidence:** HIGH (well-documented d3 best practice)
-**Phase relevance:** Phase 2 (visualization) -- set up imports correctly from the first d3 code.
+**What goes wrong:** User switches to week-mode, then changes the project filter. The filter's fetch callback re-renders the visualization, but defaults back to year-mode because the mode selection is not part of the render state. The current `doRender()` function (line 339-344) always calls `renderHeatmap()` -- the year view.
 
-### Pitfall 5: Nix + PHP + Composer Dev Environment Complexity
+**Why it happens:** The current architecture has no shared state object. Mode and filter are independent UI controls that both trigger re-renders, but neither knows about the other's state.
 
-**What goes wrong:** Getting a working Kimai instance inside a Nix devshell is non-trivial. Kimai requires PHP 8.1+, specific PHP extensions (intl, gd, mbstring, zip, xml), MySQL/MariaDB or SQLite, and Composer. Nix's PHP packaging sometimes has extension version mismatches, and Kimai's `composer install` may try to download packages that conflict with Nix's hermetic approach.
-**Why it happens:** PHP ecosystem tooling (Composer, PECL extensions) assumes a mutable system. Nix is immutable. These philosophies clash in subtle ways -- e.g., Composer's `post-install-cmd` scripts that try to write to vendor directories, or PHP extensions that need specific system libraries.
-**Consequences:** Days lost fighting the dev environment before writing any plugin code. Temptation to abandon Nix and use Docker instead.
-**Prevention:**
-- Use `pkgs.php83` (or latest) with extensions via `php.withExtensions`
-- Use SQLite for the dev database (simpler than spinning up MariaDB in Nix)
-- Consider a hybrid approach: Nix provides PHP + Composer + Node, but let Composer manage vendor/ normally (don't try to Nixify Composer dependencies)
-- Set `COMPOSER_HOME` to a writable temp directory
-- Pre-seed the database with a SQL fixture, not Kimai's interactive installer
-- Test the devshell setup as the very first task -- do not proceed to plugin code until `bin/console kimai:version` works
-**Detection:** `nix develop` fails to start, or Kimai throws "extension missing" errors at runtime.
-**Confidence:** MEDIUM (based on general Nix+PHP experience; Kimai-specific Nix setup is uncommon)
-**Phase relevance:** Phase 0 / Pre-phase -- this blocks everything else. Must be solved first.
+**Consequences:** User frustration. Every filter change resets the view mode. Feels broken.
 
-### Pitfall 6: d3.js SVG Performance with 365+ Day Cells
+**Prevention:** Introduce a state object BEFORE adding the first new mode:
+```typescript
+interface WidgetState {
+  mode: 'year' | 'week' | 'day' | 'combined';
+  metric: 'hours' | 'count';
+  filters: { customerId: number | null; projectId: number | null; activityId: number | null };
+  data: HeatmapData | null;
+}
+```
+All UI actions (mode switch, filter change, metric toggle) update state, then call a single `render(state)` dispatcher that picks the right visualization function.
 
-**What goes wrong:** Rendering 365 individual `<rect>` elements in SVG is fine. But adding tooltips, hover effects, and click handlers to each cell via d3's `.on()` creates 365+ event listeners. Combined with CSS transitions, this can cause jank on lower-end machines or when the widget shares the dashboard with other widgets.
-**Why it happens:** The naive approach of binding events per-element is the d3 tutorial default.
-**Prevention:**
-- Use event delegation: attach a single mousemove/click listener to the SVG container, use `document.elementFromPoint()` or d3's `pointer()` + geometric lookup to identify the hovered cell
-- Alternatively, for 365 cells, individual listeners are actually fine in modern browsers -- only becomes a real problem at 1000+ elements. So: measure first, optimize only if dashboard feels sluggish
-- Avoid CSS `transition` on all 365 rects simultaneously (e.g., on theme change)
-**Detection:** Dashboard sluggishness. DevTools Performance tab shows long "Recalculate Style" times.
-**Confidence:** HIGH (well-understood SVG performance characteristics)
-**Phase relevance:** Phase 2 (visualization) -- implement event delegation from the start if supporting multi-year views, otherwise defer optimization.
+**Phase warning:** This refactor MUST happen before adding any new visualization mode. Retrofitting state management after multiple modes exist is painful and error-prone.
 
-### Pitfall 7: Kimai's Webpack Encore Integration for Plugins
+### Pitfall 5: Cascading API Response Format Assumptions
 
-**What goes wrong:** Kimai plugins must integrate with Kimai's existing Webpack Encore setup, not ship their own. Developers create a standalone webpack.config.js, build separately, and the assets don't load because Kimai's asset manifest doesn't know about them.
-**Why it happens:** Symfony Encore documentation describes standalone setup. Kimai's plugin asset pipeline is plugin-specific and less documented.
-**Prevention:**
-- Follow Kimai's plugin asset conventions: assets go in `Resources/public/` or use `assets/` with an `encore` entry
-- Study how existing Kimai plugins (e.g., CustomCSS, ExpensesBundle) register their JS/CSS
-- Kimai 2.x may use its own asset inclusion mechanism via Twig blocks in widget templates rather than Encore entries -- verify against the version you target
-- For d3.js, consider whether you even need Encore: a single pre-built JS file in `Resources/public/` that the widget template includes via `<script>` may be simpler and more maintainable than wiring into Encore
-**Detection:** JavaScript console shows 404 for your JS file. Widget renders but heatmap area is blank.
-**Confidence:** MEDIUM (Kimai's asset pipeline has evolved; verify against current version)
-**Phase relevance:** Phase 1 (scaffold) -- resolve asset loading before writing d3 code.
+**What goes wrong:** Kimai's `/api/projects?customer=X` returns objects with `parentTitle` (customer name), `id`, `name`, and more. Activities can be "global" (no project parent). If you build your own cascade, you must handle this format correctly -- or your own simplified format if you use custom controller endpoints.
+
+**Why it happens:** Kimai's API response shape is designed for `KimaiFormSelect._updateSelect()` which groups by `parentTitle` into optgroups. Rolling your own cascade means either parsing the same format or defining your own.
+
+**Prevention:** Use custom controller endpoints (like the existing `getUserProjects()`) that return a simple `[{id, name}]` format. This avoids parsing Kimai's complex API response structure with optgroups and `parentTitle`. Handle edge cases:
+- Customer with no projects -> empty project list
+- Project with no activities -> empty activity list
+- Global activities (no project association) -> include them when no project filter is set
+
+### Pitfall 6: Color Scale Domain Mismatch Across Modes
+
+**What goes wrong:** Year-mode uses `max(data.days, d => d.hours)` as the scale ceiling (typically 8-12). Week-mode aggregates by day-of-week over a year (totals could be 200+). Day-mode shows hour slots (0-3 range). Reusing one color scale makes week-mode cells all dark and day-mode cells all light.
+
+**Why it happens:** Each mode has fundamentally different value ranges. Easy to forget when the scale is set up once in shared code.
+
+**Prevention:** Each mode computes its own color scale domain from its own data. Extract scale creation into a factory function that accepts a data array. Never share a global scale instance.
+
+### Pitfall 7: TomSelect Bundle Size Duplication
+
+**What goes wrong:** Importing `tom-select` in `heatmap.ts` and bundling with esbuild ships a second copy (~50KB min) alongside Kimai's own TomSelect that Webpack Encore already loaded.
+
+**Why it happens:** The plugin ships a standalone IIFE bundle independent of Kimai's module system. No shared module resolution between them.
+
+**Prevention:** Do NOT bundle TomSelect. Options:
+1. **Best for personal use:** Plain `<select>` elements with Tabler CSS. For <50 projects, native browser select works fine. No TomSelect needed.
+2. **If TomSelect is needed:** Check if `window.TomSelect` exists at runtime (Kimai may expose it globally). Mark as external in esbuild config.
+3. **Fallback:** Accept the duplication if autocomplete search is essential and Kimai does not expose a global.
+
+**Recommendation:** Start with plain selects. Add TomSelect only if the list sizes demand it.
+
+### Pitfall 8: Kimai API Auth from Widget Context
+
+**What goes wrong:** If the cascade pickers call Kimai's standard API routes (`/api/customers`, `/api/projects`), those routes may require API token authentication depending on Kimai configuration.
+
+**Why it happens:** Dashboard widgets run in authenticated session context, so session cookies are sent. Kimai's API accepts session auth for browser requests. But some Kimai installations restrict API access to token-only.
+
+**Prevention:** Add thin controller endpoints in the plugin itself (`/heatmap/customers`, `/heatmap/projects`, `/heatmap/activities`) that call Kimai's repositories directly, exactly like the existing `getUserProjects()` method. This avoids API auth concerns entirely and lets you shape the response format.
+
+**Detection:** 401 responses when cascade pickers try to fetch data. Test by calling `/api/customers` from browser console on the dashboard page.
 
 ## Minor Pitfalls
 
-### Pitfall 8: Color Scale Not Adapting to Kimai Themes
+### Pitfall 9: ResizeObserver vs Window Resize
 
-**What goes wrong:** Hard-coding heatmap colors (e.g., GitHub's green palette) that clash with Kimai's dark mode or custom themes. The heatmap looks fine in default theme but illegible in dark mode.
-**Why it happens:** GitHub's green heatmap palette is the default in every tutorial. Kimai supports theme switching.
-**Prevention:**
-- Read Kimai's CSS custom properties / SCSS variables for primary/accent colors
-- Build the color scale from CSS variables: `getComputedStyle(document.documentElement).getPropertyValue('--primary-color')`
-- Use luminance-based interpolation (light background to saturated primary) rather than a fixed green palette
-- Test in both light and dark Kimai themes
-**Detection:** Visual review in dark mode -- colors wash out or become invisible.
-**Confidence:** HIGH (standard theming concern)
-**Phase relevance:** Phase 2 (visualization) -- implement theme-aware colors from the start.
+**What goes wrong:** Current code uses `window.addEventListener('resize')`. Different modes have different natural widths (week-mode is much narrower than year-mode). Kimai's sidebar toggle changes container width without a window resize event.
 
-### Pitfall 9: Missing Empty State Handling
+**Prevention:** Use `ResizeObserver` on the container element instead. It fires on any container size change regardless of cause.
 
-**What goes wrong:** New users or users with sparse data see a completely blank widget. No indication that the widget is working -- looks broken.
-**Why it happens:** Developers test with seeded data and never encounter the empty state.
-**Prevention:**
-- Show an empty state message: "No time entries in this period"
-- Handle partial data gracefully: a year view where only 2 months have data should still render the full year grid with empty (but visible) cells
-- Include the empty state in test fixtures
-**Detection:** Install plugin on a fresh Kimai instance with no time entries.
-**Confidence:** HIGH (universal UX concern)
-**Phase relevance:** Phase 2 (visualization) -- implement alongside the heatmap.
+### Pitfall 10: Entry Count Toggle Is Not Just a CSS Swap
 
-### Pitfall 10: Clicking Day Cell -- Kimai URL Structure Assumptions
+**What goes wrong:** The hours/count toggle seems trivial -- just show `d.hours` vs `d.count`. But the color scale domain must change (hours: 0-12 vs count: 0-20+), tooltips must show different labels, and stats must recalculate.
 
-**What goes wrong:** Building the "click to navigate to timesheet" URL by guessing Kimai's route structure (`/en/timesheet?date=2026-04-08`). The URL structure depends on Kimai's locale prefix, routing configuration, and filter parameter names, which change between versions.
-**Why it happens:** Hardcoding URLs instead of using Symfony's router to generate them.
-**Prevention:**
-- Generate the timesheet URL on the PHP side using Symfony's `UrlGeneratorInterface` / `router->generate()`
-- Pass the URL template to JavaScript as a data attribute: `data-timesheet-url-template="/en/timesheet/?daterange={date}~{date}"`
-- Let JS only do string interpolation on the template, never URL construction
-**Detection:** Clicking a cell leads to 404 or wrong page. Breaks when Kimai locale changes.
-**Confidence:** MEDIUM (URL parameter names need verification against current Kimai version)
-**Phase relevance:** Phase 2/3 (interactivity) -- when implementing click-to-navigate.
+**Prevention:** Treat the metric toggle as a state change that triggers a full re-render with the appropriate color scale, tooltip format, and stats calculation. The backend already returns both `hours` and `count` in `DayEntry`, so no API changes needed.
 
-### Pitfall 11: Testing d3.js Output in a Headless Environment
+### Pitfall 11: Week Start Preference Must Propagate to All Modes
 
-**What goes wrong:** PHPUnit cannot test JavaScript. Jest/Vitest cannot access a real Kimai DOM. Developers skip frontend tests entirely because "it's just a visualization."
-**Why it happens:** d3.js renders SVG in the DOM. Testing SVG output requires either a DOM environment (jsdom) or snapshot testing. Neither feels natural.
-**Prevention:**
-- Use jsdom with Vitest to test d3 rendering: create a container, run your heatmap function, assert SVG structure (number of rects, correct date attributes, color classes)
-- Separate data transformation (pure functions: input dates/hours, output cell data) from rendering (d3 DOM manipulation). Test transformations with plain unit tests -- these catch the important bugs
-- Snapshot test the SVG output for regression detection, but keep snapshots small (test one month, not a full year)
-**Detection:** Heatmap breaks after refactoring with no test catching it.
-**Confidence:** HIGH (standard d3 testing approach)
-**Phase relevance:** Phase 1 (TDD setup) -- establish the test infrastructure before writing d3 code.
+**What goes wrong:** Year-mode respects `data-week-start` (monday/sunday). Week-mode aggregation (day-of-week buckets) must also respect this -- Monday-first vs Sunday-first changes which column is "day 0". Day-mode hour bucketing is unaffected but the combined day/hour matrix is.
+
+**Prevention:** Include `weekStart` in the state object passed to all visualization modes. Test both configurations explicitly in Vitest.
+
+### Pitfall 12: Multiple Render Functions Diverging Over Time
+
+**What goes wrong:** Starting with one `renderHeatmap()` and adding `renderWeekMode()`, `renderDayMode()`, `renderCombinedMode()` as separate functions. Over time, bug fixes (tooltip positioning, accessibility, theme colors) get applied to one function but not others.
+
+**Prevention:** Extract shared concerns (tooltip management, color scale creation, cell click handling, stats rendering) into utility functions that all modes use. Each mode only implements its unique layout logic (grid generation, axis labels, cell positioning).
 
 ## Phase-Specific Warnings
 
 | Phase Topic | Likely Pitfall | Mitigation |
 |-------------|---------------|------------|
-| Dev environment (Phase 0) | Nix+PHP+Kimai setup eats days (Pitfall 5) | Timebox to 1 day. Fall back to Docker if stuck. |
-| Scaffold (Phase 1) | Widget not appearing on dashboard (Pitfall 3) | Study existing plugins first. Get empty widget visible before anything else. |
-| Scaffold (Phase 1) | Asset loading fails (Pitfall 7) | Start with inline `<script>` in Twig, migrate to proper assets after it works. |
-| Data layer (Phase 1) | Timezone-wrong day aggregation (Pitfall 2) | Aggregate in PHP, send date strings. Write test comparing against Kimai's own report. |
-| Visualization (Phase 2) | Hard-coded colors break in dark mode (Pitfall 8) | Use CSS variables from day one. |
-| Visualization (Phase 2) | Full d3 import bloats bundle (Pitfall 4) | Import specific modules only. |
-| Interactivity (Phase 2-3) | Hardcoded timesheet URLs break (Pitfall 10) | Generate URL template server-side. |
-| Maintenance (ongoing) | Kimai update breaks plugin (Pitfall 1) | Pin version, integration test that boots kernel. |
+| State management refactor | Pitfall 4 (mode state lost on filter) | Implement state object BEFORE adding any new mode |
+| Entity pickers / cascade | Pitfall 1 (KimaiFormSelect needs form lifecycle) | Roll your own cascade with fetch + plain selects |
+| Entity pickers / cascade | Pitfall 7 (TomSelect bundle duplication) | Start with plain selects, no TomSelect |
+| Cascade API endpoints | Pitfall 5 (API response format), Pitfall 8 (auth) | Own controller endpoints returning simple format |
+| Week/day modes | Pitfall 2 (tooltip cleanup), Pitfall 6 (color scale per mode) | Shared tooltip manager, per-mode scale factory |
+| Day/hour visualization | Pitfall 3 (hour aggregation query perf) | Narrow date range for hour-level queries |
+| Hours/count toggle | Pitfall 10 (not just CSS) | Full re-render with different scale and stats |
+| All new modes | Pitfall 11 (week start), Pitfall 12 (code divergence) | Shared utilities, weekStart in state, test both configs |
 
 ## Sources
 
-- Kimai documentation at kimai.org/documentation (not fetched -- web tools unavailable)
-- Kimai GitHub repository structure and plugin examples (based on training data, not live verification)
-- d3.js modular import documentation (d3js.org)
-- General Symfony bundle development practices
-- Nix PHP packaging ecosystem knowledge
-
-**Confidence note:** All findings are based on training data (cutoff ~early 2025). Kimai's plugin API, asset pipeline, and widget system should be verified against the current Kimai release before implementation begins. The Kimai ecosystem moves fast and is primarily one-developer-driven, so APIs can shift without extended deprecation periods.
+- `dev/kimai/assets/js/forms/KimaiFormSelect.js` lines 386-447: cascade logic via `_activateApiSelects`, `getContainer().getPlugin('api')` dependency at line 433
+- `dev/kimai/src/Form/Extension/SelectWithApiDataExtension.php`: wires `data-api-url`, `data-related-select`, `data-empty-url` onto Symfony EntityType form views only
+- `dev/kimai/src/Form/Type/ProjectType.php` lines 124-137: `api_data` option configures activity cascade route
+- `assets/src/heatmap.ts`: tooltip on `document.body` (line 267), `innerHTML` cleanup (line 184), resize handler (lines 392-398), `doRender` always calls year-view (line 341)
+- `src/Service/HeatmapService.php`: daily aggregation via `DATE(t.date)` GROUP BY (lines 24-31)
+- `assets/src/types.ts`: `DayEntry` has both `hours` and `count` fields
+- `.claude/projects/.../memory/project_kimai_lessons.md`: Phase 1-2 lessons on DI, widget system, testing

.planning/research/STACK.md

@@ -1,255 +1,179 @@
-# Technology Stack
+# Technology Stack: v1.1 Additions
 
-**Project:** Kimai Heatmap Plugin
+**Project:** Kimai Heatmap Plugin v1.1
 **Researched:** 2026-04-08
-**Note:** WebSearch/WebFetch unavailable. Recommendations based on training data (cutoff May 2025). Versions should be verified against current Kimai releases before starting development.
+**Scope:** NEW stack additions only. Existing validated stack (PHP 8.2, Symfony 6.4, d3 v7, TypeScript, esbuild, Vitest, PHPUnit) is not re-evaluated.
 
-## Recommended Stack
+## New Dependencies
 
-### Core Framework (Kimai Plugin)
+### TomSelect (Entity Pickers)
 
 | Technology | Version | Purpose | Why | Confidence |
 |------------|---------|---------|-----|------------|
-| PHP | 8.2+ | Plugin runtime | Kimai 2.x requires PHP 8.1 minimum; 8.2 for current features and performance. Verify against Kimai's composer.json. | MEDIUM |
-| Symfony | 6.4 LTS | Bundle framework | Kimai 2.x is built on Symfony 6.4 LTS. Plugins must match the host Symfony version exactly. | MEDIUM |
-| Kimai | 2.x (latest) | Host application | Target the current stable release. Check github.com/kimai/kimai/releases before starting. | MEDIUM |
+| tom-select | ^2.4.3 | Customer/project/activity cascading pickers | Kimai uses TomSelect 2.4.3 for all its entity pickers. Matching the version ensures visual consistency with Kimai's existing selects. ~16KB gzipped complete, ~12KB base. | HIGH |
+| @types/tom-select | latest | TypeScript definitions | Type safety for TomSelect API calls (constructor options, instance methods like `clear()`, `sync()`, `destroy()`). | HIGH |
 
-### Visualization
+**Why bundle TomSelect ourselves instead of reusing Kimai's instance:**
 
-| Technology | Version | Purpose | Why | Confidence |
-|------------|---------|---------|-----|------------|
-| d3 | ^7.9 | Core visualization library | d3 v7 is the current stable. ESM-native, tree-shakeable. Use specific sub-modules, not the full bundle. | HIGH |
-| d3-scale | ^4.0 | Color and position scales | Needed for mapping hours/counts to color intensities and day positions. | HIGH |
-| d3-selection | ^3.0 | DOM manipulation | Core d3 pattern for binidng data to SVG elements. | HIGH |
-| d3-time | ^3.1 | Date calculations | Week/day grid layout calculations for the calendar. | HIGH |
-| d3-time-format | ^4.1 | Date formatting | Tooltip and axis labels. | HIGH |
-| d3-scale-chromatic | ^3.1 | Color schemes | Provides sequential color scales (Greens, Blues) as starting points before mapping to Kimai theme vars. | HIGH |
-| d3-shape | ^3.2 | Rect generation | For the heatmap cell rectangles. | HIGH |
+Kimai bundles TomSelect inside its Webpack Encore build (`app` entry point). It is NOT exposed as a `window` global. Our plugin ships as a standalone IIFE via esbuild, loaded separately from Kimai's bundle. There is no way to import from Kimai's Webpack chunks at runtime.
 
-**Do NOT use:**
-- `cal-heatmap` or other d3-wrapper heatmap libraries: They add abstraction over d3 that limits customization (Kimai theme integration, click-to-navigate, toggle modes). Rolling your own with raw d3 modules is straightforward for a calendar heatmap and gives full control.
-- `d3` full bundle import: Import only the sub-modules you need. Keeps the asset small and avoids polluting the Kimai frontend.
+Verified by examining: `dev/kimai/webpack.config.js` (no `externals` or global exposure), `dev/kimai/assets/js/forms/KimaiFormSelect.js` (imports TomSelect as ESM module), and `dev/kimai/assets/js/KimaiLoader.js` (all form plugins are internal to the Kimai container system).
 
-### Testing
+**CSS consideration:** Kimai already loads TomSelect's CSS via its Sass pipeline. Our TomSelect instances will inherit Kimai's existing `.ts-wrapper`, `.ts-control`, `.ts-dropdown` styles automatically. We do NOT need to bundle TomSelect CSS -- only the JS.
 
-| Technology | Version | Purpose | Why | Confidence |
-|------------|---------|---------|-----|------------|
-| PHPUnit | ^10.5 or ^11.0 | Backend tests | Kimai uses PHPUnit for its own tests. Match the version Kimai ships with in its dev dependencies. | MEDIUM |
-| Vitest | ^3.0 | JS heatmap tests | Fast, ESM-native, works with d3's ESM modules out of the box. Jest struggles with ESM d3 imports without transformation config. | HIGH |
-| jsdom | (via vitest) | DOM environment | Vitest's jsdom environment provides enough DOM for d3 selection/rendering tests without a browser. | HIGH |
+**Import strategy:** Use `tom-select/dist/js/tom-select.complete` (includes change_listener plugin needed for cascading) or cherry-pick `tom-select/src/tom-select` + specific plugins. The complete bundle is fine at 16KB gzipped given we already bundle d3 modules.
 
-**Do NOT use:**
-- `Jest` for JS tests: d3 v7 is ESM-only. Jest's ESM support requires `--experimental-vm-modules` and transform config. Vitest handles ESM natively.
-- `Cypress`/`Playwright` for the heatmap: Overkill for a single widget. SVG output assertions via jsdom + snapshot testing covers the rendering. Save E2E for integration testing against a running Kimai instance if needed later.
+### No New d3 Modules Needed
 
-### Development Environment
+The existing d3 dependencies are sufficient for all four visualization modes:
 
-| Technology | Version | Purpose | Why | Confidence |
-|------------|---------|---------|-----|------------|
-| Nix flake | - | Reproducible dev env | Matches Toph's NixOS infra. Provides PHP, Node, Composer, and a local Kimai instance. | HIGH |
-| Composer | ^2.7 | PHP dependency management | Standard for Symfony/Kimai. | HIGH |
-| npm | ^10.x | JS dependency management | For d3 modules and Vitest. Simpler than yarn/pnpm for a single-widget plugin. | HIGH |
-| esbuild | ^0.24 | JS bundling | Bundle d3 modules into a single file for Kimai's asset pipeline. Faster than webpack, simpler config, handles ESM natively. | HIGH |
+| Mode | Layout Approach | d3 Modules Used |
+|------|----------------|-----------------|
+| Year (existing) | Week columns x 7 day rows | d3-selection, d3-scale, d3-time, d3-time-format, d3-array |
+| Week | 7 columns (Mon-Sun), single row of aggregated values | d3-selection, d3-scale, d3-array |
+| Day (time-of-day) | 24 columns (hours), 7 rows (days-of-week) | d3-selection, d3-scale, d3-array |
+| Combined (day/hour) | Date columns x 24 hour rows, or 7 day-of-week columns x 24 hour rows | d3-selection, d3-scale, d3-array, d3-time |
 
-**Do NOT use:**
-- `Webpack Encore`: Kimai's own frontend uses it, but for a plugin shipping a single JS file, esbuild is simpler. One build command, no Symfony Encore config to maintain.
-- `Docker` for dev: The project spec calls for Nix flake. Docker would work but adds friction on NixOS and doesn't match the user's infrastructure.
+All modes render SVG rect grids -- the same pattern as the year view. The difference is in data aggregation (backend) and grid layout math (frontend), not in d3 capabilities.
 
-### Database
+`d3-shape` (listed in v1.0 STACK.md) was never added to package.json and is not needed. Rectangles are drawn with `rect` elements via d3-selection, not d3-shape.
 
-No additional database needed. The plugin reads from Kimai's existing `kimai2_timesheet` table via Kimai's `TimesheetRepository` or a custom DQL query. No migrations required.
+## Backend Additions
 
-## Kimai Plugin Structure
+### New Query Aggregations
 
-This is the critical structural knowledge. A Kimai plugin is a Symfony bundle installed in `var/plugins/` (development) or via Composer (distribution).
+The existing `HeatmapService::getDailyAggregation()` groups by `DATE(t.date)`. New modes need:
 
-### Directory Layout
+| Mode | SQL Aggregation | New Method |
+|------|----------------|------------|
+| Week (day-of-week) | `GROUP BY DAYOFWEEK(t.date)` | `getWeekdayAggregation()` |
+| Day (time-of-day) | `GROUP BY HOUR(t.begin)` | `getHourlyAggregation()` |
+| Combined | `GROUP BY DAYOFWEEK(t.date), HOUR(t.begin)` | `getDayHourAggregation()` |
 
-```
-KimaiHeatmapBundle/
-  KimaiHeatmapBundle.php          # Bundle class, extends PluginInterface
-  DependencyInjection/
-    KimaiHeatmapExtension.php     # Loads services config
-  Resources/
-    config/
-      services.yaml               # Service definitions
-    views/
-      widget/
-        heatmap.html.twig         # Widget template
-    public/
-      heatmap.js                  # Bundled d3 heatmap (esbuild output)
-      heatmap.css                 # Widget styles
-  EventSubscriber/
-    DashboardSubscriber.php       # Registers widget on dashboard
-  Widget/
-    HeatmapWidget.php             # Widget class implementing WidgetInterface
-  Repository/
-    HeatmapRepository.php         # Data aggregation queries
-  composer.json                   # Package metadata
-  package.json                    # JS dependencies (d3, vitest)
-  esbuild.config.mjs             # JS build config
-  assets/
-    src/
-      heatmap.ts                  # Source d3 heatmap code
-    test/
-      heatmap.test.ts             # Vitest tests
-  tests/
-    Widget/
-      HeatmapWidgetTest.php       # PHPUnit tests
-    Repository/
-      HeatmapRepositoryTest.php   # PHPUnit tests
-```
+These are Doctrine DQL queries using the same `TimesheetRepository` and `QueryBuilder` pattern as the existing method. No new PHP packages needed.
 
-**Confidence: MEDIUM** -- This structure follows Kimai's documented plugin patterns as of my training data. Verify against the current plugin developer guide and existing plugins like `ExpensesBundle` or `CustomContentBundle` on GitHub.
+**Note:** Kimai stores `t.begin` (start time) and `t.end` (end time) on timesheet entries. For hourly breakdown, use `HOUR(t.begin)` to assign each entry to its starting hour. Multi-hour entries will be attributed to their start hour for simplicity; splitting across hours would require duration-proportional allocation (complex, defer to future).
 
-### Bundle Registration
+### New Controller Endpoints
 
-```php
-// KimaiHeatmapBundle.php
-namespace KimaiPlugin\KimaiHeatmapBundle;
+The existing `HeatmapController::data()` endpoint needs:
+- `mode` query param (`year|week|day|combined`, default `year`)
+- `customer` query param (for cascading filter support)
+- `activity` query param (for activity filtering)
 
-use App\Plugin\PluginInterface;
-use Symfony\Component\DependencyInjection\ContainerBuilder;
-use Symfony\Component\HttpKernel\Bundle\Bundle;
+These are additions to the existing controller, not new bundles or packages.
 
-class KimaiHeatmapBundle extends Bundle implements PluginInterface
-{
-}
-```
+### Entity Cascade Endpoints
 
-Kimai auto-discovers bundles in `var/plugins/` by scanning for classes implementing `PluginInterface`. No manual kernel registration needed.
+**Decision: Use our own endpoints, NOT Kimai's API routes.**
 
-### Dashboard Widget Registration
+Kimai's API routes (`get_customers`, `get_projects`, `get_activities`) are guarded by `#[IsGranted('API')]`, which requires the user to have the API permission. Dashboard widget users may not have API access. Additionally, Kimai's cascading logic lives in `KimaiFormSelect.js` which depends on `KimaiContainer.getPlugin('api')` -- the entire Kimai plugin system that our standalone widget cannot access.
 
-Kimai uses an event-based widget system. You implement `WidgetInterface` and subscribe to the dashboard event.
+Instead, add lightweight endpoints to our own `HeatmapController`:
+- `GET /heatmap/customers` -- customers the user has timesheet entries for
+- `GET /heatmap/projects?customer={id}` -- projects filtered by customer
+- `GET /heatmap/activities?project={id}` -- activities filtered by project
 
-```php
-// Widget/HeatmapWidget.php
-namespace KimaiPlugin\KimaiHeatmapBundle\Widget;
+These use `IS_AUTHENTICATED_REMEMBERED` + `view_own_timesheet` (same as our existing data endpoint) and query only entities the user has actually tracked time against. This is better UX anyway -- no empty customers/projects cluttering the pickers.
 
-use App\Widget\Type\AbstractWidget;
-use App\Widget\WidgetInterface;
+## UI Additions
 
-class HeatmapWidget extends AbstractWidget
-{
-    public function getTitle(): string
-    {
-        return 'Activity Heatmap';
-    }
+### Mode Switcher
 
-    public function getTemplateName(): string
-    {
-        return '@KimaiHeatmap/widget/heatmap.html.twig';
-    }
+Use Tabler's `btn-group` (segmented control) for mode switching. Tabler is Kimai's UI framework and is already loaded. No additional CSS or JS framework needed.
 
-    public function getData(array $options = []): mixed
-    {
-        // Query timesheet data, aggregate by day
-        // Return array of [date => hours/count]
-    }
-}
-```
-
-**Confidence: MEDIUM** -- Widget API may have changed. Check `App\Widget\Type\AbstractWidget` and `App\Widget\WidgetInterface` in current Kimai source.
-
-### Twig Template Pattern
-
-```twig
-{# Resources/views/widget/heatmap.html.twig #}
-{% extends '@theme/widget.html.twig' %}
-
-{% block widget_content %}
-<div id="kimai-heatmap"
-     data-entries="{{ widget.data|json_encode }}"
-     data-base-url="{{ path('timesheet') }}">
+```html
+<div class="btn-group" role="group">
+  <button class="btn btn-sm btn-outline-primary active">Year</button>
+  <button class="btn btn-sm btn-outline-primary">Week</button>
+  <button class="btn btn-sm btn-outline-primary">Day</button>
+  <button class="btn btn-sm btn-outline-primary">Combined</button>
 </div>
-{% endblock %}
-
-{% block widget_javascript %}
-<script src="{{ asset('bundles/kimaiheatmap/heatmap.js') }}"></script>
-{% endblock %}
 ```
 
-Pass data as a JSON data attribute. The JS reads it and renders the SVG. This avoids API calls and works with Kimai's server-side rendering model.
+### Display Toggle (Hours vs Entry Count)
 
-**Confidence: LOW** -- The exact Twig block names and asset path conventions should be verified against a working Kimai plugin. The `@theme/widget.html.twig` base template may differ.
+Same pattern -- `btn-group` or a simple toggle. The data is already in `DayEntry` (`hours` and `count` fields). This is purely a frontend change to switch which field drives the color scale.
 
-## Alternatives Considered
+## What NOT to Add
 
-| Category | Recommended | Alternative | Why Not |
-|----------|-------------|-------------|---------|
-| JS Visualization | d3 sub-modules | cal-heatmap | Limits customization for Kimai theme integration, click navigation, and mode toggling |
-| JS Visualization | d3 sub-modules | Chart.js matrix | Less control over calendar layout, weaker SVG customization |
-| JS Bundler | esbuild | Webpack Encore | Overkill for bundling a single widget's JS. Encore adds Symfony config overhead. |
-| JS Testing | Vitest | Jest | d3 v7 is ESM-only; Jest's ESM support requires workarounds |
-| JS Language | TypeScript | Plain JS | Type safety for the d3 code, catches data shape mismatches at build time |
-| PHP Testing | PHPUnit | Pest | Kimai's own tests use PHPUnit. Consistency with the host app matters. |
-| Dev Env | Nix flake | Docker Compose | User runs NixOS; Nix is native. Docker adds a layer. |
+| Temptation | Why Not |
+|------------|---------|
+| `d3-axis` | The new modes don't need formal axes. Simple text labels (like the existing month/day labels) are sufficient and lighter. |
+| `d3-shape` | We draw rectangles with `<rect>`, not path generators. |
+| `d3-transition` | Animations between mode switches would be nice but add complexity. Defer to polish. |
+| `chart.js` or `cal-heatmap` | Same rationale as v1.0 -- raw d3 gives us full control over Kimai theme integration. |
+| TomSelect CSS bundle | Already loaded by Kimai's Sass pipeline. Bundling it would cause style conflicts. |
+| Kimai's `KimaiFormSelect.js` | Depends on `KimaiContainer` plugin system. Our widget is standalone IIFE. |
+| `luxon` or `date-fns` | d3-time and d3-time-format handle all our date math. No need for another date library. |
 
-## TypeScript for d3
+## Updated Type Definitions
 
-Use TypeScript for the heatmap source code. d3 v7 ships with type definitions. TypeScript catches common d3 mistakes (wrong scale types, missing data fields) at build time. esbuild handles `.ts` natively.
+New types needed in `types.ts`:
 
-```json
-// tsconfig.json (minimal)
-{
-  "compilerOptions": {
-    "target": "ES2022",
-    "module": "ESNext",
-    "moduleResolution": "bundler",
-    "strict": true,
-    "noEmit": true,
-    "types": ["vitest/globals"]
-  },
-  "include": ["assets/src/**/*.ts", "assets/test/**/*.ts"]
+```typescript
+// Visualization modes
+type HeatmapMode = 'year' | 'week' | 'day' | 'combined';
+
+// Display metric toggle
+type DisplayMetric = 'hours' | 'count';
+
+// Hourly data for day/combined modes
+interface HourEntry {
+  hour: number;       // 0-23
+  dayOfWeek: number;  // 0-6 (Monday=0)
+  hours: number;
+  count: number;
+}
+
+// Weekday aggregation for week mode
+interface WeekdayEntry {
+  dayOfWeek: number;  // 0-6
+  hours: number;
+  count: number;
+}
+
+// Entity picker options
+interface CustomerOption {
+  id: number;
+  name: string;
+}
+
+interface ActivityOption {
+  id: number;
+  name: string;
 }
 ```
 
 ## Installation Commands
 
 ```bash
-# PHP dependencies (in the plugin directory)
-composer init --name="kimai/heatmap-bundle" --type="kimai-plugin"
-# No extra PHP packages needed beyond Kimai's own dependencies
+# New runtime dependency
+npm install tom-select@^2.4.3
 
-# JS dependencies
-npm init -y
-npm install d3-scale d3-selection d3-time d3-time-format d3-scale-chromatic d3-shape
-npm install -D typescript esbuild vitest jsdom @types/d3-scale @types/d3-selection @types/d3-time @types/d3-time-format @types/d3-scale-chromatic @types/d3-shape
+# New dev dependency (check if types ship with tom-select itself first)
+npm install -D @types/tom-select
 ```
 
-## Nix Flake Approach
+No new PHP/Composer dependencies required.
 
-The flake should provide:
-1. **PHP 8.2** with extensions: `mbstring`, `intl`, `pdo_mysql` (or `pdo_sqlite` for dev), `xml`, `zip`
-2. **Composer 2.x**
-3. **Node.js 22 LTS** with npm
-4. **MariaDB** or **SQLite** for the local Kimai DB
-5. A **devShell** script that clones Kimai, runs migrations, seeds test data, and symlinks the plugin into `var/plugins/`
+## esbuild Consideration
 
-SQLite is recommended for local dev to avoid running a separate DB server. Kimai supports SQLite out of the box.
+TomSelect's package includes CSS files. When importing from `tom-select`, esbuild may try to bundle CSS. Since Kimai already loads TomSelect CSS, import only the JS entry point:
 
-**Confidence: HIGH** for the Nix approach concept. The specific Kimai setup commands need verification.
+```typescript
+import TomSelect from 'tom-select/dist/js/tom-select.complete';
+```
 
-## Key Version Verification Checklist
-
-Before starting development, verify these against current sources:
-
-- [ ] Kimai latest stable version (check GitHub releases)
-- [ ] Kimai's required PHP version (check `composer.json`)
-- [ ] Kimai's Symfony version (check `composer.lock`)
-- [ ] Kimai's `WidgetInterface` API (check `src/Widget/` in Kimai source)
-- [ ] Kimai's Twig widget template blocks (check existing dashboard widgets in Kimai source)
-- [ ] Kimai's asset serving mechanism for plugins (may use Symfony AssetMapper now instead of Encore)
-- [ ] d3 v7 latest patch version on npm
+This avoids CSS duplication and style conflicts.
 
 ## Sources
 
-- Kimai plugin documentation: https://www.kimai.org/documentation/plugin-development.html
-- Kimai GitHub: https://github.com/kimai/kimai
-- d3.js documentation: https://d3js.org/
-- d3 calendar heatmap examples: https://observablehq.com/@d3/calendar
-- Vitest documentation: https://vitest.dev/
-- esbuild documentation: https://esbuild.github.io/
-
-**All sources are from training data, not live-fetched. Confidence levels reflect this limitation.**
+- Kimai TomSelect integration: `dev/kimai/assets/js/forms/KimaiFormSelect.js` (local source, verified)
+- Kimai webpack config: `dev/kimai/webpack.config.js` (local source, confirmed no TomSelect global exposure)
+- Kimai API permissions: `dev/kimai/src/API/ProjectController.php` (local source, `#[IsGranted('API')]`)
+- Kimai API cascading pattern: `dev/kimai/src/Form/Extension/SelectWithApiDataExtension.php` (local source)
+- Kimai package.json: `dev/kimai/package.json` (local source, `tom-select: ^2.4.3`)
+- [tom-select on npm](https://www.npmjs.com/package/tom-select) -- v2.5.2 latest, ~16KB gzipped
+- [tom-select v2.5.2 on Bundlephobia](https://bundlephobia.com/package/tom-select) -- bundle size analysis
+- [TomSelect documentation](https://tom-select.js.org/)

.planning/research/SUMMARY.md

@@ -1,150 +1,161 @@
 # Project Research Summary
 
-**Project:** Kimai Heatmap Plugin
-**Domain:** Time-tracking dashboard widget (Symfony bundle + d3.js visualization)
+**Project:** Kimai Heatmap Plugin v1.1 (Modes & Filtering)
+**Domain:** Time-tracking dashboard visualization -- multi-mode heatmap with cascading entity filters
 **Researched:** 2026-04-08
-**Confidence:** MEDIUM
+**Confidence:** HIGH
 
 ## Executive Summary
 
-This is a Kimai 2.x plugin that adds a GitHub-style activity heatmap to the dashboard. The product pattern is well-established: calendar grid, color intensity for activity levels, tooltips, click-through navigation. The technology choices are straightforward -- a Symfony bundle for the backend (matching Kimai's framework), d3.js sub-modules for the SVG visualization, TypeScript for type safety, and esbuild for bundling. No additional database is needed; the plugin reads from Kimai's existing timesheet table.
+v1.1 adds four visualization modes (year, week, day-of-week, day/hour combined matrix), cascading entity pickers (customer/project/activity), and an hours-vs-count display toggle to the existing heatmap widget. The existing stack (PHP 8.2, Symfony 6.4, d3 v7, TypeScript, esbuild) handles everything. The only new dependency is TomSelect for entity pickers -- and even that should be deferred until the final phase. The core work is a rendering architecture refactor (strategy pattern for modes), three new backend aggregation queries, and a state management object to coordinate filters, modes, and display metric.
 
-The recommended approach is a strict 4-phase build: plugin scaffold first (prove the widget appears on the dashboard), then data layer (aggregation API), then visualization (d3 heatmap rendering), then interactivity (filters, toggles, click navigation). This ordering is dictated by hard dependencies -- you cannot render a heatmap without data, and you cannot build data queries without a working plugin scaffold. The Nix dev environment setup is a prerequisite phase that should be timeboxed to one day.
+The recommended approach is to refactor the monolithic `renderHeatmap()` into a mode-dispatched renderer system BEFORE adding any new visualization. This is the critical sequencing insight: state management and the renderer interface must exist before the first new mode lands, or every subsequent mode will be a retrofit nightmare. Week-mode (day-of-week aggregation) should come first because it needs zero backend changes -- it aggregates existing daily data client-side -- which validates the renderer architecture cheaply. Entity pickers come last because they are the most complex integration point and everything else works fine with the existing project dropdown.
 
-The primary risks are: (1) Kimai's plugin API is under-documented and shifts between releases -- the widget interface, DI tags, and asset conventions all need verification against the target Kimai version before writing code; (2) timezone-incorrect day aggregation will produce wrong data silently -- aggregation must happen server-side in the user's configured timezone; (3) the Nix + PHP + Kimai dev environment setup can consume days if not timeboxed. All three are manageable with the mitigations outlined below.
+The primary risks are: (1) accidentally coupling to Kimai's internal KimaiFormSelect.js system, which silently fails outside Kimai's form lifecycle; (2) tooltip/DOM cleanup leaks when switching between modes; and (3) TomSelect bundle duplication. All three are well-understood and have clear preventions documented in the research. The hour-level aggregation queries (day/combined modes) are the only performance concern -- they defeat index usage -- but for personal use with <10K entries this is acceptable latency, not a blocker.
 
 ## Key Findings
 
 ### Recommended Stack
 
-The plugin is a standard Symfony bundle running inside Kimai 2.x. The frontend is a self-contained d3.js visualization bundled with esbuild and shipped as a single JS file in `Resources/public/`. No integration with Kimai's Webpack Encore build is needed or desired.
+No new PHP/Composer dependencies. One new npm dependency: `tom-select@^2.4.3` (only when entity pickers are implemented). All four visualization modes use existing d3 sub-modules -- no new d3 packages needed. `d3-shape` was listed in v1.0 research but was never needed and should not be added.
 
-**Core technologies:**
-- **PHP 8.2+ / Symfony 6.4 LTS**: Must match Kimai's runtime exactly. Verify against Kimai's `composer.json`.
-- **d3.js sub-modules** (d3-scale, d3-selection, d3-time, d3-time-format, d3-scale-chromatic, d3-shape): Selective imports keep bundle size to ~50-80KB vs ~500KB for full d3.
-- **TypeScript**: d3 v7 ships types. Catches data shape bugs at build time. esbuild handles `.ts` natively.
-- **esbuild**: Single-command bundling of d3 modules into one JS file. Simpler than Webpack Encore for a single widget.
-- **Vitest + jsdom**: ESM-native testing for d3 code. Jest struggles with d3 v7's ESM-only modules.
-- **PHPUnit**: Matches Kimai's own test framework.
-- **Nix flake**: Reproducible dev env with PHP 8.2, Composer, Node 22, SQLite.
+**New additions only:**
+- **TomSelect ^2.4.3**: Cascading entity pickers -- matches Kimai's own version for visual consistency. Bundle JS only (Kimai already loads TomSelect CSS globally). Defer to final phase.
+- **Tabler btn-group**: Mode switcher and display toggle UI -- already loaded by Kimai, zero cost.
+
+**Explicitly rejected:** cal-heatmap, d3-axis, d3-transition, d3-shape, luxon/date-fns, TomSelect CSS bundle, Kimai's KimaiFormSelect.js.
 
 ### Expected Features
 
 **Must have (table stakes):**
-- Calendar grid layout (weeks x days) with color intensity mapping
-- Tooltip on hover showing date, hours, entry count
-- Day-of-week and month labels
-- Empty state rendering (no-data days visible, not invisible)
-- Click-through to Kimai timesheet filtered by date
-- Kimai theme integration via CSS variables
-- Default trailing 12-month range
+- Mode switcher UI (segmented control) with year + week modes
+- Hours/count display toggle (data already present, purely frontend)
+- Activity filtering (backend `?activity=N` param)
+- Cascading entity pickers (customer -> project -> activity)
+- Persistent filter/mode state across re-renders
 
 **Should have (differentiators):**
-- Toggle between hours/day and entry count (different questions answered)
-- Project/activity filter dropdown
-- Configurable time range (3/6/12 months)
-- Streak indicator and summary stats row
+- Day-of-week mode (week view) -- which weekdays are busiest
+- Time-of-day mode (day view) -- when during the day work happens
+- Combined day/hour matrix -- full punchcard (7x24 grid)
+- Color scale legend
+- Customer-level filtering
 
-**Defer indefinitely:**
-- Hour-of-day matrix, export/share, goal setting, animations, multi-user, mobile layout, custom color picker -- all anti-features for a personal tracking widget.
+**Defer (v2+):**
+- Configurable date range selector
+- Animated transitions between modes
+- Drag-to-select, drill-down charts, export/share
+- Multi-user comparison, real-time refresh, custom color themes
 
 ### Architecture Approach
 
-The architecture follows a clean separation: thin Twig template (HTML shell + controls), XHR data fetching from a dedicated API controller, and client-side d3 rendering. The widget registers via Kimai's `WidgetInterface` + `kimai.widget` DI tag. Data flows from Kimai's timesheet table through a `HeatmapService` (Doctrine QueryBuilder, GROUP BY date, user-scoped), to a `HeatmapController` (JSON API), to the d3 module (SVG rendering).
+Refactor the monolithic `renderHeatmap()` into a strategy-pattern mode system. A `ModeController` dispatches to mode-specific renderers (`year.ts`, `week.ts`, `day.ts`, `combined.ts`) that share extracted utilities (tooltip, color scale, cell click handler). A centralized `HeatmapState` object tracks mode, display metric, filters, and cached data. All UI changes (mode switch, filter change, metric toggle) update state then call a unified render dispatcher. The display toggle (hours/count) re-renders from cached data without a new fetch; all other changes trigger a fetch.
 
 **Major components:**
-1. **KimaiHeatmapBundle** -- Symfony bundle class implementing `PluginInterface`, auto-discovered by Kimai
-2. **HeatmapWidget** -- `WidgetInterface` implementation, registers on dashboard, renders Twig template
-3. **HeatmapController** -- API endpoint (`/api/plugins/heatmap/data`) returning aggregated JSON
-4. **HeatmapService** -- Server-side aggregation (hours/count per day, timezone-aware, user-scoped)
-5. **d3 heatmap module** -- TypeScript, calendar grid rendering, event handling, theme integration
+1. **ModeController** -- mode switching, data fetching orchestration, state management
+2. **Renderers (year/week/day/combined)** -- mode-specific layout logic implementing a shared `ModeRenderer` interface
+3. **Shared utilities (tooltip, colorScale)** -- extracted from current `renderHeatmap()`, reused by all modes
+4. **Filter bar (filters.ts)** -- TomSelect entity pickers with cascade logic, independent of Kimai's form system
+5. **HeatmapService (PHP)** -- three new aggregation methods (`getWeekdayAggregation`, `getHourlyAggregation`, `getCombinedAggregation`)
+6. **HeatmapController (PHP)** -- `mode` and `activity` query params, custom cascade endpoints
 
 ### Critical Pitfalls
 
-1. **Kimai plugin API instability** -- Pin to a specific Kimai version. Write an integration test that boots the Symfony kernel with the plugin loaded. Subscribe to Kimai releases for breaking change awareness.
-2. **Timezone mismatch (PHP vs JS day boundaries)** -- Aggregate by day on the PHP side using `$user->getTimezone()`. Send date strings to the frontend, never raw timestamps. Compare output against Kimai's own reports.
-3. **Widget system misunderstanding** -- Use `WidgetInterface` + `kimai.widget` DI tag from the start. Do not build a standalone controller page. Study existing Kimai widgets before coding.
-4. **Asset loading failures** -- Ship prebuilt JS in `Resources/public/`, loaded via `<script>` in Twig. Do not hook into Kimai's Webpack Encore. Start with inline script as fallback.
-5. **Nix + PHP dev environment** -- Timebox to 1 day. Use SQLite. Set `COMPOSER_HOME` to a writable temp dir. Fall back to Docker if stuck.
+1. **KimaiFormSelect cannot be used standalone** -- It depends on Kimai's plugin container (`getContainer().getPlugin('api')`). Selects with `data-api-url` inside the widget card silently fail. Prevention: roll your own cascade with plain `fetch()` calls to custom controller endpoints.
+
+2. **Tooltip DOM leaks on mode switch** -- Tooltips are appended to `document.body`, outside the SVG container. `container.innerHTML = ''` does not clean them up. Prevention: shared tooltip module with a single reusable tooltip div.
+
+3. **Mode state lost on filter change** -- Current `doRender()` always calls `renderHeatmap()` (year view). Without a state object, any filter change resets the mode. Prevention: implement `HeatmapState` BEFORE adding any new mode.
+
+4. **Color scale domain mismatch across modes** -- Year mode maxes at ~12h, week mode at ~200h, day mode at ~3h. A shared scale makes some modes unreadable. Prevention: each mode computes its own color scale domain.
+
+5. **TomSelect bundle duplication** -- Kimai already bundles TomSelect but does not expose it globally. Importing it again adds ~30KB. Prevention: start with plain `<select>` elements; add TomSelect only if list sizes demand it, and verify `window.TomSelect` availability first.
 
 ## Implications for Roadmap
 
-### Phase 0: Development Environment
-**Rationale:** Everything blocks on a working Kimai instance with the plugin loaded. Nix+PHP setup is the highest-risk non-code task.
-**Delivers:** `nix develop` shell with PHP 8.2, Composer, Node 22, local Kimai on SQLite, plugin symlinked into `var/plugins/`.
-**Avoids:** Pitfall 5 (Nix+PHP complexity) -- timeboxed to 1 day with Docker fallback.
+### Phase 1: Renderer Refactor + State Management
 
-### Phase 1: Plugin Scaffold + Data Layer
-**Rationale:** Proves the plugin loads, widget appears on dashboard, and data flows correctly. These are the hardest unknowns (Kimai plugin API, widget system, timezone aggregation).
-**Delivers:** Empty widget visible on dashboard. API endpoint returning correct per-day aggregated JSON. PHPUnit tests for service and controller.
-**Addresses:** Table stakes groundwork (no visible features yet, but the pipeline works end-to-end).
-**Avoids:** Pitfalls 1, 2, 3, 7 (plugin API, timezone, widget system, asset loading).
+**Rationale:** Everything depends on this. Cannot add modes without the renderer interface. Cannot coordinate filters/modes without state management. Zero new features -- pure refactor that preserves existing behavior.
+**Delivers:** Strategy-pattern renderer system, extracted shared utilities (tooltip, colorScale), `HeatmapState` object, `ModeRenderer` interface, year-view refactored into `renderers/year.ts`.
+**Addresses:** Architectural foundation for all subsequent phases.
+**Avoids:** Pitfall 4 (mode state lost), Pitfall 2 (tooltip leaks), Pitfall 12 (renderer divergence).
 
-### Phase 2: Core Heatmap Visualization
-**Rationale:** With data flowing, build the actual product. The calendar grid with all table-stakes features is the MVP.
-**Delivers:** d3 calendar heatmap rendering from API data. Tooltips, labels, empty state, click-through, theme integration.
-**Addresses:** All table-stakes features from FEATURES.md.
-**Avoids:** Pitfalls 4, 8, 9 (d3 bundle size, color theming, empty state).
+### Phase 2: Mode Switcher + Week Mode + Display Toggle
 
-### Phase 3: Interactivity and Polish
-**Rationale:** Differentiators that make the widget genuinely useful beyond a static picture. Low complexity, high value.
-**Delivers:** Hours/count toggle, project filter dropdown, configurable time range, streak indicator, summary stats.
-**Addresses:** All differentiator features from FEATURES.md.
-**Avoids:** Pitfall 10 (hardcoded URLs -- generate timesheet URL template server-side).
+**Rationale:** First user-visible v1.1 feature with zero backend changes. Week mode aggregates existing daily data client-side. Proves the mode system works end-to-end before adding backend complexity.
+**Delivers:** Mode switcher UI (Tabler segmented control), week-mode renderer, hours/count toggle, all wired through state management.
+**Addresses:** Mode switcher UI, day-of-week mode, hours/count toggle (3 table-stakes features).
+**Avoids:** Pitfall 6 (color scale mismatch -- week mode has very different domain than year), Pitfall 10 (toggle is a full re-render, not CSS swap), Pitfall 11 (week-start must propagate).
+
+### Phase 3: Backend Aggregation + Activity Filtering + Custom Endpoints
+
+**Rationale:** Day and combined modes need new backend queries. Activity filtering needs a new query param. Custom cascade endpoints are needed for Phase 5's entity pickers and avoid API auth pitfalls. Group all backend work together.
+**Delivers:** `getHourlyAggregation()`, `getCombinedAggregation()`, `getWeekdayAggregation()` (backend optimization over client-side), `mode` query param on data endpoint, `activity` filter param, cascade endpoints (`/heatmap/customers`, `/heatmap/projects`, `/heatmap/activities`).
+**Addresses:** Backend foundation for day/combined modes, activity filtering.
+**Avoids:** Pitfall 3 (hour query performance -- profile with EXPLAIN), Pitfall 5 (API response format -- own endpoints return simple `{id, name}`), Pitfall 8 (API auth -- own endpoints use session auth).
+
+### Phase 4: Day + Combined Visualization Modes
+
+**Rationale:** Backend data is ready from Phase 3. Fill in the remaining renderers.
+**Delivers:** Day-mode (24-column hour-of-day heatmap), combined mode (7x24 punchcard matrix), color scale legend.
+**Addresses:** Time-of-day mode, combined matrix, legend (differentiator features).
+**Avoids:** Pitfall 6 (per-mode color scales), Pitfall 11 (week-start in combined matrix).
+
+### Phase 5: Entity Pickers (TomSelect Cascade)
+
+**Rationale:** Most complex integration point. Everything else works with the existing plain project dropdown. Upgrades filtering UX without blocking other features. Needs runtime verification of TomSelect global availability.
+**Delivers:** TomSelect-enhanced customer/project/activity pickers with cascading, replaces plain `<select>`, uses custom endpoints from Phase 3.
+**Addresses:** Cascading entity pickers, customer-level filtering.
+**Avoids:** Pitfall 1 (KimaiFormSelect dependency -- own cascade logic), Pitfall 7 (TomSelect duplication -- verify global first, bundle only as fallback).
 
 ### Phase Ordering Rationale
 
-- Phase 0 before everything: no plugin code without a working dev environment.
-- Phase 1 combines scaffold + data because the scaffold alone is not testable in a meaningful way -- you need data flowing to confirm the widget system integration works.
-- Phase 2 is pure frontend work that depends on Phase 1's API but is otherwise independent.
-- Phase 3 layers interactivity onto an already-working heatmap. Each feature is independently shippable.
-- This ordering front-loads risk: the hardest unknowns (Kimai plugin API, widget system, timezone handling) are resolved in Phase 1. Phases 2 and 3 use well-established d3 patterns with high confidence.
+- Phases 1-2 deliver visible value with zero backend changes, validating the architecture cheaply.
+- Phase 3 groups all backend work (queries + endpoints) to minimize PHP context-switching.
+- Phase 4 depends on Phase 3's data but is purely frontend work.
+- Phase 5 is isolated from everything else and has the most unknowns (TomSelect availability, cascade edge cases). Doing it last means it cannot block other features.
 
 ### Research Flags
 
 Phases likely needing deeper research during planning:
-- **Phase 0:** Kimai Nix setup is uncommon. May need to inspect current Kimai `composer.json` and PHP extension requirements live.
-- **Phase 1:** Kimai's `WidgetInterface`, DI tags, and route registration need verification against the target Kimai version. The plugin API documentation is sparse -- reading existing plugin source code is essential.
+- **Phase 5 (Entity Pickers):** TomSelect global availability must be verified in the dev environment before implementation. Cascade edge cases (global activities, empty lists) need testing against real data.
 
-Phases with standard patterns (skip research):
-- **Phase 2:** d3 calendar heatmap is a well-documented pattern with official Observable examples. TypeScript + esbuild bundling is straightforward.
-- **Phase 3:** Filter dropdowns, toggle buttons, and URL template interpolation are standard frontend work.
+Phases with standard patterns (skip research-phase):
+- **Phase 1 (Refactor):** Standard strategy pattern extraction. Existing code is well-understood.
+- **Phase 2 (Modes + Toggle):** Tabler segmented controls are documented. Week-mode is simple client-side aggregation.
+- **Phase 3 (Backend):** Doctrine DQL GROUP BY queries -- same pattern as existing `getDailyAggregation()`.
+- **Phase 4 (Renderers):** d3 rect grid rendering -- same pattern as year-view with different layout math.
 
 ## Confidence Assessment
 
 | Area | Confidence | Notes |
 |------|------------|-------|
-| Stack | MEDIUM | PHP/Symfony/d3 choices are solid. Exact Kimai version requirements need live verification. |
-| Features | MEDIUM-HIGH | GitHub-style heatmap is a proven pattern. Feature priorities are well-reasoned from reference products. |
-| Architecture | MEDIUM | Symfony bundle + API + d3 rendering is sound. Kimai-specific widget API details (interface methods, DI tags, Twig blocks) need verification. |
-| Pitfalls | MEDIUM-HIGH | Timezone and d3 pitfalls are universal and well-understood. Kimai-specific pitfalls (plugin API instability, asset pipeline) based on training data, not live docs. |
+| Stack | HIGH | No new dependencies except TomSelect. All tools verified against existing codebase and Kimai source. |
+| Features | HIGH | Feature set derived from existing codebase analysis and time-tracking domain conventions. Clear table-stakes vs differentiator separation. |
+| Architecture | HIGH | Based on direct reading of existing plugin code and Kimai internals. Strategy pattern is well-understood. |
+| Pitfalls | HIGH | All pitfalls identified from actual source code analysis (line numbers cited). Prevention strategies are concrete. |
 
-**Overall confidence:** MEDIUM
+**Overall confidence:** HIGH
 
 ### Gaps to Address
 
-- **Kimai widget API verification**: The exact `WidgetInterface` methods, `AbstractWidgetType` hierarchy, and `kimai.widget` DI tag must be verified against the target Kimai release. This is the single biggest unknown.
-- **Kimai asset serving for plugins**: Whether Kimai uses `assets:install` to copy `Resources/public/` to `public/bundles/` or has a different mechanism needs checking.
-- **Kimai CSS variable names**: The actual theme variable names for colors are unknown. Fallback values mitigate this, but proper theme integration requires inspecting a running Kimai instance.
-- **Kimai timesheet URL structure**: The route name and filter parameter format for click-through navigation must be verified.
-- **Twig widget template blocks**: The exact block names (`widget_content`, `widget_javascript`) and base template path need verification.
+- **TomSelect global availability:** Must verify `window.TomSelect` in browser console on Kimai dashboard before Phase 5. If not available, decision: bundle (~30KB cost) or stick with plain selects.
+- **Hour-level query performance:** Profile `GROUP BY HOUR(t.begin)` with EXPLAIN against the dev database during Phase 3. If slow, consider narrowing date range for day/combined modes or client-side aggregation of raw entries.
+- **`t.begin` time component:** Verify that Kimai's Timesheet entity stores actual time-of-day in `t.begin` (not just date). Required for day and combined modes.
+- **Week-start in DAYOFWEEK():** MySQL's `DAYOFWEEK()` returns 1=Sunday. Must map correctly based on user's week-start preference. Test both configurations.
 
 ## Sources
 
 ### Primary (HIGH confidence)
-- d3.js documentation and calendar heatmap patterns (d3js.org, Observable)
-- Symfony bundle system documentation (symfony.com)
-- Vitest and esbuild documentation
-- General timezone handling and SVG performance patterns
+- Kimai source code (`dev/kimai/`) -- KimaiFormSelect.js, webpack.config.js, API controllers, form extensions
+- Existing plugin codebase -- `assets/src/heatmap.ts`, `src/Service/HeatmapService.php`, `src/Controller/HeatmapController.php`
+- d3.js documentation: https://d3js.org/
+- TomSelect documentation: https://tom-select.js.org/
 
 ### Secondary (MEDIUM confidence)
-- Kimai plugin development documentation (kimai.org/documentation/plugin-development.html) -- from training data
-- Kimai GitHub repository structure and existing plugins -- from training data
-- Kimai widget system internals -- from training data
-
-### Tertiary (LOW confidence)
-- Kimai Twig template block names and asset path conventions -- inferred, needs validation
-- Kimai CSS custom property names -- inferred, needs validation
+- Tabler segmented control docs: https://docs.tabler.io/ui/components/segmented-control
+- d3 heatmap patterns: https://d3-graph-gallery.com/heatmap.html
+- tom-select on npm/bundlephobia (bundle size analysis)
 
 ---
 *Research completed: 2026-04-08*

.planning/seeds/SEED-002-visualization-modes.md

@@ -0,0 +1,45 @@
+---
+id: SEED-002
+status: dormant
+planted: 2026-04-08
+planted_during: v1.0 milestone completion
+trigger_when: v1.1 or next milestone
+scope: medium
+---
+
+# SEED-002: Switchable visualization modes (year/week/day/combined)
+
+## Why This Matters
+
+The current year-view heatmap shows broad patterns but hides finer-grained detail. A week-mode (day-of-week aggregation) reveals which weekdays are busiest. A day-mode (time-of-day heatmap) shows when during the day work happens. A combined day/hour matrix gives the full picture. Together, these modes turn the heatmap from a single view into a flexible time-analysis tool.
+
+## When to Surface
+
+**Trigger:** v1.1 or next milestone
+
+This seed should be presented during `/gsd-new-milestone` when the milestone
+scope matches any of these conditions:
+- Next milestone after v1.0
+- Milestone includes visualization improvements or display modes
+- Milestone includes the INTR-02 requirement (toggle between display modes)
+
+## Scope Estimate
+
+**Medium** — Each mode is a distinct d3 layout (week grid, hour grid, combined matrix) plus a mode switcher UI element. Likely 1-2 phases: one for the mode switcher + week-mode, one for day-mode + combined.
+
+## Breadcrumbs
+
+Related code and decisions found in the current codebase:
+
+- `assets/src/heatmap.ts` — current year-view rendering with `buildGrid()`, `renderHeatmap()`, week interval logic
+- `assets/src/types.ts` — `DayEntry` type (has `date`, `totalHours`, `entryCount`) — day-mode would need hour-level data
+- `src/Service/HeatmapService.php` — `getAggregatedData()` groups by DATE — hour-mode would need GROUP BY HOUR
+- `src/Controller/HeatmapController.php` — API endpoint would need a `mode` query param
+- REQUIREMENTS.md (archived) — INTR-02: "Toggle between hours-per-day and entry-count display modes" (v2 deferred)
+
+## Notes
+
+- The existing `renderHeatmap()` function could be refactored to accept a layout strategy
+- Week-mode and day-mode need different backend aggregation queries
+- Consider whether the mode switcher is tabs, a dropdown, or segmented control (Tabler has all three)
+- The combined day/hour matrix is the most complex — may warrant its own phase

Controller/HeatmapController.php

@@ -21,16 +21,51 @@ class HeatmapController extends AbstractController
         $end = new \DateTimeImmutable('today');
         $begin = $end->modify('-1 year');
 
+        $mode = $request->query->getString('mode', 'daily');
+        $projectId = $request->query->getInt('project') ?: null;
+        $customerId = $request->query->getInt('customer') ?: null;
+        $activityId = $request->query->getInt('activity') ?: null;
+
+        $range = ['begin' => $begin->format('Y-m-d'), 'end' => $end->format('Y-m-d')];
+
+        return match ($mode) {
+            'hourly' => new JsonResponse([
+                'hours' => $service->getHourlyAggregation($user, $begin, $end, $projectId, $customerId, $activityId),
+                'range' => $range,
+            ]),
+            'dayhour' => new JsonResponse([
+                'matrix' => $service->getDayHourAggregation($user, $begin, $end, $projectId, $customerId, $activityId, $user->getFirstDayOfWeek()),
+                'range' => $range,
+            ]),
+            default => new JsonResponse([
+                'days' => $service->getDailyAggregation($user, $begin, $end, $projectId, $customerId, $activityId),
+                'range' => $range,
+            ]),
+        };
+    }
+
+    #[Route(path: '/customers', name: 'heatmap_customers', methods: ['GET'])]
+    #[IsGranted('view_own_timesheet')]
+    public function customers(HeatmapService $service): JsonResponse
+    {
+        return new JsonResponse($service->getUserCustomers($this->getUser()));
+    }
+
+    #[Route(path: '/projects', name: 'heatmap_projects', methods: ['GET'])]
+    #[IsGranted('view_own_timesheet')]
+    public function projects(Request $request, HeatmapService $service): JsonResponse
+    {
+        $customerId = $request->query->getInt('customer') ?: null;
+
+        return new JsonResponse($service->getUserProjects($this->getUser(), $customerId));
+    }
+
+    #[Route(path: '/activities', name: 'heatmap_activities', methods: ['GET'])]
+    #[IsGranted('view_own_timesheet')]
+    public function activities(Request $request, HeatmapService $service): JsonResponse
+    {
         $projectId = $request->query->getInt('project') ?: null;
 
-        $days = $service->getDailyAggregation($user, $begin, $end, $projectId);
-
-        return new JsonResponse([
-            'days' => $days,
-            'range' => [
-                'begin' => $begin->format('Y-m-d'),
-                'end' => $end->format('Y-m-d'),
-            ],
-        ]);
+        return new JsonResponse($service->getUserActivities($this->getUser(), $projectId));
     }
 }

Resources/public/heatmap.css

@@ -93,3 +93,7 @@
   color: var(--tblr-body-color);
   font-weight: 600;
 }
+
+.heatmap-week-cell {
+  cursor: default;
+}

Resources/views/widget/heatmap.html.twig

@@ -1,6 +1,9 @@
 {% embed '@theme/embeds/card.html.twig' with {'margin_bottom': 0} %}
     {% block box_title %}
+        <div style="display: flex; align-items: center; gap: 12px; flex-wrap: wrap;">
             {{ title }}
+            <div id="heatmap-controls" style="display: flex; gap: 8px; margin-left: auto;"></div>
+        </div>
     {% endblock %}
     {% block box_body %}
         <link rel="stylesheet" href="{{ asset('bundles/kimaiheatmap/heatmap.css') }}">

Service/HeatmapService.php

@@ -4,17 +4,20 @@ namespace KimaiPlugin\KimaiHeatmapBundle\Service;
 
 use App\Entity\User;
 use App\Repository\TimesheetRepository;
+use Doctrine\ORM\EntityManagerInterface;
 
 class HeatmapService
 {
-    public function __construct(private readonly TimesheetRepository $repository)
-    {
+    public function __construct(
+        private readonly TimesheetRepository $repository,
+        private readonly EntityManagerInterface $entityManager,
+    ) {
     }
 
     /**
      * @return array<int, array{date: string, hours: float, count: int}>
      */
-    public function getDailyAggregation(User $user, \DateTimeInterface $begin, \DateTimeInterface $end, ?int $projectId = null): array
+    public function getDailyAggregation(User $user, \DateTimeInterface $begin, \DateTimeInterface $end, ?int $projectId = null, ?int $customerId = null, ?int $activityId = null): array
     {
         $qb = $this->repository->createQueryBuilder('t');
 
@@ -37,6 +40,17 @@ class HeatmapService
                ->setParameter('project', $projectId);
         }
 
+        if ($activityId !== null) {
+            $qb->andWhere($qb->expr()->eq('t.activity', ':activity'))
+               ->setParameter('activity', $activityId);
+        }
+
+        if ($customerId !== null) {
+            $qb->join('t.project', 'p')
+               ->andWhere($qb->expr()->eq('p.customer', ':customer'))
+               ->setParameter('customer', $customerId);
+        }
+
         $results = $qb->getQuery()->getResult();
 
         return array_map(function (array $row) {
@@ -48,10 +62,112 @@ class HeatmapService
         }, $results);
     }
 
+    /**
+     * @return array<int, array{hour: int, hours: float, count: int}>
+     */
+    public function getHourlyAggregation(User $user, \DateTimeInterface $begin, \DateTimeInterface $end, ?int $projectId = null, ?int $customerId = null, ?int $activityId = null): array
+    {
+        $conn = $this->entityManager->getConnection();
+        $offsetStr = $this->computeTimezoneOffset($user);
+
+        $sql = 'SELECT HOUR(CONVERT_TZ(t.start_time, \'+00:00\', :tz)) as hour_slot,
+                       COALESCE(SUM(t.duration), 0) as duration,
+                       COUNT(t.id) as count
+                FROM kimai2_timesheet t
+                WHERE t.user = :user
+                  AND t.date_tz BETWEEN :begin AND :end
+                  AND t.end_time IS NOT NULL';
+
+        $params = [
+            'tz' => $offsetStr,
+            'user' => $user->getId(),
+            'begin' => $begin->format('Y-m-d'),
+            'end' => $end->format('Y-m-d'),
+        ];
+
+        if ($projectId !== null) {
+            $sql .= ' AND t.project_id = :project';
+            $params['project'] = $projectId;
+        }
+
+        if ($activityId !== null) {
+            $sql .= ' AND t.activity_id = :activity';
+            $params['activity'] = $activityId;
+        }
+
+        if ($customerId !== null) {
+            $sql .= ' AND t.project_id IN (SELECT p.id FROM kimai2_projects p WHERE p.customer_id = :customer)';
+            $params['customer'] = $customerId;
+        }
+
+        $sql .= ' GROUP BY hour_slot ORDER BY hour_slot ASC';
+
+        $results = $conn->executeQuery($sql, $params)->fetchAllAssociative();
+
+        return array_map(fn(array $row) => [
+            'hour' => (int) $row['hour_slot'],
+            'hours' => round((int) $row['duration'] / 3600, 2),
+            'count' => (int) $row['count'],
+        ], $results);
+    }
+
+    /**
+     * @return array<int, array{day: int, hour: int, hours: float, count: int}>
+     */
+    public function getDayHourAggregation(User $user, \DateTimeInterface $begin, \DateTimeInterface $end, ?int $projectId = null, ?int $customerId = null, ?int $activityId = null, string $weekStart = 'monday'): array
+    {
+        $conn = $this->entityManager->getConnection();
+        $offsetStr = $this->computeTimezoneOffset($user);
+
+        $sql = 'SELECT DAYOFWEEK(t.date_tz) as dow,
+                       HOUR(CONVERT_TZ(t.start_time, \'+00:00\', :tz)) as hour_slot,
+                       COALESCE(SUM(t.duration), 0) as duration,
+                       COUNT(t.id) as count
+                FROM kimai2_timesheet t
+                WHERE t.user = :user
+                  AND t.date_tz BETWEEN :begin AND :end
+                  AND t.end_time IS NOT NULL';
+
+        $params = [
+            'tz' => $offsetStr,
+            'user' => $user->getId(),
+            'begin' => $begin->format('Y-m-d'),
+            'end' => $end->format('Y-m-d'),
+        ];
+
+        if ($projectId !== null) {
+            $sql .= ' AND t.project_id = :project';
+            $params['project'] = $projectId;
+        }
+
+        if ($activityId !== null) {
+            $sql .= ' AND t.activity_id = :activity';
+            $params['activity'] = $activityId;
+        }
+
+        if ($customerId !== null) {
+            $sql .= ' AND t.project_id IN (SELECT p.id FROM kimai2_projects p WHERE p.customer_id = :customer)';
+            $params['customer'] = $customerId;
+        }
+
+        $sql .= ' GROUP BY dow, hour_slot ORDER BY dow, hour_slot';
+
+        $results = $conn->executeQuery($sql, $params)->fetchAllAssociative();
+
+        $weekStartOffset = ($weekStart === 'sunday') ? 1 : 2;
+
+        return array_map(fn(array $row) => [
+            'day' => ((int) $row['dow'] - $weekStartOffset + 7) % 7,
+            'hour' => (int) $row['hour_slot'],
+            'hours' => round((int) $row['duration'] / 3600, 2),
+            'count' => (int) $row['count'],
+        ], $results);
+    }
+
     /**
      * @return array<int, array{id: int, name: string}>
      */
-    public function getUserProjects(User $user): array
+    public function getUserProjects(User $user, ?int $customerId = null): array
     {
         $qb = $this->repository->createQueryBuilder('t');
         $qb->select('DISTINCT IDENTITY(t.project) as projectId, p.name')
@@ -61,9 +177,69 @@ class HeatmapService
            ->setParameter('user', $user)
            ->orderBy('p.name', 'ASC');
 
+        if ($customerId !== null) {
+            $qb->join('p.customer', 'c')
+               ->andWhere($qb->expr()->eq('c.id', ':customer'))
+               ->setParameter('customer', $customerId);
+        }
+
         return array_map(fn(array $row) => [
             'id' => (int) $row['projectId'],
             'name' => $row['name'],
         ], $qb->getQuery()->getResult());
     }
+
+    /**
+     * @return array<int, array{id: int, name: string}>
+     */
+    public function getUserCustomers(User $user): array
+    {
+        $qb = $this->repository->createQueryBuilder('t');
+        $qb->select('DISTINCT IDENTITY(p.customer) as customerId, c.name')
+           ->join('t.project', 'p')
+           ->join('p.customer', 'c')
+           ->andWhere($qb->expr()->eq('t.user', ':user'))
+           ->andWhere($qb->expr()->isNotNull('t.end'))
+           ->setParameter('user', $user)
+           ->orderBy('c.name', 'ASC');
+
+        return array_map(fn(array $row) => [
+            'id' => (int) $row['customerId'],
+            'name' => $row['name'],
+        ], $qb->getQuery()->getResult());
+    }
+
+    /**
+     * @return array<int, array{id: int, name: string}>
+     */
+    public function getUserActivities(User $user, ?int $projectId = null): array
+    {
+        $qb = $this->repository->createQueryBuilder('t');
+        $qb->select('DISTINCT IDENTITY(t.activity) as activityId, a.name')
+           ->join('t.activity', 'a')
+           ->andWhere($qb->expr()->eq('t.user', ':user'))
+           ->andWhere($qb->expr()->isNotNull('t.end'))
+           ->setParameter('user', $user)
+           ->orderBy('a.name', 'ASC');
+
+        if ($projectId !== null) {
+            $qb->andWhere($qb->expr()->eq('t.project', ':project'))
+               ->setParameter('project', $projectId);
+        }
+
+        return array_map(fn(array $row) => [
+            'id' => (int) $row['activityId'],
+            'name' => $row['name'],
+        ], $qb->getQuery()->getResult());
+    }
+
+    private function computeTimezoneOffset(User $user): string
+    {
+        $tz = new \DateTimeZone($user->getTimezone());
+        $offset = $tz->getOffset(new \DateTime('now', new \DateTimeZone('UTC')));
+        $hours = intdiv($offset, 3600);
+        $minutes = abs(intdiv($offset % 3600, 60));
+
+        return sprintf('%+03d:%02d', $hours, $minutes);
+    }
 }

Tests/Controller/HeatmapControllerTest.php

@@ -11,6 +11,25 @@ use Symfony\Component\HttpFoundation\Request;
 
 class HeatmapControllerTest extends TestCase
 {
+    private function createControllerWithUser(): array
+    {
+        $user = $this->createMock(User::class);
+        $user->method('getTimezone')->willReturn('Europe/Berlin');
+        $user->method('getFirstDayOfWeek')->willReturn('monday');
+
+        $controller = new HeatmapController();
+        $container = $this->createMock(\Symfony\Component\DependencyInjection\ContainerInterface::class);
+        $tokenStorage = $this->createMock(\Symfony\Component\Security\Core\Authentication\Token\Storage\TokenStorageInterface::class);
+        $token = $this->createMock(\Symfony\Component\Security\Core\Authentication\Token\TokenInterface::class);
+        $token->method('getUser')->willReturn($user);
+        $tokenStorage->method('getToken')->willReturn($token);
+        $container->method('has')->willReturn(true);
+        $container->method('get')->willReturn($tokenStorage);
+        $controller->setContainer($container);
+
+        return [$controller, $user];
+    }
+
     public function testDataReturnsJsonWithDaysAndRange(): void
     {
         $mockDays = [
@@ -20,18 +39,7 @@ class HeatmapControllerTest extends TestCase
         $service = $this->createMock(HeatmapService::class);
         $service->method('getDailyAggregation')->willReturn($mockDays);
 
-        $controller = new HeatmapController();
-
-        // Mock user via reflection (AbstractController::getUser is protected)
-        $user = $this->createMock(User::class);
-        $container = $this->createMock(\Symfony\Component\DependencyInjection\ContainerInterface::class);
-        $tokenStorage = $this->createMock(\Symfony\Component\Security\Core\Authentication\Token\Storage\TokenStorageInterface::class);
-        $token = $this->createMock(\Symfony\Component\Security\Core\Authentication\Token\TokenInterface::class);
-        $token->method('getUser')->willReturn($user);
-        $tokenStorage->method('getToken')->willReturn($token);
-        $container->method('has')->willReturn(true);
-        $container->method('get')->willReturn($tokenStorage);
-        $controller->setContainer($container);
+        [$controller, $user] = $this->createControllerWithUser();
 
         $response = $controller->data(new Request(), $service);
 
@@ -43,4 +51,143 @@ class HeatmapControllerTest extends TestCase
         $this->assertArrayHasKey('begin', $data['range']);
         $this->assertArrayHasKey('end', $data['range']);
     }
+
+    public function testDataReturnsHourlyMode(): void
+    {
+        $mockHours = [['hour' => 9, 'hours' => 2.0, 'count' => 5]];
+
+        $service = $this->createMock(HeatmapService::class);
+        $service->method('getHourlyAggregation')->willReturn($mockHours);
+
+        [$controller, $user] = $this->createControllerWithUser();
+
+        $request = new Request(['mode' => 'hourly']);
+        $response = $controller->data($request, $service);
+
+        $data = json_decode($response->getContent(), true);
+        $this->assertArrayHasKey('hours', $data);
+        $this->assertArrayHasKey('range', $data);
+        $this->assertEquals($mockHours, $data['hours']);
+    }
+
+    public function testDataReturnsDayHourMode(): void
+    {
+        $mockMatrix = [['day' => 0, 'hour' => 9, 'hours' => 1.0, 'count' => 1]];
+
+        $service = $this->createMock(HeatmapService::class);
+        $service->method('getDayHourAggregation')->willReturn($mockMatrix);
+
+        [$controller, $user] = $this->createControllerWithUser();
+
+        $request = new Request(['mode' => 'dayhour']);
+        $response = $controller->data($request, $service);
+
+        $data = json_decode($response->getContent(), true);
+        $this->assertArrayHasKey('matrix', $data);
+        $this->assertArrayHasKey('range', $data);
+        $this->assertEquals($mockMatrix, $data['matrix']);
+    }
+
+    public function testDataDefaultsToDailyMode(): void
+    {
+        $mockDays = [['date' => '2026-01-01', 'hours' => 1.0, 'count' => 2]];
+
+        $service = $this->createMock(HeatmapService::class);
+        $service->method('getDailyAggregation')->willReturn($mockDays);
+
+        [$controller, $user] = $this->createControllerWithUser();
+
+        $request = new Request(); // no mode param
+        $response = $controller->data($request, $service);
+
+        $data = json_decode($response->getContent(), true);
+        $this->assertArrayHasKey('days', $data);
+        $this->assertEquals($mockDays, $data['days']);
+    }
+
+    public function testDataPassesFilterParams(): void
+    {
+        $service = $this->createMock(HeatmapService::class);
+        $service->expects($this->once())
+            ->method('getDailyAggregation')
+            ->with(
+                $this->anything(),  // user
+                $this->anything(),  // begin
+                $this->anything(),  // end
+                $this->isNull(),    // projectId
+                3,                  // customerId
+                5                   // activityId
+            )
+            ->willReturn([]);
+
+        [$controller, $user] = $this->createControllerWithUser();
+
+        $request = new Request(['activity' => '5', 'customer' => '3']);
+        $controller->data($request, $service);
+    }
+
+    public function testCustomersEndpoint(): void
+    {
+        $mockCustomers = [['id' => 1, 'name' => 'Acme']];
+
+        $service = $this->createMock(HeatmapService::class);
+        $service->method('getUserCustomers')->willReturn($mockCustomers);
+
+        [$controller, $user] = $this->createControllerWithUser();
+
+        $response = $controller->customers($service);
+
+        $this->assertInstanceOf(JsonResponse::class, $response);
+        $data = json_decode($response->getContent(), true);
+        $this->assertEquals($mockCustomers, $data);
+    }
+
+    public function testProjectsEndpoint(): void
+    {
+        $mockProjects = [['id' => 1, 'name' => 'Web']];
+
+        $service = $this->createMock(HeatmapService::class);
+        $service->method('getUserProjects')->willReturn($mockProjects);
+
+        [$controller, $user] = $this->createControllerWithUser();
+
+        $response = $controller->projects(new Request(), $service);
+
+        $this->assertInstanceOf(JsonResponse::class, $response);
+        $data = json_decode($response->getContent(), true);
+        $this->assertEquals($mockProjects, $data);
+    }
+
+    public function testActivitiesEndpoint(): void
+    {
+        $mockActivities = [['id' => 1, 'name' => 'Dev']];
+
+        $service = $this->createMock(HeatmapService::class);
+        $service->method('getUserActivities')->willReturn($mockActivities);
+
+        [$controller, $user] = $this->createControllerWithUser();
+
+        $response = $controller->activities(new Request(), $service);
+
+        $this->assertInstanceOf(JsonResponse::class, $response);
+        $data = json_decode($response->getContent(), true);
+        $this->assertEquals($mockActivities, $data);
+    }
+
+    public function testActivitiesWithProjectParam(): void
+    {
+        $service = $this->createMock(HeatmapService::class);
+        $service->expects($this->once())
+            ->method('getUserActivities')
+            ->with(
+                $this->anything(),  // user
+                3                   // projectId
+            )
+            ->willReturn([]);
+
+        [$controller, $user] = $this->createControllerWithUser();
+
+        $request = new Request(['project' => '3']);
+        $controller->activities($request, $service);
+    }
 }

Tests/Service/HeatmapServiceTest.php

@@ -63,6 +63,172 @@ class HeatmapServiceTest extends TestCase
         $this->assertEquals(1.51, $result[0]['hours']);
     }
 
+    public function testGetHourlyAggregationReturnsFormattedResults(): void
+    {
+        $service = $this->createServiceWithNativeResults([
+            ['hour_slot' => 9, 'duration' => 7200, 'count' => 5],
+        ]);
+
+        $user = $this->createMock(User::class);
+        $user->method('getTimezone')->willReturn('Europe/Berlin');
+        $user->method('getId')->willReturn(1);
+
+        $result = $service->getHourlyAggregation(
+            $user,
+            new \DateTimeImmutable('2026-04-01'),
+            new \DateTimeImmutable('2026-04-30')
+        );
+
+        $this->assertCount(1, $result);
+        $this->assertSame(9, $result[0]['hour']);
+        $this->assertSame(2.0, $result[0]['hours']);
+        $this->assertSame(5, $result[0]['count']);
+    }
+
+    public function testGetHourlyAggregationReturnsEmptyForNoData(): void
+    {
+        $service = $this->createServiceWithNativeResults([]);
+
+        $user = $this->createMock(User::class);
+        $user->method('getTimezone')->willReturn('UTC');
+        $user->method('getId')->willReturn(1);
+
+        $result = $service->getHourlyAggregation(
+            $user,
+            new \DateTimeImmutable('2026-04-01'),
+            new \DateTimeImmutable('2026-04-30')
+        );
+
+        $this->assertCount(0, $result);
+    }
+
+    public function testGetDayHourAggregationReturnsFormattedResults(): void
+    {
+        // MySQL DAYOFWEEK: 2 = Monday
+        // weekStart=monday -> Monday = day 0
+        $service = $this->createServiceWithNativeResults([
+            ['dow' => 2, 'hour_slot' => 14, 'duration' => 3600, 'count' => 1],
+        ]);
+
+        $user = $this->createMock(User::class);
+        $user->method('getTimezone')->willReturn('Europe/Berlin');
+        $user->method('getId')->willReturn(1);
+
+        $result = $service->getDayHourAggregation(
+            $user,
+            new \DateTimeImmutable('2026-04-01'),
+            new \DateTimeImmutable('2026-04-30'),
+            null, null, null,
+            'monday'
+        );
+
+        $this->assertCount(1, $result);
+        $this->assertSame(0, $result[0]['day']);
+        $this->assertSame(14, $result[0]['hour']);
+        $this->assertSame(1.0, $result[0]['hours']);
+        $this->assertSame(1, $result[0]['count']);
+    }
+
+    public function testGetDayHourAggregationSundayStart(): void
+    {
+        // MySQL DAYOFWEEK: 2 = Monday
+        // weekStart=sunday -> Monday = day 1
+        $service = $this->createServiceWithNativeResults([
+            ['dow' => 2, 'hour_slot' => 14, 'duration' => 3600, 'count' => 1],
+        ]);
+
+        $user = $this->createMock(User::class);
+        $user->method('getTimezone')->willReturn('Europe/Berlin');
+        $user->method('getId')->willReturn(1);
+
+        $result = $service->getDayHourAggregation(
+            $user,
+            new \DateTimeImmutable('2026-04-01'),
+            new \DateTimeImmutable('2026-04-30'),
+            null, null, null,
+            'sunday'
+        );
+
+        $this->assertCount(1, $result);
+        $this->assertSame(1, $result[0]['day']);
+        $this->assertSame(14, $result[0]['hour']);
+        $this->assertSame(1.0, $result[0]['hours']);
+        $this->assertSame(1, $result[0]['count']);
+    }
+
+    public function testGetDailyAggregationWithActivityFilter(): void
+    {
+        $service = $this->createServiceWithResults([
+            ['day' => '2026-04-01', 'duration' => 3600, 'count' => 1],
+        ]);
+
+        $result = $service->getDailyAggregation(
+            $this->createMock(User::class),
+            new \DateTimeImmutable('2026-04-01'),
+            new \DateTimeImmutable('2026-04-30'),
+            null,
+            null,
+            42
+        );
+
+        $this->assertCount(1, $result);
+    }
+
+    public function testGetDailyAggregationWithCustomerFilter(): void
+    {
+        $service = $this->createServiceWithResults([
+            ['day' => '2026-04-01', 'duration' => 3600, 'count' => 1],
+        ]);
+
+        $result = $service->getDailyAggregation(
+            $this->createMock(User::class),
+            new \DateTimeImmutable('2026-04-01'),
+            new \DateTimeImmutable('2026-04-30'),
+            null,
+            99
+        );
+
+        $this->assertCount(1, $result);
+    }
+
+    public function testGetUserCustomersReturnsFormattedResults(): void
+    {
+        $service = $this->createServiceWithResults([
+            ['customerId' => 1, 'name' => 'Acme'],
+        ]);
+
+        $result = $service->getUserCustomers($this->createMock(User::class));
+
+        $this->assertCount(1, $result);
+        $this->assertSame(1, $result[0]['id']);
+        $this->assertSame('Acme', $result[0]['name']);
+    }
+
+    public function testGetUserActivitiesReturnsFormattedResults(): void
+    {
+        $service = $this->createServiceWithResults([
+            ['activityId' => 5, 'name' => 'Dev'],
+        ]);
+
+        $result = $service->getUserActivities($this->createMock(User::class));
+
+        $this->assertCount(1, $result);
+        $this->assertSame(5, $result[0]['id']);
+        $this->assertSame('Dev', $result[0]['name']);
+    }
+
+    public function testGetUserActivitiesWithProjectScope(): void
+    {
+        $service = $this->createServiceWithResults([
+            ['activityId' => 5, 'name' => 'Dev'],
+        ]);
+
+        $result = $service->getUserActivities($this->createMock(User::class), 10);
+
+        $this->assertCount(1, $result);
+        $this->assertSame(5, $result[0]['id']);
+    }
+
     private function createServiceWithResults(array $results): HeatmapService
     {
         $query = $this->createMock(AbstractQuery::class);
@@ -75,12 +241,31 @@ class HeatmapServiceTest extends TestCase
         $qb->method('setParameter')->willReturnSelf();
         $qb->method('groupBy')->willReturnSelf();
         $qb->method('orderBy')->willReturnSelf();
+        $qb->method('join')->willReturnSelf();
         $qb->method('expr')->willReturn(new Expr());
         $qb->method('getQuery')->willReturn($query);
 
         $repo = $this->createMock(TimesheetRepository::class);
         $repo->method('createQueryBuilder')->willReturn($qb);
 
-        return new HeatmapService($repo);
+        $em = $this->createMock(\Doctrine\ORM\EntityManagerInterface::class);
+
+        return new HeatmapService($repo, $em);
+    }
+
+    private function createServiceWithNativeResults(array $results): HeatmapService
+    {
+        $statement = $this->createMock(\Doctrine\DBAL\Result::class);
+        $statement->method('fetchAllAssociative')->willReturn($results);
+
+        $connection = $this->createMock(\Doctrine\DBAL\Connection::class);
+        $connection->method('executeQuery')->willReturn($statement);
+
+        $em = $this->createMock(\Doctrine\ORM\EntityManagerInterface::class);
+        $em->method('getConnection')->willReturn($connection);
+
+        $repo = $this->createMock(TimesheetRepository::class);
+
+        return new HeatmapService($repo, $em);
     }
 }

Tests/bootstrap.php

@@ -7,7 +7,22 @@ $autoloadPaths = [
 
 foreach ($autoloadPaths as $path) {
     if (file_exists($path)) {
-        require_once $path;
+        $loader = require_once $path;
+        // In worktree contexts, register a prepended autoloader so worktree classes
+        // take priority over the classmap entries pointing to the main repo symlink.
+        $pluginRoot = dirname(__DIR__) . '/';
+        spl_autoload_register(function (string $class) use ($pluginRoot) {
+            $prefix = 'KimaiPlugin\\KimaiHeatmapBundle\\';
+            if (str_starts_with($class, $prefix)) {
+                $relative = str_replace('\\', '/', substr($class, strlen($prefix)));
+                $file = $pluginRoot . $relative . '.php';
+                if (file_exists($file)) {
+                    require $file;
+                    return true;
+                }
+            }
+            return false;
+        }, true, true); // prepend=true
         return;
     }
 }

assets/src/heatmap.ts

@@ -1,305 +1,15 @@
-import { select } from 'd3-selection';
-import { scaleQuantize } from 'd3-scale';
-import { timeMonday, timeSunday, timeDay, timeMonth } from 'd3-time';
-import { timeFormat } from 'd3-time-format';
-import { max } from 'd3-array';
-import type { DayEntry, HeatmapData, HeatmapConfig, ProjectOption } from './types';
+import type { HeatmapData, HeatmapMode, DisplayMetric, ProjectOption } from './types';
+import { createInitialState } from './state';
+import type { HeatmapState } from './state';
+import { getRenderer, registerRenderer } from './renderers/registry';
+import { YearModeRenderer } from './renderers/year';
+import { WeekModeRenderer } from './renderers/week';
+import { renderStats } from './shared/stats';
+import { createModeControl, createMetricControl } from './ui/controls';
 
-const DEFAULT_CONFIG: HeatmapConfig = {
-  cellSize: 13,
-  cellGap: 2,
-  marginTop: 20,
-  marginLeft: 30,
-  marginBottom: 4,
-};
-
-const FALLBACK_COLORS = ['#9be9a8', '#40c463', '#30a14e', '#216e39'];
-const DAY_LABELS_MONDAY = ['Mon', '', 'Wed', '', 'Fri', '', ''];
-const DAY_LABELS_SUNDAY = ['Sun', '', 'Tue', '', 'Thu', '', 'Sat'];
-
-function getDayLabels(weekStart: string): string[] {
-  return weekStart === 'sunday' ? DAY_LABELS_SUNDAY : DAY_LABELS_MONDAY;
-}
-const MONTH_FORMAT = timeFormat('%b');
-const DATE_FORMAT = timeFormat('%Y-%m-%d');
-const DISPLAY_FORMAT = timeFormat('%a, %b %-d, %Y');
-
-interface DayCell {
-  date: Date;
-  dateStr: string;
-  entry: DayEntry | null;
-  week: number;
-  day: number;
-  isWeekend: boolean;
-}
-
-function resolveColors(container: HTMLElement): string[] {
-  try {
-    const style = getComputedStyle(container);
-    const test = style.getPropertyValue('--tblr-bg-surface');
-    if (!test) return FALLBACK_COLORS;
-    return FALLBACK_COLORS; // Use hardcoded greens — Tabler doesn't expose a green scale via CSS vars
-  } catch {
-    return FALLBACK_COLORS;
-  }
-}
-
-function buildDateMap(days: DayEntry[]): Map<string, DayEntry> {
-  const map = new Map<string, DayEntry>();
-  for (const d of days) {
-    map.set(d.date, d);
-  }
-  return map;
-}
-
-function getWeekInterval(weekStart: string) {
-  return weekStart === 'sunday' ? timeSunday : timeMonday;
-}
-
-function generateCells(
-  begin: Date,
-  end: Date,
-  dateMap: Map<string, DayEntry>,
-  weekStart: string = 'monday',
-): DayCell[] {
-  const weekInterval = getWeekInterval(weekStart);
-  const firstWeekDay = weekInterval.floor(begin);
-  const cells: DayCell[] = [];
-  let current = new Date(begin);
-
-  while (current <= end) {
-    const dateStr = DATE_FORMAT(current);
-    const weeksSinceStart = weekInterval.count(firstWeekDay, current);
-    const jsDay = current.getDay(); // 0=Sunday, 6=Saturday
-    const dayOfWeek = weekStart === 'sunday'
-      ? jsDay // Sunday=0 already first
-      : (jsDay + 6) % 7; // Monday=0, Sunday=6
-    const isWeekend = jsDay === 0 || jsDay === 6;
-
-    cells.push({
-      date: new Date(current),
-      dateStr,
-      entry: dateMap.get(dateStr) || null,
-      week: weeksSinceStart,
-      day: dayOfWeek,
-      isWeekend,
-    });
-
-    current = timeDay.offset(current, 1);
-  }
-
-  return cells;
-}
-
-function createTooltip(): HTMLDivElement {
-  const tip = document.createElement('div');
-  tip.className = 'heatmap-tooltip';
-  tip.style.display = 'none';
-  return tip;
-}
-
-export function calculateStreak(days: DayEntry[]): number {
-  if (days.length === 0) return 0;
-
-  const tracked = new Set(
-    days.filter((d) => d.hours > 0).map((d) => d.date),
-  );
-  if (tracked.size === 0) return 0;
-
-  const today = new Date();
-  today.setHours(0, 0, 0, 0);
-  let current = new Date(today);
-
-  // If today has no entry, start from yesterday
-  if (!tracked.has(DATE_FORMAT(current))) {
-    current = timeDay.offset(current, -1);
-  }
-
-  let streak = 0;
-  while (tracked.has(DATE_FORMAT(current))) {
-    streak++;
-    current = timeDay.offset(current, -1);
-  }
-
-  return streak;
-}
-
-export interface HeatmapStats {
-  totalHours: number;
-  avgHours: number;
-  busiestDay: { date: string; hours: number } | null;
-}
-
-export function calculateStats(days: DayEntry[]): HeatmapStats {
-  const withEntries = days.filter((d) => d.hours > 0);
-  if (withEntries.length === 0) {
-    return { totalHours: 0, avgHours: 0, busiestDay: null };
-  }
-
-  const totalHours = Math.round(withEntries.reduce((sum, d) => sum + d.hours, 0) * 10) / 10;
-  const avgHours = Math.round((totalHours / withEntries.length) * 10) / 10;
-  const busiest = withEntries.reduce((best, d) => (d.hours > best.hours ? d : best));
-
-  return {
-    totalHours,
-    avgHours,
-    busiestDay: { date: busiest.date, hours: busiest.hours },
-  };
-}
-
-function renderStats(container: HTMLElement, days: DayEntry[]): void {
-  // Remove existing stats
-  const existing = container.querySelector('.heatmap-stats');
-  if (existing) existing.remove();
-
-  const streak = calculateStreak(days);
-  const stats = calculateStats(days);
-
-  const statsDiv = document.createElement('div');
-  statsDiv.className = 'heatmap-stats';
-
-  const parts: string[] = [];
-  parts.push(`<span>\u{1F525} <span class="stat-value">${streak}</span> days</span>`);
-  parts.push(`<span>Total: <span class="stat-value">${stats.totalHours}h</span></span>`);
-  parts.push(`<span>Avg: <span class="stat-value">${stats.avgHours}h/day</span></span>`);
-
-  if (stats.busiestDay) {
-    const d = new Date(stats.busiestDay.date + 'T00:00:00');
-    const label = DISPLAY_FORMAT(d);
-    parts.push(`<span>Busiest: <span class="stat-value">${label} \u2014 ${stats.busiestDay.hours.toFixed(1)}h</span></span>`);
-  }
-
-  statsDiv.innerHTML = parts.join('');
-  container.appendChild(statsDiv);
-}
-
-export function renderHeatmap(
-  container: HTMLElement,
-  data: HeatmapData,
-  config: HeatmapConfig = DEFAULT_CONFIG,
-  onCellClick?: (dateStr: string) => void,
-  emptyMessage?: string,
-  weekStart: string = 'monday',
-): void {
-  container.innerHTML = '';
-
-  if (!data.days || data.days.length === 0) {
-    const msg = document.createElement('div');
-    msg.textContent = emptyMessage || 'No tracking data available';
-    msg.style.padding = '1rem';
-    msg.style.color = 'var(--tblr-secondary, #6c757d)';
-    container.appendChild(msg);
-    return;
-  }
-
-  const dateMap = buildDateMap(data.days);
-  const begin = new Date(data.range.begin);
-  const end = new Date(data.range.end);
-  const cells = generateCells(begin, end, dateMap, weekStart);
-
-  const maxHours = max(data.days, (d) => d.hours) || 1;
-  const colors = resolveColors(container);
-
-  const colorScale = scaleQuantize<string>()
-    .domain([0, maxHours])
-    .range(colors);
-
-  const { cellGap, marginTop, marginLeft, marginBottom } = config;
-  const numWeeks = (max(cells, (c) => c.week) ?? 0) + 1;
-
-  // Compute cell size to fill available width, capped at 16px
-  const containerWidth = container.clientWidth || 800;
-  const maxCellSize = 22;
-  const minCellSize = 10;
-  const cellSize = Math.min(maxCellSize, Math.max(minCellSize, Math.floor((containerWidth - marginLeft) / numWeeks) - cellGap));
-  const step = cellSize + cellGap;
-  const svgWidth = marginLeft + numWeeks * step;
-  const svgHeight = marginTop + 7 * step + marginBottom;
-
-  const wrapper = document.createElement('div');
-  wrapper.style.maxWidth = `${svgWidth}px`;
-  wrapper.style.margin = '0 auto';
-  container.appendChild(wrapper);
-
-  const svg = select(wrapper)
-    .append('svg')
-    .attr('width', svgWidth)
-    .attr('height', svgHeight)
-    .attr('class', 'heatmap-svg');
-
-  // Month labels
-  const weekInterval = getWeekInterval(weekStart);
-  const months: { date: Date; week: number }[] = [];
-  const firstWeekDay = weekInterval.floor(begin);
-  timeMonth.range(timeMonth.ceil(begin), end).forEach((m) => {
-    months.push({
-      date: m,
-      week: weekInterval.count(firstWeekDay, m),
-    });
-  });
-
-  svg
-    .selectAll('.month-label')
-    .data(months)
-    .join('text')
-    .attr('class', 'heatmap-label month-label')
-    .attr('x', (d) => marginLeft + d.week * step)
-    .attr('y', marginTop - 6)
-    .text((d) => MONTH_FORMAT(d.date));
-
-  // Day labels
-  svg
-    .selectAll('.day-label')
-    .data(getDayLabels(weekStart))
-    .join('text')
-    .attr('class', 'heatmap-label day-label')
-    .attr('x', marginLeft - 6)
-    .attr('y', (_d, i) => marginTop + i * step + cellSize - 2)
-    .attr('text-anchor', 'end')
-    .text((d) => d);
-
-  // Tooltip (fixed positioning to escape overflow clipping)
-  // Remove any stale tooltip from previous renders
-  document.querySelectorAll('.heatmap-tooltip').forEach(el => el.remove());
-  const tooltip = createTooltip();
-  tooltip.style.position = 'fixed';
-  document.body.appendChild(tooltip);
-
-  // Cells
-  svg
-    .selectAll('.heatmap-cell')
-    .data(cells)
-    .join('rect')
-    .attr('class', (d) => {
-      let cls = 'heatmap-cell';
-      if (!d.entry) cls += ' heatmap-empty';
-      if (d.isWeekend) cls += ' heatmap-weekend';
-      return cls;
-    })
-    .attr('x', (d) => marginLeft + d.week * step)
-    .attr('y', (d) => marginTop + d.day * step)
-    .attr('width', cellSize)
-    .attr('height', cellSize)
-    .attr('fill', (d) => (d.entry ? colorScale(d.entry.hours) : ''))
-    .on('mouseenter', function (event: MouseEvent, d: DayCell) {
-      const hours = d.entry ? d.entry.hours.toFixed(1) : '0.0';
-      const count = d.entry ? d.entry.count : 0;
-      tooltip.innerHTML = `<strong>${DISPLAY_FORMAT(d.date)}</strong><br>${hours}h (${count} entries)`;
-      tooltip.style.display = 'block';
-
-      const rect = (event.target as SVGRectElement).getBoundingClientRect();
-      tooltip.style.left = `${rect.left + cellSize / 2}px`;
-      tooltip.style.top = `${rect.top - tooltip.offsetHeight - 8}px`;
-    })
-    .on('mouseleave', function () {
-      tooltip.style.display = 'none';
-    })
-    .on('click', function (_event: MouseEvent, d: DayCell) {
-      if (!onCellClick) return;
-      onCellClick(d.dateStr);
-    });
-
-}
+// Register built-in renderers
+registerRenderer(new YearModeRenderer());
+registerRenderer(new WeekModeRenderer());
 
 export function init(container: HTMLElement): void {
   const baseUrl = container.getAttribute('data-url');
@@ -313,13 +23,13 @@ export function init(container: HTMLElement): void {
   const projectsJson = container.getAttribute('data-projects');
   const projects: ProjectOption[] = projectsJson ? JSON.parse(projectsJson) : [];
 
-  let activeProjectId: number | null = null;
+  const state: HeatmapState = createInitialState(weekStart);
 
   const onCellClick = (dateStr: string): void => {
     const daterange = `${dateStr} - ${dateStr}`;
     let url = `${timesheetUrl}?daterange=${encodeURIComponent(daterange)}`;
-    if (activeProjectId) {
-      url += `&projects[]=${activeProjectId}`;
+    if (state.filters.projectId) {
+      url += `&projects[]=${state.filters.projectId}`;
     }
     window.location.href = url;
   };
@@ -333,14 +43,47 @@ export function init(container: HTMLElement): void {
   svgArea.className = 'heatmap-svg-area';
   wrapper.appendChild(svgArea);
 
-  // Shared state for current data (used by resize re-render and filter)
-  let currentData: HeatmapData | null = null;
+  // Wire mode and metric controls into header
+  const controlsContainer = document.getElementById('heatmap-controls');
+  if (controlsContainer) {
+    const modeControl = createModeControl(state.mode, [
+      { key: 'year', label: 'Year' },
+      { key: 'week', label: 'Week' },
+    ], (mode) => {
+      state.mode = mode as HeatmapMode;
+      doRender();
+    });
 
-  const doRender = (data: HeatmapData, emptyMsg?: string) => {
-    currentData = data;
-    renderHeatmap(svgArea, data, DEFAULT_CONFIG, onCellClick, emptyMsg, weekStart);
-    renderStats(container, data.days);
+    const metricControl = createMetricControl(state.metric, (metric) => {
+      state.metric = metric as DisplayMetric;
+      doRender();
+    });
+
+    controlsContainer.appendChild(modeControl);
+    controlsContainer.appendChild(metricControl);
+  }
+
+  const doRender = () => {
+    if (!state.data) return;
+    const renderer = getRenderer(state.mode);
+    renderer.destroy?.();
+    renderer.render({
+      container: svgArea,
+      data: state.data,
+      state,
+      config: { cellSize: 13, cellGap: 2, marginTop: 20, marginLeft: 30, marginBottom: 4 },
+      onCellClick,
+      emptyMessage: state.filters.projectId ? 'No tracking data for this project' : undefined,
+    });
+    if (state.mode === 'year') {
+      renderStats(container, state.data.days);
+    } else {
+      const existingStats = container.querySelector('.heatmap-stats');
+      if (existingStats) existingStats.remove();
+    }
+    if (state.mode === 'year') {
       svgArea.scrollLeft = svgArea.scrollWidth;
+    }
   };
 
   // Build filter dropdown (only if projects exist)
@@ -348,25 +91,25 @@ export function init(container: HTMLElement): void {
     const filterDiv = document.createElement('div');
     filterDiv.className = 'heatmap-filter';
 
-    const select = document.createElement('select');
-    select.className = 'form-select form-select-sm';
-    select.setAttribute('aria-label', 'Filter by project');
+    const selectEl = document.createElement('select');
+    selectEl.className = 'form-select form-select-sm';
+    selectEl.setAttribute('aria-label', 'Filter by project');
 
     const defaultOpt = document.createElement('option');
     defaultOpt.value = '';
     defaultOpt.textContent = 'All Projects';
-    select.appendChild(defaultOpt);
+    selectEl.appendChild(defaultOpt);
 
     for (const p of projects) {
       const opt = document.createElement('option');
       opt.value = String(p.id);
       opt.textContent = p.name;
-      select.appendChild(opt);
+      selectEl.appendChild(opt);
     }
 
-    select.addEventListener('change', () => {
-      const val = select.value;
-      activeProjectId = val ? parseInt(val, 10) : null;
+    selectEl.addEventListener('change', () => {
+      const val = selectEl.value;
+      state.filters.projectId = val ? parseInt(val, 10) : null;
       const fetchUrl = val ? `${baseUrl}?project=${val}` : baseUrl;
 
       fetch(fetchUrl)
@@ -375,14 +118,15 @@ export function init(container: HTMLElement): void {
           return res.json() as Promise<HeatmapData>;
         })
         .then(data => {
-          doRender(data, 'No tracking data for this project');
+          state.data = data;
+          doRender();
         })
         .catch(err => {
           console.error('KimaiHeatmap: failed to load filtered data', err);
         });
     });
 
-    filterDiv.appendChild(select);
+    filterDiv.appendChild(selectEl);
     wrapper.appendChild(filterDiv);
   }
 
@@ -393,7 +137,7 @@ export function init(container: HTMLElement): void {
   window.addEventListener('resize', () => {
     clearTimeout(resizeTimer);
     resizeTimer = setTimeout(() => {
-      if (currentData) doRender(currentData);
+      if (state.data) doRender();
     }, 200);
   });
 
@@ -404,7 +148,8 @@ export function init(container: HTMLElement): void {
       return res.json() as Promise<HeatmapData>;
     })
     .then(data => {
-      doRender(data);
+      state.data = data;
+      doRender();
     })
     .catch(err => {
       console.error('KimaiHeatmap: failed to load data', err);

assets/src/renderers/registry.ts

@@ -0,0 +1,17 @@
+import type { ModeRenderer } from './types';
+
+const renderers = new Map<string, ModeRenderer>();
+
+export function registerRenderer(renderer: ModeRenderer): void {
+  renderers.set(renderer.mode, renderer);
+}
+
+export function getRenderer(mode: string): ModeRenderer {
+  const r = renderers.get(mode);
+  if (!r) throw new Error(`Unknown heatmap mode: ${mode}`);
+  return r;
+}
+
+export function clearRegistry(): void {
+  renderers.clear();
+}

assets/src/renderers/types.ts

@@ -0,0 +1,17 @@
+import type { HeatmapData, HeatmapConfig } from '../types';
+import type { HeatmapState } from '../state';
+
+export interface RenderContext {
+  container: HTMLElement;
+  data: HeatmapData;
+  state: HeatmapState;
+  config: HeatmapConfig;
+  onCellClick?: (dateStr: string) => void;
+  emptyMessage?: string;
+}
+
+export interface ModeRenderer {
+  readonly mode: string;
+  render(ctx: RenderContext): void;
+  destroy?(): void;
+}

assets/src/renderers/week.ts

@@ -0,0 +1,154 @@
+import { select } from 'd3-selection';
+import type { ModeRenderer, RenderContext } from './types';
+import { createTooltip, showTooltip, hideTooltip } from '../shared/tooltip';
+import { buildColorScale } from '../shared/color-scale';
+import type { DayEntry } from '../types';
+
+interface WeekdayAggregate {
+  dayIndex: number;
+  label: string;
+  shortLabel: string;
+  totalHours: number;
+  totalCount: number;
+  dayCount: number;
+}
+
+const WEEKDAY_NAMES_MONDAY = ['Monday', 'Tuesday', 'Wednesday', 'Thursday', 'Friday', 'Saturday', 'Sunday'];
+const WEEKDAY_NAMES_SUNDAY = ['Sunday', 'Monday', 'Tuesday', 'Wednesday', 'Thursday', 'Friday', 'Saturday'];
+const WEEKDAY_SHORT_MONDAY = ['Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat', 'Sun'];
+const WEEKDAY_SHORT_SUNDAY = ['Sun', 'Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat'];
+
+function aggregateByWeekday(days: DayEntry[], weekStart: string): WeekdayAggregate[] {
+  const names = weekStart === 'sunday' ? WEEKDAY_NAMES_SUNDAY : WEEKDAY_NAMES_MONDAY;
+  const shorts = weekStart === 'sunday' ? WEEKDAY_SHORT_SUNDAY : WEEKDAY_SHORT_MONDAY;
+
+  const buckets: WeekdayAggregate[] = Array.from({ length: 7 }, (_, i) => ({
+    dayIndex: i,
+    label: names[i],
+    shortLabel: shorts[i],
+    totalHours: 0,
+    totalCount: 0,
+    dayCount: 0,
+  }));
+
+  const seenDates = new Map<number, Set<string>>();
+
+  for (const d of days) {
+    const jsDay = new Date(d.date + 'T00:00:00').getDay();
+    const idx = weekStart === 'sunday' ? jsDay : (jsDay + 6) % 7;
+    buckets[idx].totalHours += d.hours;
+    buckets[idx].totalCount += d.count;
+
+    if (!seenDates.has(idx)) seenDates.set(idx, new Set());
+    seenDates.get(idx)!.add(d.date);
+  }
+
+  for (const [idx, dates] of seenDates) {
+    buckets[idx].dayCount = dates.size;
+  }
+
+  return buckets;
+}
+
+export class WeekModeRenderer implements ModeRenderer {
+  readonly mode = 'week';
+  private tooltip: HTMLDivElement | null = null;
+
+  render(ctx: RenderContext): void {
+    ctx.container.innerHTML = '';
+
+    if (!ctx.data.days || ctx.data.days.length === 0) {
+      const msg = document.createElement('div');
+      msg.textContent = ctx.emptyMessage || 'No tracking data available';
+      msg.style.padding = '1rem';
+      msg.style.color = 'var(--tblr-secondary, #6c757d)';
+      ctx.container.appendChild(msg);
+      return;
+    }
+
+    this.destroy();
+    this.tooltip = createTooltip();
+
+    const aggregates = aggregateByWeekday(ctx.data.days, ctx.state.weekStart);
+
+    // Build color scale from aggregates that have data
+    const syntheticDays: DayEntry[] = aggregates
+      .filter(a => a.dayCount > 0)
+      .map(a => ({ date: '', hours: a.totalHours, count: a.totalCount }));
+    const colorScale = buildColorScale(syntheticDays, ctx.state.metric);
+
+    // Layout constants per UI-SPEC
+    const cellWidth = 60;
+    const cellHeight = 40;
+    const cellGap = 4;
+    const labelWidth = 50;
+    const labelHeight = 16;
+    const totalWidth = labelWidth + 7 * (cellWidth + cellGap);
+    const totalHeight = labelHeight + cellHeight;
+
+    const wrapper = document.createElement('div');
+    wrapper.style.maxWidth = `${totalWidth}px`;
+    wrapper.style.margin = '0 auto';
+    ctx.container.appendChild(wrapper);
+
+    const svg = select(wrapper)
+      .append('svg')
+      .attr('width', totalWidth)
+      .attr('height', totalHeight)
+      .attr('class', 'heatmap-svg');
+
+    const tooltip = this.tooltip;
+    const metric = ctx.state.metric;
+
+    // Render labels above cells
+    aggregates.forEach((agg, i) => {
+      svg.append('text')
+        .attr('class', 'heatmap-label')
+        .attr('x', labelWidth + i * (cellWidth + cellGap) + cellWidth / 2)
+        .attr('y', labelHeight - 2)
+        .attr('text-anchor', 'middle')
+        .text(agg.shortLabel);
+    });
+
+    // Render 7 weekday rects
+    aggregates.forEach((agg, i) => {
+      const hasData = agg.dayCount > 0;
+      const cls = 'heatmap-week-cell' + (hasData ? '' : ' heatmap-empty');
+      const fill = hasData
+        ? colorScale(metric === 'hours' ? agg.totalHours : agg.totalCount)
+        : '';
+
+      svg.append('rect')
+        .attr('class', cls)
+        .attr('x', labelWidth + i * (cellWidth + cellGap))
+        .attr('y', labelHeight)
+        .attr('width', cellWidth)
+        .attr('height', cellHeight)
+        .attr('fill', fill)
+        .attr('rx', 2)
+        .attr('ry', 2)
+        .on('mouseenter', function (event: MouseEvent) {
+          let html: string;
+          if (hasData) {
+            if (metric === 'hours') {
+              html = `<strong>${agg.label}</strong><br>${agg.totalHours.toFixed(1)}h (${agg.totalCount} entries)`;
+            } else {
+              html = `<strong>${agg.label}</strong><br>${agg.totalCount} entries (${agg.totalHours.toFixed(1)}h)`;
+            }
+          } else {
+            html = `<strong>${agg.label}</strong><br>No tracked time`;
+          }
+          const rect = (event.target as SVGRectElement).getBoundingClientRect();
+          showTooltip(tooltip, html, rect, cellWidth);
+        })
+        .on('mouseleave', function () {
+          hideTooltip(tooltip);
+        });
+    });
+  }
+
+  destroy(): void {
+    this.tooltip?.remove();
+    this.tooltip = null;
+  }
+}

assets/src/renderers/year.ts

@@ -0,0 +1,131 @@
+import { select } from 'd3-selection';
+import { timeMonth } from 'd3-time';
+import { max } from 'd3-array';
+import type { ModeRenderer, RenderContext } from './types';
+import { createTooltip, showTooltip, hideTooltip } from '../shared/tooltip';
+import { buildColorScale } from '../shared/color-scale';
+import {
+  buildDateMap, generateCells, getWeekInterval, getDayLabels,
+  MONTH_FORMAT, DISPLAY_FORMAT, type DayCell,
+} from '../shared/date-utils';
+
+export class YearModeRenderer implements ModeRenderer {
+  readonly mode = 'year';
+  private tooltip: HTMLDivElement | null = null;
+
+  render(ctx: RenderContext): void {
+    ctx.container.innerHTML = '';
+
+    // Handle empty data
+    if (!ctx.data.days || ctx.data.days.length === 0) {
+      const msg = document.createElement('div');
+      msg.textContent = ctx.emptyMessage || 'No tracking data available';
+      msg.style.padding = '1rem';
+      msg.style.color = 'var(--tblr-secondary, #6c757d)';
+      ctx.container.appendChild(msg);
+      return;
+    }
+
+    // Destroy previous tooltip
+    this.destroy();
+    this.tooltip = createTooltip();
+
+    const weekStart = ctx.state.weekStart;
+    const dateMap = buildDateMap(ctx.data.days);
+    const begin = new Date(ctx.data.range.begin);
+    const end = new Date(ctx.data.range.end);
+    const cells = generateCells(begin, end, dateMap, weekStart);
+
+    // Build color scale using state metric (hours vs count)
+    const colorScale = buildColorScale(ctx.data.days, ctx.state.metric);
+
+    const { cellGap, marginTop, marginLeft, marginBottom } = ctx.config;
+    const numWeeks = (max(cells, (c) => c.week) ?? 0) + 1;
+
+    // Compute cell size to fill available width, capped
+    const containerWidth = ctx.container.clientWidth || 800;
+    const maxCellSize = 22;
+    const minCellSize = 13;
+    const cellSize = Math.min(maxCellSize, Math.max(minCellSize, Math.floor((containerWidth - marginLeft) / numWeeks) - cellGap));
+    const step = cellSize + cellGap;
+    const svgWidth = marginLeft + numWeeks * step;
+    const svgHeight = marginTop + 7 * step + marginBottom;
+
+    const wrapper = document.createElement('div');
+    wrapper.style.maxWidth = `${svgWidth}px`;
+    wrapper.style.margin = '0 auto';
+    ctx.container.appendChild(wrapper);
+
+    const svg = select(wrapper)
+      .append('svg')
+      .attr('width', svgWidth)
+      .attr('height', svgHeight)
+      .attr('class', 'heatmap-svg');
+
+    // Month labels
+    const weekInterval = getWeekInterval(weekStart);
+    const months: { date: Date; week: number }[] = [];
+    const firstWeekDay = weekInterval.floor(begin);
+    timeMonth.range(timeMonth.ceil(begin), end).forEach((m) => {
+      months.push({ date: m, week: weekInterval.count(firstWeekDay, m) });
+    });
+
+    svg.selectAll('.month-label')
+      .data(months)
+      .join('text')
+      .attr('class', 'heatmap-label month-label')
+      .attr('x', (d) => marginLeft + d.week * step)
+      .attr('y', marginTop - 6)
+      .text((d) => MONTH_FORMAT(d.date));
+
+    // Day labels
+    svg.selectAll('.day-label')
+      .data(getDayLabels(weekStart))
+      .join('text')
+      .attr('class', 'heatmap-label day-label')
+      .attr('x', marginLeft - 6)
+      .attr('y', (_d, i) => marginTop + i * step + cellSize - 2)
+      .attr('text-anchor', 'end')
+      .text((d) => d);
+
+    // Cells with tooltip and click
+    const tooltip = this.tooltip;
+    svg.selectAll('.heatmap-cell')
+      .data(cells)
+      .join('rect')
+      .attr('class', (d) => {
+        let cls = 'heatmap-cell';
+        if (!d.entry) cls += ' heatmap-empty';
+        if (d.isWeekend) cls += ' heatmap-weekend';
+        return cls;
+      })
+      .attr('x', (d) => marginLeft + d.week * step)
+      .attr('y', (d) => marginTop + d.day * step)
+      .attr('width', cellSize)
+      .attr('height', cellSize)
+      .attr('fill', (d) => {
+        if (!d.entry) return '';
+        const val = ctx.state.metric === 'hours' ? d.entry.hours : d.entry.count;
+        return colorScale(val);
+      })
+      .on('mouseenter', function (event: MouseEvent, d: DayCell) {
+        const hours = d.entry ? d.entry.hours.toFixed(1) : '0.0';
+        const count = d.entry ? d.entry.count : 0;
+        const html = `<strong>${DISPLAY_FORMAT(d.date)}</strong><br>${hours}h (${count} entries)`;
+        const rect = (event.target as SVGRectElement).getBoundingClientRect();
+        showTooltip(tooltip, html, rect, cellSize);
+      })
+      .on('mouseleave', function () {
+        hideTooltip(tooltip);
+      })
+      .on('click', function (_event: MouseEvent, d: DayCell) {
+        if (!ctx.onCellClick) return;
+        ctx.onCellClick(d.dateStr);
+      });
+  }
+
+  destroy(): void {
+    this.tooltip?.remove();
+    this.tooltip = null;
+  }
+}

assets/src/shared/color-scale.ts

@@ -0,0 +1,16 @@
+import { scaleQuantize } from 'd3-scale';
+import { max } from 'd3-array';
+import type { DayEntry, DisplayMetric } from '../types';
+
+export const FALLBACK_COLORS = ['#9be9a8', '#40c463', '#30a14e', '#216e39'];
+
+export function buildColorScale(
+  days: DayEntry[],
+  metric: DisplayMetric = 'hours',
+): ReturnType<typeof scaleQuantize<string>> {
+  const accessor = metric === 'hours'
+    ? (d: DayEntry) => d.hours
+    : (d: DayEntry) => d.count;
+  const maxVal = max(days, accessor) || 1;
+  return scaleQuantize<string>().domain([0, maxVal]).range(FALLBACK_COLORS);
+}

assets/src/shared/date-utils.ts

@@ -0,0 +1,70 @@
+import { timeMonday, timeSunday, timeDay, timeMonth } from 'd3-time';
+import { timeFormat } from 'd3-time-format';
+import type { DayEntry } from '../types';
+
+export const DAY_LABELS_MONDAY = ['Mon', '', 'Wed', '', 'Fri', '', ''];
+export const DAY_LABELS_SUNDAY = ['Sun', '', 'Tue', '', 'Thu', '', 'Sat'];
+
+export function getDayLabels(weekStart: string): string[] {
+  return weekStart === 'sunday' ? DAY_LABELS_SUNDAY : DAY_LABELS_MONDAY;
+}
+
+export const MONTH_FORMAT = timeFormat('%b');
+export const DATE_FORMAT = timeFormat('%Y-%m-%d');
+export const DISPLAY_FORMAT = timeFormat('%a, %b %-d, %Y');
+
+export interface DayCell {
+  date: Date;
+  dateStr: string;
+  entry: DayEntry | null;
+  week: number;
+  day: number;
+  isWeekend: boolean;
+}
+
+export function buildDateMap(days: DayEntry[]): Map<string, DayEntry> {
+  const map = new Map<string, DayEntry>();
+  for (const d of days) {
+    map.set(d.date, d);
+  }
+  return map;
+}
+
+export function getWeekInterval(weekStart: string) {
+  return weekStart === 'sunday' ? timeSunday : timeMonday;
+}
+
+export function generateCells(
+  begin: Date,
+  end: Date,
+  dateMap: Map<string, DayEntry>,
+  weekStart: string = 'monday',
+): DayCell[] {
+  const weekInterval = getWeekInterval(weekStart);
+  const firstWeekDay = weekInterval.floor(begin);
+  const cells: DayCell[] = [];
+  let current = new Date(begin);
+
+  while (current <= end) {
+    const dateStr = DATE_FORMAT(current);
+    const weeksSinceStart = weekInterval.count(firstWeekDay, current);
+    const jsDay = current.getDay(); // 0=Sunday, 6=Saturday
+    const dayOfWeek = weekStart === 'sunday'
+      ? jsDay // Sunday=0 already first
+      : (jsDay + 6) % 7; // Monday=0, Sunday=6
+    const isWeekend = jsDay === 0 || jsDay === 6;
+
+    cells.push({
+      date: new Date(current),
+      dateStr,
+      entry: dateMap.get(dateStr) || null,
+      week: weeksSinceStart,
+      day: dayOfWeek,
+      isWeekend,
+    });
+
+    current = timeDay.offset(current, 1);
+  }
+
+  return cells;
+}

assets/src/shared/stats.ts

@@ -0,0 +1,81 @@
+import { timeDay } from 'd3-time';
+import { timeFormat } from 'd3-time-format';
+import type { DayEntry } from '../types';
+
+const DATE_FORMAT = timeFormat('%Y-%m-%d');
+const DISPLAY_FORMAT = timeFormat('%a, %b %-d, %Y');
+
+export function calculateStreak(days: DayEntry[]): number {
+  if (days.length === 0) return 0;
+
+  const tracked = new Set(
+    days.filter((d) => d.hours > 0).map((d) => d.date),
+  );
+  if (tracked.size === 0) return 0;
+
+  const today = new Date();
+  today.setHours(0, 0, 0, 0);
+  let current = new Date(today);
+
+  // If today has no entry, start from yesterday
+  if (!tracked.has(DATE_FORMAT(current))) {
+    current = timeDay.offset(current, -1);
+  }
+
+  let streak = 0;
+  while (tracked.has(DATE_FORMAT(current))) {
+    streak++;
+    current = timeDay.offset(current, -1);
+  }
+
+  return streak;
+}
+
+export interface HeatmapStats {
+  totalHours: number;
+  avgHours: number;
+  busiestDay: { date: string; hours: number } | null;
+}
+
+export function calculateStats(days: DayEntry[]): HeatmapStats {
+  const withEntries = days.filter((d) => d.hours > 0);
+  if (withEntries.length === 0) {
+    return { totalHours: 0, avgHours: 0, busiestDay: null };
+  }
+
+  const totalHours = Math.round(withEntries.reduce((sum, d) => sum + d.hours, 0) * 10) / 10;
+  const avgHours = Math.round((totalHours / withEntries.length) * 10) / 10;
+  const busiest = withEntries.reduce((best, d) => (d.hours > best.hours ? d : best));
+
+  return {
+    totalHours,
+    avgHours,
+    busiestDay: { date: busiest.date, hours: busiest.hours },
+  };
+}
+
+export function renderStats(container: HTMLElement, days: DayEntry[]): void {
+  // Remove existing stats
+  const existing = container.querySelector('.heatmap-stats');
+  if (existing) existing.remove();
+
+  const streak = calculateStreak(days);
+  const stats = calculateStats(days);
+
+  const statsDiv = document.createElement('div');
+  statsDiv.className = 'heatmap-stats';
+
+  const parts: string[] = [];
+  parts.push(`<span>\u{1F525} <span class="stat-value">${streak}</span> days</span>`);
+  parts.push(`<span>Total: <span class="stat-value">${stats.totalHours}h</span></span>`);
+  parts.push(`<span>Avg: <span class="stat-value">${stats.avgHours}h/day</span></span>`);
+
+  if (stats.busiestDay) {
+    const d = new Date(stats.busiestDay.date + 'T00:00:00');
+    const label = DISPLAY_FORMAT(d);
+    parts.push(`<span>Busiest: <span class="stat-value">${label} \u2014 ${stats.busiestDay.hours.toFixed(1)}h</span></span>`);
+  }
+
+  statsDiv.innerHTML = parts.join('');
+  container.appendChild(statsDiv);
+}

assets/src/shared/tooltip.ts

@@ -0,0 +1,26 @@
+export function createTooltip(): HTMLDivElement {
+  document.querySelectorAll('.heatmap-tooltip').forEach(el => el.remove());
+
+  const tip = document.createElement('div');
+  tip.className = 'heatmap-tooltip';
+  tip.style.display = 'none';
+  tip.style.position = 'fixed';
+  document.body.appendChild(tip);
+  return tip;
+}
+
+export function showTooltip(
+  tip: HTMLDivElement,
+  html: string,
+  anchorRect: DOMRect,
+  cellSize: number,
+): void {
+  tip.innerHTML = html;
+  tip.style.display = 'block';
+  tip.style.left = `${anchorRect.left + cellSize / 2}px`;
+  tip.style.top = `${anchorRect.top - tip.offsetHeight - 8}px`;
+}
+
+export function hideTooltip(tip: HTMLDivElement): void {
+  tip.style.display = 'none';
+}

assets/src/state.ts

@@ -0,0 +1,21 @@
+import type { HeatmapData, HeatmapMode, DisplayMetric, FilterState } from './types';
+
+export type { HeatmapMode, DisplayMetric, FilterState };
+
+export interface HeatmapState {
+  mode: HeatmapMode;
+  metric: DisplayMetric;
+  filters: FilterState;
+  weekStart: string;
+  data: HeatmapData | null;
+}
+
+export function createInitialState(weekStart: string): HeatmapState {
+  return {
+    mode: 'year',
+    metric: 'hours',
+    filters: { projectId: null, customerId: null, activityId: null },
+    weekStart,
+    data: null,
+  };
+}

assets/src/types.ts

@@ -12,6 +12,29 @@ export interface HeatmapData {
   };
 }
 
+export interface HourEntry {
+  hour: number;   // 0-23
+  hours: number;
+  count: number;
+}
+
+export interface DayHourEntry {
+  day: number;    // 0-6, relative to weekStart
+  hour: number;   // 0-23
+  hours: number;
+  count: number;
+}
+
+export interface HourlyData {
+  hours: HourEntry[];
+  range: { begin: string; end: string };
+}
+
+export interface DayHourData {
+  matrix: DayHourEntry[];
+  range: { begin: string; end: string };
+}
+
 export interface HeatmapConfig {
   cellSize: number;
   cellGap: number;
@@ -24,3 +47,12 @@ export interface ProjectOption {
   id: number;
   name: string;
 }
+
+export type DisplayMetric = 'hours' | 'count';
+export type HeatmapMode = 'year' | 'week' | 'day' | 'combined';
+
+export interface FilterState {
+  projectId: number | null;
+  customerId: number | null;
+  activityId: number | null;
+}

assets/src/ui/controls.ts

@@ -0,0 +1,42 @@
+export function createModeControl(
+  activeMode: string,
+  modes: Array<{ key: string; label: string }>,
+  onChange: (mode: string) => void,
+): HTMLElement {
+  const nav = document.createElement('nav');
+  nav.className = 'nav nav-segmented nav-sm';
+  nav.setAttribute('role', 'tablist');
+
+  for (const m of modes) {
+    const btn = document.createElement('button');
+    btn.className = m.key === activeMode ? 'nav-link active' : 'nav-link';
+    btn.setAttribute('role', 'tab');
+    btn.setAttribute('aria-selected', m.key === activeMode ? 'true' : 'false');
+    btn.textContent = m.label;
+
+    btn.addEventListener('click', () => {
+      nav.querySelectorAll('button').forEach((b) => {
+        b.classList.remove('active');
+        b.setAttribute('aria-selected', 'false');
+      });
+      btn.classList.add('active');
+      btn.setAttribute('aria-selected', 'true');
+      onChange(m.key);
+    });
+
+    nav.appendChild(btn);
+  }
+
+  return nav;
+}
+
+export function createMetricControl(
+  activeMetric: string,
+  onChange: (metric: string) => void,
+): HTMLElement {
+  const nav = createModeControl(activeMetric, [
+    { key: 'hours', label: 'Hours' },
+    { key: 'count', label: 'Count' },
+  ], onChange);
+  return nav;
+}

assets/test/color-scale.test.ts

@@ -0,0 +1,35 @@
+import { describe, it, expect } from 'vitest';
+import { buildColorScale, FALLBACK_COLORS } from '../src/shared/color-scale';
+import type { DayEntry } from '../src/types';
+
+describe('buildColorScale', () => {
+  const days: DayEntry[] = [
+    { date: '2025-01-01', hours: 2, count: 3 },
+    { date: '2025-01-02', hours: 8, count: 5 },
+    { date: '2025-01-03', hours: 0, count: 0 },
+  ];
+
+  it('builds scale for hours metric', () => {
+    const scale = buildColorScale(days, 'hours');
+    // max hours is 8, so domain is [0, 8]
+    expect(scale(0)).toBe(FALLBACK_COLORS[0]);
+    expect(scale(8)).toBe(FALLBACK_COLORS[3]);
+  });
+
+  it('builds scale for count metric', () => {
+    const scale = buildColorScale(days, 'count');
+    // max count is 5, so domain is [0, 5]
+    expect(scale(0)).toBe(FALLBACK_COLORS[0]);
+    expect(scale(5)).toBe(FALLBACK_COLORS[3]);
+  });
+
+  it('defaults to hours metric', () => {
+    const scale = buildColorScale(days);
+    expect(scale(8)).toBe(FALLBACK_COLORS[3]);
+  });
+
+  it('handles empty array with domain [0, 1]', () => {
+    const scale = buildColorScale([]);
+    expect(scale.domain()).toEqual([0, 1]);
+  });
+});

assets/test/controls.test.ts

@@ -0,0 +1,111 @@
+import { describe, it, expect, vi } from 'vitest';
+import { createModeControl, createMetricControl } from '../src/ui/controls';
+
+describe('createModeControl', () => {
+  const modes = [
+    { key: 'year', label: 'Year' },
+    { key: 'week', label: 'Week' },
+  ];
+
+  it('returns a nav element with nav-segmented class and tablist role', () => {
+    const nav = createModeControl('year', modes, () => {});
+    expect(nav.tagName).toBe('NAV');
+    expect(nav.className).toBe('nav nav-segmented nav-sm');
+    expect(nav.getAttribute('role')).toBe('tablist');
+  });
+
+  it('renders buttons for each mode', () => {
+    const nav = createModeControl('year', modes, () => {});
+    const buttons = nav.querySelectorAll('button');
+    expect(buttons.length).toBe(2);
+    expect(buttons[0].textContent).toBe('Year');
+    expect(buttons[1].textContent).toBe('Week');
+  });
+
+  it('marks the active mode with active class and aria-selected', () => {
+    const nav = createModeControl('year', modes, () => {});
+    const buttons = nav.querySelectorAll('button');
+    expect(buttons[0].classList.contains('active')).toBe(true);
+    expect(buttons[0].getAttribute('aria-selected')).toBe('true');
+    expect(buttons[1].classList.contains('active')).toBe(false);
+    expect(buttons[1].getAttribute('aria-selected')).toBe('false');
+  });
+
+  it('all buttons have nav-link class and role=tab', () => {
+    const nav = createModeControl('year', modes, () => {});
+    const buttons = nav.querySelectorAll('button');
+    buttons.forEach((btn) => {
+      expect(btn.classList.contains('nav-link')).toBe(true);
+      expect(btn.getAttribute('role')).toBe('tab');
+    });
+  });
+
+  it('clicking inactive button updates active state and calls onChange', () => {
+    const onChange = vi.fn();
+    const nav = createModeControl('year', modes, onChange);
+    const buttons = nav.querySelectorAll('button');
+
+    buttons[1].click();
+
+    expect(onChange).toHaveBeenCalledWith('week');
+    expect(buttons[1].classList.contains('active')).toBe(true);
+    expect(buttons[1].getAttribute('aria-selected')).toBe('true');
+    expect(buttons[0].classList.contains('active')).toBe(false);
+    expect(buttons[0].getAttribute('aria-selected')).toBe('false');
+  });
+
+  it('clicking already active button still calls onChange', () => {
+    const onChange = vi.fn();
+    const nav = createModeControl('year', modes, onChange);
+    const buttons = nav.querySelectorAll('button');
+
+    buttons[0].click();
+
+    expect(onChange).toHaveBeenCalledWith('year');
+  });
+});
+
+describe('createMetricControl', () => {
+  it('returns a nav element with nav-segmented nav-sm classes', () => {
+    const nav = createMetricControl('hours', () => {});
+    expect(nav.tagName).toBe('NAV');
+    expect(nav.className).toBe('nav nav-segmented nav-sm');
+    expect(nav.getAttribute('role')).toBe('tablist');
+  });
+
+  it('renders Hours and Count buttons', () => {
+    const nav = createMetricControl('hours', () => {});
+    const buttons = nav.querySelectorAll('button');
+    expect(buttons.length).toBe(2);
+    expect(buttons[0].textContent).toBe('Hours');
+    expect(buttons[1].textContent).toBe('Count');
+  });
+
+  it('marks hours as active by default', () => {
+    const nav = createMetricControl('hours', () => {});
+    const buttons = nav.querySelectorAll('button');
+    expect(buttons[0].classList.contains('active')).toBe(true);
+    expect(buttons[1].classList.contains('active')).toBe(false);
+  });
+
+  it('clicking Count calls onChange with count', () => {
+    const onChange = vi.fn();
+    const nav = createMetricControl('hours', onChange);
+    const buttons = nav.querySelectorAll('button');
+
+    buttons[1].click();
+
+    expect(onChange).toHaveBeenCalledWith('count');
+    expect(buttons[1].classList.contains('active')).toBe(true);
+    expect(buttons[0].classList.contains('active')).toBe(false);
+  });
+
+  it('buttons have proper ARIA attributes', () => {
+    const nav = createMetricControl('count', () => {});
+    const buttons = nav.querySelectorAll('button');
+    expect(buttons[0].getAttribute('role')).toBe('tab');
+    expect(buttons[0].getAttribute('aria-selected')).toBe('false');
+    expect(buttons[1].getAttribute('role')).toBe('tab');
+    expect(buttons[1].getAttribute('aria-selected')).toBe('true');
+  });
+});

assets/test/date-utils.test.ts

@@ -0,0 +1,61 @@
+import { describe, it, expect } from 'vitest';
+import { buildDateMap, generateCells, getWeekInterval } from '../src/shared/date-utils';
+import { timeMonday, timeSunday } from 'd3-time';
+import type { DayEntry } from '../src/types';
+
+describe('date-utils', () => {
+  const days: DayEntry[] = [
+    { date: '2025-01-06', hours: 4, count: 2 },
+    { date: '2025-01-07', hours: 2, count: 1 },
+  ];
+
+  describe('buildDateMap', () => {
+    it('creates Map keyed by date string', () => {
+      const map = buildDateMap(days);
+      expect(map).toBeInstanceOf(Map);
+      expect(map.size).toBe(2);
+      expect(map.get('2025-01-06')).toEqual(days[0]);
+      expect(map.get('2025-01-07')).toEqual(days[1]);
+      expect(map.get('2025-01-08')).toBeUndefined();
+    });
+  });
+
+  describe('getWeekInterval', () => {
+    it('returns timeMonday for monday', () => {
+      expect(getWeekInterval('monday')).toBe(timeMonday);
+    });
+
+    it('returns timeSunday for sunday', () => {
+      expect(getWeekInterval('sunday')).toBe(timeSunday);
+    });
+  });
+
+  describe('generateCells', () => {
+    it('returns correct count for a 7-day range', () => {
+      const begin = new Date('2025-01-06'); // Monday
+      const end = new Date('2025-01-12');   // Sunday
+      const map = buildDateMap(days);
+      const cells = generateCells(begin, end, map, 'monday');
+      expect(cells.length).toBe(7);
+    });
+
+    it('marks weekend cells correctly', () => {
+      const begin = new Date('2025-01-06');
+      const end = new Date('2025-01-12');
+      const map = buildDateMap(days);
+      const cells = generateCells(begin, end, map, 'monday');
+      const weekendCells = cells.filter(c => c.isWeekend);
+      expect(weekendCells.length).toBe(2); // Saturday + Sunday
+    });
+
+    it('links entries from dateMap', () => {
+      const begin = new Date('2025-01-06');
+      const end = new Date('2025-01-08');
+      const map = buildDateMap(days);
+      const cells = generateCells(begin, end, map, 'monday');
+      expect(cells[0].entry).toEqual(days[0]);
+      expect(cells[1].entry).toEqual(days[1]);
+      expect(cells[2].entry).toBeNull();
+    });
+  });
+});

assets/test/heatmap.test.ts

@@ -1,6 +1,20 @@
-import { describe, it, expect, beforeEach } from 'vitest';
-import { renderHeatmap } from '../src/heatmap';
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { YearModeRenderer } from '../src/renderers/year';
+import type { RenderContext } from '../src/renderers/types';
 import type { HeatmapData } from '../src/types';
+import { createInitialState } from '../src/state';
+
+const DEFAULT_CONFIG = { cellSize: 13, cellGap: 2, marginTop: 20, marginLeft: 30, marginBottom: 4 };
+
+function makeCtx(container: HTMLElement, data: HeatmapData, overrides?: Partial<RenderContext>): RenderContext {
+  return {
+    container,
+    data,
+    state: createInitialState('monday'),
+    config: DEFAULT_CONFIG,
+    ...overrides,
+  };
+}
 
 function makeMockData(overrides: Partial<HeatmapData> = {}): HeatmapData {
   return {
@@ -21,34 +35,41 @@ function makeMockData(overrides: Partial<HeatmapData> = {}): HeatmapData {
 
 describe('renderHeatmap', () => {
   let container: HTMLDivElement;
+  let renderer: YearModeRenderer;
 
   beforeEach(() => {
     container = document.createElement('div');
     document.body.appendChild(container);
+    renderer = new YearModeRenderer();
+  });
+
+  afterEach(() => {
+    renderer.destroy();
+    document.querySelectorAll('.heatmap-tooltip').forEach(el => el.remove());
   });
 
   it('renders an SVG element', () => {
-    renderHeatmap(container, makeMockData());
+    renderer.render(makeCtx(container, makeMockData()));
     const svg = container.querySelector('svg');
     expect(svg).not.toBeNull();
   });
 
   it('renders correct number of rect elements for date range', () => {
-    renderHeatmap(container, makeMockData());
+    renderer.render(makeCtx(container, makeMockData()));
     const rects = container.querySelectorAll('rect.heatmap-cell');
     // Jan 1 to Jan 31 = 31 days
     expect(rects.length).toBe(31);
   });
 
   it('applies heatmap-empty class to cells with no data', () => {
-    renderHeatmap(container, makeMockData());
+    renderer.render(makeCtx(container, makeMockData()));
     const emptyRects = container.querySelectorAll('rect.heatmap-empty');
     // 31 days total, 5 with data = 26 empty
     expect(emptyRects.length).toBe(26);
   });
 
   it('applies fill attribute to cells with data', () => {
-    renderHeatmap(container, makeMockData());
+    renderer.render(makeCtx(container, makeMockData()));
     const allRects = container.querySelectorAll('rect.heatmap-cell:not(.heatmap-empty)');
     expect(allRects.length).toBe(5);
     allRects.forEach((rect) => {
@@ -57,7 +78,7 @@ describe('renderHeatmap', () => {
   });
 
   it('renders day labels (Mon, Wed, Fri)', () => {
-    renderHeatmap(container, makeMockData());
+    renderer.render(makeCtx(container, makeMockData()));
     const dayLabels = container.querySelectorAll('text.day-label');
     expect(dayLabels.length).toBe(7); // all 7 slots rendered
     const texts = Array.from(dayLabels).map((el) => el.textContent);
@@ -75,7 +96,7 @@ describe('renderHeatmap', () => {
         { date: '2025-02-10', hours: 4.0, count: 1 },
       ],
     });
-    renderHeatmap(container, data);
+    renderer.render(makeCtx(container, data));
     const monthLabels = container.querySelectorAll('text.month-label');
     expect(monthLabels.length).toBeGreaterThan(0);
     const texts = Array.from(monthLabels).map((el) => el.textContent);
@@ -83,7 +104,7 @@ describe('renderHeatmap', () => {
   });
 
   it('creates tooltip on mouseenter', () => {
-    renderHeatmap(container, makeMockData());
+    renderer.render(makeCtx(container, makeMockData()));
     const rect = container.querySelector(
       'rect.heatmap-cell:not(.heatmap-empty)',
     );
@@ -102,7 +123,7 @@ describe('renderHeatmap', () => {
   });
 
   it('hides tooltip on mouseleave', () => {
-    renderHeatmap(container, makeMockData());
+    renderer.render(makeCtx(container, makeMockData()));
     const rect = container.querySelector(
       'rect.heatmap-cell:not(.heatmap-empty)',
     );
@@ -115,7 +136,7 @@ describe('renderHeatmap', () => {
   });
 
   it('handles empty days array gracefully', () => {
-    renderHeatmap(container, makeMockData({ days: [] }));
+    renderer.render(makeCtx(container, makeMockData({ days: [] })));
     const svg = container.querySelector('svg');
     expect(svg).toBeNull();
     expect(container.textContent).toContain('No tracking data available');
@@ -129,7 +150,7 @@ describe('renderHeatmap', () => {
       ],
       range: { begin: '2025-03-01', end: '2025-03-07' },
     };
-    renderHeatmap(container, data);
+    renderer.render(makeCtx(container, data));
     const rects = container.querySelectorAll('rect.heatmap-cell');
     expect(rects.length).toBe(7);
   });
@@ -142,7 +163,7 @@ describe('renderHeatmap', () => {
       ],
       range: { begin: '2025-01-01', end: '2025-01-07' },
     };
-    renderHeatmap(container, data);
+    renderer.render(makeCtx(container, data));
     const weekendRects = container.querySelectorAll('rect.heatmap-weekend');
     // Jan 1 (Wed) through Jan 7 (Tue): Sat Jan 4 + Sun Jan 5 = 2 weekend cells
     expect(weekendRects.length).toBe(2);
@@ -155,14 +176,14 @@ describe('renderHeatmap', () => {
       ],
       range: { begin: '2025-01-06', end: '2025-01-10' },
     };
-    renderHeatmap(container, data);
+    renderer.render(makeCtx(container, data));
     const weekendRects = container.querySelectorAll('rect.heatmap-weekend');
     // Mon-Fri, no weekends
     expect(weekendRects.length).toBe(0);
   });
 
   it('renders day labels for Sunday week start', () => {
-    renderHeatmap(container, makeMockData(), undefined, undefined, undefined, 'sunday');
+    renderer.render(makeCtx(container, makeMockData(), { state: createInitialState('sunday') }));
     const dayLabels = container.querySelectorAll('text.day-label');
     const texts = Array.from(dayLabels).map((el) => el.textContent);
     expect(texts).toContain('Sun');

assets/test/interaction.test.ts

@@ -1,5 +1,7 @@
 import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
-import { renderHeatmap, init } from '../src/heatmap';
+import { init } from '../src/heatmap';
+import { YearModeRenderer } from '../src/renderers/year';
+import { createInitialState } from '../src/state';
 import type { HeatmapData } from '../src/types';
 
 const MOCK_DATA: HeatmapData = {
@@ -10,22 +12,31 @@ const MOCK_DATA: HeatmapData = {
   range: { begin: '2025-01-01', end: '2025-01-14' },
 };
 
+const DEFAULT_CONFIG = { cellSize: 13, cellGap: 2, marginTop: 20, marginLeft: 30, marginBottom: 4 };
+
 describe('click navigation', () => {
   let container: HTMLDivElement;
+  let renderer: YearModeRenderer;
 
   beforeEach(() => {
     container = document.createElement('div');
     document.body.appendChild(container);
+    renderer = new YearModeRenderer();
   });
 
   afterEach(() => {
+    renderer.destroy();
+    document.querySelectorAll('.heatmap-tooltip').forEach(el => el.remove());
     document.body.removeChild(container);
     vi.restoreAllMocks();
   });
 
   it('calls onCellClick with dateStr when a data cell is clicked', () => {
     const onClick = vi.fn();
-    renderHeatmap(container, MOCK_DATA, undefined, onClick);
+    renderer.render({
+      container, data: MOCK_DATA, state: createInitialState('monday'),
+      config: DEFAULT_CONFIG, onCellClick: onClick,
+    });
     const cell = container.querySelector('rect.heatmap-cell:not(.heatmap-empty)') as SVGRectElement;
     cell.dispatchEvent(new MouseEvent('click', { bubbles: true }));
     expect(onClick).toHaveBeenCalledOnce();
@@ -34,20 +45,29 @@ describe('click navigation', () => {
 
   it('calls onCellClick when an empty cell is clicked', () => {
     const onClick = vi.fn();
-    renderHeatmap(container, MOCK_DATA, undefined, onClick);
+    renderer.render({
+      container, data: MOCK_DATA, state: createInitialState('monday'),
+      config: DEFAULT_CONFIG, onCellClick: onClick,
+    });
     const emptyCell = container.querySelector('rect.heatmap-empty') as SVGRectElement;
     emptyCell.dispatchEvent(new MouseEvent('click', { bubbles: true }));
     expect(onClick).toHaveBeenCalledOnce();
   });
 
   it('does not throw when no onCellClick provided', () => {
-    renderHeatmap(container, MOCK_DATA);
+    renderer.render({
+      container, data: MOCK_DATA, state: createInitialState('monday'),
+      config: DEFAULT_CONFIG,
+    });
     const cell = container.querySelector('rect.heatmap-cell') as SVGRectElement;
     expect(() => cell.dispatchEvent(new MouseEvent('click', { bubbles: true }))).not.toThrow();
   });
 
   it('all cells have heatmap-cell class for cursor styling', () => {
-    renderHeatmap(container, MOCK_DATA);
+    renderer.render({
+      container, data: MOCK_DATA, state: createInitialState('monday'),
+      config: DEFAULT_CONFIG,
+    });
     const allRects = container.querySelectorAll('rect.heatmap-cell');
     expect(allRects.length).toBeGreaterThan(0);
     allRects.forEach((rect) => {

assets/test/registry.test.ts

@@ -0,0 +1,34 @@
+import { describe, it, expect, beforeEach } from 'vitest';
+import { registerRenderer, getRenderer, clearRegistry } from '../src/renderers/registry';
+import type { ModeRenderer, RenderContext } from '../src/renderers/types';
+
+function makeMockRenderer(mode: string): ModeRenderer {
+  return {
+    mode,
+    render(_ctx: RenderContext): void {},
+  };
+}
+
+describe('renderer registry', () => {
+  beforeEach(() => {
+    clearRegistry();
+  });
+
+  it('registers and retrieves a renderer by mode', () => {
+    const renderer = makeMockRenderer('year');
+    registerRenderer(renderer);
+    expect(getRenderer('year')).toBe(renderer);
+  });
+
+  it('throws for unknown mode', () => {
+    expect(() => getRenderer('nonexistent')).toThrowError('Unknown heatmap mode');
+  });
+
+  it('overwrites renderer for same mode', () => {
+    const first = makeMockRenderer('year');
+    const second = makeMockRenderer('year');
+    registerRenderer(first);
+    registerRenderer(second);
+    expect(getRenderer('year')).toBe(second);
+  });
+});

assets/test/state.test.ts

@@ -0,0 +1,26 @@
+import { describe, it, expect } from 'vitest';
+import { createInitialState } from '../src/state';
+
+describe('createInitialState', () => {
+  it('returns correct defaults for monday start', () => {
+    const state = createInitialState('monday');
+    expect(state).toEqual({
+      mode: 'year',
+      metric: 'hours',
+      filters: { projectId: null, customerId: null, activityId: null },
+      weekStart: 'monday',
+      data: null,
+    });
+  });
+
+  it('returns correct defaults for sunday start', () => {
+    const state = createInitialState('sunday');
+    expect(state).toEqual({
+      mode: 'year',
+      metric: 'hours',
+      filters: { projectId: null, customerId: null, activityId: null },
+      weekStart: 'sunday',
+      data: null,
+    });
+  });
+});

assets/test/stats.test.ts

@@ -1,7 +1,7 @@
 import { describe, it, expect } from 'vitest';
 import { timeFormat } from 'd3-time-format';
 import { timeDay } from 'd3-time';
-import { calculateStreak, calculateStats } from '../src/heatmap';
+import { calculateStreak, calculateStats } from '../src/shared/stats';
 import type { DayEntry } from '../src/types';
 
 const DATE_FORMAT = timeFormat('%Y-%m-%d');

assets/test/tooltip.test.ts

@@ -0,0 +1,52 @@
+import { describe, it, expect, beforeEach } from 'vitest';
+import { createTooltip, showTooltip, hideTooltip } from '../src/shared/tooltip';
+
+describe('tooltip', () => {
+  beforeEach(() => {
+    document.body.innerHTML = '';
+  });
+
+  describe('createTooltip', () => {
+    it('returns a div with class heatmap-tooltip and display none', () => {
+      const tip = createTooltip();
+      expect(tip).toBeInstanceOf(HTMLDivElement);
+      expect(tip.className).toBe('heatmap-tooltip');
+      expect(tip.style.display).toBe('none');
+    });
+
+    it('appends tooltip to document.body with fixed positioning', () => {
+      const tip = createTooltip();
+      expect(document.body.contains(tip)).toBe(true);
+      expect(tip.style.position).toBe('fixed');
+    });
+
+    it('removes existing tooltip before creating new one', () => {
+      const first = createTooltip();
+      const second = createTooltip();
+      const tooltips = document.querySelectorAll('.heatmap-tooltip');
+      expect(tooltips.length).toBe(1);
+      expect(tooltips[0]).toBe(second);
+      expect(document.body.contains(first)).toBe(false);
+    });
+  });
+
+  describe('showTooltip', () => {
+    it('sets display to block and positions tooltip', () => {
+      const tip = createTooltip();
+      const rect = { left: 100, top: 200 } as DOMRect;
+      showTooltip(tip, '<strong>Test</strong>', rect, 13);
+      expect(tip.style.display).toBe('block');
+      expect(tip.innerHTML).toBe('<strong>Test</strong>');
+      expect(tip.style.left).toBe('106.5px'); // 100 + 13/2
+    });
+  });
+
+  describe('hideTooltip', () => {
+    it('sets display to none', () => {
+      const tip = createTooltip();
+      tip.style.display = 'block';
+      hideTooltip(tip);
+      expect(tip.style.display).toBe('none');
+    });
+  });
+});

assets/test/week.test.ts

@@ -0,0 +1,178 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { WeekModeRenderer } from '../src/renderers/week';
+import type { RenderContext } from '../src/renderers/types';
+import type { HeatmapData } from '../src/types';
+import { createInitialState } from '../src/state';
+
+const DEFAULT_CONFIG = { cellSize: 13, cellGap: 2, marginTop: 20, marginLeft: 30, marginBottom: 4 };
+
+function makeCtx(container: HTMLElement, data: HeatmapData, overrides?: Partial<RenderContext>): RenderContext {
+  return {
+    container,
+    data,
+    state: createInitialState('monday'),
+    config: DEFAULT_CONFIG,
+    ...overrides,
+  };
+}
+
+// Known dates:
+// 2025-01-06 = Monday
+// 2025-01-07 = Tuesday
+// 2025-01-08 = Wednesday
+// 2025-01-13 = Monday (second Monday entry)
+function makeMockData(): HeatmapData {
+  return {
+    days: [
+      { date: '2025-01-06', hours: 2.5, count: 3 },  // Monday
+      { date: '2025-01-07', hours: 5.0, count: 5 },  // Tuesday
+      { date: '2025-01-08', hours: 1.0, count: 1 },  // Wednesday
+      { date: '2025-01-13', hours: 3.0, count: 2 },  // Monday (second)
+    ],
+    range: { begin: '2025-01-01', end: '2025-01-31' },
+  };
+}
+
+describe('WeekModeRenderer', () => {
+  let container: HTMLDivElement;
+  let renderer: WeekModeRenderer;
+
+  beforeEach(() => {
+    container = document.createElement('div');
+    document.body.appendChild(container);
+    renderer = new WeekModeRenderer();
+  });
+
+  afterEach(() => {
+    renderer.destroy();
+    document.querySelectorAll('.heatmap-tooltip').forEach(el => el.remove());
+    container.remove();
+  });
+
+  it('has mode "week"', () => {
+    expect(renderer.mode).toBe('week');
+  });
+
+  it('renders an SVG with exactly 7 rect elements', () => {
+    renderer.render(makeCtx(container, makeMockData()));
+    const svg = container.querySelector('svg.heatmap-svg');
+    expect(svg).not.toBeNull();
+    const rects = container.querySelectorAll('rect');
+    expect(rects.length).toBe(7);
+  });
+
+  it('aggregates same-weekday entries (two Mondays summed)', () => {
+    renderer.render(makeCtx(container, makeMockData()));
+    // Monday is index 0 for monday-start. It should have data (2.5+3.0=5.5h)
+    const rects = container.querySelectorAll('rect');
+    const mondayRect = rects[0]; // First rect = Monday
+    expect(mondayRect.classList.contains('heatmap-empty')).toBe(false);
+    expect(mondayRect.getAttribute('fill')).toBeTruthy();
+  });
+
+  it('marks weekdays with no data as heatmap-empty', () => {
+    renderer.render(makeCtx(container, makeMockData()));
+    // Data on Mon, Tue, Wed only. Thu, Fri, Sat, Sun should be empty = 4 empty
+    const emptyRects = container.querySelectorAll('rect.heatmap-empty');
+    expect(emptyRects.length).toBe(4);
+  });
+
+  it('data weekdays get a fill color (not empty)', () => {
+    renderer.render(makeCtx(container, makeMockData()));
+    const filledRects = container.querySelectorAll('rect:not(.heatmap-empty)');
+    expect(filledRects.length).toBe(3); // Mon, Tue, Wed
+    filledRects.forEach(rect => {
+      expect(rect.getAttribute('fill')).toBeTruthy();
+    });
+  });
+
+  it('renders all 7 weekday labels for monday start', () => {
+    renderer.render(makeCtx(container, makeMockData()));
+    const labels = container.querySelectorAll('text.heatmap-label');
+    expect(labels.length).toBe(7);
+    const texts = Array.from(labels).map(el => el.textContent);
+    expect(texts[0]).toBe('Mon');
+    expect(texts[6]).toBe('Sun');
+  });
+
+  it('renders labels in sunday-first order when weekStart is sunday', () => {
+    const state = createInitialState('sunday');
+    renderer.render(makeCtx(container, makeMockData(), { state }));
+    const labels = container.querySelectorAll('text.heatmap-label');
+    const texts = Array.from(labels).map(el => el.textContent);
+    expect(texts[0]).toBe('Sun');
+    expect(texts[1]).toBe('Mon');
+    expect(texts[6]).toBe('Sat');
+  });
+
+  it('shows tooltip with full weekday name and hours on hover', () => {
+    renderer.render(makeCtx(container, makeMockData()));
+    // Hover over Monday rect (index 0)
+    const rect = container.querySelectorAll('rect')[0];
+    rect.dispatchEvent(new MouseEvent('mouseenter', { bubbles: true }));
+
+    const tooltip = document.body.querySelector('.heatmap-tooltip') as HTMLDivElement;
+    expect(tooltip).not.toBeNull();
+    expect(tooltip.style.display).toBe('block');
+    expect(tooltip.innerHTML).toContain('Monday');
+    expect(tooltip.innerHTML).toContain('5.5h');
+    expect(tooltip.innerHTML).toContain('5 entries');
+  });
+
+  it('shows count-first tooltip when metric is count', () => {
+    const state = createInitialState('monday');
+    state.metric = 'count';
+    renderer.render(makeCtx(container, makeMockData(), { state }));
+    const rect = container.querySelectorAll('rect')[0]; // Monday
+    rect.dispatchEvent(new MouseEvent('mouseenter', { bubbles: true }));
+
+    const tooltip = document.body.querySelector('.heatmap-tooltip') as HTMLDivElement;
+    expect(tooltip.innerHTML).toContain('5 entries');
+    expect(tooltip.innerHTML).toContain('5.5h');
+    // Count should come before hours in the text
+    const html = tooltip.innerHTML;
+    expect(html.indexOf('5 entries')).toBeLessThan(html.indexOf('5.5h'));
+  });
+
+  it('shows "No tracked time" tooltip for empty weekday', () => {
+    renderer.render(makeCtx(container, makeMockData()));
+    // Thursday is index 3 (monday-start), has no data
+    const rect = container.querySelectorAll('rect')[3];
+    rect.dispatchEvent(new MouseEvent('mouseenter', { bubbles: true }));
+
+    const tooltip = document.body.querySelector('.heatmap-tooltip') as HTMLDivElement;
+    expect(tooltip.innerHTML).toContain('Thursday');
+    expect(tooltip.innerHTML).toContain('No tracked time');
+  });
+
+  it('destroy() removes tooltip element', () => {
+    renderer.render(makeCtx(container, makeMockData()));
+    expect(document.body.querySelector('.heatmap-tooltip')).not.toBeNull();
+    renderer.destroy();
+    expect(document.body.querySelector('.heatmap-tooltip')).toBeNull();
+  });
+
+  it('handles empty data gracefully', () => {
+    const data: HeatmapData = {
+      days: [],
+      range: { begin: '2025-01-01', end: '2025-01-31' },
+    };
+    renderer.render(makeCtx(container, data));
+    const svg = container.querySelector('svg');
+    expect(svg).toBeNull();
+    expect(container.textContent).toContain('No tracking data available');
+  });
+
+  it('all rects have heatmap-week-cell class', () => {
+    renderer.render(makeCtx(container, makeMockData()));
+    const rects = container.querySelectorAll('rect.heatmap-week-cell');
+    expect(rects.length).toBe(7);
+  });
+
+  it('rects have rounded corners', () => {
+    renderer.render(makeCtx(container, makeMockData()));
+    const rect = container.querySelector('rect');
+    expect(rect?.getAttribute('rx')).toBe('2');
+    expect(rect?.getAttribute('ry')).toBe('2');
+  });
+});

composer.json

@@ -3,6 +3,17 @@
     "type": "kimai-plugin",
     "description": "GitHub-style activity heatmap dashboard widget for Kimai",
     "license": "MIT",
+    "keywords": ["kimai", "plugin", "heatmap", "dashboard", "time-tracking"],
+    "homepage": "https://git.toph.so/toph/kimai-plugin-heatmap",
+    "authors": [
+        {
+            "name": "Christopher Mühl",
+            "homepage": "https://toph.so"
+        }
+    ],
+    "require": {
+        "php": ">=8.2"
+    },
     "autoload": {
         "psr-4": {
             "KimaiPlugin\\KimaiHeatmapBundle\\": ""