v4.0.0 — "Horizon"

Draft Release Notes

✨ New Features

Monthly View for Savings vs Investment Growth

• Added a monthly breakdown mode to the "Savings vs Investment Growth" chart on the History page
• Toggle between Annual (year-by-year) and Monthly (month-by-month) views directly in the chart header
• In monthly view, select any year from the dropdown to see all 12 months side-by-side
• Each bar shows how much of that month's net worth change came from disciplined saving vs market performance
• Months where investment returns were negative are shown in red; positive months in blue — same visual language as the annual view

Stamp Duty (Imposta di Bollo) Tracking

• Enable stamp duty tracking from Settings with a configurable annual rate (e.g. 0.20%)
• Stamp duty cost is included in the "Annual Portfolio Cost" card on the dashboard, alongside TER costs — a breakdown shows each component when both are active
• Specify which cash sub-category represents checking accounts (conti correnti): stamp duty for these accounts applies only when their balance exceeds €5,000
• Mark any individual asset as exempt from stamp duty directly from the asset edit dialog — useful for pension funds, real estate, or any other asset that qualifies for exemption

Linked Cash Account for Transactions

• Link any expense or income entry to a cash account (bank account, current account) directly from the transaction dialog
• Account balance updates automatically when a transaction is saved — no manual adjustment needed
• Bidirectional: editing a transaction adjusts the balance by the delta; deleting reverses the effect
• For recurring and installment series, only the first entry updates the account balance
• Optional field: fully backwards-compatible with existing transactions

Default Cash Accounts in Settings

• Set a default withdrawal account for expenses and a separate default credit account for income in Settings
• Pre-selected automatically when creating new transactions — override anytime in the dialog
• Label in the dialog adapts dynamically: "Withdrawal Account" for expenses, "Credit Account" for income
• Dropdowns only appear in Settings if you have at least one cash-class asset

Unified Month Filter for Cashflow Charts

• Added unified month filter for 3 main cashflow charts in Current Year tab: Sankey diagram, Expenses by Category, and Income by Category
• Filter dropdown with all 12 months in Italian + "All year" option to easily analyze specific months
• Charts reordered with filtered section at the top for better visibility (Sankey → Expenses → Income → other charts)
• Visual grouping with blue-bordered container clearly showing which charts are affected by the filter
• Visual indicator banner showing active filter with quick clear button
• Dynamic chart titles update to reflect selected month (e.g., "Expenses by Category - March 2026")
• Drill-down navigation preserved when changing month filter - explore subcategories in filtered data without losing your place
• Helpful empty state message when selected month has no transactions
• Timezone-aware filtering ensures consistent results regardless of server location
• Filter does not affect other charts (trends, expense types) for full year comparison

Doubling Time Analysis

• Added Doubling Time Analysis section to History page to track how long your net worth takes to double over time
• Dual-mode visualization:
  • Geometric mode: Track exponential growth (2x, 4x, 8x, 16x...)
  • Fixed Thresholds mode: Track psychological milestones (€100k, €200k, €500k, €1M, €2M)
• Toggle button to easily switch between calculation modes
• Summary metrics dashboard showing:
  • Fastest doubling period achieved
  • Average time to double across all milestones
  • Total number of milestones completed
• Timeline visualization displaying all completed milestones with detailed information
• Progress tracking for current milestone in progress with percentage completion and progress bar
• Smart handling of edge cases (negative net worth periods, insufficient data, portfolios starting above thresholds)

AI Performance Analysis

• Added AI-powered portfolio analysis button on Performance page powered by Claude Sonnet 4.5
• Click "Analizza con AI" button (with sparkles icon) to get instant AI-generated insights on your portfolio metrics
• Real-time streaming analysis appears progressively as it's generated (ChatGPT-style experience)
• AI analyzes all your performance metrics (returns, risk, dividends) for the selected time period
• Get actionable insights including:
  • Interpretation of key metrics and what they mean for your portfolio
  • Strengths highlighted in your performance
  • Areas for improvement or risks to consider
  • Concrete suggestions when appropriate
• Beautiful dialog interface with markdown formatting (bold text, bullet points) for easy reading
• Regenerate button to get fresh analysis if needed
• Works across all time periods (YTD, 1Y, 3Y, 5Y, ALL, CUSTOM)
• Analysis in Italian language matching the rest of the app
• Disclaimer footer reminding users that AI analysis is not financial advice

Period Analysis in Total History (Cashflow)

• Added "Analisi Periodo" section to the Total History (Storico Totale) tab in Cashflow page
• Three interactive charts: Sankey flow diagram, Expenses by Category pie chart, Income by Category pie chart
• Year + Month filtering: optionally filter by year first, then refine by month
• Shows all historical data (2025+) by default — filters are optional refinements, not prerequisites
• Three-level drill-down on pie charts: Category → Subcategory → Individual transactions with dates, amounts, notes, and links
• Blue-bordered container with filter badge showing active filters and quick clear button
• Dynamic chart titles update to reflect selected period (e.g., "Flusso Finanziario - Gennaio 2026")
• Drill-down state resets automatically when filters change to prevent stale data
• Removed redundant standalone Sankey chart (now integrated in the Analisi Periodo section with filtering support)

Hall of Fame Dedicated Notes System

• Added dedicated notes system for Hall of Fame rankings, completely separate from History page notes
• Create and edit notes associated with specific time periods (year and optional month)
• Multi-section support: Associate a single note with multiple ranking tables using checkboxes
  • Example: "Bought car €22,000" can appear in both "Worst Month: Expenses" and "Worst Month: Net Worth Change"
