Make the storage map mean something: kind colors, reclaimable hatch, free-space projection (disktree-inspired)

[sarthakagrawal927]

Released acceptance - 5 October 2026

Released in 0.1.4 build113, tag v0.1.4-113, exact source 94fe203bd663f9d058e72ad3f9ab2c5af9130483. Implementation PR55, label refinement PR57, protected signed release, public download.

Semantic kind colors and legend, candidate hatch, current/free upper-bound projection, bytes/file-count weights, direct staging, filter dimming and bounded local Git review are shipped. Owner-selected direct white labels replace opaque label plates in build113; nested/filtered/staged contrast and compact native shells are verified.

Validation: full CI256 Swift tests, optimized build, Python packaging checks and shared candidate pass. Protected exact-tag candidate, signing/notarization, public feed/download bytes and installed Sparkle update are verified separately in the release receipt. Native evidence is retained under .fleet-local/storage-accounting/, with three-width full-shell fixtures explicitly synthetic and live installed/isolated captures explicitly identified. Full VoiceOver, enlarged text, exhaustive OS/hardware coverage and live App Health counts are not claimed.

Required acceptance is complete. Earlier prepared-source and control-pipe limitations below are historical snapshots, superseded by this release evidence where stated.

---

Why

Our treemap colors tiles by FNV name-hash — visually pleasant but information-free. tobi/disktree (released Sept 24, ~300 stars) shows what a map can carry: color = kind of data, a diagonal hatch = reclaimable space, free disk space visible the whole time, direct tile marking, and measure toggles. We already own the classification logic (DeveloperInsights, cleanupCategory) and the mark-absorption rule (App.swift staging) — the map just doesn't use them.

What

Make the Explore map mean something:

1. Semantic tile color — classify directories into kinds (code, caches, toolchains, package stores, git, media, documents, agent/AI scratch, generic) from names and shape heuristics (target beside Cargo.toml, node_modules beside package.json, etc.). Reuse existing classification where it exists; one muted color per kind, lighter with depth.
2. Reclaimable hatch — diagonal hatch overlay on tiles matching reclaimable categories (caches, build output, package stores), independent of color. Two data dimensions on one map.
3. Free-space projection — persistent header/panel element: disk free now → free after staged cleanup items. Data already available (volumeAvailableCapacity).
4. File-count measure — toggle the map weight between bytes and descendant file count (t-key style).
5. Direct marking on tiles — mark/unmark a tile (keyboard + gesture), staged tiles render in the danger color and propagate to contents per the existing absorption rule.
6. Name filter highlight — when the existing filter field has text, non-matching tiles dim on the map rather than only filtering the list.
7. Git evidence in Inspector — for a git checkout, surface uncommitted-changes / unpushed-commits / stash presence as cleanup-review evidence (local git status only, no network).

Deferred (not this issue): continuous scroll-zoom into directories, memoized widen-scan from breadcrumbs, removal-rules audit — candidates for follow-up issues.

Design

• DiskCore/Classification.swift: name + shape → StorageKind enum; single source consumed by map color, legend, and "worth a look" ordering.
• DiskMapView: swap Tints.forNode hash color for kind color; add hatch path overlay; staged tiles get coral/danger fill.
• ExplorerModel: measure: .bytes | .fileCount; staged already exists — add tile-mark path that calls existing stage()/unstage().
• Inspector: new evidence row for git checkouts.
• Legend row under the map explaining kind colors + hatch meaning.

Specs

Requirement: Semantic map color

Treemap tiles SHALL be colored by classified storage kind, with a visible legend.

Scenario: Kind-colored map

• WHEN a scan contains node_modules and a .git directory
• THEN their tiles use the package-store and git kind colors, distinguishable in the legend

Requirement: Reclaimable hatch

Tiles whose contents are reclaimable categories SHALL draw a diagonal hatch independent of tile color.

Requirement: Free-space projection

Explore SHALL show current volume free space and projected free space after staged items.

Scenario: Staged items change projection

• WHEN items are staged or unstaged
• THEN the projected-free figure updates without a rescan

Requirement: File-count measure

The map SHALL support weighting by file count in addition to bytes.

Requirement: Direct tile marking

Tiles SHALL be markable directly (propagating to descendants per existing absorption rules) and rendered in the staged/danger color.

Requirement: Git evidence

Inspector SHALL show change/stash/unpushed indicators for recognized git checkouts as review evidence, never as automatic cleanup criteria.

Tasks

• 1. Classification.swift + kind palette + legend
• 2. Semantic color + hatch rendering in DiskMapView
• 3. Free now → free after staged header
• 4. File-count measure toggle
• 5. Direct tile marking + staged tile visual state
• 6. Filter highlight dimming
• 7. Git-checkout evidence in Inspector
• 8. Tests, native screenshots in artifacts/design/, DESIGN.md/PROJECT_STATUS.md updates

Prepared source and remaining acceptance — 2 October 2026

Prepared isolated source (uncommitted/unpublished) at base 44dbb36a596d102499ca8aafadc507340c10a270: Kind classification, candidate hatching, bytes/file count, free-space upper bound, staged non-color cues, name highlighting, bounded Git inspector evidence.

Final combined feature/protection SwiftPM checks passed with no failures. Native SwiftUI/AppKit component fixtures at 880/1200/1440 were independently inspected; scoped P1 visual findings are resolved. Full native acceptance remains partial: the native control pipe failed, whole-shell captures were unusable GPU artifacts, and real-window interaction/VoiceOver/hardware behavior was not verified. Combined tests/native-acceptance checklist items remain open. No real home inventory, provider call, cleanup/Trash, commit, push or release was performed.

DESIGN.md and PROJECT_STATUS.md have prepared owner-local updates; both are ignored and have not been silently force-added. Source implementation checkmarks below mean prepared local code, not shipped or full native acceptance.

[sarthakagrawal927]

Owner selected A — Map & inspector on 2026-10-02 for the map, Projects, and Duplicates work (#33–35), after inspecting three native SwiftUI direction previews. Preserve the black/mint shell and spatial footprint-first workflow, with contextual ownership/reclaim evidence and deliberate review before cleanup. Projects and Duplicates should extend this system rather than replace the app identity.

The compared previews use original in-memory example data; they are direction evidence, not implemented scan/staging/cleanup behavior. The selected preview is /tmp/fleet-visual-20261002/storagedaddy/directions/direction-1.png. Implementation and correctness qualification remain pending the all-project audit barrier.

[sarthakagrawal927]

Prepared isolated source (uncommitted/unpublished) at base 44dbb36a596d102499ca8aafadc507340c10a270: Kind classification, candidate hatching, bytes/file count, free-space upper bound, staged non-color cues, name highlighting, bounded Git inspector evidence.

Final combined feature/protection SwiftPM checks passed with no failures. Native SwiftUI/AppKit component fixtures at 880/1200/1440 were independently inspected; scoped P1 visual findings are resolved. Full native acceptance remains partial: the native control pipe failed, whole-shell captures were unusable GPU artifacts, and real-window interaction/VoiceOver/hardware behavior was not verified. Combined tests/native-acceptance checklist items remain open. No real home inventory, provider call, cleanup/Trash, commit, push or release was performed.

DESIGN.md and PROJECT_STATUS.md have prepared owner-local updates; both are ignored and have not been silently force-added. Source implementation checkmarks below mean prepared local code, not shipped or full native acceptance.