perf(core): allocate the label atlas only for multi-label annotations

[tsenoner]

Third and last of the #456/#457 series. Stacked on #459, which is stacked on #458. Merge order: #458 → #459 → this.

What this is

The pie-chart colour atlas is 32 of the 76 bytes per point resident on the GPU — 42% — and for a single-label annotation every one of them is dead weight. Nothing samples it: the shader's pie branch needs v_labelCount > 1.5, and fillLabelColorTexels returns immediately for a one-colour point.

At Swiss-Prot scale (573,649 proteins) that is 17.5 MiB of CPU and 17.5 MiB of GPU held for a feature the view is not using — plus a full-surface upload on every restage, i.e. on every legend recolour.

This is small because #458 did the hard part: it made "no atlas" a first-class, tested state — nullable backing array, staging that skips texels, a 1×1 placeholder keeping the sampler complete, and a shader gate that makes the pie branch unreachable. That was built for the device-limit failure path. This change adds a second, deliberate reason to enter it, so a revert cannot regress to corruption.

How the gate stays honest

Pull-based, computed inside createStyleGetters over the same data binding the colour getters close over.

That makes staleness structurally impossible in the direction that matters. getColors returns [...new Set(values)] for the selected annotation, so getColors(p).length >= 2 implies the storage is multi-valued, implies the gate is true. It can only ever over-report — allocate when it needn't — never under-report and drop a segment.

And it covers, in one place, every transition a push-based scheme would have had to enumerate individually: annotation switch, projection switch, dataset swap, the EAT overlay, isolation, legend hide/show. All of them go through a getter rebuild, and data is in the cache key.

Two details worth flagging for review:

• The predicate is memoized on a WeakMap keyed by the storage object. The dense form is data.some(v => v.length > 1) — O(N), 573K at Swiss-Prot scale — and the getters rebuild on a legend hide, a selection, a projection switch. Sound because no producer mutates an AnnotationData in place; every one returns fresh storage.
• The renderer tracks the transition itself rather than trusting a caller to invalidate. A change in multi-label-ness need not move the style signature (it samples four points' colours) but it changes every point's staged slice count. This is load-bearing, not belt-and-braces: _refreshSelectedAnnotationValues nulls the style-getter cache without calling invalidateStyleCache, so a caller-driven scheme would have a real hole.

One asymmetry, on purpose

isMultilabel is required on WebGLStyleGetters so TypeScript consumers cannot omit it, but the renderer calls it optionally and defaults to true. A consumer that omits the getter over-allocates, which costs memory; one that under-reports silently drops pie segments — a wrong picture presented as data. Only the first failure direction is acceptable.

The storage-vs-colour distinction

The gate answers from stored values, never from rendered colours. A colour-shaped test would read false the moment hidden values collapse every point to one colour — and would then release the atlas exactly one un-hide before it is needed again. point-visibility carries this as a normative requirement (added by #458); this change implements it, and there is a test that pins it.

Verification

pnpm test 2,293 green · pnpm test:e2e 124 green · pnpm precommit + pnpm format:check green.

Four new renderer tests: a single-label annotation allocates nothing beyond the placeholder and never issues a texSubImage2D; single → multi → single allocates exactly once and releases; the transition re-stages even though the signature cannot see it; staying multi-label refreshes in place rather than reallocating. Plus memo tests covering per-object (not per-content) caching and the storage-shaped property.

The assertions filter atlas allocations from framebuffer ones — the gamma pipeline allocates its own canvas-sized texture, which caught me out first time round.

No user-visible change on a multi-label annotation

Pixels are identical; only the unused case stops paying.

Please merge or rebase, not squash (repo-wide allow_squash_merge: false).

🤖 Generated with Claude Code

https://claude.ai/code/session_01USFuj7M2Ls1hpJXKaX2uJp