refi-calculator 0.8.0__py3-none-any.whl

refi_calculator/gui/builders/__init__.py

@@ -0,0 +1,9 @@
+"""GUI builder package for each tab."""
+
+from __future__ import annotations
+
+__all__: list[str] = []
+
+__description__ = """
+Builders shared across GUI tabs.
+"""

refi_calculator/gui/builders/analysis_tab.py

@@ -0,0 +1,92 @@
+"""Analysis tab builders."""
+
+from __future__ import annotations
+
+import tkinter as tk
+from tkinter import ttk
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from ..app import RefinanceCalculatorApp
+
+
+def build_sensitivity_tab(
+    app: RefinanceCalculatorApp,
+    parent: ttk.Frame,
+) -> None:
+    """Build the sensitivity analysis tree.
+
+    Args:
+        app: App instance owning the sensitivity data.
+        parent: Container frame for the sensitivity tab.
+    """
+    ttk.Label(
+        parent,
+        text="Sensitivity: Breakeven by New Rate",
+        font=("Segoe UI", 10, "bold"),
+    ).pack(anchor=tk.W, pady=(0, 10))
+
+    columns = ("rate", "savings", "simple_be", "npv_be", "npv_5yr")
+    app.sens_tree = ttk.Treeview(parent, columns=columns, show="headings", height=10)
+
+    app.sens_tree.heading("rate", text="New Rate")
+    app.sens_tree.heading("savings", text="Monthly Savings")
+    app.sens_tree.heading("simple_be", text="Simple BE")
+    app.sens_tree.heading("npv_be", text="NPV BE")
+    app.sens_tree.heading("npv_5yr", text="5-Yr NPV")
+
+    for col in columns:
+        app.sens_tree.column(col, width=90, anchor=tk.CENTER)
+
+    app.sens_tree.pack(fill=tk.BOTH, expand=True)
+    ttk.Button(
+        parent,
+        text="Export Sensitivity CSV",
+        command=app._export_sensitivity_csv,
+    ).pack(pady=10)
+
+
+def build_holding_period_tab(
+    app: RefinanceCalculatorApp,
+    parent: ttk.Frame,
+) -> None:
+    """Build the holding period analysis tree.
+
+    Args:
+        app: App instance owning the holding period data.
+        parent: Container frame for the holding period tab.
+    """
+    ttk.Label(parent, text="NPV by Holding Period", font=("Segoe UI", 10, "bold")).pack(
+        anchor=tk.W,
+        pady=(0, 10),
+    )
+
+    columns = ("years", "nominal_savings", "npv", "npv_after_tax", "recommendation")
+    app.holding_tree = ttk.Treeview(parent, columns=columns, show="headings", height=12)
+
+    app.holding_tree.heading("years", text="Hold (Years)")
+    app.holding_tree.heading("nominal_savings", text="Nominal Savings")
+    app.holding_tree.heading("npv", text="NPV")
+    app.holding_tree.heading("npv_after_tax", text="NPV (After-Tax)")
+    app.holding_tree.heading("recommendation", text="Recommendation")
+
+    app.holding_tree.column("years", width=80, anchor=tk.CENTER)
+    app.holding_tree.column("nominal_savings", width=100, anchor=tk.CENTER)
+    app.holding_tree.column("npv", width=90, anchor=tk.CENTER)
+    app.holding_tree.column("npv_after_tax", width=100, anchor=tk.CENTER)
+    app.holding_tree.column("recommendation", width=110, anchor=tk.CENTER)
+
+    app.holding_tree.pack(fill=tk.BOTH, expand=True)
+    ttk.Button(parent, text="Export Holding Period CSV", command=app._export_holding_csv).pack(
+        pady=10,
+    )
+
+
+__all__ = [
+    "build_sensitivity_tab",
+    "build_holding_period_tab",
+]
+
+__description__ = """
+Constructors for the analysis sub-tabs.
+"""

refi_calculator/gui/builders/helpers.py