• Improved UX with dual-dialog pattern: Click amber icon to view note first (read-only), then optionally edit
  • View dialog shows note content with period and associated sections in clean, organized layout
  • "Modifica Nota" button in view dialog footer transitions to edit mode when needed
  • Separates casual viewing from intentional editing for better user experience
• Smart month field: Automatically hides when only yearly sections selected, becomes required for monthly sections
• Visual note indicators: Amber message icon buttons displayed in relevant ranking tables
• "Aggiungi Nota" button in page header for creating new notes
• Note preservation: User notes automatically preserved during ranking recalculations (triggered after new snapshots)
• 500 character limit with real-time counter and color-coded warnings (green/orange/red)
• Full CRUD operations: Create, view, edit, and delete notes with instant UI updates
• Period-specific filtering: Notes only appear in tables matching their year/month and selected sections
• Available for all 8 ranking tables: 4 monthly (Best/Worst by Net Worth/Income/Expenses) + 4 yearly

Bond Coupon Scheduling with Step-Up Rates and Final Premium

• Bonds now support automatic coupon generation: configure coupon rate, frequency (monthly/quarterly/semiannual/annual), issue date, maturity date, and nominal value per unit to generate the next coupon automatically on every save
• Step-up coupon rates: enable variable coupon rates with up to 5 rate tiers, each covering a range of bond years (e.g. BTP Valore: 2.50% years 1–2, 2.80% years 3–4, 3.20% years 5–6) — each coupon is calculated using the applicable rate for its payment date
• Final premium (Premio Finale): set an optional bonus percentage paid at maturity (e.g. BTP Valore 0.8% of nominal value) — automatically recorded as a "Premio Finale" dividend entry on the maturity date
• Italian government bond tax hint: clickable shortcut under the tax rate field fills in 12.5% for BTP, BOT, and CCT bonds
• Bond details (coupon schedule) and cost basis sections now open automatically when creating a new bond asset
• Coupon and final premium entries are recreated automatically whenever you edit and save the asset (e.g. when updating quantity)

Bond Price Tracking from Borsa Italiana

• Added automatic bond price updates from Borsa Italiana for Italian MOT bonds with ISIN codes
• ISIN field now editable for bonds in asset form (previously only available for stocks/ETFs for dividend tracking)
• Dual-source price fetching: Borsa Italiana as primary source for bonds, Yahoo Finance as fallback
• Integrated in 3 price update flows: monthly automatic snapshots, manual "Update Prices" button, and "Create Snapshot" button
• Dynamic UI labels show correct price source ("Borsa Italiana" for bonds with ISIN, "Yahoo Finance" for other assets)
• Graceful error handling with automatic fallback to Yahoo Finance if Borsa Italiana scraping fails
• Multi-level fallback strategy within Borsa Italiana scraper (ultimo contratto → prezzo ufficiale → apertura → table structure)
• Test API endpoint /api/prices/bond-quote?isin={ISIN} for manual price validation
• 6 new unit tests covering ISIN validation logic for Italian bonds
• Timeout optimized for Borsa Italiana's response times (30 seconds)
• Backwar...

v3.0.0 - New features + optimization

What's New

Features

• Cashflow Sankey - Subcategories Toggle: Optional detailed view showing subcategory breakdown directly in main flow chart
  • Toggle control: "Mostra sottocategorie" button in top-right corner switches between 4-layer and 5-layer visualization
  • 5-layer structure: Income → Budget → Types → Categories → Subcategories + Savings for granular expense visibility
  • One-click navigation: Direct click on any subcategory opens transaction details (vs 3 clicks in drill-down)
  • Smart filtering: Categories without real subcategories (only "Altro") remain at 4-layer for cleaner view
  • Clean labels: Subcategories display name only (e.g., "Coop" instead of "Cibo_Coop") for better readability
  • Mobile optimized: Top 4 subcategories per category on mobile prevents overcrowding (~50 nodes total)
  • Color hierarchy: Subcategory colors automatically derived from parent category with brightness variations
  • Dual navigation paths: Use either traditional drill-down (Type → Category → Subcategory) or direct 5-layer click
  • Backward compatible: Default OFF preserves existing UX, toggle state preserved during navigation
  • Responsive positioning: Toggle button stacks vertically on mobile, aligned right on desktop (matches "% Percentuali" pattern)

Features

• FIRE Calculator - Primary Residence Exclusion: Enhanced FIRE (Financial Independence Retire Early) calculations with configurable primary residence treatment

  • Primary residence flag: Mark real estate assets as "Casa di Abitazione" (primary residence) in the asset form
  • Conditional UI: Checkbox appears only for real estate assets, keeps form clean for other asset types
  • Global FIRE setting: New toggle "Includi Casa di Abitazione nel Calcolo FIRE" in FIRE Calculator settings
  • Standard FIRE methodology: Default behavior excludes primary residences (you need somewhere to live, not liquid for retirement income)
  • Flexible inclusion: Easily include all primary residences with one toggle if planning to downsize or relocate in retirement
  • Outstanding debt handling: Net equity calculation automatically factors in mortgages/loans before applying exclusion
  • Smart calculation: New calculateFIRENetWorth() function conditionally filters primary residences based on user preference
  • PDF consistency: Export reports use identical calculation and setting as UI for accurate documentation
  • No breaking changes: Existing assets without flag are included by default; existing settings default to exclusion (FIRE standard)
  • Multiple properties: Support for marking multiple primary residences, all controlled by single global toggle
  • Educational help text: Inline explanations guide users on FIRE methodology and when to include/exclude
  • Real-time updates: FIRE Number, progress percentage, and current allowances recalculate instantly when toggling setting
  • Example scenario: €300k primary residence + €200k investment property + €100k stocks → Setting OFF = €300k FIRE net worth, Setting ON = €600k FIRE net worth

