spendwise 1.0.0

package/src/renderer/js/app.js

@@ -0,0 +1,185 @@
+/* global Alpine, FinEngine, showToast, unwrap */
+'use strict';
+
+document.addEventListener('alpine:init', () => {
+    Alpine.store('data', {
+        loaded: false,
+        path: '',
+        version: '',
+        db: null,
+        // update check: { available, latest, url, unreachable, enabled }
+        update: { available: false, latest: null, url: '', checking: false, checked: false },
+    });
+
+    Alpine.store('ui', {
+        view: 'month', // month | insights | settings
+        locked: false, // app-password lock screen (desktop only - web logs in at the server)
+        offline: false, // web only: no server → read-only until it's back
+        switching: false, // month change rendering: hides main, shows "loading…"
+        settingsDirty: false, // mirrored by settingsView for the unsaved-changes gate
+        currentKey: null,
+        unlockedKeys: [],
+        savedSnapshot: '',
+        monthGoto: null, // set by monthView: header picker → goto(key)
+        recomputeChanges: [],
+        importSummary: null,
+        importMap: { folder: '', groups: [] },
+        modals: {
+            recompute: false,
+            importMap: false,
+            importSummary: false,
+            backups: false,
+            confirm: false,
+        },
+        confirm: {
+            open: false, title: '', body: '', confirmText: 'Confirm',
+            cancelText: 'Cancel', altText: null, danger: false, resolve: null,
+        },
+        toast: { show: false, message: '', type: 'info', timeout: 3500 },
+    });
+});
+
+function appRoot () {
+    return {
+        async init () {
+            try {
+                const res = unwrap(await window.api.loadDb());
+                const data = Alpine.store('data');
+                data.db = res.data;
+                data.path = res.path;
+                data.version = res.version || '';
+                data.loaded = true;
+
+                const ui = Alpine.store('ui');
+                const keys = FinEngine.monthKeys(res.data);
+                const open = keys.filter((k) => res.data.months[k].status === 'open');
+                ui.currentKey = open.length ? open[open.length - 1] : keys[keys.length - 1];
+                ui.savedSnapshot = JSON.stringify(res.data.months[ui.currentKey]);
+                // desktop privacy lock; web clients authenticated at the server
+                ui.locked = !!(res.data.settings && res.data.settings.auth) && !window.IS_WEB;
+            } catch (e) {
+                showToast('Failed to load data: ' + e.message, 'error', 12000);
+            }
+            this.watchConnection();
+            this.startPolling();
+            this.guardUnsaved();
+            this.checkUpdate(); // deliberately not awaited - never delays first paint
+        },
+
+        /**
+         * Ask the main/server process whether a newer release is tagged. Any
+         * failure is a non-event: no toast, no error, the app does not need
+         * GitHub. The nudge is a dot on the settings gear plus a line in
+         * Settings - never a modal in the way of the books.
+         */
+        async checkUpdate ({ force = false } = {}) {
+            const data = Alpine.store('data');
+            data.update.checking = true;
+            try {
+                const res = unwrap(await window.api.checkUpdate({ force }));
+                data.update = {
+                    ...res,
+                    checking: false,
+                    checked: true,
+                    available: !!res.available,
+                };
+                if (res.available) {
+                    showToast(`Spend Wise ${res.latest} is available - see Settings`, 'info', 8000);
+                }
+            } catch {
+                data.update.checking = false;
+                data.update.checked = true;
+                data.update.unreachable = true;
+            }
+        },
+
+        async openReleases () {
+            try { await window.api.openReleases(); } catch { /* nothing to do */ }
+        },
+
+        /**
+         * Nothing is written until you press Update, so closing or reloading
+         * with edits in flight would drop them silently.
+         *
+         * The web gets the browser's own leave-confirmation. Electron does NOT:
+         * a beforeunload handler that returns a value there just cancels the
+         * close without asking, so the desktop is gated in the main process
+         * instead (main.js), which calls the hook below.
+         */
+        guardUnsaved () {
+            window.__unsavedSummary = () => {
+                const data = Alpine.store('data');
+                const ui = Alpine.store('ui');
+                if (!data.loaded || !data.db) return null;
+                const cur = ui.currentKey && data.db.months[ui.currentKey];
+                const monthDirty = !!cur && JSON.stringify(cur) !== ui.savedSnapshot;
+                if (!monthDirty && !ui.settingsDirty) return null;
+                const parts = [];
+                if (monthDirty) parts.push(FinEngine.keyLabel(ui.currentKey));
+                if (ui.settingsDirty) parts.push('Settings');
+                return parts.join(' and ');
+            };
+            if (!window.IS_WEB) return;
+            window.addEventListener('beforeunload', (e) => {
+                if (!window.__unsavedSummary()) return;
+                e.preventDefault();
+                e.returnValue = ''; // required by older browsers to trigger the prompt
+            });
+        },
+
+        /**
+         * A web client needs the server for every read and write, so losing it
+         * puts the app in read-only rather than letting edits pile up with
+         * nowhere to go. The desktop app talks to its own process - it is
+         * never offline, even with the network down.
+         */
+        watchConnection () {
+            if (!window.IS_WEB) return;
+            const ui = Alpine.store('ui');
+            ui.offline = navigator.onLine === false;
+            // instant signal for a dropped network; the rev poll below is what
+            // catches "connected to wifi, but the server is gone"
+            window.addEventListener('offline', () => { ui.offline = true; });
+            window.addEventListener('online', () => { ui.offline = false; });
+        },
+
+        /**
+         * Co-editing freshness: when another session bumps the rev while this
+         * one has no unsaved edits, quietly reload. With edits in flight we
+         * leave the screen alone - the merge happens at save time instead.
+         */
+        startPolling () {
+            if (this._pollTimer || !window.api.rev) return;
+            this._pollTimer = setInterval(async () => {
+                const data = Alpine.store('data');
+                const ui = Alpine.store('ui');
+                if (!data.loaded || ui.locked) return;
+                let r;
+                try {
+                    r = await window.api.rev();
+                } catch {
+                    if (window.IS_WEB) ui.offline = true; // server unreachable
+                    return;
+                }
+                if (window.IS_WEB && r.ok) ui.offline = false;
+                try {
+                    if (!r.ok || r.rev === data.db.meta.rev) return;
+                    const cur = ui.currentKey && data.db.months[ui.currentKey];
+                    if (cur && JSON.stringify(cur) !== ui.savedSnapshot) return; // dirty - don't clobber
+                    const res = unwrap(await window.api.loadDb());
+                    data.db = res.data;
+                    if (!res.data.months[ui.currentKey]) {
+                        const keys = FinEngine.monthKeys(res.data);
+                        ui.currentKey = keys[keys.length - 1];
+                    }
+                    ui.savedSnapshot = JSON.stringify(res.data.months[ui.currentKey]);
+                    window.dispatchEvent(new CustomEvent('db-refreshed'));
+                } catch { /* transient - next tick retries */ }
+            }, 20000);
+        },
+
+        switchView (view) {
+            Alpine.store('ui').view = view;
+        },
+    };
+}

