Module treemap 

The treemap pane — a spike, and its escape hatch is Maps not being Maps::Can.

Reclaimable space is spatial, and a treemap answers “where are the bytes” in a way a sorted list structurally cannot: ~/repos/archived being two thirds of the picture is one glance, where the list makes it one number to compare against forty others. kondo, npkill and dua all render rows and nothing else, so this is also the one thing on the table that would make pristine visibly unlike them rather than better along an axis they already occupy.

It degrades to nothing, three times over

1. The terminal has to be known to speak the protocol, from the environment and nothing else — see super::chrome::Decor, whose table this reads a column of. There is a documented “do you speak this” query and it is a round trip with no bound on the silence, which is exactly the blocking probe the chrome refuses to make.
2. The terminal has to report a pixel size. TIOCGWINSZ carries one and costs no round trip, so a terminal that fills it in with zeros — which is most of them, and every terminal seen through tmux — gets no map rather than a guess at its own cell size.
3. The pane has to fit. Below MIN_WIDTH columns the map would cost the tree more than it is worth, and the tree alone is the complete interface.

The first two are one answer, Maps, and that is #656’s whole lesson. They were two answers taken at two different times — the allowlist before the layout, the pixel size at the draw — so a terminal that passed one and failed the other cost the tree columns that nothing was ever drawn in. Both are now folded into the predicate the layout reads, and it is re-asked every frame, because a window can lose its pixel fields while a run is going.

Nothing above is a flag the reader has to find. What is a key is m, which turns the pane off on a terminal that could have one — and on a terminal that could not, says which of the two reasons it is, because an enhancement you cannot dismiss is not an enhancement and a rectangle that declines without a word is worse than no rectangle.

What is expensive, and what is done about it

A pane of 44×40 cells on a retina terminal is about 900 kB of RGB, which is 1.2 MB of base64 down the pty. At the 100 ms frame rate that would be 12 MB/s to say nothing new, so the image is emitted only when the picture actually changes — and the two kinds of change are treated differently, because they have different deadlines:

• Steering — the cursor moving, a drill-in, a mark, a filter, the pane resizing — is the reader’s own hand and is redrawn on the next frame, always.
• Arriving — a price landing, a claim appearing, a row being deleted — happens hundreds of times a second during a breakdown and is redrawn at most every [SETTLE]. A map that repaints 10 times a second while 16,013 prices land is a map nobody can read anyway.

“Has it changed” is answered from what the map is made of, never from the map. The spike asked it by squarifying the whole thing and comparing, which cost 467 µs on a frame where nothing had happened — 200× what the animation beside it spends to answer the same question, paid forever, on a pane showing the picture it showed last frame. Reading the inputs instead costs 50 ns: a View::map_stamp for the mapped subtree, and a hash of the handful of values the reader controls.

That stamp is lens-aware, and it has to be. A run opens on a view that hides the gitignored tier, so tier-two claims stream in under the very directory the map is of while changing not one rectangle; answering each of those with the tree’s own stamp would be a megabyte down the pty to redraw the picture already on it.

Taking the picture down is not a redraw and is never throttled — see tiles::mappable.

See the note in brain — areas/pristine/design/2026-08-11-treemap-spike.md — for what this measured out at, and for the verdict.

Modules

kitty

The kitty graphics protocol, in the two sequences this needs.

paint

Turning a Map into pixels.

tiles

Where each rectangle goes, and what it is allowed to claim about itself.

Structs

Pane

The pane the map goes in, in cells and in pixels.

Screen

The image on the terminal, and the promise to take it back.

Enums

Drawn

What a call to Screen::show left on the terminal.

Maps

Whether a map can appear in this terminal right now, and when it cannot, why.

Constants

MIN_HEIGHT

The shortest pane worth drawing rectangles in.

MIN_WIDTH

The narrowest terminal that gets a map.