• Performance Metrics Categorization: Reorganized 15 performance metrics into 4 logical categories with visual section headers for improved scannability

  • Four category sections: Metriche di Rendimento (4 metrics), Metriche di Rischio (5 metrics), Metriche di Contesto (2 metrics), Metriche Dividendi (4 metrics)
  • Visual section headers: Each category displays title with emoji icon and descriptive subtitle explaining what metrics measure
  • Rendimento section: Groups return metrics (ROI, CAGR, TWR, IRR) showing portfolio growth performance
  • Rischio section: Consolidates risk metrics (Volatilità, Sharpe Ratio, Max Drawdown, Drawdown Duration, Recovery Time) for downside analysis
  • Contesto section: Contextual information (Contributi Netti, Durata) providing period details and capital flow data
  • Dividendi section: Dividend metrics (YOC Gross/Net, Current Yield Gross/Net) with conditional rendering (visible only when data available)
  • Better information architecture: Logical grouping reduces cognitive load when scanning 15+ metrics
  • Educational value: Section descriptions teach users what each category represents and why it matters
  • Reusable component: New MetricSection component enables consistent layout across all categories
  • Responsive grid: Mobile (1 column), tablet (2 columns), desktop (4 columns) for optimal viewing on all devices
  • No gap in Row 3: Risk section now displays 5 cards (was 3 with empty space) for balanced visual layout
  • Semantic HTML: h2 headers for section titles improve accessibility and screen reader support
  • Dark mode support: Section headers and descriptions adapt to dark theme with appropriate text colors
  • Updated methodology notes: New "Organizzazione delle Metriche" section explains categorization rationale
  • Zero functional changes: All existing metrics, tooltips, calculations remain identical - purely UX improvement
  • Same period switching: Category headers persist when changing timeframes (YTD, 1Y, 3Y, 5Y, ALL, Custom)

• PDF Export - Performance Section: Comprehensive performance metrics now available in PDF portfolio reports for offline analysis and record-keeping

  • 8-section PDF reports: New Performance section joins Portfolio, Allocation, History, Cashflow, FIRE, and Summary for complete portfolio documentation
  • All 15 metrics included: Four category sections (Rendimento, Rischio, Contesto, Dividendi) with professional formatting and color coding
  • Smart availability: Performance section enabled only for annual (YTD) and total (all-time) exports - automatically disabled for monthly reports lacking sufficient data
  • Period-aware display: Section header shows exact timeframe analyzed (e.g., "Performance Portafoglio - YTD 2026" or "Performance Portafoglio - Storico Totale")
  • Detailed Contributi Netti: Net contributions card includes breakdown showing Entrate (income), Dividendi (dividends), and Uscite (expenses) matching Performance page UI
  • Professional formatting: Percentages, currencies, and durations formatted with Italian conventions; color-coded values (green positive, red negative, gray neutral)
  • Graceful degradation: Section automatically omitted when insufficient data (< 2 snapshots) without breaking PDF generation
  • Dividend metrics conditional: YOC and Current Yield section appears only when dividend data available for cleaner reports
  • User benefit: Export complete performance snapshot for tax documentation, financial advisor consultations, or personal record-keeping
  • UI consistency: Checkbox in export dialog matches time filter restrictions (disabled for monthly with explanatory tooltip)
  • Zero performance impact: Reuses existing performance calculation engine with cached snapshots and parallel API fetching

Features

• Current Yield Metrics (Gross & Net): Comprehensive dividend yield analysis based on current market value

  • Dual metrics: Current Yield Lordo (gross) and Current Yield Netto (net, after-tax) for complete dividend yield visibility
  • Market-based calculation: Formula uses current portfolio value instead of original cost basis (unlike YOC)
  • Period-aware annualization: All timeframes (YTD, 1Y, 3Y, 5Y, All Time, Custom) use annualized dividends for fair comparison across periods
  • Annualization logic: Periods < 12 months scale up (e.g., 6 months → ×2), periods ≥ 12 months use average annual rate
  • Dynamic YOC comparison: Automatic tooltip comparison between Current Yield and YOC metrics (Gross vs Gross, Net vs Net)
  • Performance page integration: Four-card Row 4 layout - YOC Lordo | YOC Netto | Current Yield Lordo | Current Yield Netto
  • Detailed card info: Each card displays total dividends (gross/net), current portfolio value, and number of assets included
  • Educational content: Comprehensive methodology notes with formulas, real examples (€9,500 portfolio example), and interpretation guidance
  • Investment insights: Shows if dividends grew faster than stock price (CY < YOC = good for early investors) or vice versa (CY > YOC = capital appreciation)
  • Removed from Cashflow: "Yield Medio" card removed from dividend stats (consolidated in Performance page for better discoverability)
  • API architecture: Server-side /api/performance/current-yield endpoint using Firebase Admin SDK for optimal data access

• Savings vs Investment Growth Chart: New visualization in History page breaking down net worth growth into controllable vs external factors

  • Dual component breakdown: Stacked bars showing Net Savings (green) from your income/expenses + Investment Growth (blue/red) from market performance
  • Annual granularity: Year-by-year comparison for clear long-term trends without monthly noise
  • Conditional coloring: Blue bars for positive market gains, red bars for market losses - immediate visual recognition
  • Total visibility: Stacked bar height always equals total net worth growth, showing exact composition
  • Resilience insight: See how your savings habit protected wealth during market downturns (e.g., +€10k savings offsetting -€2k market loss = +€8k growth)
  • Performance attribution: Understand whether growth came from your discipline (savings) or external luck (markets)
  • Smart filtering: Only displays years with both snapshots and cashflow data for accurate calculations
  • Responsive design: Adapts to mobile (280px), landscape (300px), and desktop (400px) with hidden legends on small screens
  • Italian timezone handling: All calculations use Europe/Rome timezone for con...

