Skip to content

Commit 1f9f1c2

Browse files
Prithvi-Webclaude
andcommitted
CHANGELOG for v5.0.0, and the version bump
The repo has never had a CHANGELOG. This one starts at 5.0.0 and covers everything since v3.2.1, because v3.2.1 is what the public actually has — the whole 4.x line was developed in this repository and never published, so 188 commits of work arrive at once. Written for a user rather than a committer: what changed for them, grouped Added / Changed / Fixed / Security / Removed, in the app's own voice. Every line traces to a real commit; nothing is invented. The seven number fixes from this session are in Fixed and Security beside the rest. The Known limitations section is the part that matters most on a Releases page, and each item is a decision rather than a defect: the macOS build is signed but not notarized, so the only instruction that works is open it once then System Settings › Privacy & Security › Open Anyway — with the about-an-hour clock on that button, which is what stops people concluding the download is broken. Apple removed right-click → Open in Sequoia and it is not mentioned. The mac build is Apple Silicon only, the Windows installer is unsigned, there is no Linux desktop download (the suite runs on Linux in CI; only packaging is unpublished), sizes step in 1024s under KB/MB/GB labels so they read about 7% under the Finder, and a fast rescan's claimed-versus-held figure is a floor. Two tests pin it: the newest heading equals package.json's version, and the 5.0.0 entry states each limitation. Five mutants — one escaped, and it was the interesting one: asserting /Linux/ stayed green with the Linux limitation deleted, because the Fixed section mentions Linux for an unrelated reason. Tightened to the sentence itself, then it bit. Two corrections to my own work while bumping. SECURITY.md still said "the latest 4.x release only" — its own test caught that. And replacing every `"version": "4.2.0"` in package-lock.json silently bumped SIX third-party dependencies (js-yaml, crypto-js, smart-buffer, lodash.defaults and two more) to a version that does not exist; the lock now moves only the two nodes that describe TreeMap itself, and `npm ls` confirms it resolves. Gate: 2,412 tests, 0 fail, 3 skipped. typecheck clean. build-ui --check matches at 112 parts. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
1 parent 5d4071f commit 1f9f1c2

5 files changed

Lines changed: 351 additions & 4 deletions

File tree

‎CHANGELOG.md‎