@@ -0,0 +1,90 @@
+"""Common helpers for building UI tabs."""
+
+from __future__ import annotations
+
+import tkinter as tk
+from collections.abc import Callable
+from tkinter import ttk
+
+
+def add_input(
+    parent: tk.Misc,
+    label: str,
+    var: tk.StringVar,
+    row: int,
+    on_change: Callable[[], None],
+) -> None:
+    """Add a labeled entry bound to the provided StringVar.
+
+    Args:
+        parent: Parent frame hosting the entry row.
+        label: Text displayed next to the entry.
+        var: StringVar that stores the entry value.
+        row: Grid row for the label/entry pair.
+        on_change: Callback invoked when the value changes.
+    """
+    ttk.Label(parent, text=label).grid(row=row, column=0, sticky=tk.W, pady=3)
+    entry = ttk.Entry(parent, textvariable=var, width=14)
+    entry.grid(row=row, column=1, sticky=tk.E, pady=3, padx=(10, 0))
+    entry.bind("<Return>", lambda e: on_change())
+    entry.bind("<FocusOut>", lambda e: on_change())
+
+
+def add_option(
+    parent: tk.Misc,
+    label: str,
+    var: tk.StringVar,
+    row: int,
+    tooltip: str,
+) -> None:
+    """Add a labeled option input with descriptive tooltip.
+
+    Args:
+        parent: Parent frame used for the input row.
+        label: Label text describing the option.
+        var: StringVar associated with the option entry.
+        row: Row index inside the grid layout.
+        tooltip: Supplemental explanation shown alongside input.
+    """
+    ttk.Label(parent, text=label).grid(row=row, column=0, sticky=tk.W, pady=6)
+    entry = ttk.Entry(parent, textvariable=var, width=10)
+    entry.grid(row=row, column=1, sticky=tk.W, pady=6, padx=(10, 15))
+    ttk.Label(parent, text=tooltip, font=("Segoe UI", 8), foreground="#666").grid(
+        row=row,
+        column=2,
+        sticky=tk.W,
+    )
+
+
+def result_block(
+    parent: ttk.Frame,
+    title: str,
+    col: int,
+) -> ttk.Label:
+    """Create a title + value display block within a row.
+
+    Args:
+        parent: Parent frame that hosts the result block.
+        title: Title text displayed above the value.
+        col: Column index used for layout (unused but maintained for parity).
+
+    Returns:
+        The label that shows the numeric value.
+    """
+    frame = ttk.Frame(parent)
+    frame.pack(side=tk.LEFT, expand=True, fill=tk.X)
+    ttk.Label(frame, text=title, style="Header.TLabel").pack()
+    label = ttk.Label(frame, text="—", style="Result.TLabel")
+    label.pack(pady=2)
+    return label
+
+
+__all__ = [
+    "add_input",
+    "add_option",
+    "result_block",
+]
+
+__description__ = """
+Shared helpers for building Tkinter tabs.
+"""

refi_calculator/gui/builders/info_tab.py