Bugfix Release - Settings Overwrite Issue

Critical Bug Fix

• FIRE Settings and Dividend Settings Overwrite
  • Fixed critical bug where FIRE settings (Safe Withdrawal Rate, Planned Annual Expenses) and dividend settings (Income Category, Subcategory) were overwriting each other when saved independently
  • Both setting types are stored in the same Firestore document (assetAllocationTargets/{userId})
  • Save handlers were not preserving all optional fields when calling setSettings()
  • Firestore's setDoc() overwrites entire document, causing unpreserved fields to be deleted

What Was Broken

• Before this fix:
  • ❌ Saving FIRE settings → Dividend category configuration lost
  • ❌ Saving dividend settings → Safe Withdrawal Rate and Planned Expenses lost
  • Users had to reconfigure settings repeatedly

What's Fixed

• After this fix:
  • ✅ Saving FIRE settings → Dividend settings properly preserved
  • ✅ Saving dividend settings → FIRE settings properly preserved
  • ✅ All settings persist correctly across different configuration screens
  • ✅ Settings persist after page reload
  • ✅ No regression on other settings (allocation targets, user age, risk-free rate)

Technical Changes

• FireCalculatorTab.tsx (components/fire-simulations/FireCalculatorTab.tsx)

  • Added preservation of dividendIncomeCategoryId and dividendIncomeSubCategoryId fields
  • Save handler now includes all optional fields from current settings

• Settings Page (app/dashboard/settings/page.tsx)

  • Added preservation of withdrawalRate and plannedAnnualExpenses fields
  • Save handler now includes all optional fields from current settings

Impact

• Backward Compatibility

  • Fully backward compatible with existing user data
  • No database migration required
  • No breaking changes to data structure

• User Experience

  • Settings no longer lost when configuring different features
  • Dividend automation continues to work correctly with preserved category settings
  • FIRE calculations use correct withdrawal rate after dividend settings changes

Recommendation

⚠️ All users should update immediately to prevent accidental loss of settings configuration.

Files Modified

• components/fire-simulations/FireCalculatorTab.tsx (lines 116-125)
• app/dashboard/settings/page.tsx (lines 436-445)

v2.0.1 - new features + polish

🎯 Dividend Tracking & Income Automation

A comprehensive system for tracking dividend income from equity investments with automatic data collection, expense synchronization, and detailed analytics. Designed specifically for Italian investors with first-class Borsa Italiana integration.

---

✨ Key Features

📊 Automatic Dividend Data Collection

• Daily Borsa Italiana Scraping (Cron Job at 00:00 UTC)

  • Automatically fetches dividend history for Italian stocks/ETFs using ISIN lookup
  • 60-day lookback window from run date
  • Smart filtering: only dividends after asset creation date
  • Duplicate prevention by asset + ex-date combination
  • Auto-generated dividends marked with isAutoGenerated: true
  • Vercel Cron configuration in vercel.json

• 🔄 "Scarica Tutti" (Scrape All) Button - Historical Bulk Import

  • Manual backfill for dividends older than 60 days
  • Fetches ALL available dividend history from Borsa Italiana
  • One-click per asset in DividendTrackingTab
  • Progress indicator during scraping
  • Duplicate detection prevents re-importing existing data
  • Perfect for newly added assets with historical dividends
  • No 60-day limitation (filters only by asset creation date)

✍️ Manual Dividend Entry

• Comprehensive form with automatic calculations
  • Real-time 26% Italian withholding tax calculation (customizable for foreign dividends)
  • Asset dropdown (equity only, quantity > 0)
  • Auto-population: quantity, gross/tax/net amounts
  • Four dividend types: Ordinary, Extraordinary, Interim, Final
  • Multi-currency support: EUR, USD, GBP, CHF
  • Fields: per-share amount, ex-date, payment date, notes, source URL
  • Smart validation: payment date ≥ ex-date

💰 Expense System Integration

• Automatic income entry creation on payment date
  • Configurable dividend income category in Settings (optional subcategory)
  • Bidirectional linking via expenseId field
  • Net amount (after tax) used for income value
  • Only paid dividends create expenses (payment date ≤ today)
  • Bulk sync/unsync operations available
  • Update propagation: dividend changes auto-update linked expenses
  • Seamless integration with Cashflow page

📈 Analytics Dashboard

• Comprehensive dividend statistics and visualizations
  • Metrics cards: Period totals (gross/tax/net), All-time totals, TTM yield, Upcoming payments
  • Interactive pie chart: Dividends by asset (top contributors)
  • Bar chart: Annual dividends with gross/tax/net breakdown
  • Line chart: Monthly dividend income (12-month trend)
  • Top 10 assets table: Ranked by total net dividends
  • Advanced filtering: By asset, type, date range with real-time chart updates
  • CSV export for filtered data

🎨 User Interface

• New "Dividendi" tab in Cashflow page
  • DividendTable: 50 items/page pagination, sortable by ex-date/payment-date/amount
  • Color-coded type badges (blue: ordinary, purple: extraordinary, yellow: interim, green: final)
  • Per-share and total amounts displayed (gross in EUR, tax in red, net in green)
  • Action buttons: Add Dividend, Scarica Tutti, Export CSV
  • Edit/Delete with confirmation dialogs
  • Mobile-responsive grid layout

---

🔧 Technical Implementation

Database Schema

