@trackunit/react-map 0.2.163 → 0.2.166

package/index.cjs.js

@@ -4736,7 +4736,7 @@ const useHoverPreloadInitiator = (initiator, onShouldPreload) => {
 };
 
 const DEFAULT_PROXIMITY_COUNT = 5;
-const EMPTY_IDS = [];
+const EMPTY_IDS$1 = [];
 /**
  * Squared Euclidean distance in lat/lon space. Sufficient for proximity
  * ranking — we need relative ordering, not geographic accuracy.
@@ -4766,11 +4766,11 @@ const useProximityPreloadInitiator = (initiator, api, onShouldPreload) => {
     });
     const nearestIds = react.useMemo(() => {
         if (referenceEntityId === null || entities === undefined || entities.length === 0) {
-            return EMPTY_IDS;
+            return EMPTY_IDS$1;
         }
         const reference = entities.find(e => e.id === referenceEntityId);
         if (reference === undefined)
-            return EMPTY_IDS;
+            return EMPTY_IDS$1;
         return entities
             .filter(e => e.id !== referenceEntityId)
             .map(e => ({ id: e.id, dist: squaredDistance(e.position, reference.position) }))
@@ -4780,7 +4780,7 @@ const useProximityPreloadInitiator = (initiator, api, onShouldPreload) => {
     }, [referenceEntityId, entities, count]);
     // Sync computed nearest ids to a ref so the stable effect below always
     // reads the freshest result without being re-scheduled on every render.
-    const nearestIdsRef = react.useRef(EMPTY_IDS);
+    const nearestIdsRef = react.useRef(EMPTY_IDS$1);
     react.useLayoutEffect(() => {
         nearestIdsRef.current = nearestIds;
     }, [nearestIds]);
@@ -5578,6 +5578,180 @@ const useFitToContent = (api, handles, options) => {
     return react.useMemo(() => ({ hasFitted, isWaiting, fitNow }), [hasFitted, isWaiting, fitNow]);
 };
 
+/**
+ * Do two label footprints overlap? Each is a box of its own size centred on its point, so the boxes
+ * overlap when the centres are closer than the sum of their half-extents in each axis. Shared by the
+ * placement core and the stick solver so Tier A and Tier B collide by exactly the same rule.
+ */
+const overlaps = (a, aFootprint, b, bFootprint) => Math.abs(a[0] - b[0]) < (aFootprint.widthDeg + bFootprint.widthDeg) / 2 &&
+    Math.abs(a[1] - b[1]) < (aFootprint.heightDeg + bFootprint.heightDeg) / 2;
+/** Squared euclidean distance between two planar points. */
+const sqDistance = (a, b) => {
+    const dx = a[0] - b[0];
+    const dy = a[1] - b[1];
+    return dx * dx + dy * dy;
+};
+
+/** Screen "up" in math radians (+x right, y down): −π/2 points up on screen. */
+const UP_ANGLE_RAD = -Math.PI / 2;
+/** Anchor pin radius in px (the `xs` dot, 8px + 2px border): only feeds the tip's soft floor. */
+const ANCHOR_DOT_RADIUS_PX = 5;
+const collidesWithPlaced = (point, footprint, placed) => placed.some(other => overlaps(point, footprint, other.point, other.footprint));
+/** Liang–Barsky: does the segment a→b enter the axis-aligned box [minX,minY]–[maxX,maxY]? */
+const segmentIntersectsBox = (a, b, minX, minY, maxX, maxY) => {
+    const dx = b[0] - a[0];
+    const dy = b[1] - a[1];
+    let t0 = 0;
+    let t1 = 1;
+    const clip = (p, q) => {
+        if (p === 0)
+            return q >= 0; // parallel to this slab: only crosses if the origin is inside it
+        const r = q / p;
+        if (p < 0) {
+            if (r > t1)
+                return false;
+            if (r > t0)
+                t0 = r;
+        }
+        else {
+            if (r < t0)
+                return false;
+            if (r < t1)
+                t1 = r;
+        }
+        return true;
+    };
+    return clip(-dx, a[0] - minX) && clip(dx, maxX - a[0]) && clip(-dy, a[1] - minY) && clip(dy, maxY - a[1]) && t0 <= t1;
+};
+/**
+ * Does the leader line anchor→tip pass over another placed label's box? A box containing the anchor
+ * is skipped — the line necessarily starts inside the collision that forced the stick, which is
+ * unavoidable. Each placed label uses its own half-extent box.
+ */
+const lineCrossesPlaced = (anchor, tip, placed) => placed.some(({ point, footprint }) => {
+    const halfW = footprint.widthDeg / 2;
+    const halfH = footprint.heightDeg / 2;
+    if (Math.abs(anchor[0] - point[0]) <= halfW && Math.abs(anchor[1] - point[1]) <= halfH)
+        return false;
+    return segmentIntersectsBox(anchor, tip, point[0] - halfW, point[1] - halfH, point[0] + halfW, point[1] + halfH);
+});
+/** Squared distance from `point` to the nearest placed label centre (Infinity when none). */
+const clearanceSq = (point, placed) => {
+    let min = Infinity;
+    for (const other of placed) {
+        const d = sqDistance(point, other.point);
+        if (d < min)
+            min = d;
+    }
+    return min;
+};
+/**
+ * Finds a stick offset for a guaranteed (Tier-A) label whose anchor is taken.
+ *
+ * Searches a candidate ring — `anglesPerRing` evenly-spaced angles, at increasing radii from
+ * `baseDistancePx` outward (`radiusSteps` rings). At the shortest ring that has room it aims the
+ * stick into the **most open direction** — the footprint-free angle whose displaced label is
+ * farthest from every other label — preferring angles whose leader line does not cross a label, and
+ * breaking ties straight-up-first for determinism. Candidates whose pill would fall outside `viewBox`
+ * are rejected so a guaranteed label is not pushed off-canvas. If a ring offers only line-crossing
+ * angles it keeps looking outward for a clean one, else falls back to the most-open crossing angle of
+ * the innermost ring that had room; if every candidate is rejected it returns `undefined` (the caller
+ * then keeps the label at its anchor — never dropped). `previousOffset` is reused only while it stays
+ * footprint-free, on-canvas and line-clear, so a clean stick keeps its direction between settles.
+ *
+ * Geometry matches the renderer: the collision/reserved point is the **rendered pill centre**
+ * (`resolveTentativeTip` + `computePillCSSPlacement`), not the raw polar tip; the line is tested to
+ * that tip.
+ */
+const findStickOffset = ({ anchor, placed, footprint, degreesPerPixel, viewBox, baseDistancePx, radiusStepPx, radiusSteps, anglesPerRing, previousOffset, }) => {
+    // Recover the pill's px dimensions from the geo footprint (inverse of `labelFootprintDeg`), so the
+    // pill-centre geometry matches what the renderer paints.
+    const pillWidthPx = footprint.widthDeg / degreesPerPixel.lng;
+    const pillHeightPx = footprint.heightDeg / degreesPerPixel.lat;
+    const halfWidthDeg = footprint.widthDeg / 2;
+    const halfHeightDeg = footprint.heightDeg / 2;
+    const outsideViewBox = (point) => viewBox !== undefined &&
+        (point[0] < viewBox[0] + halfWidthDeg ||
+            point[0] > viewBox[2] - halfWidthDeg ||
+            point[1] < viewBox[1] + halfHeightDeg ||
+            point[1] > viewBox[3] - halfHeightDeg);
+    // Rendered pill centre + leader-line tip (both anchor-relative geo) for a polar offset.
+    const geometryFor = (angleRad, distancePx) => {
+        const positioning = { type: "polar", angleRad, distance: distancePx };
+        const tip = resolveTentativeTip(positioning, pillHeightPx, ANCHOR_DOT_RADIUS_PX, pillWidthPx);
+        const css = computePillCSSPlacement(tip.x, tip.y, pillHeightPx);
+        // Pill centre X = left edge + half width; `translateXPct` shifts the element by its own width.
+        const pillCentreXpx = css.pillLeft + (css.translateXPct / 100 + 0.5) * pillWidthPx;
+        return {
+            // Screen y is down, so a negative tip.y (up on screen) raises latitude.
+            pillCentre: [anchor[0] + pillCentreXpx * degreesPerPixel.lng, anchor[1] - tip.y * degreesPerPixel.lat],
+            tip: [anchor[0] + tip.x * degreesPerPixel.lng, anchor[1] - tip.y * degreesPerPixel.lat],
+        };
+    };
+    const evaluate = (angleRad, distancePx) => {
+        const { pillCentre, tip } = geometryFor(angleRad, distancePx);
+        if (outsideViewBox(pillCentre))
+            return undefined;
+        if (collidesWithPlaced(pillCentre, footprint, placed))
+            return undefined;
+        return { pillCentre, lineClear: !lineCrossesPlaced(anchor, tip, placed) };
+    };
+    // Reuse the remembered offset only while it stays clean, so a settled stick keeps its direction.
+    if (previousOffset !== undefined) {
+        const prev = evaluate(previousOffset.angleRad, previousOffset.distancePx);
+        if (prev !== undefined && prev.lineClear) {
+            return {
+                positioning: { type: "polar", angleRad: previousOffset.angleRad, distance: previousOffset.distancePx },
+                pillCentre: prev.pillCentre,
+            };
+        }
+    }
+    const angleStep = (2 * Math.PI) / anglesPerRing;
+    // A candidate only beats the current best when meaningfully more open; near-ties (including the
+    // float noise of a radially symmetric ring) keep the earlier, up-first angle — deterministic.
+    const beats = (clearance, best) => best === undefined || clearance > best.clearance * (1 + 1e-6);
+    let fallback;
+    for (let ring = 0; ring < radiusSteps; ring++) {
+        const distance = baseDistancePx + ring * radiusStepPx;
+        let bestClear;
+        let bestCrossing;
+        for (let a = 0; a < anglesPerRing; a++) {
+            const angleRad = UP_ANGLE_RAD + a * angleStep;
+            const evaluated = evaluate(angleRad, distance);
+            if (evaluated === undefined)
+                continue;
+            const clearance = clearanceSq(evaluated.pillCentre, placed);
+            if (evaluated.lineClear) {
+                if (beats(clearance, bestClear))
+                    bestClear = { angleRad, pillCentre: evaluated.pillCentre, clearance };
+            }
+            else if (beats(clearance, bestCrossing)) {
+                bestCrossing = { angleRad, pillCentre: evaluated.pillCentre, clearance };
+            }
+        }
+        if (bestClear !== undefined) {
+            return {
+                positioning: { type: "polar", angleRad: bestClear.angleRad, distance },
+                pillCentre: bestClear.pillCentre,
+            };
+        }
+        if (fallback === undefined && bestCrossing !== undefined) {
+            fallback = {
+                positioning: { type: "polar", angleRad: bestCrossing.angleRad, distance },
+                pillCentre: bestCrossing.pillCentre,
+            };
+        }
+    }
+    return fallback;
+};
+
+const EMPTY_IDS = new Set();
+// Candidate-ring stick search (tunable): base distance from the shared stick tuning, then out.
+const STICK_BASE_DISTANCE_PX = MARKER_TUNING.stick.defaultPositioning.distance;
+const STICK_RADIUS_STEP_PX = 24;
+const STICK_RADIUS_STEPS = 3;
+const STICK_ANGLES_PER_RING = 8;
+const byId = (a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0);
 const isWithinBounds = (position, bounds) => {
     const [lng, lat] = position;
     const [minLng, minLat, maxLng, maxLat] = bounds;
@@ -5598,32 +5772,81 @@ const boundsCentreLng = (bounds) => {
  * centroid/distance/overlap math then uses plain deltas with no ±180° discontinuity.
  */
 const unwrapLng = (lng, reference) => lng - 360 * Math.round((lng - reference) / 360);
-const overlaps = (a, b, footprint) => Math.abs(a[0] - b[0]) < footprint.widthDeg && Math.abs(a[1] - b[1]) < footprint.heightDeg;
-const sqDistance = (a, b) => {
-    const dx = a[0] - b[0];
-    const dy = a[1] - b[1];
-    return dx * dx + dy * dy;
+/**
+ * Selects up to `count` candidates from `pool` spread as far apart as possible: the first pick is
+ * the candidate nearest the pool centroid (or, when `seeds` already exist, the one farthest from
+ * them), each subsequent pick maximises the distance to everything chosen so far. `pool` must be
+ * id-sorted; ties break to the earlier (lower-id) candidate, so the result is deterministic.
+ */
+const disperseSelect = (pool, count, seeds) => {
+    const remaining = [...pool];
+    const chosenPoints = [...seeds];
+    const out = [];
+    while (out.length < count && remaining.length > 0) {
+        let bestIndex = 0;
+        if (chosenPoints.length === 0) {
+            let cx = 0;
+            let cy = 0;
+            for (const candidate of remaining) {
+                cx += candidate.point[0];
+                cy += candidate.point[1];
+            }
+            const centroid = [cx / remaining.length, cy / remaining.length];
+            let bestSeedDist = Infinity;
+            remaining.forEach((candidate, index) => {
+                const d = sqDistance(candidate.point, centroid);
+                if (d < bestSeedDist) {
+                    bestSeedDist = d;
+                    bestIndex = index;
+                }
+            });
+        }
+        else {
+            let bestMinDist = -1;
+            remaining.forEach((candidate, index) => {
+                let minDist = Infinity;
+                for (const other of chosenPoints) {
+                    const d = sqDistance(candidate.point, other);
+                    if (d < minDist)
+                        minDist = d;
+                }
+                if (minDist > bestMinDist) {
+                    bestMinDist = minDist;
+                    bestIndex = index;
+                }
+            });
+        }
+        const [chosen] = remaining.splice(bestIndex, 1);
+        if (chosen === undefined)
+            break;
+        out.push(chosen);
+        chosenPoints.push(chosen.point);
+    }
+    return out;
 };
 /**
- * Chooses which markers render a label so that no two labels overlap, in priority order.
+ * Chooses which markers render a label, and how, in priority order.
  *
- * Walks `focus.tiers` high→low; only items matching a tier are eligible. Within each tier,
- * incumbents (in `previousIds`) are considered before newcomers, and each group is visited in
- * dynamic **farthest-point** order — the candidate whose nearest-neighbour distance to every
- * already-placed label is largest is tried first — so labels spread across the view box rather
- * than lumping. Each pick is collision-tested against the placed footprints and skipped if it
- * would overlap. Placement stops at `ceiling`; the budget is otherwise emergent (what fits).
+ * **Tier A (guaranteed):** every in-view `mustShowIds` marker (regardless of tier), plus the
+ * top-`tierACount` eligible markers by priority — the latter chosen high→low tier then, within a
+ * tier, by spatial spread so one cluster cannot consume the whole guarantee. None are dropped: each
+ * takes its anchor if collision-free, else a candidate-ring solver finds a leader-line **stick**
+ * offset (kept on-canvas), else it stays at the anchor overlapping. Tier A uses the same `footprint`
+ * as Tier B, so a guaranteed label may overlap a denser neighbour a little (accepted trade-off).
  *
- * All geometry runs in longitudes unwrapped around the view-box centre, so a viewport crossing
- * the antimeridian is handled correctly. Deterministic: all ties (centroid seed and
- * farthest-point) break by `getId` ascending, so the result is independent of server return order.
+ * **Tier B (collision-fill):** the remaining eligible markers, walked high→low tier, placed at their
+ * anchor only if collision-free with the (possibly narrower) `footprint`, most-dispersed-first, until
+ * the `ceiling` is hit. Incumbents (`previousIds`) are preferred within their tier (hysteresis).
+ *
+ * All geometry runs in longitudes unwrapped around the view-box centre, so a viewport crossing the
+ * antimeridian is handled correctly. Deterministic: ties break by `getId` ascending, so the result is
+ * independent of server return order. Returns a placement map keyed by id.
  */
-const buildLabelPlacement = ({ items, getId, getPosition, focus, bounds, footprint, ceiling, previousIds, }) => {
-    const shown = new Set();
+const buildLabelPlacement = ({ items, getId, getPosition, focus, bounds, footprint, degreesPerPixel, ceiling, tierACount, mustShowIds, previousIds, previousStickOffsets, }) => {
+    const placements = new Map();
     const placed = [];
     // Reference longitude for unwrapping: the view-box centre when clipping, else the lowest-id
-    // item's longitude — a fixed, order-independent anchor so the result never depends on input
-    // order (a plain "first item" reference would not; see the order-independence guarantee above).
+    // item's longitude — a fixed, order-independent anchor so the result never depends on input order.
     let referenceLng;
     if (bounds !== null) {
         referenceLng = boundsCentreLng(bounds);
@@ -5644,29 +5867,92 @@ const buildLabelPlacement = ({ items, getId, getPosition, focus, bounds, footpri
         const p = getPosition(item);
         return [unwrapLng(p[0], referenceLng), p[1]];
     };
-    // Below this squared distance a point is inside every label footprint, so it always overlaps.
+    const toCandidate = (item) => ({ id: getId(item), point: planar(item) });
+    const inView = (item) => bounds === null || isWithinBounds(getPosition(item), bounds);
+    // Planar (unwrapped) view box for the stick solver, so it can keep displaced pills on-canvas.
+    const planarViewBox = bounds === null
+        ? undefined
+        : [unwrapLng(bounds[0], referenceLng), bounds[1], unwrapLng(bounds[2], referenceLng), bounds[3]];
+    // Below this squared distance a point is inside every Tier-B footprint, so it always overlaps.
     const minFootprintSq = Math.min(footprint.widthDeg, footprint.heightDeg) ** 2;
-    // Try to place a group of same-tier candidates, most-dispersed-first, collision-gated.
+    // ---- Tier A membership ----
+    const mustShow = mustShowIds ?? EMPTY_IDS;
+    // Must-show is guaranteed even if it matches no tier (e.g. a selected asset with null state).
+    const mustShowCandidates = items
+        .filter(item => mustShow.has(getId(item)) && inView(item))
+        .map(toCandidate)
+        .sort(byId);
+    const guaranteed = new Set(mustShowCandidates.map(candidate => candidate.id));
+    // Top-N by priority: fill from higher tiers first, choosing within a tier by spatial spread.
+    const selectedPoints = mustShowCandidates.map(candidate => candidate.point);
+    const seenTier = new Set();
+    const topN = [];
+    for (const tier of focus.tiers) {
+        if (topN.length >= tierACount)
+            break;
+        const pool = items
+            .filter(item => tier.match(item) && inView(item) && !seenTier.has(getId(item)))
+            .map(toCandidate)
+            .sort(byId);
+        for (const candidate of pool)
+            seenTier.add(candidate.id);
+        const eligible = pool.filter(candidate => !guaranteed.has(candidate.id));
+        const picked = disperseSelect(eligible, tierACount - topN.length, selectedPoints);
+        for (const candidate of picked) {
+            topN.push(candidate);
+            selectedPoints.push(candidate.point);
+        }
+    }
+    for (const candidate of topN)
+        guaranteed.add(candidate.id);
+    // ---- Place Tier A (never dropped), must-show first so a touched asset claims its anchor ----
+    for (const candidate of [...mustShowCandidates, ...topN]) {
+        if (placements.size >= ceiling)
+            break;
+        if (!placed.some(other => overlaps(other.point, other.footprint, candidate.point, footprint))) {
+            placements.set(candidate.id, { mode: "anchor" });
+            placed.push({ point: candidate.point, footprint });
+            continue;
+        }
+        const stick = findStickOffset({
+            anchor: candidate.point,
+            placed,
+            footprint,
+            degreesPerPixel,
+            viewBox: planarViewBox,
+            baseDistancePx: STICK_BASE_DISTANCE_PX,
+            radiusStepPx: STICK_RADIUS_STEP_PX,
+            radiusSteps: STICK_RADIUS_STEPS,
+            anglesPerRing: STICK_ANGLES_PER_RING,
+            previousOffset: previousStickOffsets?.get(candidate.id),
+        });
+        if (stick !== undefined) {
+            placements.set(candidate.id, { mode: "stick", stickPositioning: stick.positioning });
+            // Reserve the rendered pill centre (not the anchor) so Tier B avoids where the label paints.
+            placed.push({ point: stick.pillCentre, footprint });
+        }
+        else {
+            // Ring full or no on-canvas spot — keep the guaranteed label at its anchor, overlapping.
+            placements.set(candidate.id, { mode: "anchor" });
+            placed.push({ point: candidate.point, footprint });
+        }
+    }
+    // ---- Tier B (collision-fill), most-dispersed-first, using the (possibly narrower) footprint ----
     const placeGroup = (group) => {
-        // Sort by id first so every tie below resolves by id ascending, deterministically.
-        const pool = group
-            .map(item => ({ id: getId(item), point: planar(item) }))
-            .sort((a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
-        while (pool.length > 0 && shown.size < ceiling) {
+        const pool = [...group].sort(byId);
+        while (pool.length > 0 && placements.size < ceiling) {
             let bestIndex = 0;
             if (placed.length === 0) {
-                // Seed the very first label on the candidate nearest the group centroid so the
-                // spread fans out evenly from the middle.
                 let cx = 0;
                 let cy = 0;
-                for (const c of pool) {
-                    cx += c.point[0];
-                    cy += c.point[1];
+                for (const candidate of pool) {
+                    cx += candidate.point[0];
+                    cy += candidate.point[1];
                 }
                 const centroid = [cx / pool.length, cy / pool.length];
                 let bestSeedDist = Infinity;
-                pool.forEach((c, index) => {
-                    const d = sqDistance(c.point, centroid);
+                pool.forEach((candidate, index) => {
+                    const d = sqDistance(candidate.point, centroid);
                     if (d < bestSeedDist) {
                         bestSeedDist = d;
                         bestIndex = index;
@@ -5674,12 +5960,11 @@ const buildLabelPlacement = ({ items, getId, getPosition, focus, bounds, footpri
                 });
             }
             else {
-                // Pick the candidate whose nearest already-placed label is farthest away.
                 let bestMinDist = -1;
-                pool.forEach((c, index) => {
+                pool.forEach((candidate, index) => {
                     let minDist = Infinity;
                     for (const other of placed) {
-                        const d = sqDistance(other, c.point);
+                        const d = sqDistance(other.point, candidate.point);
                         if (d < minDist)
                             minDist = d;
                     }
@@ -5688,32 +5973,36 @@ const buildLabelPlacement = ({ items, getId, getPosition, focus, bounds, footpri
                         bestIndex = index;
                     }
                 });
-                // Even the most-dispersed remaining candidate sits inside a placed footprint → every
-                // candidate now overlaps something placed, so none can be added. Stop scanning this group.
+                // Every remaining candidate sits inside a placed footprint → none can be added. Stop.
                 if (bestMinDist < minFootprintSq)
                     break;
             }
             const [chosen] = pool.splice(bestIndex, 1);
             if (chosen === undefined)
                 break;
-            if (placed.some(other => overlaps(other, chosen.point, footprint)))
+            if (placed.some(other => overlaps(other.point, other.footprint, chosen.point, footprint)))
                 continue;
-            shown.add(chosen.id);
-            placed.push(chosen.point);
+            placements.set(chosen.id, { mode: "anchor" });
+            placed.push({ point: chosen.point, footprint });
         }
     };
     for (const tier of focus.tiers) {
-        if (shown.size >= ceiling)
+        if (placements.size >= ceiling)
             break;
-        const candidates = items.filter(item => !shown.has(getId(item)) && tier.match(item) && (bounds === null || isWithinBounds(getPosition(item), bounds)));
+        const candidates = items
+            .filter(item => {
+            const id = getId(item);
+            return !placements.has(id) && !guaranteed.has(id) && tier.match(item) && inView(item);
+        })
+            .map(toCandidate);
         if (previousIds === undefined) {
             placeGroup(candidates);
             continue;
         }
-        placeGroup(candidates.filter(item => previousIds.has(getId(item))));
-        placeGroup(candidates.filter(item => !previousIds.has(getId(item))));
+        placeGroup(candidates.filter(candidate => previousIds.has(candidate.id)));
+        placeGroup(candidates.filter(candidate => !previousIds.has(candidate.id)));
     }
-    return shown;
+    return placements;
 };
 
 const WEB_MERCATOR_TILE_SIZE_PX = 256;
@@ -5732,66 +6021,128 @@ const degreesPerPixel$1 = (zoom, latitudeDeg) => {
     return { lng, lat: lng * Math.cos((latitudeDeg * Math.PI) / 180) };
 };
 /**
- * Upper-bound label footprint as a geo-space width/height, for collision testing.
+ * Label footprint as a geo-space width/height, for collision testing.
  *
- * A rendered pill's size does NOT follow the zoom circle-size tier: `MapMarker`
- * lays every pill out at the fixed {@link MARKER_PILL_CONTENT_LAYOUT_SIZE}, and the
- * label text is capped at `maxLabelWidthPx` (ellipsis beyond). We size the collision
- * box to that upper bound — widest pill that can render — so the box is never smaller
- * than what paints, which is what keeps the "no two labels overlap" guarantee honest.
- * Density is tuned via `paddingPx`, not by shrinking the box.
+ * A rendered pill's size does NOT follow the zoom circle-size tier: `MapMarker` lays every pill out
+ * at the fixed {@link MARKER_PILL_CONTENT_LAYOUT_SIZE}, and the label text is capped at
+ * `maxLabelWidthPx` (ellipsis beyond). By default the box is sized to that cap — the widest pill
+ * that can render — so it is never smaller than what paints (no two labels overlap). Callers can pass
+ * a smaller `labelWidthPx` to pack denser at the cost of occasional overlap for long names; density
+ * is otherwise tuned via `paddingPx`.
  */
-const labelFootprintDeg = ({ zoom, latitudeDeg, paddingPx }) => {
+const labelFootprintDeg = ({ zoom, latitudeDeg, paddingPx, labelWidthPx, }) => {
     const { circle, pillPaddingY } = MARKER_SIZE_MAP[MARKER_PILL_CONTENT_LAYOUT_SIZE];
     const { maxLabelWidthPx, gapPx, paddingRightPx } = MARKER_TUNING.pill;
-    // Left pad (== pillPaddingY) + icon disc + gap + max label text + right pad. Assume the icon
-    // disc is present (the wider case) so the box stays an upper bound.
-    const widthPx = pillPaddingY + circle + gapPx + maxLabelWidthPx + paddingRightPx + 2 * paddingPx;
+    // Assumed text width: the render cap by default (upper bound → no overlap), or a caller override.
+    const textWidthPx = labelWidthPx ?? maxLabelWidthPx;
+    // Left pad (== pillPaddingY) + icon disc + gap + label text + right pad. Assume the icon disc is
+    // present (the wider case).
+    const widthPx = pillPaddingY + circle + gapPx + textWidthPx + paddingRightPx + 2 * paddingPx;
     const heightPx = markerPillOuterHeightPx(MARKER_PILL_CONTENT_LAYOUT_SIZE) + 2 * paddingPx;
     const perPixel = degreesPerPixel$1(zoom, latitudeDeg);
     return { widthDeg: widthPx * perPixel.lng, heightDeg: heightPx * perPixel.lat };
 };
 
-const EMPTY_LABEL_IDS = new Set();
+const EMPTY_PLACEMENTS = new Map();
+const samePlacement = (a, b) => {
+    if (a.mode === "anchor")
+        return b.mode === "anchor";
+    if (b.mode === "anchor")
+        return false;
+    const pa = a.stickPositioning;
+    const pb = b.stickPositioning;
+    return pa.type === "polar" && pb.type === "polar" && pa.angleRad === pb.angleRad && pa.distance === pb.distance;
+};
+const placementsEqual = (a, b) => {
+    if (a.size !== b.size)
+        return false;
+    for (const [id, placement] of a) {
+        const other = b.get(id);
+        if (other === undefined || !samePlacement(placement, other))
+            return false;
+    }
+    return true;
+};
+/** Extracts the polar stick offsets from a placement map, to seed the next solve (incumbency). */
+const stickOffsetsFrom = (placements) => {
+    const offsets = new Map();
+    for (const [id, placement] of placements) {
+        if (placement.mode === "stick" && placement.stickPositioning.type === "polar") {
+            offsets.set(id, {
+                angleRad: placement.stickPositioning.angleRad,
+                distancePx: placement.stickPositioning.distance,
+            });
+        }
+    }
+    return offsets;
+};
 /**
- * Viewport-driven label placement with hysteresis: returns the ids of the markers that should
- * render a label such that no two labels overlap, in priority order, bounded by `ceiling`.
+ * Viewport-driven label placement with hysteresis: returns a map of the markers that should render
+ * a label to how they render it (`anchor` or a displaced `stick`), no two overlapping, in priority
+ * order, bounded by `ceiling`.
  *
- * Stateful wrapper around the pure {@link buildLabelPlacement} — feeds the previous result back
- * as `previousIds` so labels that were shown stay shown across pan/zoom refetches (incumbents
- * that leave the view box drop via candidate clipping). Memory resets when `focus.id` changes,
- * not on viewport change. Returns the previous `Set` reference when content is unchanged so
- * downstream `useMemo`/callbacks stay stable. Same render-phase-setState pattern as
- * `useExpandedIds`.
+ * Stateful wrapper around the pure {@link buildLabelPlacement} — feeds the previous result back as
+ * `previousIds` (so Tier-B labels stay shown across pan/zoom refetches) and as `previousStickOffsets`
+ * (so a displaced Tier-A label keeps its stick direction). Memory resets when `focus.id` changes,
+ * not on viewport change. Returns the previous map reference when content is unchanged so downstream
+ * `useMemo`/callbacks stay stable. Same render-phase-setState pattern as `useExpandedIds`.
  */
-const useLabelPlacement = ({ enabled, items, getId, getPosition, focus, bounds, zoom, paddingPx, ceiling, }) => {
+const useLabelPlacement = ({ enabled, items, getId, getPosition, focus, bounds, zoom, paddingPx, labelWidthPx, ceiling, tierACount, mustShowIds, frozen, }) => {
     const [snapshot, setSnapshot] = react.useState(() => ({
         focusId: focus.id,
-        ids: EMPTY_LABEL_IDS,
+        placements: EMPTY_PLACEMENTS,
     }));
-    if (!enabled) {
-        if (snapshot.ids !== EMPTY_LABEL_IDS || snapshot.focusId !== focus.id) {
-            setSnapshot({ focusId: focus.id, ids: EMPTY_LABEL_IDS });
-        }
-        return EMPTY_LABEL_IDS;
-    }
-    const prevIds = snapshot.focusId === focus.id ? snapshot.ids : EMPTY_LABEL_IDS;
+    // Incumbency source: the prior placement, unless disabled or the focus changed (memory reset).
+    const prev = enabled && snapshot.focusId === focus.id ? snapshot.placements : EMPTY_PLACEMENTS;
+    // Hold the last placement while a viewport refetch is in flight (frozen), so labels resettle once
+    // the new data lands rather than blinking as the view box moves ahead of the data.
+    const held = enabled && frozen === true && snapshot.focusId === focus.id;
     const latitudeDeg = bounds === null ? 0 : (bounds[1] + bounds[3]) / 2;
-    const footprint = labelFootprintDeg({ zoom, latitudeDeg, paddingPx });
-    const result = buildLabelPlacement({
+    // Memoised so a re-render that doesn't change any input (e.g. cursor movement upstream) reuses the
+    // last placement instead of recomputing. `prev` only changes when the result itself changed.
+    const result = react.useMemo(() => {
+        if (!enabled)
+            return EMPTY_PLACEMENTS;
+        if (held)
+            return prev;
+        // One footprint for both tiers: `labelWidthPx` narrows the width only (height stays full, so
+        // labels never overlap vertically). A guaranteed label may overlap a denser neighbour a little.
+        const footprint = labelFootprintDeg({ zoom, latitudeDeg, paddingPx, labelWidthPx });
+        return buildLabelPlacement({
+            items,
+            getId,
+            getPosition,
+            focus,
+            bounds,
+            footprint,
+            degreesPerPixel: degreesPerPixel$1(zoom, latitudeDeg),
+            ceiling,
+            tierACount,
+            mustShowIds,
+            previousIds: new Set(prev.keys()),
+            previousStickOffsets: stickOffsetsFrom(prev),
+        });
+    }, [
+        enabled,
+        held,
         items,
         getId,
         getPosition,
         focus,
         bounds,
-        footprint,
+        zoom,
+        latitudeDeg,
+        paddingPx,
+        labelWidthPx,
         ceiling,
-        previousIds: prevIds,
-    });
+        tierACount,
+        mustShowIds,
+        prev,
+    ]);
     // Return the previous reference when content is identical — keeps downstream caches stable.
-    const stable = result.size === prevIds.size && [...result].every(id => prevIds.has(id)) ? prevIds : result;
-    if (stable !== snapshot.ids || focus.id !== snapshot.focusId) {
-        setSnapshot({ focusId: focus.id, ids: stable });
+    const stable = placementsEqual(result, prev) ? prev : result;
+    if (stable !== snapshot.placements || focus.id !== snapshot.focusId) {
+        setSnapshot({ focusId: focus.id, placements: stable });
     }
     return stable;
 };