Label declutter: screen-space overlap culling, on by default

[aaltshuler]

Problem

Density had no spatial control: the label selector ranks and viewport-culls, but never checks where labels land on screen — so in dense clusters the top-ranked winners stack into an unreadable pile (they are all in the same blob by construction).

Fix

Greedy screen-space occupancy in rank order, the standard map-renderer declutter pass, inside selectLabelCandidates:

• Each candidate gets an estimated label box (fixed per-character width — decluttering, not typesetting); a box intersecting an already-placed label loses its slot to the next-ranked candidate (rejects don't consume capacity).
• showFor ids always render and claim their space first.
• New LabelConfig fields: overlap: 'hide' (default) | 'allow', overlapPadding (px, default 2). A cell grid prunes intersection tests; the pass runs only on the existing throttled re-rank triggers — never per frame.
• Overlap-blind when the viewport cannot project screen coordinates.

Default is on — same philosophy as the settle camera and fit clamp: the out-of-box render should be legible. FakeEngine projects identity coordinates, so decluttering engages in headless tests too; suites that pin label sets over tightly-packed fixtures opt out with overlap: 'allow' (this repo's scheduling suites and the react security fixture now do, each with a comment saying why).

Evidence

New Labels/Declutter story (in this PR): the same 1,500-node fixture with overlap: 'allow' shows text smears in every cluster core; with the default, every rendered label is legible and spaced.

Tests

Seven new selector tests: stacked-winner culling, slot promotion, showFor exemption + space claiming, 'allow' restores stacking, unprojectable-viewport fallback, padding widening, determinism. Full check green: 1,807 tests.

🤖 Generated with Claude Code

https://claude.ai/code/session_018SeFxK217ZrHSERqK6kjcb

Greptile Summary

The PR adds default-on, greedy screen-space overlap culling to ranked node-label selection, with opt-out and padding controls.

• Forced labels render first and reserve their projected screen area.
• Ranked labels that intersect reserved boxes yield their capacity to lower-ranked candidates.
• Tests and Storybook coverage demonstrate culling, fallback, padding, determinism, and legacy overlap behavior.

Confidence Score: 4/5

The PR needs a finite-value guard for overlap padding before merging because an accepted configuration can hang label recomputation on the main thread.

The new occupancy pass derives incrementing grid-loop bounds directly from overlapPadding; positive infinity survives the current clamp and creates a loop whose negative-infinity counter can never advance.

Files Needing Attention: packages/core/src/labels.ts

Important Files Changed

Filename	Overview
packages/core/src/labels.ts	Implements the occupancy-grid declutter pass, but non-finite overlap padding can make its grid traversal non-terminating.
packages/core/src/types.ts	Adds the public overlap policy and padding configuration contracts.
packages/core/test/labels.test.ts	Covers normal declutter behavior comprehensively but does not exercise non-finite padding.
apps/storybook/src/graph/Labels.stories.tsx	Adds an interactive comparison of overlap hiding and legacy overlap behavior.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
  A[Visible candidates] --> B[Forced labels]
  B --> C[Claim forced label boxes]
  C --> D[Rank remaining candidates]
  D --> E{Projectable box?}
  E -- No --> F[Keep candidate]
  E -- Yes --> G{Intersects claimed box?}
  G -- Yes --> H[Skip and try next rank]
  G -- No --> I[Keep and claim box]
  F --> J{Capacity reached?}
  I --> J
  H --> J
  J -- No --> D
  J -- Yes --> K[Emit placements]

Loading

_{Reviews (1): Last reviewed commit: "Label declutter: screen-space overlap cu..." | Re-trigger Greptile}

Greptile also left 1 inline comment on this PR.

Context used:

• Knowledge Base — Visual presentation and export

[greptile-apps]

Infinite padding hangs selection

When a host supplies overlapPadding: Infinity, the clamp preserves infinity and the derived label box gives the occupancy grid infinite loop bounds. The loop counter starts at negative infinity and never advances, hanging label recomputation on the main thread.

Suggested change

	const pad = Math.max(0, config.overlapPadding ?? 2);
	const configuredPad = config.overlapPadding ?? 2;
	const pad = Number.isFinite(configuredPad) ? Math.max(0, configuredPad) : 2;

Knowledge Base Used: Visual presentation and export