package/src/renderer/js/boot.js

@@ -0,0 +1,4 @@
+/* global parseCustomComponents */
+// Runs at the end of <body>, after the x-component templates exist and before
+// Alpine (deferred) boots - external file so the CSP can stay inline-script-free.
+parseCustomComponents();

package/src/renderer/js/charts.js

@@ -0,0 +1,116 @@
+/* global ApexCharts, FinEngine */
+'use strict';
+
+const Charts = {
+    instances: {},
+
+    destroy (id) {
+        const inst = this.instances[id];
+        if (inst) {
+            // destroy() can throw when the chart's DOM was already torn down
+            // (the Insights view is x-if gated) - the map entry must go anyway
+            try { inst.destroy(); } catch (e) { /* detached DOM */ }
+            delete this.instances[id];
+        }
+    },
+
+    /**
+     * Must run BEFORE the Insights DOM is torn down (view switch): an
+     * ApexCharts instance that outlives its element keeps a ResizeObserver
+     * and repaints its stale content over later renders (zombie chart).
+     */
+    teardownInsights () {
+        ['insights-donut', 'insights-bar', 'insights-savings',
+            'insights-income-donut', 'insights-income-bar'].forEach((id) => this.destroy(id));
+    },
+
+    /** Savings history line: last 12 months plus a live "Now" point - the
+        longer view lives in Insights. */
+    savingsLine (el, db, currentKey, currentSavings, lastN = 12) {
+        const keys = Object.keys(db.savingsHistory || {}).sort()
+            .filter((k) => k <= currentKey)
+            .slice(-lastN);
+        const labels = keys.map((k) => FinEngine.keyLabel(k).slice(0, 3) + ' ' + k.slice(2, 4));
+        const values = keys.map((k) => FinEngine.num(db.savingsHistory[k]));
+        labels.push('Now');
+        values.push(FinEngine.num(currentSavings));
+
+        // fast path: same months, only the values moved → update in place
+        // (a full destroy/render costs hundreds of ms and ran on every edit)
+        const sig = labels.join('|');
+        if (this.instances.savings && this._savingsSig === sig && this._savingsEl === el) {
+            this.instances.savings.updateSeries([{ name: 'Savings', data: values }], false);
+            return this.instances.savings;
+        }
+        this._savingsSig = sig;
+        this._savingsEl = el;
+
+        const options = {
+            chart: { type: 'area', height: 240, toolbar: { show: false }, zoom: { enabled: false }, animations: { enabled: false }, fontFamily: 'inherit' },
+            series: [{ name: 'Savings', data: values }],
+            xaxis: { categories: labels, labels: { rotate: -45, style: { fontSize: '10px' } }, tickAmount: 6 },
+            yaxis: { labels: { formatter: (v) => fmt(v) } },
+            colors: ['#10b981'],
+            stroke: { curve: 'smooth', width: 2.5 },
+            fill: { type: 'gradient', gradient: { opacityFrom: 0.5, opacityTo: 0.1 } },
+            dataLabels: { enabled: false },
+            tooltip: { y: { formatter: (v) => fmt(v) } },
+            grid: { borderColor: '#e4e4e7', strokeDashArray: 3 },
+        };
+
+        return this._render('savings', el, options);
+    },
+
+    donut (id, el, labels, values) {
+        const options = {
+            chart: { type: 'donut', height: 300, animations: { enabled: false }, fontFamily: 'inherit' },
+            series: values,
+            labels,
+            legend: { position: 'bottom' },
+            dataLabels: { enabled: true, formatter: (pct) => Math.round(pct) + '%' },
+            tooltip: { y: { formatter: (v) => fmt(v) } },
+        };
+        return this._render(id, el, options);
+    },
+
+    stackedBar (id, el, categories, series) {
+        const options = {
+            chart: { type: 'bar', height: 320, stacked: true, toolbar: { show: false }, animations: { enabled: false }, fontFamily: 'inherit' },
+            series,
+            xaxis: { categories, labels: { rotate: -45, style: { fontSize: '10px' } } },
+            yaxis: { labels: { formatter: (v) => fmt(v) } },
+            legend: { position: 'bottom' },
+            dataLabels: { enabled: false },
+            tooltip: { y: { formatter: (v) => fmt(v) } },
+            grid: { borderColor: '#e4e4e7', strokeDashArray: 3 },
+        };
+        return this._render(id, el, options);
+    },
+
+    line (id, el, categories, series, opts = {}) {
+        const options = {
+            chart: { type: 'line', height: 300, toolbar: { show: false }, zoom: { enabled: false }, animations: { enabled: false }, fontFamily: 'inherit' },
+            series,
+            xaxis: { categories, labels: { rotate: -45, style: { fontSize: '10px' } }, tickAmount: 12 },
+            yaxis: { labels: { formatter: (v) => fmt(v) } },
+            stroke: { curve: 'smooth', width: 2.5, dashArray: opts.dashArray || 0 },
+            legend: { position: 'bottom' },
+            dataLabels: { enabled: false },
+            tooltip: { y: { formatter: (v) => fmt(v) } },
+            grid: { borderColor: '#e4e4e7', strokeDashArray: 3 },
+        };
+        if (opts.colors) options.colors = opts.colors;
+        return this._render(id, el, options);
+    },
+
+    _render (id, el, options) {
+        if (!el) return null;
+        // destroy + clear + create: updateOptions() does not reliably apply
+        // changed label sets (donut legends stick), so a fresh instance it is
+        this.destroy(id);
+        el.innerHTML = ''; // never stack SVGs, even if a stale instance failed to clean up
+        this.instances[id] = new ApexCharts(el, options);
+        this.instances[id].render();
+        return this.instances[id];
+    },
+};

