|
| 1 | +# mapper Development Guidelines |
| 2 | + |
| 3 | +Auto-generated from all feature plans. Last updated: 2026-02-27 |
| 4 | + |
| 5 | +## Active Technologies |
| 6 | +- JavaScript ES2022+ (ES modules) + @playwright/test 1.58+, nanostores 1.1, deck.gl 9.2, Vite 7.3, Claude Code Task agents (Sonnet 4.6 / Opus 4.6 for persona evaluation — no API key needed) (004-persona-user-testing) |
| 7 | +- File-based JSON (question banks in `data/domains/`), localStorage (user progress) (004-persona-user-testing) |
| 8 | +- JavaScript ES2022+ (ES modules), HTML5, CSS3 + nanostores 1.1, Vite 7.3, Canvas 2D API, KaTeX (CDN), deck.gl 9.2 (006-performance-and-ux-refinement) |
| 9 | +- localStorage (user progress), file-based JSON (question banks in `data/domains/`) (006-performance-and-ux-refinement) |
| 10 | +- JavaScript ES2022+ (ES modules), HTML5, CSS3 + nanostores 1.1, Vite 7.3, deck.gl 9.2, KaTeX (CDN) (007-fix-mobile-mode) |
| 11 | +- localStorage (user progress), file-based JSON (question banks) (007-fix-mobile-mode) |
| 12 | +- JavaScript ES2022+ (ES modules), HTML5, CSS3 + nanostores 1.1, Vite 7.3, deck.gl 9.2, KaTeX (CDN), pako (new — for deflate compression) (008-shareable-map-links) |
| 13 | +- localStorage (user progress), URL query parameter (shared state) (008-shareable-map-links) |
| 14 | + |
| 15 | +- JavaScript ES2022+ (ES modules), HTML5, CSS3 + nanostores 1.1.0, Vite 7.3.1, Canvas 2D API, KaTeX (CDN) (003-ux-bugfix-cleanup) |
| 16 | + |
| 17 | +## Project Structure |
| 18 | + |
| 19 | +```text |
| 20 | +backend/ |
| 21 | +frontend/ |
| 22 | +tests/ |
| 23 | +``` |
| 24 | + |
| 25 | +## Commands |
| 26 | + |
| 27 | +npm test && npm run lint |
| 28 | + |
| 29 | +## Code Style |
| 30 | + |
| 31 | +JavaScript ES2022+ (ES modules), HTML5, CSS3: Follow standard conventions |
| 32 | + |
| 33 | +## Recent Changes |
| 34 | +- 008-shareable-map-links: Added JavaScript ES2022+ (ES modules), HTML5, CSS3 + nanostores 1.1, Vite 7.3, deck.gl 9.2, KaTeX (CDN), pako (new — for deflate compression) |
| 35 | +- 007-fix-mobile-mode: Added JavaScript ES2022+ (ES modules), HTML5, CSS3 + nanostores 1.1, Vite 7.3, deck.gl 9.2, KaTeX (CDN) |
| 36 | +- 006-performance-and-ux-refinement: Added JavaScript ES2022+ (ES modules), HTML5, CSS3 + nanostores 1.1, Vite 7.3, Canvas 2D API, KaTeX (CDN), deck.gl 9.2 |
| 37 | + |
| 38 | + |
| 39 | +<!-- MANUAL ADDITIONS START --> |
| 40 | + |
| 41 | +## Mobile Testing |
| 42 | + |
| 43 | +- Mobile view is **landscape** (the app locks to landscape on phone-sized devices) |
| 44 | +- Test mobile at viewport ~812×375 (iPhone landscape), NOT portrait |
| 45 | +- The landscape breakpoint is `@media (max-height: 500px) and (orientation: landscape)` |
| 46 | +- The portrait ≤480px breakpoint also applies but landscape is the primary mobile experience |
| 47 | + |
| 48 | +## Browser Automation (Playwright MCP) |
| 49 | + |
| 50 | +- Use **screenshots** (`browser_take_screenshot`), NOT snapshots (`browser_snapshot`), to inspect page content — snapshots return massive DOM trees that exceed token limits on complex pages |
| 51 | +- Use `browser_evaluate` for targeted DOM queries when you need specific element state |
| 52 | +- The deck.gl canvas does NOT auto-resize when hiding DOM elements — must dispatch `window resize` event or reload at the correct viewport size |
| 53 | + |
| 54 | +<!-- MANUAL ADDITIONS END --> |
0 commit comments