@@ -0,0 +1,195 @@
+"""Background and help info tab builders."""
+
+from __future__ import annotations
+
+import tkinter as tk
+from tkinter import ttk
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from ..app import RefinanceCalculatorApp
+
+
+def build_background_tab(
+    app: RefinanceCalculatorApp,
+    parent: ttk.Frame,
+) -> None:
+    """Build background information scroll area.
+
+    Args:
+        app: Application instance that displays the background text.
+        parent: Frame that hosts the scrollable background content.
+    """
+    canvas = tk.Canvas(parent, highlightthickness=0)
+    scrollbar = ttk.Scrollbar(parent, orient="vertical", command=canvas.yview)
+    scroll_frame = ttk.Frame(canvas)
+
+    scroll_frame.bind(
+        "<Configure>",
+        lambda e: canvas.configure(scrollregion=canvas.bbox("all")),
+    )
+    canvas_window = canvas.create_window((0, 0), window=scroll_frame, anchor="nw")
+    canvas.configure(yscrollcommand=scrollbar.set)
+
+    def on_canvas_configure(event):
+        canvas.itemconfig(canvas_window, width=event.width)
+
+    canvas.bind("<Configure>", on_canvas_configure)
+
+    canvas.pack(side=tk.LEFT, fill=tk.BOTH, expand=True)
+    scrollbar.pack(side=tk.RIGHT, fill=tk.Y)
+
+    app._background_canvas = canvas
+    content = scroll_frame
+
+    ttk.Label(
+        content,
+        text="Refinancing: Background & Concepts",
+        font=("Segoe UI", 12, "bold"),
+    ).pack(anchor=tk.W, pady=(0, 15))
+
+    sections = [
+        (
+            "What is Refinancing?",
+            "Refinancing replaces your existing mortgage with a new loan, typically to secure a lower interest rate, change the loan term, or access home equity (cash-out refinance). The new loan pays off your old mortgage, and you begin making payments on the new terms.\n\nCommon reasons to refinance:\n• Lower your interest rate and monthly payment\n• Shorten your loan term to pay off faster\n• Switch from adjustable-rate to fixed-rate (or vice versa)\n• Access equity for major expenses (cash-out refi)\n• Remove private mortgage insurance (PMI)",
+        ),
+        (
+            "Key Costs to Consider",
+            "Refinancing isn't free. Typical closing costs run 2-5% of the loan amount and may include:\n\n• Origination fees (lender charges)\n• Appraisal fee ($300-$700)\n• Title search and insurance\n• Recording fees\n• Credit report fee\n• Prepaid interest, taxes, and insurance\n\nThese costs can be paid upfront, rolled into the loan balance, or covered by accepting a slightly higher rate (\"no-cost\" refi). Rolling costs into the loan means you'll pay interest on them over time.",
+        ),
+        (
+            "The Breakeven Concept",
+            "The fundamental question: How long until your monthly savings recoup the closing costs?\n\nSimple Breakeven = Closing Costs ÷ Monthly Savings\n\nExample: $6,000 in costs with $200/month savings = 30 months to breakeven.\n\nIf you plan to stay in the home longer than the breakeven period, refinancing likely makes sense. If you might move or refinance again before breakeven, you'll lose money on the transaction.\n\nImportant caveat: Simple breakeven ignores the time value of money. A dollar saved three years from now is worth less than a dollar today.",
+        ),
+        (
+            "Net Present Value (NPV)",
+            'NPV provides a more sophisticated analysis by discounting future savings to today\'s dollars. It accounts for the "opportunity cost" of your closing costs — what you could have earned by investing that money instead.\n\nNPV = -Closing Costs + Σ (Monthly Savings / (1 + r)^n)\n\nWhere r is the monthly discount rate and n is the month number.\n\nA positive NPV means refinancing creates value even after accounting for opportunity cost. The higher the NPV, the more clearly beneficial the refinance.',
+        ),
+        (
+            "The Term Reset Problem",
+            "A critical nuance many borrowers miss: refinancing often resets your amortization clock.\n\nExample: You're 5 years into a 30-year mortgage (25 years remaining). If you refinance into a new 30-year loan, you've added 5 years to your payoff timeline — even if your rate dropped.\n\nThis can dramatically increase total interest paid over the life of the loan, even with a lower rate. Solutions:\n• Refinance into a shorter term (e.g., 20 or 15 years)\n• Make extra principal payments to maintain your original payoff date\n• Compare total interest paid, not just monthly payment",
+        ),
+        (
+            "Tax Implications",
+            "Mortgage interest is tax-deductible if you itemize deductions. This effectively reduces your true interest rate:\n\nAfter-Tax Rate = Nominal Rate × (1 - Marginal Tax Rate)\n\nExample: 6% rate with 24% marginal bracket = 4.56% effective rate\n\nNote: The 2017 tax law changes increased the standard deduction significantly, meaning fewer homeowners now itemize. If you take the standard deduction, there's no mortgage interest tax benefit.",
+        ),
+        (
+            "Cash-Out Refinancing",
+            "A cash-out refi lets you borrow against your home equity, receiving the difference as cash. Your new loan balance equals your old balance plus the cash withdrawn plus closing costs.\n\nConsiderations:\n• You're converting home equity into debt\n• Monthly payment will likely increase even with a lower rate\n• Interest on cash-out amounts above original loan may not be tax-deductible\n• Good for consolidating high-interest debt or funding investments\n• Risky if used for consumption or if home values decline",
+        ),
+        (
+            "When NOT to Refinance",
+            "Refinancing isn't always beneficial:\n\n• Short holding period: If you'll move before breakeven\n• Small rate reduction: Less than 0.5-0.75% often doesn't justify costs\n• Extended payoff: If resetting to 30 years significantly increases total interest\n• High closing costs: Some lenders charge excessive fees\n• Credit issues: Poor credit may mean higher rates or denial\n• Equity constraints: Most lenders require 20%+ equity for best rates\n\nRule of thumb: A 1% rate reduction with typical costs usually breaks even in 2-3 years.",
+        ),
+    ]
+
+    for title, text in sections:
+        ttk.Label(content, text=title, font=("Segoe UI", 10, "bold")).pack(
+            anchor=tk.W,
+            pady=(10, 5),
+        )
+        ttk.Label(
+            content,
+            text=text,
+            wraplength=450,
+            justify=tk.LEFT,
+            font=("Segoe UI", 9),
+        ).pack(anchor=tk.W, padx=(10, 0), pady=(0, 5))
+
+
+def build_help_tab(
+    app: RefinanceCalculatorApp,
+    parent: ttk.Frame,
+) -> None:
+    """Build help info tab UI.
+
+    Args:
+        app: Application instance that displays the help text.
+        parent: Frame that hosts the scrollable help content.
+    """
+    canvas = tk.Canvas(parent, highlightthickness=0)
+    scrollbar = ttk.Scrollbar(parent, orient="vertical", command=canvas.yview)
+    scroll_frame = ttk.Frame(canvas)
+
+    scroll_frame.bind(
+        "<Configure>",
+        lambda e: canvas.configure(scrollregion=canvas.bbox("all")),
+    )
+    canvas_window = canvas.create_window((0, 0), window=scroll_frame, anchor="nw")
+    canvas.configure(yscrollcommand=scrollbar.set)
+
+    def on_canvas_configure(event):
+        canvas.itemconfig(canvas_window, width=event.width)
+
+    canvas.bind("<Configure>", on_canvas_configure)
+
+    canvas.pack(side=tk.LEFT, fill=tk.BOTH, expand=True)
+    scrollbar.pack(side=tk.RIGHT, fill=tk.Y)
+
+    app._help_canvas = canvas
+    content = scroll_frame
+
+    ttk.Label(content, text="Application Help", font=("Segoe UI", 12, "bold")).pack(
+        anchor=tk.W,
+        pady=(0, 15),
+    )
+
+    sections = [
+        (
+            "Overview",
+            "This calculator helps you analyze whether refinancing your mortgage makes financial sense. It goes beyond simple breakeven calculations to provide NPV analysis, tax-adjusted figures, sensitivity tables, and visualizations.\n\nAll calculations update automatically when you change inputs or press Enter.",
+        ),
+        (
+            "Calculator Tab",
+            "The main analysis screen with inputs and results.\n\nINPUTS - Current Loan:\n• Balance ($): Your remaining mortgage principal\n• Rate (%): Current annual interest rate\n• Years Remaining: Time left on your current loan\n\nINPUTS - New Loan:\n• Rate (%): Proposed new interest rate\n• Term (years): Length of new loan (typically 15, 20, or 30)\n• Closing Costs ($): Total refinance fees\n• Cash Out ($): Additional amount to borrow (0 for rate-only refi)\n• Opportunity Rate (%): Expected return on alternative investments\n• Marginal Tax Rate (%): Your tax bracket (0 if you don't itemize)",
+        ),
+        (
+            "Rate Sensitivity Tab",
+            'Shows how breakeven and NPV change at different new interest rates.\n\nThe table displays scenarios from your current rate down to the maximum reduction specified in Options (default: 2% in 0.25% steps).\n\nUse this to answer questions like:\n• "Should I wait for rates to drop further?"\n• "How much does each 0.25% reduction improve my outcome?"',
+        ),
+        (
+            "Holding Period Tab",
+            "Shows NPV at various holding periods (1-20 years).\n\nThis helps when you're uncertain how long you'll stay in the home. The recommendation column provides guidance:\n• Strong Yes (green): NPV > $5,000\n• Yes (dark green): NPV > $0\n• Marginal (orange): NPV between -$2,000 and $0\n• No (red): NPV < -$2,000",
+        ),
+        (
+            "Loan Visualizations Tab",
+            "The Loan Visualizations tab contains the annual amortization comparison table, which now includes a cumulative interest Δ column alongside colored savings/cost indicators so you can track how the refinance affects total interest year over year.",
+        ),
+        (
+            "Charts within Loan Visualizations",
+            "Two charts live on the Loan Visualizations tab:\n\n"
+            "1. Cumulative Savings Chart — shows nominal (blue) and NPV-adjusted (green) savings with monthly ticks, a labeled zero line, and a dashed vertical line marking the NPV breakeven point.\n"
+            "2. Loan Balance Comparison Chart — plots the remaining balances for the current (red) and new (blue) loans so you can see how the term reset or accelerated payoff affects your timeline.",
+        ),
+        (
+            "Options Tab",
+            "Customize calculation parameters:\n\n• NPV Window (years): Time horizon for NPV calculation displayed on main tab\n• Chart Horizon (years): How many years shown on the chart\n• Max Rate Reduction (%): How far below current rate to show in sensitivity table\n• Rate Step (%): Increment between rows in sensitivity table",
+        ),
+        (
+            "Exporting Data",
+            "Export buttons are available on Calculator, Rate Sensitivity, Holding Period, and Amortization tabs. Files are saved with timestamps to avoid overwriting.",
+        ),
+    ]
+
+    for title, text in sections:
+        ttk.Label(content, text=title, font=("Segoe UI", 10, "bold")).pack(
+            anchor=tk.W,
+            pady=(10, 5),
+        )
+        ttk.Label(
+            content,
+            text=text,
+            wraplength=450,
+            justify=tk.LEFT,
+            font=("Segoe UI", 9),
+        ).pack(anchor=tk.W, padx=(10, 0), pady=(0, 5))
+
+
+__all__ = [
+    "build_background_tab",
+    "build_help_tab",
+]
+
+__description__ = """
+Builders for the background and help tabs.
+"""