package/src/renderer/js/components.js

@@ -0,0 +1,39 @@
+/**
+ * x-component system: each <template x-component="name"> in index.html becomes
+ * a <x-name> custom element - one source of truth per component. Attributes on
+ * the element flow into the template's Alpine scope via xProps (helpers.js);
+ * <slot> (default and named) is replaced with the element's original children.
+ *
+ * Must run before Alpine boots (Alpine is loaded with defer; this is not).
+ */
+'use strict';
+
+function parseCustomComponents () {
+    document.querySelectorAll('template[x-component]').forEach((template) => {
+        const name = `x-${template.getAttribute('x-component')}`;
+
+        class Component extends HTMLElement {
+            connectedCallback () {
+                const content = template.content.cloneNode(true);
+
+                content.querySelectorAll('slot').forEach((slot) => {
+                    const slotName = slot.getAttribute('name');
+                    if (slotName) {
+                        const match = this.querySelector(`[slot="${slotName}"]`);
+                        if (match) slot.replaceWith(match.cloneNode(true));
+                        else slot.remove();
+                    } else {
+                        const children = Array.from(this.childNodes).filter((n) =>
+                            n.nodeType === Node.ELEMENT_NODE || n.nodeType === Node.TEXT_NODE);
+                        slot.replaceWith(...children.map((n) => n.cloneNode(true)));
+                    }
+                });
+
+                this.innerHTML = '';
+                this.appendChild(content);
+            }
+        }
+
+        customElements.define(name, Component);
+    });
+}

