/** * @module worldOverlayDraw * @description Pure geometry, measurement, and Canvas2D painters for the * shared world overlay. This module owns presentation only: no layer state, * fetching, Cesium scene queries, or source selection policy belongs here. */ import { WORLD_OVERLAY_STYLE } from './worldOverlayTokens.js'; // Two high-cardinality infrastructure sources share this cache; 1024 avoids // repeated O(n) eviction scans while keeping host-lifetime retention bounded. const TEXT_MEASURE_CACHE_LIMIT = 1024; const _textMeasureCache = new Map(); let _textMeasureCacheSize = 0; // Recency is a monotonic integer stamp rather than a doubly linked list: a // cache hit happens twice per painted entry per frame, and re-linking four // object pointers on every hit costs real write-barrier traffic. A Smi store // costs nothing, and eviction (only above the cap) can afford a scan. let _textMeasureClock = 0; let _fontInvalidationInstalled = false; let _fontInvalidationGeneration = 0; let _observedFontSet = null; function evictOldestTextMeasureEntry() { let oldestFont = null; let oldestText = null; let oldestUsedAt = Number.POSITIVE_INFINITY; _textMeasureCache.forEach((fontCache, font) => { fontCache.forEach((entry, text) => { if (entry.usedAt >= oldestUsedAt) return; oldestUsedAt = entry.usedAt; oldestFont = font; oldestText = text; }); }); if (oldestFont === null) return; const fontCache = _textMeasureCache.get(oldestFont); fontCache.delete(oldestText); if (fontCache.size === 0) _textMeasureCache.delete(oldestFont); _textMeasureCacheSize--; } /** Clear cached text widths after web-font availability changes. */ export function clearWorldOverlayTextMeasureCache() { _textMeasureCache.clear(); _textMeasureCacheSize = 0; _textMeasureClock = 0; } /** Install the font-loading invalidation hooks once, when the API exists. */ export function installWorldOverlayFontInvalidation() { if ( _fontInvalidationInstalled || typeof document === 'undefined' || !document.fonts ) return; _fontInvalidationInstalled = true; _observedFontSet = document.fonts; const generation = ++_fontInvalidationGeneration; Promise.resolve(document.fonts.ready) .then(() => { if (generation === _fontInvalidationGeneration) clearWorldOverlayTextMeasureCache(); }) .catch(() => {}); _observedFontSet.addEventListener?.( 'loadingdone', clearWorldOverlayTextMeasureCache, ); } /** Remove font hooks and cached measurements when the overlay host is destroyed. */ export function destroyWorldOverlayDraw() { _fontInvalidationGeneration++; _observedFontSet?.removeEventListener?.( 'loadingdone', clearWorldOverlayTextMeasureCache, ); _observedFontSet = null; _fontInvalidationInstalled = false; clearWorldOverlayTextMeasureCache(); } /** * Measure text with a font-aware cache. * @param {CanvasRenderingContext2D} ctx * @param {string} text * @param {string} font * @returns {number} */ export function measureWorldOverlayText(ctx, text, font) { if (!_fontInvalidationInstalled) installWorldOverlayFontInvalidation(); const normalizedText = String(text ?? ''); const normalizedFont = String(font || WORLD_OVERLAY_STYLE.fontLabel); let fontCache = _textMeasureCache.get(normalizedFont); const cached = fontCache?.get(normalizedText); if (cached) { cached.usedAt = ++_textMeasureClock; return cached.width; } ctx.font = normalizedFont; const width = Number(ctx.measureText(normalizedText)?.width) || 0; if (!fontCache) { fontCache = new Map(); _textMeasureCache.set(normalizedFont, fontCache); } fontCache.set(normalizedText, { width, usedAt: ++_textMeasureClock }); _textMeasureCacheSize++; if (_textMeasureCacheSize > TEXT_MEASURE_CACHE_LIMIT) evictOldestTextMeasureEntry(); return width; } /** @returns {number} Current cache size, exposed for focused diagnostics/tests. */ export function getWorldOverlayTextMeasureCacheSize() { return _textMeasureCacheSize; } /** * Append a rounded rectangle to the current Canvas2D path. * @param {CanvasRenderingContext2D|Path2D} path * @param {number} x * @param {number} y * @param {number} w * @param {number} h * @param {number} radius */ export function roundedRectPath( path, x, y, w, h, radius = WORLD_OVERLAY_STYLE.radius, ) { if (typeof path.roundRect === 'function') { path.roundRect(x, y, w, h, radius); return; } const r = Math.max(0, Math.min(Number(radius) || 0, w / 2, h / 2)); path.moveTo(x + r, y); path.arcTo(x + w, y, x + w, y + h, r); path.arcTo(x + w, y + h, x, y + h, r); path.arcTo(x, y + h, x, y, r); path.arcTo(x, y, x + w, y, r); path.closePath(); } /** * FIRMS-compatible distance fade: full through 70% of the far range, then a * linear ramp to zero. A finite minimum is a hard near-range policy boundary. * @param {number} distanceM * @param {object} [options] * @param {number} [options.minDistance] * @param {number} [options.maxDistance] * @param {number} [options.fadeStartRatio] * @returns {number} */ export function distanceFade( distanceM, { minDistance = 0, maxDistance = Number.POSITIVE_INFINITY, fadeStartRatio = 0.7, } = {}, ) { if (!Number.isFinite(distanceM)) return 0; const min = Number.isFinite(minDistance) ? Math.max(0, minDistance) : 0; if (distanceM < min) return 0; if (!Number.isFinite(maxDistance)) return 1; const max = Math.max(min, maxDistance); if (distanceM >= max) return 0; const ratio = Math.max(0, Math.min(1, Number(fadeStartRatio) || 0)); const fadeStart = min + (max - min) * ratio; if (distanceM <= fadeStart || fadeStart >= max) return 1; return 1 - (distanceM - fadeStart) / (max - fadeStart); } /** * Cesium NearFarScalar-compatible distance scale for a complete overlay card. * Values clamp outside the curve and interpolate linearly between its stops. * @param {number} distanceM * @param {object|null} [curve] * @param {number} [curve.near] * @param {number} [curve.nearValue] * @param {number} [curve.far] * @param {number} [curve.farValue] * @returns {number} */ export function distanceScale(distanceM, curve = null) { if (!curve || !Number.isFinite(distanceM)) return 1; const near = Math.max(0, Number(curve.near) || 0); const far = Math.max(near, Number(curve.far) || near); const nearValue = Math.max(0, Number(curve.nearValue) || 0); const farValue = Math.max(0, Number(curve.farValue) || 0); if (distanceM <= near || far === near) return nearValue; if (distanceM >= far) return farValue; const progress = (distanceM - near) / (far - near); return nearValue + (farValue - nearValue) * progress; } /** * Source-configurable camera-altitude scale for a complete overlay card. * The first leg may use smoothstep to preserve CCTV's shipped street-to-city * transition; the second leg is linear and clamps at the source's minimum. * @param {number} altitudeM * @param {object|null} [curve] * @returns {number} */ export function altitudeScale(altitudeM, curve = null) { if (!curve || !Number.isFinite(altitudeM)) return 1; const fullEnd = Number(curve.fullEnd); const midEnd = Number(curve.midEnd); const end = Number(curve.end); const midValue = Number(curve.midValue); const endValue = Number(curve.endValue); if ( !Number.isFinite(fullEnd) || !Number.isFinite(midEnd) || !Number.isFinite(end) || !Number.isFinite(midValue) || !Number.isFinite(endValue) ) return 1; if (altitudeM <= fullEnd) return 1; if (altitudeM <= midEnd) { const span = Math.max(1, midEnd - fullEnd); let progress = Math.max(0, Math.min(1, (altitudeM - fullEnd) / span)); if (curve.smoothToMid === true) progress = progress * progress * (3 - 2 * progress); return 1 + (midValue - 1) * progress; } if (altitudeM >= end) return endValue; const progress = Math.max( 0, Math.min(1, (altitudeM - midEnd) / Math.max(1, end - midEnd)), ); return midValue + (endValue - midValue) * progress; } /** * Linear camera-altitude fade. Sources opt in with finite fade boundaries. * @param {number} altitudeM * @param {object} [options] * @param {number} [options.minAltitude] * @param {number} [options.fadeStart] * @param {number} [options.fadeEnd] * @returns {number} */ export function altitudeFade( altitudeM, { minAltitude = Number.NEGATIVE_INFINITY, fadeStart = Number.POSITIVE_INFINITY, fadeEnd = Number.POSITIVE_INFINITY, } = {}, ) { if (!Number.isFinite(altitudeM)) return 1; if (Number.isFinite(minAltitude) && altitudeM < minAltitude) return 0; if (!Number.isFinite(fadeEnd)) return 1; const end = fadeEnd; const start = Number.isFinite(fadeStart) ? Math.min(fadeStart, end) : end; if (altitudeM <= start) return 1; if (altitudeM >= end || start === end) return 0; return 1 - (altitudeM - start) / (end - start); } /** Multiply the five independent opacity channels in the binding order. */ export function combinedOverlayAlpha({ sourceAlpha = 1, temporalFade = 1, distanceFade: distanceAlpha = 1, altitudeFade: altitudeAlpha = 1, keyholeEdgeFade = 1, } = {}) { return ( clampUnit(sourceAlpha) * clampUnit(temporalFade) * clampUnit(distanceAlpha) * clampUnit(altitudeAlpha) * clampUnit(keyholeEdgeFade) ); } function clampUnit(value) { return Number.isFinite(Number(value)) ? Math.max(0, Math.min(1, Number(value))) : 1; } function trackDisplayText(entry) { const title = entry?.title || ''; const detail = Array.isArray(entry?.details) ? entry.details[0] || '' : ''; if ( entry._overlayTrackDisplayTitle !== title || entry._overlayTrackDisplayDetail !== detail ) { entry._overlayTrackDisplayTitle = title; entry._overlayTrackDisplayDetail = detail; entry._overlayTrackDisplayText = title && detail ? `${title} · ${detail}` : title || detail; } return entry._overlayTrackDisplayText || ''; } /** * Measure the selected entry variant into a caller-owned layout object. * @param {CanvasRenderingContext2D} ctx * @param {object} entry * @param {object} [out] * @returns {{w:number,h:number,padX:number,padY:number,titleH:number,lineH:number,thumbW:number,thumbH:number}} */ export function measureOverlayEntry(ctx, entry, out = {}) { const variant = entry?.selected ? 'selected' : String(entry?.variant || 'label'); const details = Array.isArray(entry?.details) ? entry.details : []; const selected = variant === 'selected'; const tracked = variant === 'tracked'; const tactical = entry?.cardStyle === 'tactical'; const titleFont = tracked ? WORLD_OVERLAY_STYLE.fontTrackedTitle : selected ? WORLD_OVERLAY_STYLE.fontSelected : WORLD_OVERLAY_STYLE.fontTitle; let titleWidth = measureWorldOverlayText( ctx, entry?.title || '', variant === 'label' ? WORLD_OVERLAY_STYLE.fontLabel : titleFont, ); if (variant === 'track' && details[0]) { titleWidth = measureWorldOverlayText( ctx, trackDisplayText(entry), WORLD_OVERLAY_STYLE.fontTrack, ); } let detailWidth = 0; for (let i = 0; i < details.length; i++) { detailWidth = Math.max( detailWidth, measureWorldOverlayText( ctx, details[i], tracked ? WORLD_OVERLAY_STYLE.fontTrackedDetail : WORLD_OVERLAY_STYLE.fontDetail, ), ); } out.padX = tracked ? 13 : selected ? 12 : variant === 'label' || variant === 'track' ? 6 : 9; out.padY = tracked ? 9 : selected ? 8 : variant === 'label' || variant === 'track' ? 4 : 6; out.titleH = tactical ? selected ? 14 : 12 : tracked ? 13 : selected ? 15 : variant === 'label' || variant === 'track' ? 11 : 13; out.lineH = tracked ? 17 : selected ? 15 : 13; out.thumbW = 0; out.thumbH = 0; if (variant === 'thumbnail') { out.padX = Math.max(0, Number(entry?.thumbnailPadX) || 0); out.padY = Math.max(0, Number(entry?.thumbnailPadTop) || 0); out.padBottom = Math.max(0, Number(entry?.thumbnailPadBottom) || 0); out.titleGap = Math.max(0, Number(entry?.thumbnailTitleGap) || 0); const thumbnailTitleHeight = Number(entry?.thumbnailTitleHeight); out.titleH = Number.isFinite(thumbnailTitleHeight) ? Math.max(0, thumbnailTitleHeight) : out.titleH; out.thumbW = Math.max(1, Number(entry?.thumbnailWidth) || 96); out.thumbH = Math.max(1, Number(entry?.thumbnailHeight) || 54); out.w = out.thumbW + out.padX * 2; out.h = out.padY + out.thumbH + out.titleGap + out.titleH + out.padBottom; } else { out.w = Math.ceil(Math.max(titleWidth, detailWidth)) + out.padX * 2; out.h = out.padY * 2 + out.titleH + details.length * out.lineH; } out.w = Math.max(8, out.w); out.h = Math.max(8, out.h); return out; } function writePlacement( out, corner, x, y, w, h, anchorX, anchorY, signedLeaderOffset = 0, ) { const placement = out || {}; placement.corner = corner; placement.rect ||= {}; placement.rect.x = Math.round(x); placement.rect.y = Math.round(y); placement.rect.w = w; placement.rect.h = h; placement.centerX = placement.rect.x + w / 2; placement.centerY = placement.rect.y + h / 2; placement.anchorX = anchorX; placement.anchorY = anchorY; // This value is computed once per entry below and copied into every pooled // placement. Keeping the signed pixel offset a Smi avoids boxing a fresh // `anchor +/- offset` double on every placement write. placement.leaderOffset = signedLeaderOffset; if (corner === 'above' || corner === 'below') { placement.leadFromX = anchorX; placement.leadFromY = anchorY; // Strictly vertical, always — the shipped leader ran from the anchor's sx to // the card edge at the same sx with no clamp. Clamping the endpoint into the // card rect made the stub visibly diagonal whenever a viewport-edge clamp had // pushed the card sideways off its anchor, which reads as "the card isn't // attached to that camera". placement.leadToX = anchorX; placement.leadToY = corner === 'above' ? placement.rect.y + h : placement.rect.y; } else { placement.leadFromX = anchorX; placement.leadFromY = anchorY; placement.leadToX = corner === 'left' ? placement.rect.x + w : placement.rect.x; placement.leadToY = Math.max( placement.rect.y, Math.min(anchorY, placement.rect.y + h), ); } return placement; } const PLACEMENT_ORDERS = Object.freeze({ above: Object.freeze(['above', 'below', 'right', 'left']), below: Object.freeze(['below', 'above', 'right', 'left']), right: Object.freeze(['right', 'above', 'below', 'left']), left: Object.freeze(['left', 'above', 'below', 'right']), }); const VERTICAL_PLACEMENT_ORDERS = Object.freeze({ above: Object.freeze(['above', 'below']), below: Object.freeze(['below', 'above']), }); function clampPlacementCoordinate(value, size, viewportSize, margin = 4) { return Math.max( margin, Math.min(value, Math.max(margin, viewportSize - size - margin)), ); } /** * Build deterministic above/below/right/left placements, clamped to the live * viewport. The caller may reuse `out` and its placement objects every frame. * @param {object} input * @param {number} input.anchorX * @param {number} input.anchorY * @param {number} input.width * @param {number} input.height * @param {number} input.viewportWidth * @param {number} input.viewportHeight * @param {number} [input.gap] * @param {string} [input.preferred] * @param {number} [input.leaderOffset] * @param {boolean} [input.verticalOnly] * @param {number} [input.viewportMargin] * @param {Array} [out] * @returns {Array} */ export function placementVariants( { anchorX, anchorY, width, height, viewportWidth, viewportHeight, gap = 12, preferred = 'auto', leaderOffset = 0, verticalOnly = false, viewportMargin = 4, }, out = [], ) { const automatic = anchorY - gap - height >= 4 ? 'above' : 'below'; const orders = verticalOnly ? VERTICAL_PLACEMENT_ORDERS : PLACEMENT_ORDERS; const order = orders[preferred] || orders[automatic]; let positiveLeaderOffset = leaderOffset; let negativeLeaderOffset = leaderOffset; if (leaderOffset !== 0) { positiveLeaderOffset = Math.round(leaderOffset); negativeLeaderOffset = -positiveLeaderOffset; } for (let i = 0; i < order.length; i++) { const corner = order[i]; let x = anchorX - width / 2; let y = anchorY - gap - height; if (corner === 'below') y = anchorY + gap; else if (corner === 'right') { x = anchorX + gap; y = anchorY - height / 2; } else if (corner === 'left') { x = anchorX - gap - width; y = anchorY - height / 2; } out[i] = writePlacement( out[i], corner, clampPlacementCoordinate(x, width, viewportWidth, viewportMargin), clampPlacementCoordinate(y, height, viewportHeight, viewportMargin), width, height, anchorX, anchorY, corner === 'above' || corner === 'left' ? negativeLeaderOffset : positiveLeaderOffset, ); } out.length = order.length; return out; } function drawLeader( ctx, placement, accent, progress = 1, width = 1, style = 'straight', ) { const reveal = Math.max(0, Math.min(1, Number(progress) || 0)); if (reveal <= 0) return; ctx.strokeStyle = accent || WORLD_OVERLAY_STYLE.leader; // Leaders are screen-space strokes. Card content may be painted inside an // altitude/distance scale transform, so counter-scale the canvas width to // retain the shipped one-CSS-pixel leader at every card size. ctx.lineWidth = width / (placement.paintScale || 1); ctx.lineCap = 'round'; ctx.lineJoin = 'round'; let startX = placement.leadFromX; let startY = placement.leadFromY; if (placement.leaderOffset !== 0) { if (placement.corner === 'above' || placement.corner === 'below') { startY += placement.leaderOffset; } else { startX += placement.leaderOffset; } } ctx.beginPath(); ctx.moveTo(startX, startY); if ( style === 'elbow' && (placement.corner === 'left' || placement.corner === 'right') ) { const elbowY = placement.rect.y + Math.min(Math.max(12, placement.rect.h * 0.12), 26); const verticalLength = Math.abs(elbowY - startY); const horizontalLength = Math.abs(placement.leadToX - startX); const totalLength = verticalLength + horizontalLength; const visibleLength = totalLength * reveal; if (visibleLength <= verticalLength && verticalLength > 0) { const direction = Math.sign(elbowY - startY); ctx.lineTo(startX, startY + visibleLength * direction); } else { ctx.lineTo(startX, elbowY); const remaining = Math.max(0, visibleLength - verticalLength); const direction = Math.sign(placement.leadToX - startX); ctx.lineTo( startX + Math.min(horizontalLength, remaining) * direction, elbowY, ); } ctx.stroke(); return; } ctx.lineTo( startX + (placement.leadToX - startX) * reveal, startY + (placement.leadToY - startY) * reveal, ); ctx.stroke(); } function drawAnchorDot(ctx, entry, placement) { if (!entry.anchorDot) return; const paintScale = placement.paintScale || 1; const radius = WORLD_OVERLAY_STYLE.anchorDotRadius / paintScale; ctx.beginPath(); ctx.arc(placement.anchorX, placement.anchorY, radius, 0, Math.PI * 2); ctx.fillStyle = entry.accent || WORLD_OVERLAY_STYLE.accent; ctx.fill(); ctx.strokeStyle = WORLD_OVERLAY_STYLE.anchorDotStroke; ctx.lineWidth = WORLD_OVERLAY_STYLE.anchorDotStrokeWidth / paintScale; ctx.stroke(); } function drawCardChrome( ctx, entry, placement, selected = false, drawLeaderLine = true, ) { const { x, y, w, h } = placement.rect; const accent = entry.accent || WORLD_OVERLAY_STYLE.accent; if (drawLeaderLine) drawLeader(ctx, placement, accent, 1, 1, entry.leaderStyle); ctx.beginPath(); roundedRectPath(ctx, x, y, w, h); ctx.fillStyle = selected ? WORLD_OVERLAY_STYLE.selectedBackground : WORLD_OVERLAY_STYLE.background; ctx.fill(); ctx.strokeStyle = selected ? WORLD_OVERLAY_STYLE.selectedBorder : WORLD_OVERLAY_STYLE.border; ctx.lineWidth = selected ? 1.25 : 1; ctx.stroke(); ctx.fillStyle = accent; ctx.fillRect(x, y + 3, selected ? 3 : 2, Math.max(1, h - 6)); } function drawCardText(ctx, entry, placement, selected = false, topOffset = 0) { const details = Array.isArray(entry.details) ? entry.details : []; const x = placement.rect.x + (selected ? 12 : 9); let y = placement.rect.y + (selected ? 8 : 6) + topOffset; ctx.fillStyle = WORLD_OVERLAY_STYLE.title; ctx.font = selected ? WORLD_OVERLAY_STYLE.fontSelected : WORLD_OVERLAY_STYLE.fontTitle; ctx.textBaseline = 'top'; ctx.fillText(String(entry.title || ''), x, y); y += selected ? 15 : 13; ctx.fillStyle = WORLD_OVERLAY_STYLE.detail; ctx.font = WORLD_OVERLAY_STYLE.fontDetail; for (let i = 0; i < details.length; i++) { ctx.fillText(String(details[i]), x, y); y += selected ? 15 : 13; } } function colorWithAlpha(color, alpha) { const text = String(color || WORLD_OVERLAY_STYLE.accent).trim(); const triplet = text.match(/^(\d{1,3})\s*,\s*(\d{1,3})\s*,\s*(\d{1,3})$/); if (triplet) return `rgba(${triplet[1]}, ${triplet[2]}, ${triplet[3]}, ${alpha})`; const hex = text.match(/^#([0-9a-f]{6})$/i); if (hex) { const value = Number.parseInt(hex[1], 16); return `rgba(${(value >> 16) & 255}, ${(value >> 8) & 255}, ${value & 255}, ${alpha})`; } return text; } function tacticalAccentColors(entry) { const accent = entry.accent || WORLD_OVERLAY_STYLE.accent; let colors = entry._overlayTacticalAccentColors; if (!colors || colors.accent !== accent) { colors = { accent, leader: colorWithAlpha(accent, 0.65), border: colorWithAlpha(accent, 0.85), rule: colorWithAlpha(accent, 0.95), }; entry._overlayTacticalAccentColors = colors; } return colors; } function animationLinearProgress(entry, timestamp) { const duration = Math.max(0, Number(entry?.leaderAnimationMs) || 0); if (!duration) return 1; const startedAt = Number(entry?.leaderAnimationStartedAt); if (!Number.isFinite(startedAt)) return 1; return Math.max(0, Math.min(1, (timestamp - startedAt) / duration)); } function leaderDrawRatio(entry) { const ratio = Number(entry?.leaderDrawRatio); return Number.isFinite(ratio) ? Math.max(0.1, Math.min(0.9, ratio)) : 0.68; } export function leaderRevealProgress( entry, timestamp = globalThis.performance?.now?.() ?? Date.now(), ) { const linear = Math.min( 1, animationLinearProgress(entry, timestamp) / leaderDrawRatio(entry), ); return 1 - Math.pow(1 - linear, 3); } export function tacticalCardRevealAlpha( entry, timestamp = globalThis.performance?.now?.() ?? Date.now(), ) { if (!(Math.max(0, Number(entry?.leaderAnimationMs) || 0) > 0)) return 1; const start = leaderDrawRatio(entry); const linear = Math.max( 0, Math.min( 1, (animationLinearProgress(entry, timestamp) - start) / Math.max(0.1, 1 - start), ), ); return linear * linear * (3 - 2 * linear); } function drawTacticalLeader(ctx, entry, placement, accent, timestamp) { ctx.strokeStyle = accent; ctx.lineWidth = (entry.leaderStyle === 'elbow' ? 1.5 : 1) / (placement.paintScale || 1); ctx.lineJoin = 'round'; ctx.lineCap = 'round'; ctx.beginPath(); if ( entry.leaderStyle !== 'elbow' || (placement.corner !== 'above' && placement.corner !== 'below') ) { if (placement.leaderOffset === 0) { ctx.moveTo(placement.leadFromX, placement.leadFromY); } else if (placement.corner === 'above' || placement.corner === 'below') { ctx.moveTo( placement.leadFromX, placement.leadFromY + placement.leaderOffset, ); } else { ctx.moveTo( placement.leadFromX + placement.leaderOffset, placement.leadFromY, ); } ctx.lineTo(placement.leadToX, placement.leadToY); ctx.stroke(); return; } const { x, y, w, h } = placement.rect; const cardX = x + Math.max(18, Math.min(w - 18, w * 0.22)); const cardY = placement.corner === 'above' ? y + h : y; const anchorRadius = Math.abs(placement.leaderOffset); const anchorX = placement.leadFromX - anchorRadius; const anchorY = placement.leadFromY; const horizontalLength = Math.abs(anchorX - cardX); const verticalLength = Math.abs(anchorY - cardY); let remaining = leaderRevealProgress(entry, timestamp) * (horizontalLength + verticalLength); ctx.moveTo(anchorX, anchorY); if (remaining <= horizontalLength) { const direction = Math.sign(cardX - anchorX) || -1; ctx.lineTo(anchorX + direction * remaining, anchorY); } else { ctx.lineTo(cardX, anchorY); remaining -= horizontalLength; const direction = Math.sign(cardY - anchorY) || -1; ctx.lineTo( cardX, anchorY + direction * Math.min(verticalLength, remaining), ); } ctx.stroke(); } /** Paint the legacy FIRMS/vessel tactical card inside the shared host. */ export function paintTacticalCard(ctx, entry, placement, alpha = 1) { const selected = entry.selected || entry.variant === 'selected'; const details = Array.isArray(entry.details) ? entry.details : []; const layout = entry._overlayLayout || {}; const { x, y, w, h } = placement.rect; const accentColors = tacticalAccentColors(entry); const animationTimestamp = globalThis.performance?.now?.() ?? Date.now(); ctx.save(); ctx.globalAlpha = alpha; drawTacticalLeader( ctx, entry, placement, entry.leaderStyle === 'elbow' ? colorWithAlpha(entry.accent, 0.95) : accentColors.leader, animationTimestamp, ); ctx.globalAlpha = alpha * tacticalCardRevealAlpha(entry, animationTimestamp); ctx.beginPath(); roundedRectPath(ctx, x, y, w, h, 4); ctx.fillStyle = WORLD_OVERLAY_STYLE.background; ctx.fill(); if (selected) { ctx.beginPath(); roundedRectPath(ctx, x + 0.5, y + 0.5, w - 1, h - 1, 4); ctx.strokeStyle = accentColors.border; ctx.lineWidth = 1; ctx.stroke(); } ctx.beginPath(); roundedRectPath(ctx, x, y, w, 2, 1); ctx.fillStyle = accentColors.rule; ctx.fill(); ctx.textAlign = 'left'; ctx.textBaseline = 'alphabetic'; ctx.fillStyle = WORLD_OVERLAY_STYLE.title; ctx.font = selected ? WORLD_OVERLAY_STYLE.fontSelected : WORLD_OVERLAY_STYLE.fontTitle; const titleBaseline = y + layout.padY + layout.titleH - 2; ctx.fillText(String(entry.title || ''), x + layout.padX, titleBaseline); ctx.fillStyle = WORLD_OVERLAY_STYLE.detail; ctx.font = WORLD_OVERLAY_STYLE.fontDetail; for (let i = 0; i < details.length; i++) { ctx.fillText( String(details[i]), x + layout.padX, titleBaseline + (i + 1) * layout.lineH, ); } ctx.restore(); return placement.rect; } /** Paint a compact ambient label. */ export function paintLabel(ctx, entry, placement, alpha = 1) { ctx.save(); ctx.globalAlpha = alpha; drawCardChrome(ctx, entry, placement, false); ctx.fillStyle = WORLD_OVERLAY_STYLE.title; ctx.font = WORLD_OVERLAY_STYLE.fontLabel; ctx.textBaseline = 'top'; ctx.fillText( String(entry.title || ''), placement.rect.x + 6, placement.rect.y + 4, ); ctx.restore(); return placement.rect; } /** Paint a compact track label with optional inline detail. */ export function paintTrack(ctx, entry, placement, alpha = 1) { ctx.save(); ctx.globalAlpha = alpha; drawCardChrome(ctx, entry, placement, false); ctx.fillStyle = WORLD_OVERLAY_STYLE.title; ctx.font = WORLD_OVERLAY_STYLE.fontTrack; ctx.textBaseline = 'top'; ctx.fillText( trackDisplayText(entry), placement.rect.x + 6, placement.rect.y + 4, ); ctx.restore(); return placement.rect; } /** Paint a standard detail card, with an opt-in staged anchor/leader reveal. */ export function paintCard( ctx, entry, placement, alpha = 1, leaderProgress = 1, contentAlpha = 1, ) { ctx.save(); ctx.globalAlpha = alpha; if (entry.anchorDot) { drawLeader( ctx, placement, entry.accent || WORLD_OVERLAY_STYLE.accent, leaderProgress, WORLD_OVERLAY_STYLE.leaderWidth, entry.leaderStyle, ); drawAnchorDot(ctx, entry, placement); ctx.globalAlpha = alpha * Math.max(0, Math.min(1, Number(contentAlpha) || 0)); drawCardChrome(ctx, entry, placement, false, false); } else { drawCardChrome(ctx, entry, placement, false); } drawCardText(ctx, entry, placement, false); ctx.restore(); return placement.rect; } /** Paint a thumbnail card. The image slot remains source-owned. */ export function paintThumbnail( ctx, entry, placement, alpha = 1, leaderProgress = 1, contentAlpha = 1, ) { const layout = entry._overlayLayout || {}; const { x, y, w, h } = placement.rect; const padX = Number.isFinite(layout.padX) ? layout.padX : 4; const padY = Number.isFinite(layout.padY) ? layout.padY : 4; const thumbW = layout.thumbW || Number(entry.thumbnailWidth) || 96; const thumbH = layout.thumbH || Number(entry.thumbnailHeight) || 54; const titleH = Number.isFinite(layout.titleH) ? layout.titleH : 13; const image = entry.image?.frame ?? entry.image; ctx.save(); ctx.globalAlpha = alpha; drawLeader( ctx, placement, entry.thumbnailLeaderColor || WORLD_OVERLAY_STYLE.leader, leaderProgress, entry.anchorDot ? WORLD_OVERLAY_STYLE.leaderWidth : 1, entry.leaderStyle, ); drawAnchorDot(ctx, entry, placement); ctx.globalAlpha = alpha * Math.max(0, Math.min(1, Number(contentAlpha) || 0)); ctx.beginPath(); roundedRectPath(ctx, x, y, w, h, Number(entry.thumbnailRadius) || 4); ctx.fillStyle = entry.thumbnailBackground || WORLD_OVERLAY_STYLE.background; ctx.fill(); const imageX = x + padX; const imageY = y + padY; if (image && typeof ctx.drawImage === 'function') { try { ctx.drawImage(image, imageX, imageY, thumbW, thumbH); } catch { // A source may replace/close a live image slot between frames. Chrome // and text remain valid; the next source update supplies the next frame. } } const ruleHeight = Math.max(0, Number(entry.thumbnailRuleHeight) || 0); if (ruleHeight > 0) { ctx.beginPath(); roundedRectPath(ctx, x, y, w, ruleHeight, Math.min(1, ruleHeight)); ctx.fillStyle = entry.thumbnailRuleColor || entry.accent || WORLD_OVERLAY_STYLE.accent; ctx.fill(); } const titleChars = Math.max( 0, Math.floor(Number(entry.thumbnailTitleChars) || 0), ); const title = entry._overlayThumbnailTitle || String(entry.title || '').toUpperCase(); ctx.textAlign = 'left'; ctx.textBaseline = 'alphabetic'; ctx.fillStyle = entry.thumbnailTitleColor || WORLD_OVERLAY_STYLE.title; ctx.font = entry.thumbnailTitleFont || WORLD_OVERLAY_STYLE.fontTitle; if (title && titleH > 0) { ctx.fillText( titleChars > 0 ? title.slice(0, titleChars) : title, imageX, imageY + thumbH + titleH - 3, ); } ctx.restore(); return placement.rect; } /** Paint the protected selected-card treatment. */ export function paintSelected(ctx, entry, placement, alpha = 1) { ctx.save(); ctx.globalAlpha = alpha; drawCardChrome(ctx, entry, placement, true); drawCardText(ctx, entry, placement, true); ctx.restore(); return placement.rect; } /** Paint the centered protected tracked-target readout treatment. */ export function paintTracked(ctx, entry, placement, alpha = 1) { const details = Array.isArray(entry.details) ? entry.details : []; const layout = entry._overlayLayout || {}; const { x, y, w, h } = placement.rect; const accent = entry.accent || WORLD_OVERLAY_STYLE.accent; ctx.save(); ctx.globalAlpha = alpha; drawLeader(ctx, placement, accent, 1, 1, entry.leaderStyle); ctx.beginPath(); roundedRectPath(ctx, x, y, w, h, 5); ctx.fillStyle = WORLD_OVERLAY_STYLE.background; ctx.fill(); ctx.beginPath(); roundedRectPath(ctx, x, y, w, 2, 1); ctx.fillStyle = accent; ctx.fill(); ctx.textAlign = 'center'; ctx.textBaseline = 'alphabetic'; const centerX = x + w / 2; const titleBaseline = y + layout.padY + layout.titleH - 2; ctx.fillStyle = WORLD_OVERLAY_STYLE.title; ctx.font = WORLD_OVERLAY_STYLE.fontTrackedTitle; ctx.fillText(String(entry.title || ''), centerX, titleBaseline); ctx.fillStyle = WORLD_OVERLAY_STYLE.detail; ctx.font = WORLD_OVERLAY_STYLE.fontTrackedDetail; for (let i = 0; i < details.length; i++) { ctx.fillText( String(details[i]), centerX, titleBaseline + (i + 1) * layout.lineH, ); } ctx.restore(); return placement.rect; } /** * Paint one ambient detection callout: backing plate, tier accent bar, leader * stub, bright primary text and a dimmer micro-field. * * This is the LEGIBILITY-CRITICAL painter. It runs on the shared normal-blend * canvas rather than the screen-blended sensor surface, because `screen` can * only lighten: a dark plate composited with `screen` over sunlit imagery * resolves to the imagery itself (measured: rgba(2,18,26,0.66) over rgb(230) * yields rgb(230,231,232)), which is why ambient callsigns used to dissolve * into bright ground while the tracked card — always painted on this same * normal-blend canvas — stayed readable in every style. * * Allocation-free by contract: no Path2D, array, or string is constructed here. * It is called once per visible callout per frame. * * @param {CanvasRenderingContext2D} ctx Shared normal-blend canvas context. * @param {object} callout Placement + text, supplied by the detection lane. * @param {number} callout.x Plate left edge, CSS px. * @param {number} callout.y Plate top edge, CSS px. * @param {number} callout.w Plate width, CSS px. * @param {number} callout.h Plate height, CSS px. * @param {number} callout.primaryX Baseline-relative x of the primary text. * @param {number} callout.microX Baseline-relative x of the micro text. * @param {number} callout.baseline Text baseline, CSS px. * @param {number} callout.leadFromX Leader start x. * @param {number} callout.leadFromY Leader start y. * @param {number} callout.leadToX Leader end x. * @param {number} callout.leadToY Leader end y. * @param {string} callout.plate Backing plate fill. * @param {number} [callout.plateScale=1] Backdrop feather: 1 over ground, down * to `SKY_PLATE_SCALE` against sky. Multiplies the PLATE only — the accent * bar, leader and text keep the composed fades, so a feathered callout loses * its box without losing its identity. * @param {string} callout.accent Tier colour for the accent bar and leader. * @param {string} callout.label Primary text fill. * @param {string} callout.primary Primary text. * @param {string} callout.micro Micro-field text ('' when absent). * @param {string} callout.font Primary font. * @param {string} callout.microFont Micro-field font. * @param {number} alpha Composed opacity; already folded through every fade. */ export function paintDetectionCallout(ctx, callout, alpha = 1) { // Scaling globalAlpha rather than rewriting the fill string keeps every // theme's own plate hue and weight, and keeps this painter allocation-free. ctx.globalAlpha = alpha * (callout.plateScale ?? 1); ctx.beginPath(); roundedRectPath(ctx, callout.x, callout.y, callout.w, callout.h, 3); ctx.fillStyle = callout.plate; ctx.fill(); ctx.globalAlpha = alpha; ctx.beginPath(); roundedRectPath(ctx, callout.x, callout.y + 2, 2, callout.h - 4, 1); ctx.fillStyle = callout.accent; ctx.fill(); ctx.globalAlpha = alpha * 0.6; ctx.strokeStyle = callout.accent; ctx.lineWidth = 1; ctx.beginPath(); ctx.moveTo(callout.leadFromX, callout.leadFromY); ctx.lineTo(callout.leadToX, callout.leadToY); ctx.stroke(); ctx.globalAlpha = alpha; ctx.fillStyle = callout.label; ctx.font = callout.font; if (callout.primary) ctx.fillText(callout.primary, callout.primaryX, callout.baseline); if (callout.micro) { ctx.globalAlpha = alpha * 0.8; ctx.font = callout.microFont; ctx.fillText(callout.micro, callout.microX, callout.baseline); } } /** Dispatch a normalized entry to its pure variant painter. */ export function paintOverlayEntry( ctx, entry, placement, alpha = 1, leaderProgress = 1, contentAlpha = 1, ) { if (entry.cardStyle === 'tactical') return paintTacticalCard(ctx, entry, placement, alpha); if (entry.variant === 'tracked') return paintTracked(ctx, entry, placement, alpha); if (entry.selected || entry.variant === 'selected') return paintSelected(ctx, entry, placement, alpha); if (entry.variant === 'thumbnail') { return paintThumbnail( ctx, entry, placement, alpha, leaderProgress, contentAlpha, ); } if (entry.variant === 'card') { return paintCard( ctx, entry, placement, alpha, leaderProgress, contentAlpha, ); } if (entry.variant === 'track') return paintTrack(ctx, entry, placement, alpha); return paintLabel(ctx, entry, placement, alpha); }