refi_calculator/gui/builders/main_tab.py

@@ -0,0 +1,173 @@
+"""Main calculator tab builder."""
+
+# ruff: noqa: PLR0915
+
+from __future__ import annotations
+
+import tkinter as tk
+from tkinter import ttk
+from typing import TYPE_CHECKING
+
+from .helpers import add_input, result_block
+
+if TYPE_CHECKING:
+    from ..app import RefinanceCalculatorApp
+
+
+def build_main_tab(
+    app: RefinanceCalculatorApp,
+    parent: ttk.Frame,
+) -> None:
+    """Build the calculator tab inputs and result panels.
+
+    Args:
+        app: Application instance that owns the tab data.
+        parent: Frame that hosts the calculator elements.
+    """
+    input_frame = ttk.Frame(parent)
+    input_frame.pack(fill=tk.X, pady=(0, 10))
+
+    current_frame = ttk.LabelFrame(input_frame, text="Current Loan", padding=10)
+    current_frame.pack(side=tk.LEFT, fill=tk.BOTH, expand=True, padx=(0, 5))
+
+    add_input(current_frame, "Balance ($):", app.current_balance, 0, app._calculate)
+    add_input(current_frame, "Rate (%):", app.current_rate, 1, app._calculate)
+    add_input(current_frame, "Years Remaining:", app.current_remaining, 2, app._calculate)
+
+    new_frame = ttk.LabelFrame(input_frame, text="New Loan", padding=10)
+    new_frame.pack(side=tk.LEFT, fill=tk.BOTH, expand=True, padx=(5, 0))
+
+    add_input(new_frame, "Rate (%):", app.new_rate, 0, app._calculate)
+    add_input(new_frame, "Term (years):", app.new_term, 1, app._calculate)
+    add_input(new_frame, "Closing Costs ($):", app.closing_costs, 2, app._calculate)
+    add_input(new_frame, "Cash Out ($):", app.cash_out, 3, app._calculate)
+    add_input(new_frame, "Opportunity Rate (%):", app.opportunity_rate, 4, app._calculate)
+    add_input(new_frame, "Marginal Tax Rate (%):", app.marginal_tax_rate, 5, app._calculate)
+
+    maintain_frame = ttk.Frame(new_frame)
+    maintain_frame.grid(row=6, column=0, columnspan=2, sticky=tk.W, pady=(8, 0))
+    ttk.Checkbutton(
+        maintain_frame,
+        text="Maintain current payment (extra → principal)",
+        variable=app.maintain_payment,
+        command=app._calculate,
+    ).pack(anchor=tk.W)
+
+    btn_frame = ttk.Frame(parent)
+    btn_frame.pack(pady=8)
+    ttk.Button(btn_frame, text="Calculate", command=app._calculate).pack(side=tk.LEFT, padx=5)
+    ttk.Button(btn_frame, text="Export CSV", command=app._export_csv).pack(
+        side=tk.LEFT,
+        padx=5,
+    )
+
+    results_frame = ttk.LabelFrame(parent, text="Analysis Results", padding=12)
+    results_frame.pack(fill=tk.BOTH, expand=True)
+
+    style = ttk.Style()
+    style.configure("Header.TLabel", font=("Segoe UI", 9, "bold"))
+    style.configure("Result.TLabel", font=("Segoe UI", 10))
+    style.configure("Big.TLabel", font=("Segoe UI", 13, "bold"))
+
+    app.pay_frame = ttk.Frame(results_frame)
+    app.pay_frame.pack(fill=tk.X, pady=(0, 8))
+    app.current_pmt_label = result_block(app.pay_frame, "Current Payment", 0)
+    app.new_pmt_label = result_block(app.pay_frame, "New Payment", 1)
+    app.savings_label = result_block(app.pay_frame, "Monthly Δ", 2)
+
+    app.balance_frame = ttk.Frame(results_frame)
+    app.balance_frame.pack(fill=tk.X, pady=(0, 8))
+    app.new_balance_label = result_block(app.balance_frame, "New Loan Balance", 0)
+    app.cash_out_label = result_block(app.balance_frame, "Cash Out", 1)
+    result_block(app.balance_frame, "", 2)
+    app.balance_frame.pack_forget()
+
+    ttk.Separator(results_frame, orient=tk.HORIZONTAL).pack(fill=tk.X, pady=6)
+
+    be_frame = ttk.Frame(results_frame)
+    be_frame.pack(fill=tk.X, pady=(0, 8))
+    app.simple_be_label = result_block(be_frame, "Simple Breakeven", 0)
+    app.npv_be_label = result_block(be_frame, "NPV Breakeven", 1)
+
+    ttk.Separator(results_frame, orient=tk.HORIZONTAL).pack(fill=tk.X, pady=6)
+
+    int_frame = ttk.Frame(results_frame)
+    int_frame.pack(fill=tk.X, pady=(0, 8))
+    app.curr_int_label = result_block(int_frame, "Current Total Interest", 0)
+    app.new_int_label = result_block(int_frame, "New Total Interest", 1)
+    app.int_delta_label = result_block(int_frame, "Interest Δ", 2)
+
+    ttk.Separator(results_frame, orient=tk.HORIZONTAL).pack(fill=tk.X, pady=6)
+
+    app.tax_section_label = ttk.Label(
+        results_frame,
+        text="After-Tax Analysis (0% marginal rate)",
+        style="Header.TLabel",
+    )
+    app.tax_section_label.pack(anchor=tk.W, pady=(0, 6))
+
+    tax_pay_frame = ttk.Frame(results_frame)
+    tax_pay_frame.pack(fill=tk.X, pady=(0, 8))
+    app.at_current_pmt_label = result_block(tax_pay_frame, "Current (After-Tax)", 0)
+    app.at_new_pmt_label = result_block(tax_pay_frame, "New (After-Tax)", 1)
+    app.at_savings_label = result_block(tax_pay_frame, "Monthly Δ (A-T)", 2)
+
+    tax_be_frame = ttk.Frame(results_frame)
+    tax_be_frame.pack(fill=tk.X, pady=(0, 8))
+    app.at_simple_be_label = result_block(tax_be_frame, "Simple BE (A-T)", 0)
+    app.at_npv_be_label = result_block(tax_be_frame, "NPV BE (A-T)", 1)
+    app.at_int_delta_label = result_block(tax_be_frame, "Interest Δ (A-T)", 2)
+
+    ttk.Separator(results_frame, orient=tk.HORIZONTAL).pack(fill=tk.X, pady=6)
+
+    app.accel_section_frame = ttk.Frame(results_frame)
+    app.accel_section_label = ttk.Label(
+        app.accel_section_frame,
+        text="Accelerated Payoff (Maintain Payment)",
+        style="Header.TLabel",
+    )
+    app.accel_section_label.pack(anchor=tk.W, pady=(0, 6))
+
+    accel_row1 = ttk.Frame(app.accel_section_frame)
+    accel_row1.pack(fill=tk.X, pady=(0, 8))
+    app.accel_months_label = result_block(accel_row1, "Payoff Time", 0)
+    app.accel_time_saved_label = result_block(accel_row1, "Time Saved", 1)
+    app.accel_interest_saved_label = result_block(accel_row1, "Interest Saved", 2)
+
+    ttk.Separator(app.accel_section_frame, orient=tk.HORIZONTAL).pack(fill=tk.X, pady=6)
+
+    npv_cost_frame = ttk.Frame(results_frame)
+    npv_cost_frame.pack(fill=tk.X, pady=(0, 8))
+
+    ttk.Label(results_frame, text="Total Cost NPV Analysis", style="Header.TLabel").pack(
+        anchor=tk.W,
+        pady=(0, 6),
+    )
+
+    npv_cost_row = ttk.Frame(results_frame)
+    npv_cost_row.pack(fill=tk.X, pady=(0, 8))
+    app.current_cost_npv_label = result_block(npv_cost_row, "Current Loan NPV", 0)
+    app.new_cost_npv_label = result_block(npv_cost_row, "New Loan NPV", 1)
+    app.cost_npv_advantage_label = result_block(npv_cost_row, "NPV Advantage", 2)
+
+    ttk.Separator(results_frame, orient=tk.HORIZONTAL).pack(fill=tk.X, pady=6)
+
+    npv_frame = ttk.Frame(results_frame)
+    npv_frame.pack(fill=tk.X)
+    app.npv_title_label = ttk.Label(
+        npv_frame,
+        text="5-Year NPV of Refinancing",
+        style="Header.TLabel",
+    )
+    app.npv_title_label.pack()
+    app.five_yr_npv_label = ttk.Label(npv_frame, text="$0", style="Big.TLabel")
+    app.five_yr_npv_label.pack(pady=3)
+
+
+__all__ = [
+    "build_main_tab",
+]
+
+__description__ = """
+Builder for the primary calculator tab.
+"""

