# A New Day

> A privacy-first daily checklist PWA designed for people rebuilding routines

## Overview

A New Day is a progressive web app (PWA) that provides a simple daily to-do list with one unique feature: automatic midnight reset. All tasks uncheck at local midnight, encouraging users to focus on today rather than accumulating incomplete tasks.

## Purpose

Built for people in recovery or rebuilding life routines. The app intentionally avoids:
- Progress tracking or streaks
- Social sharing features
- Gamification or judgment
- Analytics or user tracking

## Technical Stack

- **Framework**: Svelte 5 (latest version with new `mount()` API)
- **Build Tool**: Vite 7
- **Storage**: IndexedDB (via native browser API)
- **Styling**: TailwindCSS with custom brand colors
- **Testing**: Vitest (unit), Playwright (e2e, a11y)
- **Type Safety**: TypeScript
- **PWA**: vite-plugin-pwa with Workbox

## Key Features

1. **Midnight Reset**: Tasks automatically uncheck at local midnight
2. **Multiple List Modes**: Single list or Morning/Anytime/Evening organization
3. **Drag & Drop**: Reorder tasks with SortableJS
4. **Offline Support**: Full PWA with service worker
5. **Data Privacy**: All data stored locally, optional encrypted export
6. **Accessibility**: WCAG AA compliant, keyboard navigation, screen reader support
7. **Dark Mode**: Automatic theme detection with manual toggle

## Architecture

### Frontend Structure
```
src/
├── components/        # Svelte components
│   ├── settings/     # Settings panel content
│   ├── AddTaskForm.svelte
│   ├── SettingsDrawer.svelte
│   ├── TodoItem.svelte
│   └── TodoList.svelte
├── lib/
│   ├── db.ts         # IndexedDB operations
│   ├── reset.ts      # Midnight reset logic
│   └── state.svelte.ts  # Svelte 5 state management
├── App.svelte        # Main app component
└── main.ts           # Entry point
```

### State Management
- Uses Svelte 5's new runes system ($state, $derived, $effect)
- Global state in `state.svelte.ts`
- No external state management library needed

### Data Storage
- IndexedDB stores: `tasks`, `settings`, `appState`
- No backend or cloud sync
- Export/import via encrypted or plain JSON

### Build Configuration
- Critical CSS inlined for LCP optimization
- Font preloading with `fetchpriority="high"`
- esbuild minification targeting ES2020
- Service worker auto-generation via vite-plugin-pwa

## Performance Optimizations

- **Lighthouse Score**: 97/100 (see docs/performance.md for detailed metrics)
- **Bundle Size**: 222 KB (71 KB gzipped)
- **Critical Path**: Inline CSS for hero content
- **Font Loading**: Preload Work Sans with priority hints
- **No Code Splitting**: Single bundle for faster initial load

**Key Metrics:**
- FCP: 1.4-2.1s (score: 0.81-0.98)
- LCP: 2.3s (score: 0.94)
- TBT: 0ms (score: 1.00)
- CLS: 0 (score: 1.00)
- Speed Index: 1.4-2.1s (score: 0.99-1.00)

For detailed performance analysis, bundle composition, and optimization decisions, see `docs/performance.md`.

## Development

### Quick Start
```bash
npm install          # Install dependencies (~30s)
npm run dev         # Development server at http://localhost:5173
npm run build       # Production build (~1s)
npm run preview     # Preview production build at http://localhost:4173
```

### Testing Commands
```bash
npm run test:unit                    # Run unit tests (8 tests, <1s)
npm run test:e2e                     # Run e2e tests across all browsers (~30s)
npm run test:e2e:chromium            # Run e2e tests in Chromium only (~10s)
npm run test:e2e:keyboard-navigation # Specific keyboard navigation tests
npm run test:a11y                    # Run accessibility tests with axe-core (~15s)
```

### Performance & Analysis
```bash
npm run build                        # Generates dist/stats.html for bundle analysis
npx lighthouse http://localhost:4173 # Run Lighthouse (requires preview server)
```

### Common Workflows

**Before committing:**
```bash
npm run test:unit && npm run build
```

**Full test suite:**
```bash
npm run test:unit && npm run test:e2e && npm run test:a11y
```

**Performance check:**
```bash
npm run build && npm run preview
# Then run Lighthouse in another terminal
```

