Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
23 changes: 23 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,29 @@ Format follows [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).

---

## [1.16.4] — 2026-11-02

### Fixed
- **A JSON import lost the spotted-charge choices and the category rules on the next reload.**
- **Symptom:** after **Settings → Data & reset → Import JSON**, the charges you had confirmed or dismissed under Bills → Spotted recurring charges, and the rules under Spending → Category rules, showed at first and were gone after a reload.
- **Cause:** browser storage keeps these two under older names: `State.recurringConfirmed` as `recurring` and `State.categoryRules` as `catRules`. `importJsonFile()` saved every key under its State name, so they went to `recurringConfirmed` and `categoryRules` in localStorage and IndexedDB `app_state`, which nothing reads. Boot loaded the old values instead (`lsGet()`, `DB.loadAll()`).
- **Not affected:** `finlens-state.json` and the export itself use State names, so both were right. With a connected folder, a reload more than 5 seconds after the import (once the debounced save had run) loaded the file and kept the import. Without a folder, or once folder access had lapsed, the import was lost.
- **Fix:** one mapping, `STORAGE_KEYS` and `storageKey(stateKey)` in `core.js`. The import saves each key through it. The storage names don't change, so existing data loads as before.
- **Imported before this fix?** Import the file again.
- **Other code that saves keys by State name uses the same mapping:**
- **Data & reset:** the plan clears (`PLAN_ITEMS`, `PLAN_ALSO`) save through `storageKey()`. `PLAN_ALSO` no longer lists a storage key of its own. No change in behavior: it already used `recurring`.
- **`migrate.js`:** `migrateStores()` reads and writes browser storage through `storageKey()`. All five of its keys are stored under their State names, so nothing changes today.
- **An import with a null value broke the app.** A key set to `null` in the file replaced the current value, so a null `categoryRules` made every categorization throw. A null now counts as missing and keeps the current value, as a missing key always did.

### Unchanged
- **Older exports still import:** the export's `version` (1.0, 1.1) isn't checked. A key the file doesn't have keeps its current value.
- **Leftover keys:** an import before this fix left `recurringConfirmed` and `categoryRules` in browser storage. Nothing reads them, and **Start over** removes them.

### Docs
- **CLAUDE.md** — §1 version; §4.5 storage keys; §8 `storageKey()`; §12 adding a persisted field uses the State name as its storage key.

---

## [1.16.3] — 2026-11-02

### Fixed
Expand Down
8 changes: 5 additions & 3 deletions CLAUDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -59,7 +59,7 @@ Until then, this section is the rule.

FinLens is a **single-origin, zero-build, vanilla JavaScript personal finance dashboard** that runs entirely in the browser. There is no server, no npm, no bundler, no framework, and no TypeScript. The entry point is `index.html`; everything else is a plain `.js` file in the `js/` folder.

**Current version:** v1.16.3 (updated in `index.html` footer, `README.md`, and `CHANGELOG.md` on every release).
**Current version:** v1.16.4 (updated in `index.html` footer, `README.md`, and `CHANGELOG.md` on every release).

**What it does:** Imports CSV exports from a bank (checking + savings) and credit cards, parses and normalizes them into a unified transaction model, and renders a multi-tab financial dashboard with budgeting, debt tracking, savings forecasting, investment planning, and Claude-powered AI analysis.