refi_calculator/gui/builders/market_tab.py

@@ -0,0 +1,115 @@
+"""Builders for the market data tab."""
+
+from __future__ import annotations
+
+import tkinter as tk
+from tkinter import ttk
+from typing import TYPE_CHECKING
+
+from ...core.market.constants import MARKET_PERIOD_OPTIONS, MARKET_SERIES
+from ..market_chart import MarketChart
+
+if TYPE_CHECKING:
+    from ..app import RefinanceCalculatorApp
+
+
+def build_market_tab(
+    app: RefinanceCalculatorApp,
+    parent: ttk.Frame,
+) -> None:
+    """Construct the market history tab in the main notebook.
+
+    Args:
+        app: Application instance that owns the Tkinter state.
+        parent: Container frame that hosts the market history elements.
+    """
+    ttk.Label(
+        parent,
+        text="Historical Mortgage Rates",
+        font=("Segoe UI", 11, "bold"),
+    ).pack(anchor=tk.W, pady=(0, 6))
+
+    status_label = ttk.Label(
+        parent,
+        wraplength=720,
+        text="Loading market data...",
+    )
+    status_label.pack(anchor=tk.W, pady=(0, 6))
+
+    cache_indicator = ttk.Label(
+        parent,
+        text="Cache: initializing...",
+        font=("Segoe UI", 8),
+        foreground="#666",
+    )
+    cache_indicator.pack(anchor=tk.W, pady=(0, 6))
+
+    period_frame = ttk.Frame(parent)
+    period_frame.pack(fill=tk.X, pady=(0, 6))
+    ttk.Label(period_frame, text="Range:").pack(side=tk.LEFT)
+    for label, value in MARKET_PERIOD_OPTIONS:
+        ttk.Radiobutton(
+            period_frame,
+            text=label,
+            variable=app.market_period_var,
+            value=value,
+            command=app._populate_market_tab,
+        ).pack(side=tk.LEFT, padx=(6, 0))
+
+    action_frame = ttk.Frame(parent)
+    action_frame.pack(fill=tk.X, pady=(0, 6))
+    ttk.Button(
+        action_frame,
+        text="Refresh Market Rates",
+        command=app._refresh_market_data,
+    ).pack(side=tk.LEFT)
+
+    chart = MarketChart(parent)
+    chart.pack(fill=tk.X, pady=(0, 8))
+
+    table_frame = ttk.Frame(parent)
+    table_frame.pack(fill=tk.BOTH, expand=True)
+
+    labels = ["Date"] + [label for label, _ in MARKET_SERIES]
+    columns = ("date",) + tuple(label.lower().replace(" ", "_") for label in labels[1:])
+    tree = ttk.Treeview(table_frame, columns=columns, show="headings", height=12)
+    tree.heading("date", text="Date")
+    tree.column("date", width=130, anchor=tk.W)
+    for label, column in zip(labels[1:], columns[1:]):
+        tree.heading(column, text=label)
+        tree.column(column, width=100, anchor=tk.E)
+
+    scrollbar = ttk.Scrollbar(table_frame, orient="vertical", command=tree.yview)
+    tree.configure(yscrollcommand=scrollbar.set)
+    tree.pack(side=tk.LEFT, fill=tk.BOTH, expand=True)
+    scrollbar.pack(side=tk.RIGHT, fill=tk.Y)
+
+    legend_frame = ttk.Frame(parent)
+    legend_frame.pack(anchor=tk.W, pady=(6, 0))
+    colors = ["#2563eb", "#ec4899", "#16a34a", "#f59e0b"]
+    for idx, (label, _) in enumerate(MARKET_SERIES):
+        swatch = tk.Label(
+            legend_frame,
+            text=" ",
+            width=2,
+            bg=colors[idx % len(colors)],
+            relief=tk.SUNKEN,
+        )
+        swatch.pack(side=tk.LEFT, padx=(0, 2))
+        ttk.Label(
+            legend_frame,
+            text=label,
+            font=("Segoe UI", 8),
+        ).pack(side=tk.LEFT, padx=(0, 8))
+
+    app.market_chart = chart
+    app.market_tree = tree
+    app._market_status_label = status_label
+    app._market_cache_indicator = cache_indicator
+
+
+__all__ = ["build_market_tab"]
+
+__description__ = """
+Builders for the market history tab inside the refinance calculator UI.
+"""