package/src/renderer/js/helpers.js

@@ -0,0 +1,76 @@
+/* global Alpine, FinEngine */
+'use strict';
+
+const E = FinEngine;
+
+let _fmt = null;
+function fmt (value) {
+    if (!_fmt) {
+        const currency = (Alpine.store('data').db?.settings?.currency) || 'USD';
+        _fmt = new Intl.NumberFormat('en-US', { style: 'currency', currency, maximumFractionDigits: 0 });
+    }
+    return _fmt.format(E.num(value));
+}
+
+function fmtSigned (value) {
+    const n = E.num(value);
+    return (n > 0 ? '+' : '') + fmt(n);
+}
+
+function showToast (message, type = 'info', timeout = 3500) {
+    const t = Alpine.store('ui').toast;
+    t.message = message;
+    t.type = type;
+    t.timeout = timeout;
+    t.show = true;
+    clearTimeout(window._toastTimeout);
+    window._toastTimeout = setTimeout(() => { t.show = false; }, timeout);
+}
+
+/**
+ * Promise-based confirm dialog backed by the shared modal in index.html.
+ * confirmDialog({ title, body, confirmText, danger, altText }) → Promise
+ * Resolves true (confirm), false (cancel), or 'alt' when the optional
+ * secondary action (altText) is chosen.
+ */
+function confirmDialog (opts) {
+    return new Promise((resolve) => {
+        const c = Alpine.store('ui').confirm;
+        c.title = opts.title || 'Are you sure?';
+        c.body = opts.body || '';
+        c.confirmText = opts.confirmText || 'Confirm';
+        c.cancelText = opts.cancelText || 'Cancel';
+        c.altText = opts.altText || null;
+        c.danger = !!opts.danger;
+        c.open = true;
+        c.resolve = (answer) => { c.open = false; c.resolve = null; resolve(answer); };
+    });
+}
+
+/** Unwrap an IPC response; throws on { ok: false } and shows nothing itself. */
+function unwrap (res) {
+    if (!res || res.ok !== true) throw new Error(res && res.error || 'Unknown error');
+    return res;
+}
+
+/** Shared prop plumbing for x-components: parent attributes become reactive data. */
+function xProps (el, defaults = {}) {
+    const parent = el.parentElement;
+    const data = { ...defaults };
+    for (const attr of parent.getAttributeNames()) data[attr] = parent.getAttribute(attr);
+    return {
+        ...data,
+        _initProps () {
+            const observer = new MutationObserver((mutations) => {
+                for (const m of mutations) {
+                    if (m.type === 'attributes') this[m.attributeName] = parent.getAttribute(m.attributeName);
+                }
+            });
+            observer.observe(parent, { attributes: true });
+        },
+    };
+}
+
+function boolAttr (value) {
+    return !(value === '0' || value === 'false' || value === 'null' || value === false || value === undefined || value === null || value === '');
+}