Expand Down Expand Up @@ -320,6 +320,7 @@ loadStateFromFile() → found?
- **Fallback chain** — If filesystem load fails, IndexedDB provides a session-local cache. If IndexedDB isn't available, localStorage defaults apply.
- Always use `lsSet(key, value)` and `lsGet(key, default)` — **never** call `localStorage` directly.
- The `finlens_` prefix is applied automatically by `lsSet`/`lsGet`.
- **Two keys have older storage names (v1.16.4).** Browser storage (localStorage and IndexedDB `app_state`) keeps `State.recurringConfirmed` as `recurring` and `State.categoryRules` as `catRules`; every other key is stored under its State name. `STORAGE_KEYS` / `storageKey(stateKey)` in `core.js` is the one mapping. Code that saves or loads keys by State name in a loop must go through it: JSON import, Data & reset's plan clears, `migrate.js`. Up to v1.16.3 the JSON import didn't, and its values were lost on reload. Don't rename the storage keys: existing data lives under them. `finlens-state.json` and JSON exports use State names.
- Don't call `saveStateToFile()` directly in hot paths — it's meant to be debounced via `_saveStateDebounced()` in `lsSet()`.
- **Never use transactions straight from JSON.** `JSON.parse` turns `date` into a string and freezes the `category` getter. `loadStateFromFile()` rebuilds them with `reconstituteTx()`, as `DB.loadAll()` does; any new code that reads transactions from JSON must do the same.
- **IndexedDB may not hold the loaded transactions.** After a boot or restore from `finlens-state.json` (a new browser, cleared site data, `_restoreStateIfBrowserEmpty()`), the `transactions` store can be empty or hold only some of them. Code that changes the loaded transactions works from `State.transactions`, never by replacing them with the store's rows: a store row may only fill in a value a transaction lacks. Up to v1.16.0, Clear transaction edits replaced them and wiped every transaction (§20).
Expand Down Expand Up @@ -505,6 +506,7 @@ pct(n, decimals?) // '12.3%'
// Persistence
lsGet(key, default) // Read from localStorage (auto-prefixed)
lsSet(key, value) // Write to localStorage + mirror to IndexedDB app_state + auto-save to filesystem (debounced)
storageKey(stateKey) // The lsSet/lsGet key for a State key: 'recurring', 'catRules', else the State name (STORAGE_KEYS, §4.5)
loadStateFromFile() // Read finlens-state.json from backup folder; returns loaded state or null if not found
saveStateToFile(state) // Write state to finlens-state.json in backup folder (fire-and-forget async)
_saveStateDebounced() // Debounced wrapper (5s) — called by lsSet()
Expand Down Expand Up @@ -779,7 +781,7 @@ el.innerHTML = `<button onclick="editBudget(${i})">Edit</button>`;

### Adding a new persisted field

1. Add the field to `State` with `lsGet('myKey', defaultValue)`.
1. Add the field to `State` with `lsGet('myKey', defaultValue)`. Use the State name as the storage key; only the two older keys in `STORAGE_KEYS` differ (§4.5).
2. That's it — `lsSet` automatically mirrors to IndexedDB `app_state` and localStorage.