• New dividends collection in Firestore
  • Identity: userId, assetId, assetTicker, assetName, assetIsin
  • Dates: exDate, paymentDate (Firestore Timestamps)
  • Amounts: dividendPerShare, quantity, grossAmount, taxAmount, netAmount
  • Metadata: currency, dividendType, notes, sourceUrl, isAutoGenerated, expenseId
  • Audit: createdAt, updatedAt
  • Denormalized asset data for query performance

API Routes

• RESTful endpoints for dividend operations
  • POST /api/dividends - Create dividend (auto-creates expense if paid)
  • GET /api/dividends - Fetch with filters (userId, assetId, date range)
  • PUT /api/dividends/[id] - Update dividend (syncs linked expense)
  • DELETE /api/dividends/[id] - Delete dividend and linked expense
  • POST /api/dividends/scrape - Scrape specific asset from Borsa Italiana
  • GET /api/dividends/stats - Analytics (totals, yield, breakdowns)
  • POST /api/dividends/sync-expenses - Bulk sync dividends to expenses
  • All routes validate Firebase Auth and verify asset ownership

Cron Job

• GET /api/cron/daily-dividend-processing (Daily at 00:00 UTC)
  • Phase 1: Scrape all users' equity assets with ISINs (60-day lookback)
  • Phase 2: Create income expenses for dividends with paymentDate = today
  • Authentication: Authorization: Bearer {CRON_SECRET}
  • Response: Processing summary with counts (scraped, created, errors)
  • Configuration: vercel.json cron schedule

Services & Components

• Business Logic

  • dividendService.ts - CRUD operations, statistics, duplicate detection, tax calculation
  • dividendIncomeService.ts - Expense integration (create/update/delete/sync)
  • borsaItalianaScraperService.ts - Web scraping with cheerio (ISIN lookup, Italian date/number parsing)

• UI Components

  • DividendTrackingTab.tsx - Main container with filters and controls
  • DividendDialog.tsx - Form with validation (react-hook-form + zod)
  • DividendTable.tsx - Paginated table with sorting
  • DividendStats.tsx - Metrics cards and charts (Recharts)
  • BorsaItalianaScraperModal.tsx - "Scarica Tutti" interface with progress tracking

Settings Integration

• User preferences in assetAllocationTargets document
  • dividendIncomeCategoryId - Selected income category
  • dividendIncomeSubCategoryId - Optional subcategory
  • Used by API to auto-create expense entries

Calculations

• TTM Yield: (12-month gross dividends / portfolio value) × 100
• Tax: Gross Amount × (Tax Rate / 100), default 26%
• Upcoming: Future payment dates for assets still owned (quantity > 0)

---

🔄 Migration & Compatibility

• ✅ Fully backward compatible (no database migrations required)
• ✅ New independent dividends collection
• ✅ Opt-in feature (empty state if no data)
• ✅ Expense integration optional (requires category configuration in Settings)
• ✅ Web scraping requires ISIN codes (optional asset field)

---

⚠️ Known Limitations

• Borsa Italiana only (other exchanges require manual entry)
• ISIN required for automatic scraping
• Single currency reporting (no multi-currency conversion yet)
• Daily cron frequency (future: support for custom dividend schedules)

---

🎁 Other Features

Hall of Fame Notes Display

• Snapshot notes now visible in monthly rankings tables
  • Amber MessageSquare icon indicates months with notes
  • Tooltip preview (first 100 characters) on hover
  • Click to view full note in read-only dialog
  • Consistent UI with History page pattern
  • Mobile-friendly with direct tap-to-open

Mobile Landscape Responsive Fix

• Sidebar now works correctly on mobile landscape orientation
  • 🔧 Fixed bug where sidebar was visible but hamburger menu was hidden (~800px width)
  • Changed responsive breakpoint from md: (768px) to lg: (1024px)
  • Hamburger menu now accessible on all mobile orientations
  • Improved tablet portrait experience with toggleable sidebar
  • Seamless navigation across all device sizes

History Page Mobile Optimization

• Complete responsive redesign for mobile devices
  • Responsive chart dimensions: 280px (portrait), 300px (landscape), 400px (desktop)
  • Touch-friendly chart dots with 12px invisible hitbox (≥44x44px tap target)
  • Smart legend management: hidden on mobile, visible on desktop with 20px spacing
  • Enhanced tooltips with mobile-optimized sizing (11px mobile, 13px desktop)
  • Responsive page header and chart controls with vertical stacking on mobile
  • Landscape orientation support: 2-column snapshot grid when phone rotated
  • CreateManualSnapshotModal fully responsive: single-column forms on mobile
  • Consistent patterns with Assets and Allocation pages
  • Reduced chart margins (10px mobile vs 50px desktop) for better space utilization
  • Full-width buttons on mobile with proper wrapping behavior

Technical Improvements

• Extended MonthlyRecord type with optional note field
• Updated both client and server-side Hall of Fame services to extract notes from snapshots
• Fixed Firebase Admin SDK undefined value handling with conditional spread operator
• Optimized responsive breakpoints for better cross-device compatibility
• Replaced jsdom with cheerio for Borsa Italiana scraping (85% bundle size reduction, serverless-compatible)
• Fixed Hall of Fame cron job to use Admin SDK instead of Client SDK (resolves Firestore permissions errors)

--

v2.0.0 - new features + improvement

What's New

Features