### Expected Behaviors
- Unit tests: Always pass, fast (<1s)
- E2E tests: ~30s for all browsers, ~10s for Chromium only
- Build: Consistently produces 222KB bundle (71KB gzipped)
- Lighthouse: Expect 95-99 performance score (97 typical)
- Dev server: Hot module replacement works for all Svelte components

## Security & Privacy

1. **Content Security Policy**: Strict CSP with nonces
2. **No External Requests**: All resources served locally
3. **No Analytics**: Zero tracking or telemetry
4. **Optional Encryption**: AES-GCM for data export
5. **No Account Required**: Fully functional without authentication

## Browser Compatibility

- Modern browsers with ES2020 support
- Service worker support for offline functionality
- IndexedDB for local storage
- Prefers-color-scheme for dark mode

## Testing Strategy

- **Unit Tests**: Vitest with fake-indexeddb
- **E2E Tests**: Playwright across Chromium, Firefox, WebKit, mobile
- **A11y Tests**: @axe-core/playwright for WCAG compliance
- **Performance**: Lighthouse CI in pipeline

## Design Philosophy

1. **Simplicity**: No feature bloat, focused on core task management
2. **Privacy**: Local-first, no external dependencies
3. **Accessibility**: Keyboard navigation, screen reader support, WCAG AA
4. **Performance**: Fast initial load, smooth interactions
5. **Recovery-Focused**: Non-judgmental, present-focused tool

## Notable Implementation Details

- Midnight reset uses `setTimeout` with precise calculation to next midnight
- Tasks persist even when app is closed (IndexedDB survives browser restart)
- Service worker handles offline mode and auto-updates
- Drag-and-drop uses SortableJS for cross-browser compatibility
- Custom validation for form inputs (no HTML5 validation messages)

## Recent Changes (Changelog)

### v2.0.0 (November 2025) - Current Version

**Major Framework Upgrade:**
- Upgraded from Svelte 4 → Svelte 5 (new `mount()` API, runes system)
- Upgraded Vite 5 → Vite 7 and Vitest 1 → Vitest 4
- Migrated to new Svelte 5 state management ($state, $derived, $effect)

**Security Fixes:**
- Fixed all Dependabot vulnerabilities (glob, js-yaml, esbuild, tmp)
- Now 0 security vulnerabilities in dependencies
- Maintained strict CSP and encryption features

**Performance Optimizations:**
- Added inline critical CSS for LCP (eliminates render-blocking)
- Added `fetchpriority="high"` to font preloads
- Configured build with esbuild minification and ES2020 target
- Disabled modulePreload polyfill for modern browsers
- Lighthouse score maintained at 97/100

**Accessibility Improvements:**
- Fixed switch controls with proper `aria-labelledby` attributes
- Fixed keyboard navigation test reliability across browsers
- All Svelte compiler a11y warnings resolved

**Testing:**
- All 48 tests passing (8 unit, 30 e2e, 10 a11y)
- Improved keyboard navigation test stability
- Service worker test environment detection

### v1.1.0 (Earlier 2025)

**UI/UX Redesign:**
- Switched to Work Sans font family
- Standardized typography across components
- Updated brand color palette
- Improved dark mode contrast

**Accessibility:**
- Enhanced keyboard navigation
- Screen reader improvements
- WCAG AA compliance verified

**Service Worker:**
- Improved auto-update mechanism
- Better offline support
- Fixed test environment conflicts

### v1.0.0 (Initial Release)

- Core daily checklist functionality
- Midnight reset mechanism
- IndexedDB storage
- Single list mode
- Basic PWA support

## Contributing

This is a personal project focused on simplicity and privacy. The codebase is intentionally minimal and well-documented for easy understanding.

## Additional Documentation

- **Performance Details:** `docs/performance.md` - Bundle analysis, Lighthouse metrics, optimization decisions
- **API Reference:** `docs/api-reference.md` - IndexedDB schema, state management, data structures
- **Security Checklist:** `docs/security-checklist.md` - Threat model, CSP configuration, intentional security decisions
- **Accessibility:** `docs/a11y-report.md` - WCAG compliance testing results
- **Deployment:** `docs/deployment-netlify.md` - Netlify configuration and deployment process

## Links

- GitHub: https://github.com/studiokicobi/anewday
- Live App: https://anewday.app
- License: [Check repository]

---

Last updated: 2025-11-21
Svelte Version: 5.0.0
Node Version: >=18