package/src/renderer/js/views/insights.js

@@ -0,0 +1,259 @@
+/* global Alpine, FinEngine, Charts, fmt */
+'use strict';
+
+function insightsView () {
+    return {
+        range: '12mo', // '12mo' | 'ytd' | 'all'
+        projected12: null, // savings 12 months out at the current trend
+
+        get db () { return Alpine.store('data').db; },
+        get keys () { return this.db ? FinEngine.monthKeys(this.db) : []; },
+
+        get rangeKeys () {
+            const keys = this.keys;
+            if (!keys.length) return [];
+            const last = keys[keys.length - 1];
+            if (this.range === '12mo') return keys.slice(-12);
+            if (this.range === 'ytd') return keys.filter((k) => k.startsWith(last.slice(0, 4)));
+            return keys;
+        },
+
+        /**
+         * Spend aggregated per tag per month - computed at chart time, never
+         * stored. An expense counts under the UNION of its own tags and the
+         * tags of the envelope it draws from (a budget's tags are enforced on
+         * its linked expenses; the expense's own tags are never overridden).
+         * With no tags from either source it lands in the 'untagged' bucket.
+         * Direct envelope spending counts under the envelope's own tags.
+         */
+        aggregate () {
+            const perMonth = {}; // key → { tag → amount }
+            const totals = {};   // tag → amount
+
+            for (const key of this.rangeKeys) {
+                const month = this.db.months[key];
+                const bucket = {};
+                const add = (tag, amount) => {
+                    if (!amount) return;
+                    bucket[tag] = (bucket[tag] || 0) + amount;
+                    totals[tag] = (totals[tag] || 0) + amount;
+                };
+
+                // envelope tags, for inheritance by their linked expenses
+                const envTags = {};
+                for (const g of month.groups) {
+                    if (!FinEngine.isEnvelopeKind(g.kind)) continue;
+                    for (const f of g.fields) {
+                        if (f.tags && f.tags.length) envTags[f.id] = f.tags;
+                        // direct envelope spending under the envelope's own tags
+                        if (f.tags && f.tags.length) for (const t of f.tags) add(t, FinEngine.num(f.spent));
+                    }
+                }
+
+                for (const g of month.groups) {
+                    if (g.kind !== 'expense') continue;
+                    for (const f of g.fields) {
+                        const merged = new Set([
+                            ...(f.tags || []),
+                            ...((f.budgetId && envTags[f.budgetId]) || []),
+                        ]);
+                        const tags = merged.size ? [...merged] : ['untagged'];
+                        for (const t of tags) add(t, FinEngine.num(f.value));
+                    }
+                }
+                perMonth[key] = bucket;
+            }
+            return { perMonth, totals };
+        },
+
+        /**
+         * Income aggregated per tag per month - income streams (clients, side
+         * gigs…). Only TAGGED income counts: there is deliberately no
+         * 'untagged' bucket, and the whole section hides when nothing is
+         * tagged. Face values; a field with several tags counts under each.
+         */
+        incomeAggregate () {
+            const perMonth = {}; // key → { tag → amount }
+            const totals = {};   // tag → amount
+            for (const key of this.rangeKeys) {
+                const month = this.db.months[key];
+                const bucket = {};
+                for (const g of month.groups) {
+                    if (g.kind !== 'income') continue;
+                    for (const f of g.fields) {
+                        if (!f.tags || !f.tags.length) continue;
+                        const amount = FinEngine.num(f.value);
+                        if (!amount) continue;
+                        for (const t of f.tags) {
+                            bucket[t] = (bucket[t] || 0) + amount;
+                            totals[t] = (totals[t] || 0) + amount;
+                        }
+                    }
+                }
+                perMonth[key] = bucket;
+            }
+            return { perMonth, totals };
+        },
+
+        incomeRows () {
+            const { totals } = this.incomeAggregate();
+            const taggedTotal = Object.values(totals).reduce((a, b) => a + b, 0) || 1;
+            const n = this.rangeKeys.length || 1;
+            return Object.entries(totals)
+                .sort((a, b) => b[1] - a[1])
+                .map(([tag, total]) => ({
+                    tag,
+                    total,
+                    avg: Math.round(total / n),
+                    pct: Math.round(total / taggedTotal * 100),
+                }));
+        },
+
+        stats () {
+            const keys = this.rangeKeys;
+            let income = 0, spend = 0;
+            for (const key of keys) {
+                const m = this.db.months[key];
+                for (const g of m.groups) {
+                    const t = FinEngine.groupTotal(m, g);
+                    if (g.kind === 'income') income += t; else spend += t;
+                }
+            }
+            const n = keys.length || 1;
+            return {
+                months: keys.length,
+                avgIncome: Math.round(income / n),
+                avgSpend: Math.round(spend / n),
+                avgNet: Math.round((income - spend) / n),
+                totalIncome: income,
+                totalSpend: spend,
+            };
+        },
+
+        tagRows () {
+            const { totals } = this.aggregate();
+            const spendTotal = Object.values(totals).reduce((a, b) => a + b, 0) || 1;
+            const n = this.rangeKeys.length || 1;
+            return Object.entries(totals)
+                .sort((a, b) => b[1] - a[1])
+                .map(([tag, total]) => ({
+                    tag,
+                    total,
+                    avg: Math.round(total / n),
+                    pct: Math.round(total / spendTotal * 100),
+                }));
+        },
+
+        /** Envelope health from the most recent month. */
+        envelopes () {
+            const keys = this.keys;
+            if (!this.db || !keys.length) return [];
+            const month = this.db.months[keys[keys.length - 1]];
+            const out = [];
+            for (const g of month.groups) {
+                if (!FinEngine.isEnvelopeKind(g.kind)) continue;
+                for (const f of g.fields) {
+                    const spent = FinEngine.effectiveSpent(month, f);
+                    out.push({
+                        label: f.label || '(unnamed)',
+                        kind: g.kind,
+                        avail: FinEngine.num(f.avail),
+                        spent,
+                        left: FinEngine.num(f.avail) - spent,
+                        target: FinEngine.num(f.target),
+                        progress: g.kind === 'goal' ? FinEngine.goalProgress(month, f) : null,
+                    });
+                }
+            }
+            return out;
+        },
+
+        render () {
+            if (!this.db) return;
+            // resolve containers from the LIVE document - $refs go stale when
+            // the x-if gate re-creates the Insights DOM (charts painted into
+            // detached elements, appearing "one toggle behind")
+            const donutEl = document.getElementById('insights-chart-donut');
+            const barEl = document.getElementById('insights-chart-bar');
+            const savingsEl = document.getElementById('insights-chart-savings');
+            if (!donutEl || !barEl || !savingsEl) return; // view not mounted
+            const { perMonth, totals } = this.aggregate();
+
+            const top = Object.entries(totals).sort((a, b) => b[1] - a[1]).slice(0, 8);
+            Charts.donut('insights-donut', donutEl, top.map(([t]) => t), top.map(([, v]) => Math.round(v)));
+
+            const topTags = top.slice(0, 6).map(([t]) => t);
+            const categories = this.rangeKeys.map((k) => FinEngine.keyLabel(k).slice(0, 3) + ' ' + k.slice(2, 4));
+            const series = topTags.map((tag) => ({
+                name: tag,
+                data: this.rangeKeys.map((k) => Math.round(perMonth[k][tag] || 0)),
+            }));
+            Charts.stackedBar('insights-bar', barEl, categories, series);
+
+            // income streams - only when something is tagged; the section is
+            // x-show-gated on incomeRows().length so destroy stale instances
+            // when the range change empties it
+            const incomeDonutEl = document.getElementById('insights-chart-income-donut');
+            const incomeBarEl = document.getElementById('insights-chart-income-bar');
+            const inc = this.incomeAggregate();
+            const incTop = Object.entries(inc.totals).sort((a, b) => b[1] - a[1]).slice(0, 8);
+            if (incTop.length && incomeDonutEl && incomeBarEl) {
+                Charts.donut('insights-income-donut', incomeDonutEl,
+                    incTop.map(([t]) => t), incTop.map(([, v]) => Math.round(v)));
+                const incTags = incTop.slice(0, 6).map(([t]) => t);
+                const incSeries = incTags.map((tag) => ({
+                    name: tag,
+                    data: this.rangeKeys.map((k) => Math.round(inc.perMonth[k][tag] || 0)),
+                }));
+                Charts.stackedBar('insights-income-bar', incomeBarEl, categories, incSeries);
+            } else {
+                Charts.destroy('insights-income-donut');
+                Charts.destroy('insights-income-bar');
+            }
+
+            // savings history, windowed to the selected range
+            const allHist = Object.keys(this.db.savingsHistory || {}).sort();
+            let histKeys = allHist;
+            if (this.range === '12mo') {
+                histKeys = allHist.slice(-12);
+            } else if (this.range === 'ytd') {
+                const last = this.keys[this.keys.length - 1] || allHist[allHist.length - 1] || '';
+                histKeys = allHist.filter((k) => k.startsWith(last.slice(0, 4)));
+            }
+            const shortLabel = (k) => FinEngine.keyLabel(k).slice(0, 3) + ' ' + k.slice(2, 4);
+            const histVals = histKeys.map((k) => FinEngine.num(this.db.savingsHistory[k]));
+            let savingsCats = histKeys.map(shortLabel);
+            const savingsSeries = [{ name: 'Savings', data: [...histVals] }];
+
+            // projection: least-squares trend over the selected window,
+            // anchored at the latest actual point, 12 months out
+            this.projected12 = null;
+            const PROJ = 12;
+            if (histVals.length >= 3) {
+                const n = histVals.length;
+                const xMean = (n - 1) / 2;
+                const yMean = histVals.reduce((a, b) => a + b, 0) / n;
+                let cov = 0, varx = 0;
+                histVals.forEach((y, x) => { cov += (x - xMean) * (y - yMean); varx += (x - xMean) ** 2; });
+                const slope = varx ? cov / varx : 0;
+
+                let k = histKeys[histKeys.length - 1];
+                const futureKeys = [];
+                for (let s = 1; s <= PROJ; s++) { k = FinEngine.nextKey(k); futureKeys.push(k); }
+                savingsCats = savingsCats.concat(futureKeys.map(shortLabel));
+
+                const last = histVals[n - 1];
+                savingsSeries[0].data = histVals.concat(new Array(PROJ).fill(null));
+                savingsSeries.push({
+                    name: 'Projected',
+                    data: new Array(n - 1).fill(null)
+                        .concat([last], futureKeys.map((_, s) => Math.round(last + slope * (s + 1)))),
+                });
+                this.projected12 = Math.round(last + slope * PROJ);
+            }
+
+            Charts.line('insights-savings', savingsEl, savingsCats, savingsSeries,
+                { dashArray: [0, 6], colors: ['#3b82f6', '#8b5cf6'] });
+        },
+    };
+}