Lines changed: 313 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,313 @@
1+
# Changelog
2+
3+
All notable changes to TreeMap are recorded here. The format follows
4+
[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and TreeMap uses
5+
[semantic versioning](https://semver.org/spec/v2.0.0.html).
6+
7+
## [5.0.0] — 2026-09-02
8+
9+
The first public release since 3.2.1. Everything below landed in the seven
10+
months of work between them — the whole 4.x line was developed in the open
11+
repository but never published, so this is the release where all of it
12+
arrives at once.
13+
14+
If you are upgrading from 3.2.1, the short version: TreeMap now tells you
15+
what is *safe* to delete rather than only what is *big*, it can account for
16+
every gigabyte on the volume rather than only the ones it walked, and the
17+
numbers it prints have been audited against the code that produces them.
18+
19+
### Added
20+
21+
**Deciding what to delete**
22+
23+
- **Reclaim Score.** Every file and folder gets a score out of 100 for how
24+
safe *and* how worthwhile it is to remove, built from six signals: size
25+
against this scan's own spread, how long since it was last opened, whether
26+
a rule says it rebuilds itself, whether an identical copy is on this disk,
27+
whether it was downloaded, and whether a copy exists elsewhere.
28+
- A badge beside each score opens a breakdown that says what every signal
29+
contributed and, in amber, what could not be measured. A signal TreeMap
30+
cannot read is named and left out — never counted as zero.
31+
- A treemap colour mode and a sort that answer "what is safest to delete"
32+
instead of "what is biggest".
33+
- The six weights are yours to change in Settings, with a reset. Setting one
34+
to zero removes that signal rather than scoring it worthless.
35+
- A radar chart shows all six signals as one shape, so two files compare by
36+
silhouette. A signal that could not be measured keeps its spoke and the
37+
outline breaks around it.
38+
- **Last-opened dates**, with the source that answered them named — and an
39+
honest "not available here" where the operating system does not record
40+
them, never a stand-in date.
41+
- **"Does a copy of this exist elsewhere?"** — a recoverability verdict from
42+
Git, backups and cloud sync, with its reasons. It is never promoted to a
43+
definite yes by inference: a folder that is merely absent from a backup
44+
exclusion list is *unknown*, not *backed up*.
45+
46+
**Searching**
47+
48+
- A search grammar: `size>100mb ext:mp4`, `-in:node_modules`,
49+
`modified>90d`, `used>1y`, `git:pushed`, `score>70`.
50+
- A live query box with autocomplete, and saved views you can pin as chips.
51+
- **Ask in plain words.** The ✨ button turns "big videos I haven't opened in
52+
a year" into a real query, and always shows you the translation in an
53+
editable field before it runs. It works entirely offline, and words it
54+
ignored are listed rather than silently dropped.
55+
- A saved view can become a Clean Up rule, and a Clean Up rule can become an
56+
Autopilot policy, pre-filled.
57+
58+
**The cleanup cart**
59+
60+
- An optional cleanup target in Settings ("free 50 GB") gives the cart a
61+
meter filling toward it. A meter and nothing else: no streaks, no badges,
62+
no confetti.
63+
- Add to cart from every view that lists something reclaimable — Empty
64+
Folders, Clean Up rule matches, per-game shader caches, and "Stage N
65+
matches" from a treemap query.
66+
- **Preview after.** The map re-lays itself with the staged items taken out,
67+
and the freed space stays on the map as a hatched block, so every rectangle
68+
still means the same number of bytes.
69+
- Committing the cart runs through the Time Capsule as one undoable run — a
70+
dry run first, always, then one summary with a one-click undo that puts
71+
everything back at its original paths, even after the Trash has been
72+
emptied. Undo restores the original dates as well as the bytes.
73+
74+
**New views**
75+
76+
- **Missing GB.** One accounting statement for the volume, printed as a
77+
receipt that either adds up or names the gap. It shows what a files-only
78+
tool cannot: other volumes sharing the same storage pool (about 12 GB on a
79+
Mac), space held by programs still gripping a deleted file, and what the
80+
scan was refused. A line nobody can measure prints "unknown" with its
81+
reason — never 0.
82+
- **Disk City.** The treemap's own tiling seen from a corner, encoding three
83+
things at once: footprint is bytes, height is staleness (or file count, or
84+
depth), colour is Reclaim score (or file kind, or age).
85+
- Two more renderers on the same toolbar: **circle packing** and a **Voronoi
86+
treemap**, sharing the root, breadcrumbs, depth, colour mode and exports.
87+
- A **lasso** (drag, or freehand with Alt) that stages what you draw around,
88+
with a live count inside the loop, and a **magnifier** (hold Z) that
89+
redraws the map at 4× so two-pixel tiles become readable names.
90+
- **History**, holding **Calendar** (a year of writes, one cell per day —
91+
click or drag a range to filter the map), **Journal** (a plain-English
92+
record of significant changes, naming an app only when the path proves it
93+
and saying "an unidentified process" otherwise), and **Compare** with a
94+
photo-style split slider that wipes between two snapshots.
95+
- **Media libraries** in the Libraries tab: Photos, Final Cut, iMovie,
96+
Lightroom and Capture One, split into originals / derivatives / database,
97+
with a cart button on derivatives only and the cost of regenerating each
98+
one stated.
99+
- A **duplicate compare viewer** on every exact group and near-duplicate
100+
cluster — copies side by side with thumbnails, dimensions, the EXIF capture
101+
date or its honest absence, the differing blocks painted over
102+
near-duplicates, and the recommended keeper with the rule that picked it.
103+
- A **drive dock** under the map listing attached external drives and their
104+
free space. Drag the cart onto one to offload. A drive whose statistics
105+
cannot be read is still listed, with the reason.
106+
107+
**Playing back and exporting**
108+
109+
- Transport controls on the time slider — play/pause, ½× to 4×, loop — that
110+
play a folder's history as a film.
111+
- Export that history as an animated **GIF** (written by hand, no dependency,
112+
encoded off the main thread) or a **WebM** where the runtime can record a
113+
canvas. The menu says which you are getting.
114+
115+
**Getting around**
116+
117+
- A **command palette** on ⌘K covering every view, every action, your saved
118+
views, recent scan roots, eleven Settings sections, and "search files for…"
119+
for anything else.
120+
- A **guided first run** that walks you through picking a folder, watching
121+
the scan land, reading the map, and up to three real quick wins from your
122+
own disk. Skippable at every step.
123+
- **Folder notes.** Right-click any folder to pin words to it. A note pauses
124+
suggestions and automation for that whole subtree by default, and Autopilot
125+
reports the skip rather than quietly matching less.
126+
- **Human-scale sizes.** Beside a large folder the tooltip can add "≈ 3,100
127+
photos or 42 videos like the ones here" — always averaged from that
128+
folder's own media, never from a made-up constant. A folder with nothing
129+
comparable says nothing.
130+
- **Budget gauges** on the Dashboard: "at this pace, over in ~23 days (Sep
131+
22)", or the forecast's own refusal when the history is too short, too
132+
erratic or shrinking.
133+
134+
**The desktop app**
135+
136+
- TreeMap remembers its window — size, position, display, maximised and
137+
full-screen — and comes back where you left it.
138+
- A real application menu: Settings ⌘, Scan Folder ⌘O, Rescan ⌘R, a Help
139+
menu, and an About panel with the version.
140+
- Dock progress during a scan, and a bounce plus a notification when a long
141+
scan finishes while the window is not focused.
142+
- Dropping several folders queues them instead of losing all but one.
143+
144+
**For agents and scripts**
145+
146+
- Two new MCP tools, `reclaim_ranked` and `missing_gigabytes`, bringing the
147+
total to ten.
148+
- Eighteen new API routes, all described in the published OpenAPI document.
149+
150+
### Changed
151+
152+
- The **Games** tab became **Libraries** and now holds media libraries
153+
alongside game libraries.
154+
- Calendar, Journal and Compare became one **History** tab with an internal
155+
segment that remembers where you were. The sidebar went from seventeen tabs
156+
to fifteen.
157+
- **⌘K now opens the command palette.** `/` still summons global search.
158+
- **The Duplicates tab opens instantly.** It used to freeze for about 400 ms
159+
on every visit; it is now about 15 ms.
160+
- **The cart list is paged** at 200 with "N more staged, not listed here" and
161+
a Show all button. Every total still counts the whole cart.
162+
- **The app is faster to use.** The sidebar, all thirteen sheets and the
163+
tooltip keep their frost but lose the displacement lens; the full-screen
164+
dim behind a dialog no longer blurs; the hover beam on cards is gone.
165+
- **Hovering the treemap repaints only the two tiles that changed**, not the
166+
whole map.
167+
- **Near-duplicate clusters wrap** instead of scrolling sideways, and their
168+
thumbnails are prepared when the hunt finishes — the first look at a
169+
cluster went from about 46 ms a picture to 5 ms.
170+
- **TreeMap no longer burns CPU when you are not using it.** With the window
171+
closed it had been sitting at 20–60% eighteen minutes after a scan, because
172+
it was watching its own data folder and re-counting the whole index every
173+
400 ms.
174+
- **One dialect and one date format** throughout.
175+
- **The welcome screen explains what a treemap is** instead of comparing
176+
itself to another product.
177+
- **Every dialog takes, traps and returns focus**, the page underneath is
178+
inert, and the thirteen segmented controls are real tab lists you can drive
179+
with arrow keys.
180+
- The macOS first-launch instructions were rewritten (see Known limitations).
181+
182+
### Fixed
183+
184+
- **A folder macOS refused to open was reported as an empty folder.**
185+
Scanning Desktop or Documents without Full Disk Access showed "Scanned 0
186+
files — 0 B", toasted "Scan complete", and the first-run card congratulated
187+
you on a clean folder. TreeMap now counts what it was refused, names those
188+
folders, and offers the Privacy settings button.
189+
- **Sparse files claimed space the disk does not hold.** A virtual machine
190+
disk such as Docker.raw reserves its full size and fills only part of it —
191+
64 GB claimed, perhaps 12 GB on the disk — and TreeMap counted the claim,
192+
then blamed the difference on copy-on-write clones in the Missing GB
193+
receipt. There is a line for it now, and it is the difference *both* ways:
194+
small files hold slightly more than they claim, because a disk hands out
195+
room in fixed-size pieces.
196+
- **"Used" meant two different things.** The Dashboard tile excluded the
197+
blocks the system reserves for itself while the Missing GB receipt did not,
198+
so on Linux the two disagreed by about 5% of the disk. Six places now read
199+
one published figure, and the receipt shows the reserve as its own band.
200+
- **Offload said "need 0.0 GB, only 0.0 GB free"** about a 30 MB transfer.
201+
- **The Trends forecast line and the "disk full ~date" printed beside it were
202+
two different predictions.** They are one claim now.
203+
- **Duplicates promised bytes that trashing would not free.** On a Mac a
204+
Finder-duplicated file shares its storage, so removing the copy frees
205+
nothing. There is a line saying so, and after a duplicates trash TreeMap
206+
reports the *measured* change rather than the promise.
207+
- **Two hard-link counts wore near-identical labels** — one counted extra
208+
names, the other counted files — so two screens disagreed. Relabelled, not
209+
recounted.
210+
- **The time scrubber jumped under your finger.** Its label grew from 23 px
211+
to 174 px on the first pixel of a drag, shrinking the track by a quarter.
212+
- **Sizes never read "1024.0 KB"** any more.
213+
- **A sparse file is no longer mistaken for an online-only cloud file** — a
214+
virtual machine image or database file is not offered as safe to remove.
215+
- **A folder whose name ended in a slash or a space could not be opened**
216+
through any part of the app, while the treemap drew it perfectly.
217+
- **Ordinary filenames broke the search box.** `Screenshot (1).png` was read
218+
as a three-way query, and `-hidden.txt` highlighted every file except the
219+
one you typed.
220+
- **The Live toggle could read "Live" while nothing was being watched.**
221+
- **Instant open showed the whole indexed folder's file counts against a
222+
subfolder's tree** — a byte total describing one tree and an item count
223+
describing another.
224+
- **Empty Folders printed its 1,000-item cap as the real number**, and ticked
225+
only what it had.
226+
- **A read that failed was being treated as a fact.** A momentary error
227+
reading a file made the live index believe it had been deleted and shrink.
228+
The same shape was found and fixed in a dozen more places, including one
229+
that could have removed every protected copy the Time Capsule was holding.
230+
- **A check that could not run must not answer "nothing is open".** The guard
231+
that looks for files in use returned a clean bill of health when it had not
232+
actually looked.
233+
- **Tidying up after an undo could undo the undo** — a failed housekeeping
234+
step deleted the file that had just been restored.
235+
- **A cart with more than 500 items could not be committed at all.**
236+
- **The circle-pack layout could block the app for a second**, and the
237+
Voronoi layout for nearly three, on an awkward folder. Both are bounded
238+
now, refine across frames, and say what they could not draw.
239+
- **Drive Health named no drive on any machine**, and the scan counters
240+
beside it were invented rather than fetched.
241+
- **A media library TreeMap could not read into was reported as "no media
242+
libraries"** — on exactly the Mac the feature was built for.
243+
- A confirmation opened from Settings painted *behind* Settings, and Escape
244+
closed the sheet underneath instead of the one on top.
245+
- Dozens of smaller corrections to counts, captions and empty states, each
246+
one a number or a sentence that did not match what the code did.
247+
248+
### Security
249+
250+
- **Fleet pairing could be brute-forced.** The six-digit code had no rate
251+
limit on the peer server; an audit made 33,966 guesses in three seconds. It
252+
is now five wrong guesses per machine and fifty in total, checked before
253+
the code is even looked up, and the offer withdraws itself and tells you
254+
which machine was trying.
255+
- **A blocked system folder was reachable by another spelling.** On macOS
256+
`/System/Volumes/Data/private/var/db` — the local account database — was
257+
scannable while `/private/var/db` was blocked, because a firmlink is not a
258+
symlink and both halves of the guard compared text. The block list judges
259+
where a path really lives now.
260+
- **A folder symlink could walk the "inside the scanned folder" guard out to
261+
any file on the disk** — for trash, open, terminal and preview alike. The
262+
gate judges location rather than spelling, while a symlink itself stays
263+
removable.
264+
- **The desktop app's local API was open to any program or web page on the
265+
machine that found the port.** It starts with a per-launch token now, and
266+
the app's own window is handed a session of its own. A Host-header check
267+
and a Content-Security-Policy were added, and binding to anything other
268+
than the loopback address refuses to start without a token.
269+
- **A note that pauses automation now fails closed** — a corrupt notes file
270+
pauses Autopilot with a message instead of silently switching every pause
271+
off.
272+
- A query that does not parse, or that has no conditions, cannot be saved as
273+
an unattended policy, and a query policy never removes a folder.
274+
- The cart button was removed from an application's own bundle and its user
275+
data, which had quietly widened "clear caches safely" into a one-click
276+
staging of the app itself.
277+
278+
### Removed
279+
280+
- **The optional Ollama local-model integration**, end to end. The built-in
281+
phrase table is the whole plain-words feature, and a test proves that path
282+
contains no network code at all.
283+
- The spinning border beam on card hover, the displacement lens on every
284+
glass surface, and the blur behind an open dialog — all removed for speed.
285+
286+
### Known limitations
287+
288+
These are deliberate, and they are the things a first-time downloader meets.
289+
290+
- **The macOS build is not notarized.** TreeMap is signed, but not by an
291+
Apple-paid certificate — notarizing requires a paid Apple Developer Program
292+
membership that this free, open-source project does not have. macOS will
293+
block it the first time. Open it once, then go to **System Settings ›
294+
Privacy & Security** and press **Open Anyway**. That button only appears
295+
for about an hour after macOS blocked the app; if it is not there,
296+
double-click TreeMap again and go straight back to System Settings.
297+
- **The macOS build is Apple Silicon only.** There is no Intel build.
298+
- **The Windows installer is unsigned**, so SmartScreen shows a blue box
299+
once — More info, then Run anyway.
300+
- **There is no Linux desktop download.** The test suite runs on Linux in
301+
CI and web mode works there; only the packaged build is unpublished. You
302+
can build an AppImage locally with `npm run dist:linux`.
303+
- **Sizes are measured in 1024s and labelled KB/MB/GB.** That is about 7%
304+
smaller than the Finder, which counts in 1000s. Every number in TreeMap is
305+
measured the same way, so they always agree with each other.
306+
- **A fast rescan under-counts the claimed-versus-held line.** Folders that
307+
have not changed are read from the previous scan and not measured again, so
308+
that figure is a floor rather than a total. The receipt says so.
309+
310+
## [3.2.1] — 2026-08-26
311+
312+
The last release before this one. See the repository history for its
313+
contents; releases before 5.0.0 are not itemised here.

‎SECURITY.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22

33
## Supported versions
44

5-
TreeMap supports **the latest 4.x release only**. A fix ships as a new release; older releases receive no fixes, so if you are on anything else, update first.
5+
TreeMap supports **the latest 5.x release only**. A fix ships as a new release; older releases receive no fixes, so if you are on anything else, update first.
66

77
To find your version: on macOS, **TreeMap → About TreeMap**. Anywhere TreeMap is running — desktop or web mode — open <http://127.0.0.1:4280/api/capabilities> and read `version`.
88

‎package-lock.json‎

Lines changed: 2 additions & 2 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎package.json‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
{
22
"name": "treemap",
3-
"version": "4.2.0",
3+
"version": "5.0.0",
44
"description": "See exactly what's eating your disk \u2014 a desktop app for macOS and Windows, web mode on Linux, and an MCP server so AI agents can use it too",
55
"author": {
66
"name": "Prithvi Vinay",

0 commit comments

Comments
 (0)