fix(osm): stop using public Overpass by default (#648) (#742)

Traffic roads come from OpenFreeMap vector tiles, or TomTom flow tiles with a
key (Hybrid by default). Military areas use OpenFreeMap polygons with a bundled
worldwide name index; wide views show named points. ALPR reads an hourly
OpenStreetMap extract. Cockpit place context and country, state and US county
outlines use bundled Natural Earth and US Census data. Overpass is used only
when an operator configures their own endpoint.

Also: camera arrivals no longer land below ground, keyless terrain retries on
429, bounded relation geometry for configured Overpass, one shared
OpenStreetMap credit, and separate tile and API transports for embedders.

Co-authored-by: theGaryLarson <[email protected]>
Co-authored-by: Milan Khanal <[email protected]>

src/overlays/worldOverlay.js

@@ -143,6 +143,7 @@ export const WORLD_OVERLAY_OCCLUDER_SELECTORS = Object.freeze([
  * @property {number} [alpha=1]
  * @property {number} [cohortLimit=256] Ambient surplus retained per domain.
  * @property {number} [collisionCapacity=96] Shared domain paint budget.
+ * @property {number} [maxVisible=Infinity] Source ceiling within a shared domain.
  * @property {boolean} [moving=false] Enables bounded interval re-solves.
  * @property {number} [solveIntervalMs=125]
  */
@@ -696,6 +697,10 @@ function normalizeSourceOptions(options = {}, previous = {}) {
     collisionCapacity: Number.isFinite(requestedCapacity)
       ? Math.max(0, Math.floor(requestedCapacity))
       : DEFAULT_COLLISION_CAPACITY,
+    maxVisible: Math.max(
+      0,
+      options.maxVisible ?? previous.maxVisible ?? Infinity,
+    ),
     moving:
       options.moving !== undefined
         ? options.moving === true
@@ -786,6 +791,7 @@ function getOrCreateDomain(domainId) {
       sepCount: 0,
       renderEntries: [],
       demandBySource: new Map(),
+      limitsBySource: new Map(),
       capacity: DEFAULT_COLLISION_CAPACITY,
       lastSolveAt: Number.NEGATIVE_INFINITY,
       moving: false,
@@ -951,6 +957,9 @@ export function setOverlayEntries(sourceId, entries, options = {}) {
   for (const entry of normalized) next.set(entry.id, entry);
   for (const entry of source.entries.values()) {
     if (!next.has(entry.id)) _records.delete(entry._overlayKey);
+    const replacement = next.get(entry.id);
+    if (replacement && isProtected(entry) !== isProtected(replacement))
+      getOrCreateDomain(entry.collisionGroup).arbiter.remove(entry._overlayKey);
   }
   source.entries = next;
   rebuildSourceCohorts(source);
@@ -2122,6 +2131,7 @@ function collectFrameCandidates(keyhole, viewProjection) {
         source.id,
         source.demandByDomain.get(domainId) || 0,
       );
+      domain.limitsBySource.set(source.id, source.options.maxVisible);
       candidateCount += cohort.length;
       for (let i = 0; i < cohort.length; i++) {
         const entry = cohort[i];
@@ -2289,6 +2299,7 @@ function solveDomains(timestamp) {
       domain.arbiter.solve(domain.candidates, {
         capacity: Math.min(domain.capacity, domain.candidates.length),
         demandByLayer: domain.demandBySource,
+        limitsByLayer: domain.limitsBySource,
         now: timestamp,
         // The host publishes its own pooled counters below, so duplicating a
         // per-layer diagnostic object in the arbiter adds no observable data.
@@ -2311,6 +2322,7 @@ function solveDomains(timestamp) {
       domain.candidateMap,
       timestamp,
       domain.renderEntries,
+      domain.limitsBySource,
     );
     for (let r = 0; r < rendered.length; r++) {
       const renderedEntry = rendered[r];

src/overlays/worldOverlay.test.mjs

@@ -1,3 +1,4 @@
+import { createNamedMarkers } from '../layers/installations/namedMarkers.js';
 import { expandApplicationHtml } from '../../build/application-html.js';
 import { readStylesheet } from '../testSupport/readStylesheet.mjs';
 import test from 'node:test';
@@ -2223,3 +2224,76 @@ test('diagnostics facade preserves the complete binding shape', () => {
   ];
   assert.deepEqual(Object.keys(diagnostics).sort(), fields.sort());
 });
+
+
+test('installation titles share persistent card arbitration and retain a bounded Contacts cohort', (t) => {
+  const env = installMockEnvironment({ width: 1600, height: 1000 });
+  t.after(() => env.cleanup());
+  const scene = env.viewer.scene;
+  scene.canvas = env.viewer.canvas;
+  scene.preRender = new Cesium.Event();
+  scene.primitives = { add: (value) => value, remove() {} };
+  env.viewer.camera.changed = new Cesium.Event();
+  t.mock.method(Cesium.Cartesian3, 'fromDegrees', (lon, lat) => new Cesium.Cartesian3(lon, lat, 0));
+  t.mock.method(Cesium.EllipsoidalOccluder.prototype, 'isPointVisible', () => true);
+  t.mock.method(Cesium.SceneTransforms, 'worldToWindowCoordinates', (_scene, _point, scratch) => {
+    scratch.x = scratch.y = 100; return scratch;
+  });
+  const state = { enabled: true, viewer: env.viewer, contextAnchor: {} };
+  const markers = createNamedMarkers({ state,
+    services: { render: { governorRequestRender() {} } },
+    parts: { model: { colorFor: () => Cesium.Color.ORANGE }, rendering: { installationSurfaceHeightM: () => 0 } },
+    overlayHost: { setEntries: setOverlayEntries, clearSource: clearOverlaySource,
+      setVisible: setOverlaySourceVisible, getDiagnostics: getWorldOverlayDiagnostics },
+  });
+  initWorldOverlay(env.viewer);
+  markers.enable();
+  const records = Array.from({ length: 40 }, (_, i) => ({ id: `site:${i}`, name: `Base ${i}`,
+    namedArea: true, pointOnly: i % 2 === 0, areaM2: 1000 - i,
+    longitude: -0.8 + (i % 8) * 0.22, latitude: -0.7 + Math.floor(i / 8) * 0.32,
+  }));
+  // The smaller coincident title must lose to the larger installation.
+  records.push({ ...records[0], id: 'small', areaM2: 1 });
+  records[1].longitude = records[0].longitude + 0.03;
+  records[1].latitude = records[0].latitude;
+  markers.sync(records);
+  env.postRender.raise();
+  const source = 'military-installations';
+  env.advanceTime(250); env.postRender.raise();
+  assert.equal(markers.stats().labelsOnScreen, 24);
+  assert.ok(getOverlayPaintRect(source, 'site:0'));
+  assert.equal(getOverlayPaintRect(source, 'small'), null);
+  for (let i = 0; i < 30; i++) {
+    env.viewer.camera.viewMatrix[12] -= 0.003;
+    if (i > 15) env.viewer.camera.viewMatrix[0] = env.viewer.camera.viewMatrix[5] = 0.03;
+    scene.preRender.raiseEvent(); env.advanceTime(16); env.postRender.raise();
+    assert.ok(markers.stats().labelsOnScreen > 0 && markers.stats().labelsOnScreen <= 24);
+    // Incumbents persist through collisions during a pan, as for Data Centers.
+    if (i < 10) assert.ok(getOverlayPaintRect(source, 'site:0'));
+  }
+  state.enabled = false; markers.hide(); env.postRender.raise();
+  assert.equal(getWorldOverlayDiagnostics().entriesBySource[source], 0);
+  assert.equal(markers.stats().labelsOnScreen, 0);
+  state.enabled = true; markers.enable(); env.postRender.raise();
+  env.advanceTime(250); env.postRender.raise();
+  assert.ok(markers.stats().labelsOnScreen > 0);
+  markers.destroy(); env.postRender.raise();
+  assert.equal(getWorldOverlayDiagnostics().entriesBySource[source], 0);
+});
+
+
+test('promoting an ambient entry to selected paints it once with no fading duplicate', () => {
+  const env = installMockEnvironment();
+  try {
+    initWorldOverlay(env.viewer);
+    const entry = { id: 'site', position: position(), title: 'One site', variant: 'card', collisionGroup: 'ambient-card', horizonCull: false, edgeFade: false };
+    const paint = () => { env.ctx.calls.length = 0; env.postRender.raise(); return env.ctx.calls.filter(([op, text]) => op === 'fillText' && text === 'One site').length; };
+    setOverlayEntries('military-installations', [entry]); paint(); env.advanceTime(200);
+    assert.equal(paint(), 1);
+    setOverlayEntries('military-installations', [{ ...entry, variant: 'selected', selected: true }]);
+    assert.equal(paint(), 1, 'no ambient exit tail in the selected paint lane');
+    env.advanceTime(100); assert.equal(paint(), 1);
+    setOverlayEntries('military-installations', [entry]); paint(); env.advanceTime(200);
+    assert.equal(paint(), 1, 'deselect restores the ambient card without re-entry cooldown');
+  } finally { env.cleanup(); }
+});