### App Bar Navigation (v1.13.0)
Expand Down Expand Up @@ -984,7 +986,7 @@ Multiple credit card files can be loaded simultaneously. Each gets a unique `acc

---

*Last updated: v1.16.3 — 2026-11-02 (An import keeps the loaded transactions it doesn't replace: §4.5 an import never drops loaded transactions; §8 `mergeImported()`, `undoTransferDetection()`; §10 memory follows the same re-upload rules; §11 kept transfers are detected again; v1.16.2: Imports read every file before changing anything: §8 `loadFiles()` options and result, `parseCsvFile()` reads only, `importParsedCsv()`, `importProblemText()`, `reloadFromDirHandle()`; §20 Rebuild from your folder reads before it clears, read before clearing; v1.16.1: Clear transaction edits works from memory: §4.2 `_originalCategories`, `_originalType` and what a transaction keeps of its row; §4.5 IndexedDB may not hold the loaded transactions; §10 a stored row holds the CSV's values; §20 Clear transaction edits; v1.16.0: Trends, AI Analysis, Settings and the Welcome rebuilt: §3 file roles; §4.1 `cardDetails`, `sampleData`, AI history `model`; §6 tile tokens and Insights/Settings/Welcome components; §7 rule 7 covers Trends; §8 `loadFiles()` sample option; §9 `shellHero()`, `NO_RANGE_VIEWS`, ☰ → ×, JSON export/import buttons; §12 Settings tabs renamed, the Welcome, range label hidden on Trends and Settings; §13 quick analyses, tab state, history; §20 new fields, Use my own files, Export/Import JSON; §21 quick analyses send `AI_PROMPTS`; v1.15.0: Plan screens rebuilt: §3 file roles; §4.1 `debtPlan` and the Budget / Bucket / Debt / Scenario shapes; §6 `--teal-text` and Plan components; §7 rule 7 covers the Plan charts; §8 plan helpers (`payoffPlan()`, `growthByYear()` …); §9 plan form helpers, `simulatePayoff()` kept unused; §12 Plan titles, Forecast tabs, range label hidden on Plan screens; §13 debt balances in the summary; §20 Clear forecast scenarios / investment mix, Clear debts resets `debtPlan`; v1.14.0: Finances screens rebuilt: §4.1 Bill shape and `recurringConfirmed`; §6 new tokens and Finances components; §7 rule 7 inline SVG charts; §8 new aggregation helpers; §9 drawer, `TX_VIEWS`, SVG/heatmap/format helpers, bill helpers, removed renderers; §11 keywords re-run detection, `transferPairs()`, card payments; §12 page actions and Transactions pills; §20 Clear bills also clears spotted-charge choices; v1.13.0: Clarity redesign — §6 tokens and components; §9 theme, chart colors and app bar helpers; §12 app bar navigation replaces the sidebar and the emoji rule; §17 footer; §20 Data & Reset; v1.12.0: bank-neutral account codes, names, samples and docs; §22 `migrate.js` added; §3, §4, §5, §10, §18, §21 updated; v1.10.5: no section changes: Import Logs race fix; v1.10.4: §8, §13 single `~` is literal; §21 excerpts escape `~`; v1.10.3: §13 refusals; §21 declined runs; v1.10.2: §13 summary states its dates; §21 per-month derivations; v1.10.1: §13 `AI_MAX_TOKENS`, thinking and cut-off answers; v1.10.0: §21 AI Eval added; §13 `callClaude()` raw mode; v1.9.6: §14 folder access lasts until the last tab closes, not one page load; v1.9.5: §7 chart guard; v1.9.4: views-db.js changelog reads CRLF checkouts; v1.9.3: §14 folder permission: re-request on click, Reconnect banner, browser copy wins; v1.9.2: §0 branch, PR and approval workflow added; v1.9.1: §4.5 rehydrate transactions loaded from JSON; v1.9.0: §20 Data & Reset added; v1.8.1: §10 re-upload dedup rewritten for the occurrence-suffix fix; v1.8.0: AI Analysis restored with API-key and output hardening; `renderMarkdown()` added; `samples/` added; §1–3, §13, §14, §17 corrected to match the code)*
*Last updated: v1.16.4 — 2026-11-02 (JSON import saves under the storage keys: §4.5 `STORAGE_KEYS` / `storageKey()`; §8 `storageKey()`; §12 adding a persisted field uses the State name; v1.16.3: An import keeps the loaded transactions it doesn't replace: §4.5 an import never drops loaded transactions; §8 `mergeImported()`, `undoTransferDetection()`; §10 memory follows the same re-upload rules; §11 kept transfers are detected again; v1.16.2: Imports read every file before changing anything: §8 `loadFiles()` options and result, `parseCsvFile()` reads only, `importParsedCsv()`, `importProblemText()`, `reloadFromDirHandle()`; §20 Rebuild from your folder reads before it clears, read before clearing; v1.16.1: Clear transaction edits works from memory: §4.2 `_originalCategories`, `_originalType` and what a transaction keeps of its row; §4.5 IndexedDB may not hold the loaded transactions; §10 a stored row holds the CSV's values; §20 Clear transaction edits; v1.16.0: Trends, AI Analysis, Settings and the Welcome rebuilt: §3 file roles; §4.1 `cardDetails`, `sampleData`, AI history `model`; §6 tile tokens and Insights/Settings/Welcome components; §7 rule 7 covers Trends; §8 `loadFiles()` sample option; §9 `shellHero()`, `NO_RANGE_VIEWS`, ☰ → ×, JSON export/import buttons; §12 Settings tabs renamed, the Welcome, range label hidden on Trends and Settings; §13 quick analyses, tab state, history; §20 new fields, Use my own files, Export/Import JSON; §21 quick analyses send `AI_PROMPTS`; v1.15.0: Plan screens rebuilt: §3 file roles; §4.1 `debtPlan` and the Budget / Bucket / Debt / Scenario shapes; §6 `--teal-text` and Plan components; §7 rule 7 covers the Plan charts; §8 plan helpers (`payoffPlan()`, `growthByYear()` …); §9 plan form helpers, `simulatePayoff()` kept unused; §12 Plan titles, Forecast tabs, range label hidden on Plan screens; §13 debt balances in the summary; §20 Clear forecast scenarios / investment mix, Clear debts resets `debtPlan`; v1.14.0: Finances screens rebuilt: §4.1 Bill shape and `recurringConfirmed`; §6 new tokens and Finances components; §7 rule 7 inline SVG charts; §8 new aggregation helpers; §9 drawer, `TX_VIEWS`, SVG/heatmap/format helpers, bill helpers, removed renderers; §11 keywords re-run detection, `transferPairs()`, card payments; §12 page actions and Transactions pills; §20 Clear bills also clears spotted-charge choices; v1.13.0: Clarity redesign — §6 tokens and components; §9 theme, chart colors and app bar helpers; §12 app bar navigation replaces the sidebar and the emoji rule; §17 footer; §20 Data & Reset; v1.12.0: bank-neutral account codes, names, samples and docs; §22 `migrate.js` added; §3, §4, §5, §10, §18, §21 updated; v1.10.5: no section changes: Import Logs race fix; v1.10.4: §8, §13 single `~` is literal; §21 excerpts escape `~`; v1.10.3: §13 refusals; §21 declined runs; v1.10.2: §13 summary states its dates; §21 per-month derivations; v1.10.1: §13 `AI_MAX_TOKENS`, thinking and cut-off answers; v1.10.0: §21 AI Eval added; §13 `callClaude()` raw mode; v1.9.6: §14 folder access lasts until the last tab closes, not one page load; v1.9.5: §7 chart guard; v1.9.4: views-db.js changelog reads CRLF checkouts; v1.9.3: §14 folder permission: re-request on click, Reconnect banner, browser copy wins; v1.9.2: §0 branch, PR and approval workflow added; v1.9.1: §4.5 rehydrate transactions loaded from JSON; v1.9.0: §20 Data & Reset added; v1.8.1: §10 re-upload dedup rewritten for the occurrence-suffix fix; v1.8.0: AI Analysis restored with API-key and output hardening; `renderMarkdown()` added; `samples/` added; §1–3, §13, §14, §17 corrected to match the code)*

---

Expand Down
4 changes: 2 additions & 2 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@

> A zero-install, browser-native finance dashboard. Drop in your bank CSVs, get instant clarity on your money.

**Version:** v1.16.3 &nbsp;·&nbsp; **Stack:** Vanilla JS, HTML, CSS &nbsp;·&nbsp; **Install:** None
**Version:** v1.16.4 &nbsp;·&nbsp; **Stack:** Vanilla JS, HTML, CSS &nbsp;·&nbsp; **Install:** None

---

Expand Down Expand Up @@ -261,4 +261,4 @@ See [CHANGELOG.md](CHANGELOG.md) for the full release history.

---

*FinLens v1.16.3 — Built for one person's finances, designed to be useful for anyone's.*
*FinLens v1.16.4 — Built for one person's finances, designed to be useful for anyone's.*
2 changes: 1 addition & 1 deletion index.html
Original file line number Diff line number Diff line change
Expand Up @@ -1164,7 +1164,7 @@
<div class="folder-banner-wrap" id="folderBanner" hidden></div>
<div class="content" id="content"></div>
</main>
<footer class="appfoot">v1.16.3 · FinLens</footer>
<footer class="appfoot">v1.16.4 · FinLens</footer>

<!-- side drawer: transaction detail, bill and plan forms (ui.js openDrawer) -->
<div class="drawer-scrim" id="drawerScrim" onclick="closeDrawer()" hidden></div>
Expand Down
11 changes: 9 additions & 2 deletions js/core.js
Original file line number Diff line number Diff line change
Expand Up @@ -38,6 +38,13 @@ const lsSet = (k, v) => {
const lsClearAll = () => {
Object.keys(localStorage).filter(k => k.startsWith('finlens_')).forEach(k => localStorage.removeItem(k));
};
// Browser storage (lsSet/lsGet and IndexedDB app_state) keeps two State keys under older
// names; every other key is stored under its State name. Existing data lives under these
// names, so they stay. Code that saves or loads a key by its State name (JSON import,
// Data & reset, migrate.js) goes through storageKey(). finlens-state.json and JSON
// exports use State names.
const STORAGE_KEYS = { recurringConfirmed: 'recurring', categoryRules: 'catRules' };
const storageKey = (stateKey) => STORAGE_KEYS[stateKey] || stateKey;
const debounce = (fn, ms=300) => { let t; return (...a)=>{ clearTimeout(t); t=setTimeout(()=>fn(...a),ms); }; };
const today = () => new Date(new Date().toDateString());
const startOfMonth = (d=new Date()) => new Date(d.getFullYear(),d.getMonth(),1);
Expand Down Expand Up @@ -360,10 +367,10 @@ const State = {
buckets: lsGet('buckets', []),
debts: lsGet('debts', []),
bills: lsGet('bills', []),
recurringConfirmed: lsGet('recurring', {}),
recurringConfirmed: lsGet(storageKey('recurringConfirmed'), {}), // stored as 'recurring'
txOverrides: lsGet('txOverrides', {}), // id -> { description, categories, notes, isBill, isRecurring, isSubscription, type, accountOverride }
manualBalances: lsGet('manualBalances', {}), // id -> amount; id+'_limit' -> limit; id+'_initial' -> initial balance
categoryRules: lsGet('catRules', []),
categoryRules: lsGet(storageKey('categoryRules'), []), // stored as 'catRules'
categories: lsGet('categories', null) || [
'Food & Dining','Groceries','Housing','Transport','Entertainment',
'Health','Shopping','Bills & Utilities','Subscriptions','Personal',
Expand Down
14 changes: 8 additions & 6 deletions js/migrate.js
Original file line number Diff line number Diff line change
Expand Up @@ -29,7 +29,8 @@ const IdMigration = {
[/^Chase Credit Card$/, () => 'Bank Credit Card'],
[/^Chase \((.*)\)$/, (m) => `Bank Credit Card (${m[1]})`],
],
// Persisted State keys that hold account ids, kinds or transaction ids.
// Persisted State keys that hold account ids, kinds or transaction ids. Browser storage
// keeps each under storageKey(key) (core.js).
KEYS: ['txOverrides', 'manualBalances', 'accountLabels', 'accountOrder', 'fileAssignments'],

/* ---------- codes and names ---------- */
Expand Down Expand Up @@ -270,7 +271,7 @@ const IdMigration = {
// transactions with old codes always come with an account that has one.
const txs = accounts.some((a) => this.isOld(a.id)) ? await this._all('transactions') : [];
// Transactions moved to another account (accountOverride), per any copy of the edits
const savedOvs = (appState.find((r) => r.key === 'txOverrides') || {}).value || {};
const savedOvs = (appState.find((r) => r.key === storageKey('txOverrides')) || {}).value || {};
const moved = new Set([
...ovs.filter((o) => o.accountOverride).map((o) => o.txId),
...[savedOvs, State.txOverrides || {}].flatMap((m) => Object.keys(m).filter((k) => m[k] && m[k].accountOverride)),
Expand Down Expand Up @@ -311,8 +312,9 @@ const IdMigration = {
puts.import_log.push({ ...l, accountId: this.accountId(l.accountId), schemaId: this.kind(l.schemaId) });
}
for (const rec of appState) {
if (!this.KEYS.includes(rec.key)) continue;
const out = this._key(rec.key, rec.value, idMap);
const key = this.KEYS.find((k) => storageKey(k) === rec.key);
if (!key) continue;
const out = this._key(key, rec.value, idMap);
if (out) puts.app_state.push({ key: rec.key, value: out });
}

Expand All @@ -332,9 +334,9 @@ const IdMigration = {
}
// localStorage keeps its own copy of these keys (lsGet reads it at startup).
for (const key of this.KEYS) {
const v = lsGet(key, null);
const v = lsGet(storageKey(key), null);
const out = this._key(key, v, idMap);
if (out) lsSet(key, out);
if (out) lsSet(storageKey(key), out);
}
return result;
},
Expand Down
Loading