• Gain/Loss Column (#41): Real-time P/L tracking in assets table

  • Green/red color coding
  • Total portfolio performance
  • Special real estate calculation

• TER Tracking & Portfolio Cost Analysis (#44): Complete expense ratio monitoring

  • Optional TER field for ETFs and funds
  • Weighted average portfolio TER calculation
  • Annual portfolio cost in absolute terms (EUR)
  • Dashboard cards with real-time updates
  • PMC (Average Cost) and TER columns in assets table

• Dynamic Expense Tracking Title & Collapsible Filters (#42): Improved UX and space efficiency

  • Page title automatically displays filtered period ("Tracciamento Spese Gennaio 2025")
  • Removed redundant period indicator card for cleaner layout
  • Collapsible filters section with chevron toggle
  • Saves screen space while maintaining full functionality
  • Eliminates confusion about which period is displayed

• Smart Category Management (#47): Intelligent expense reassignment when deleting categories

  • Interactive reassignment dialog with searchable dropdown
  • Inline category creation during deletion workflow
  • Flexible deletion options: reassign or mark as "Senza categoria"
  • Automatic expense updates when renaming categories
  • Subcategory protection with same reassignment logic
  • Prevents orphaned data and maintains integrity

• Income-to-Expense Ratio Metric (#51): Financial health monitoring at a glance

  • Real-time calculation of income/expense ratio
  • Color-coded indicators: Green (≥1.2 optimal), Yellow (0.8-1.2 balanced), Red (<0.8 warning)
  • Descriptive status messages for quick assessment ("Salute finanziaria ottima", "In equilibrio", "Attenzione alle spese")
  • Year-filtered metric that updates dynamically with selected period
  • Handles edge cases (displays "N/A" when no expenses recorded)
  • Responsive 4-column grid layout (2 cols on medium, 4 on large screens)
  • Scale icon to represent financial balance

• Interactive Drill-Down Pie Charts (#52): Hierarchical expense exploration

  • Three-level navigation: Categories → Subcategories → Individual transactions
  • Click any pie slice to drill down with breadcrumb-style back navigation
  • Color inheritance for subcategories, automatic "Altro" grouping for uncategorized items
  • Transaction details table with date, amount, notes, and external links
  • Available for both "Spese per Categoria" and "Entrate per Categoria" charts
  • Year filter context maintained across all drill-down levels

• Specific Asset Allocation Tracking (#57): Granular portfolio target management

  • Three-level allocation hierarchy: Asset Class → Subcategory → Specific Assets
  • Define target percentages for individual tickers within subcategories
  • Interactive drill-down with info icon (ℹ️) and breadcrumb navigation
  • Per-subcategory toggle with collapsible UI for space efficiency
  • Real-time validation: specific asset percentages must sum to 100%
  • Theoretical targets with automatic buy/sell recommendations
  • Backward compatible with existing allocation data
  • Example: Track "AAPL 25%, MSFT 25%, GOOGL 25%, AMZN 25%" within "Single Stock" subcategory

• UI/UX Rationalization: Streamlined Navigation & Grouped Pages: Cleaner, more intuitive interface

  • Simplified sidebar navigation: Reduced from 11 items to 8 for better focus and discoverability
  • FIRE e Simulazioni unified page with tabbed navigation:
    • FIRE Calculator tab: Track progress toward Financial Independence
    • Monte Carlo tab: Run probabilistic retirement simulations
    • Seamless switching between complementary planning tools
  • Cashflow unified page consolidating all income/expense features:
    • Tracciamento tab: Full expense tracking with year/month filters and statistics
    • Anno Corrente tab: Current year drill-down charts and category analysis
    • Storico Totale tab: All-time trends across multiple years
    • Single entry point for all cashflow-related workflows
  • Tab-based navigation within grouped sections for instant context switching
  • Backward compatibility: Original routes (/dashboard/fire, /dashboard/expenses, etc.) remain functional
  • Reduced navigation complexity: Related features now logically grouped instead of scattered
  • Improved UX: Easier to understand app structure and find features
  • Example: Users no longer need to decide between "Tracciamento Spese", "Cashflow [Year]", and "Cashflow Totale" - all accessible from one "Cashflow" page with clear tabs

• Income/Expense Ratio Yearly Chart (#58): Long-term financial health visualization

  • Interactive line chart showing yearly income/expense ratio trends
  • Color-coded background zones: Green (≥1.2 optimal), Yellow (0.8-1.2 balanced), Red (<0.8 warning)
  • Break-even reference line at 1.0 for quick assessment
  • Positioned in "Storico Totale" tab after yearly trend chart
  • Multi-year pattern recognition for financial planning
  • Visual legend explaining health thresholds
  • Complements existing monthly ratio card with historical perspective

• Advanced Expense Filtering System (#50): Hierarchical Type/Category/Subcategory filters

  • Searchable comboboxes with real-time filtering
  • Progressive field enabling (Type → Category → Subcategory)
  • Individual X buttons to clear single filters
  • Smart hierarchical removal (clearing Type resets Category and Subcategory)
  • Real-time statistics updates based on filtered data
  • Cumulative AND filtering for precise expense exploration

• Percentage View Toggle for Cashflow Charts (#49): Switch between € and % views in trend charts

  • Toggle button for monthly and yearly trends (Anno Corrente & Storico Totale tabs)
  • Shows Income %, Expenses %, and Saving Rate % metrics
  • Consistent with History page toggle pattern
  • Enables period comparison regardless of absolute income levels

• Capital Gains Tax Calculator (#55): Simulate tax impact before selling assets

  • Dual input modes: sell by quantity or target sale value
  • Real-time calculations: capital gains/losses, taxes owed, net proceeds
  • Visual indicators (green for gains, red for losses) with edge case handling

• Searchable Category and Subcategory Dropdowns (#43): Faster expense entry workflow

  • Real-time search in expense form with partial match support (case-insensitive)
  • Reusable SearchableCombobox component for consistent UX across the app
  • Keyboard navigation and click-outside detection for seamless interaction
  • Color-coded category indicators in search results
  • Significant productivity improvement for users with many categories
  • No more scrolling through long dropdowns - just start typing
  • Example: Type "food" to instantly find "Food & Dining", "Fast Food", "Pet Food"
  • Maintains all existing functionality: inline creation, validation, and color display
  • Mobile-friendly with touch-optimized interactions

• Drill-Down Charts UX Improvements (#56): Enhanced discoverability and navigation

  • Dismissible info alert explaining click-to-explore functionality (persisted via localStorage)
  • Auto-scroll on drill-down to keep active chart in view
  • Fixes navigation confusion when clicking on "Entrate per Categoria" chart

• Mobile Optimization: Dashboard & Assets Pages: Enhanced mobile experience with responsive layouts

  • Responsive pie charts: adaptive sizing (350px mobile vs 500px desktop), horizontal legend placement on small screens
  • Smart legend filtering: shows only items ≥7% on mobile to reduce clutter
  • Clean chart design: removed inline labels, rely on legend + hover tooltips for better readability
  • Asset card view: collapsible details, full-width mobile layout with all data accessible without horizontal scrolling
  • Responsive action buttons: vertically stacked on mobile (sm breakpoint), horizontally aligned on tablet/desktop
  • Summary card on mobile: prominent total portfolio value with G/P visualization at bottom of asset list

• Mobile Optimization - Allocation Page (#XX): Complete mobile UX overhaul

  • Card-based layout with visual progress bars (current vs target)
  • Bottom sheet navigation for drill-down (Asset Class → SubCategory → Specific Assets)
  • Color-coded action badges and touch-friendly interactions
  • Desktop table layout unchanged (hybrid responsive design)

• Installment Payments (BNPL): Complete installment tracking system for all expense types

  • Dual input modes: Auto-calculate equal installments OR manual custom amounts
  • Flexible configuration: 2-60 installments with monthly frequency
  • Smart division preview: Shows simplified "5 rate da 100€" when equal, detailed breakdown when different
  • Auto-populate workflow: Importing total amount pre-fills installment total field
  • Visual tracking: "Rata X/Y" badges in expense table with installment series grouping
  • Bulk operations: Delete entire installment series or individual payments with confirmation
  • Rich toast notifications: Success messages display installment count and total amount
  • Mutual exclusion: Prevents conflicts with existing recurring expense feature
  • Universal support: Works with all expense types (Fixed, Variable, Debt, Income)

• UX Improvements - Searchable Combobox: Fixed value display regression

  • Selected category/subcategory now properly visible in input field after selection
  • Focus-aware display logic: shows label when closed, enables search when focused
  • Maintains search functionality while improving visual feedback

• Current Month Quick Filter (#64): One-click access to current month expenses with "Mese corrente" button

  • Auto-selects current year and month
  • Perfect alignment with existi...

Release v1.2.1 - Monte Carlo Improvements

This release focuses on improving usability and accuracy of the Monte Carlo Simulations page, with numerous chart visualization fixes and calculation bug corrections.

Bug Fixes

1. Fixed tooltip values in Portfolio Projection chart

• Issue: Tooltip displayed incorrect percentile values (e.g., showing 25th percentile instead of median)
• Solution: Corrected tooltip data reading mechanism to ensure proper matching between percentiles and displayed values
• Impact: Tooltip values now match exactly with the Percentiles Table

2. Fixed monthly snapshot count

• Issue: System incorrectly counted 0 available snapshots even when users had created several
• Solution: Test/dummy snapshots are now correctly excluded from the count
• Impact: The "Currently you have X" message now accurately reflects the user's real snapshot count

3. Clarified median value discrepancy

• Issue: The "Final Median Value" shown in the card differed from the chart tooltip value, creating confusion
• Solution: Added explicit label "(successful simulations only)" to clarify these are two different metrics
• Impact: Users now understand the card shows the median of successful simulations only, while the chart includes failures

Chart Visualization Improvements
4. Improved Y-axis label visibility

• Fixed clipping issue for labels like "€8.0 Mln", "€9.0 Mln" in Portfolio Projection chart
• Fixed visibility issue for "Number of Simulations" label in Final Values Distribution chart
• Increased Distribution chart height from 300px to 400px for better readability
• Added consistent left margin across all charts

5. Improved "Failure" line visibility

• "Failure" text now larger (14px), bold, and positioned on the right
• Better visual contrast on the €0 reference line

6. Consistent Distribution tooltip formatting

• Range labels in Distribution chart tooltip now use consistent compact format (e.g., "€1.5 Mln" instead of "€1500k")
• Format aligned with Percentiles Table and other charts

UX Improvements
7. Initial Portfolio input with thousand separators

• New feature: "Initial Portfolio" field now displays thousand separators in Italian format
• Example: 1,200,000.00 € instead of 1200000
• Benefit: Better readability and reduced chance of error when entering large amounts

Technical Details

• All Monte Carlo charts now use consistent configurations (height: 400px, margin: 50px)
• Improved dummy snapshot filtering in calculateHistoricalReturns
• Implemented formatting pattern with local state for numeric inputs
• Unified usage of formatCurrencyCompact across all visualization components

Note: This release does not introduce breaking changes. All modifications are backward compatible.

v1.2.0: Monte Carlo Retirement Simulations & Enhanced Test Data Management

MONTE CARLO RETIREMENT SIMULATIONS

This release introduces Monte Carlo simulations for probabilistic retirement planning, allowing you to model thousands of potential market scenarios and assess the probability of reaching your financial goals.

KEY FEATURES

Monte Carlo Simulation Engine
Probabilistic modeling: Runs 10,000+ simulations with random market returns based on historical volatility
Customizable parameters: Configure expected returns and volatility for equity and bonds
Historical data integration: Use your own portfolio's historical performance (requires 24+ months of data)
Success probability: Visualize the likelihood of achieving your FIRE goals across different time horizons
Multiple scenarios: Compare optimistic, realistic, and conservative projections
Interactive charts: Explore percentile distributions (10th, 25th, 50th, 75th, 90th) of potential outcomes

Market Parameters Configuration
Equity returns: Expected annual return and volatility (default: 7% return, 18% volatility)
Bonds returns: Expected annual return and volatility (default: 3% return, 5% volatility)
Toggle between: Personal historical data vs custom market assumptions
Real-time calculations: Parameters update simulation results instantly

Retirement Planning Insights
Time to FIRE: Estimated years until financial independence based on current savings rate
Portfolio growth projections: See how your net worth could evolve under different market conditions
Risk assessment: Understand the impact of market volatility on your retirement timeline
Withdrawal sustainability: Model safe withdrawal rates for retirement income

ENHANCED TEST DATA MANAGEMENT

Bulk Dummy Data Deletion

One-click cleanup: Remove all test data (snapshots, expenses, categories) in a single operation
Preview before delete: See exactly what will be removed (count of snapshots, expenses, categories)
Smart identification:
Snapshots marked with isDummy: true
Expenses with IDs starting with dummy-
Categories with IDs starting with dummy-category-
Confirmation dialog: Prevents accidental deletion of test data

Improved Dummy Data Generation
Realistic asset class returns: Each asset class (equity, bonds, crypto, real estate, cash) now grows independently with appropriate return rates and volatilities
Proper diversification effects:
Equity: ~12% annual return, 5% volatility
Bonds: ~5% annual return, 1.5% volatility
Crypto: ~15% annual return, 10% volatility (high risk)
Real Estate: ~7% annual return, 1% volatility
Cash: ~2.4% annual (inflation), minimal volatility
Perfect for Monte Carlo testing: Historical data now generates realistic equity/bonds differentiation for accurate simulations
Box-Muller transform: Uses normal distribution for realistic market variations
Adjusted default growth: Changed from 3% to 0.8% monthly (more realistic ~10% annual return)

BUG FIXES & UI IMPROVEMENTS

Monte Carlo UI Fixes
Fixed zero volatility issue: Historical data now correctly calculates volatility from return variations
Fixed identical returns: Equity and bonds no longer show identical returns when using historical data
Toggle visual feedback: "Use personal historical data" toggle now responds immediately to clicks
Optimistic UI updates: Local state ensures instant visual feedback while async operations complete

Documentation Updates
SETUP.md: Added documentation for NEXT_PUBLIC_ENABLE_TEST_SNAPSHOTS environment variable
README.md:
Comprehensive Monte Carlo simulation documentation
Dummy data identification and removal guide
Updated realistic growth rates and asset class parameters
Technical implementation details for test data generation
Inline help: Improved tooltips and hints in dummy data generation modal

NEW COMPONENTS & SERVICES

New Files
components/monte-carlo/: Complete Monte Carlo simulation suite
SimulationResults.tsx: Results visualization with percentile charts
ParametersForm.tsx: Market parameters configuration
TimeToFIRECalculator.tsx: FIRE timeline estimation
lib/services/monteCarloService.ts: Simulation engine and calculations
lib/services/dummyDataService.ts: Bulk deletion and counting functions
components/DeleteDummyDataDialog.tsx: Confirmation dialog for test data cleanup
components/ui/alert.tsx: shadcn/ui Alert component

Modified Files
types/assets.ts: Added isDummy field to MonthlySnapshot interface
lib/services/dummySnapshotGenerator.ts: Independent asset class tracking with realistic volatilities
app/dashboard/settings/page.tsx: Added bulk delete button for test data
components/CreateDummySnapshotModal.tsx: Updated defaults and documentation
Monte Carlo parameter form: Fixed toggle state management

USE CASES

The Monte Carlo simulation feature is perfect for:
Retirement planning: Model when you can safely retire based on different market scenarios
Risk assessment: Understand how market volatility affects your FIRE timeline
Strategy comparison: Compare aggressive vs conservative investment approaches
Confidence building: See probability ranges for achieving financial goals
Scenario analysis: Test "what if" scenarios with different return assumptions

The enhanced test data management is ideal for:
Development: Generate realistic historical data for testing features
Demos: Showcase the application with meaningful sample data
Monte Carlo testing: Create diverse portfolios with proper asset class differentiation
Easy cleanup: Remove all test data when switching to production use

BACKWARD COMPATIBILITY

All changes are fully backward compatible:
Existing snapshots without isDummy field are treated as real data
Monte Carlo simulation is an optional feature that doesn't affect existing functionality
No database migrations required

TECHNICAL DETAILS

Performance
Monte Carlo simulations run client-side with Web Workers for smooth UI
10,000 simulations complete in ~2-3 seconds
Dummy data generation optimized with batch writes

Data Integrity
Bulk deletion uses Firebase WriteBatch for atomic operations
All dummy data operations are user-scoped (only affects current user's data)
Confirmation dialogs prevent accidental deletions

Mathematics
Normal distribution via Box-Muller transform
Geometric Brownian motion for portfolio growth modeling
Historical volatility calculated using standard deviation of returns
Annualized returns use compound growth formula

v1.1.0: Cost Basis Tracking & Tax Estimates

Introduces cost basis tracking with unrealized gains and estimated tax calculations for each asset. Updates the dashboard to display gross/net worth, unrealized gains, and estimated taxes when cost basis tracking is enabled. Enhances the asset dialog to allow input of average cost and tax rate, and updates types and service functions to support these new fields and calculations. Documentation is updated to reflect the new features.