merge main f13c60c into feat/voice-outlines

reconcile voice outlines with main f13c60c, retaining German/Japanese,
Operator HUD retirement and Context/Radio cleanup, named-building
containment, courtyard-hole, non-Latin identity, attribution, cancellation
and antimeridian repairs

keep outline callouts above the open voice preview when an above-panel
slot fits without colliding with another callout,
and clip the compact dock location label on narrow screens

src/voice/actionSchemas.js

@@ -248,15 +248,7 @@ const schemas = [
       properties: {
         style: {
           type: 'string',
-          enum: [
-            'normal',
-            'retro',
-            'surveillance',
-            'thermal',
-            'anime',
-            'noir',
-            'snow',
-          ],
+          enum: ['normal', 'retro', 'surveillance', 'thermal', 'anime', 'noir'],
         },
       },
       required: ['style'],

src/voice/actionSchemas.test.mjs

@@ -45,7 +45,9 @@ test('the complete Realtime tool payload pins the manifest-generated layer relea
     // S2 GhostMaps extends the generated layer enums.
     // Panel adds named voice targets and timeout; shared Panel/Cockpit guidance
     // is consolidated without changing either feature's arguments.
-    '9ee82c4214499280c208c93751b19d7b724c81b7727a2d0c6dab0184749fbe15',
+    // Snow leaves the set_visual_style enum.
+    // The Operator HUD layout leaves set_hud's layout enum.
+    'f47a7f78f13b1f79978fa524fad2618e32bd813e1a5dfd746bf35d29909fc91b',
   );
 });
 
@@ -166,9 +168,22 @@ test('all legacy action arguments are byte-identical after removing the delibera
     delete center.properties[axis].minimum;
     delete center.properties[axis].maximum;
   }
-  // Cyber adds one HUD layout.
+  // Cyber adds one HUD layout and Operator was retired.
   const hud = property('set_hud').layout;
-  hud.enum = hud.enum.filter((layout) => layout !== 'cyber');
+  assert.deepEqual(hud.enum, ['tactical', 'minimal', 'cyber']);
+  hud.enum = ['tactical', 'operator', 'minimal'];
+  // Snow is retired from set_visual_style; restore it to keep the legacy pin.
+  const visualStyle = legacy.find((tool) => tool.name === 'set_visual_style')
+    .parameters.properties.style;
+  assert.deepEqual(visualStyle.enum, [
+    'normal',
+    'retro',
+    'surveillance',
+    'thermal',
+    'anime',
+    'noir',
+  ]);
+  visualStyle.enum = [...visualStyle.enum, 'snow'];
   // Derived by applying the same removals to the 4b56d0e9 actionSchemas.
   assert.equal(
     createHash('sha256').update(JSON.stringify(legacy)).digest('hex'),

src/voice/gevActions.js

@@ -12,6 +12,11 @@ import { msg } from '../i18n/index.js';
 import * as Cesium from 'cesium';
 import { CITY_POIS } from '../cityPois.js';
 import { greatCircleKm } from '../geoDistance.js';
+import {
+  hudViewportSamples,
+  placeLookupView,
+  placeLookupViewChanged,
+} from '../hudPlaceLookup.js';
 import {
   findPoiByName,
   flyToGlobeView,
@@ -61,7 +66,6 @@ const ALLOWED_STYLES = new Set([
   'thermal',
   'anime',
   'noir',
-  'snow',
 ]);
 const PANEL_ALIASES = new Map([
   ['data', 'data-panel'],
@@ -2692,13 +2696,20 @@ function runManagedVoiceNavigation(
   };
 }
 
+/**
+ * Place labels for the HUD's passive summary. It geocodes the view center
+ * and one more point. While the view still shows about the same area (see
+ * hudPlaceLookup.js) it answers for the points the last lookup asked about
+ * instead, so a settled camera does not buy a new set of Google requests for
+ * every small pan; those points are cache hits, and only what the last
+ * lookup did not get (a timeout, a failure, an empty answer) is asked again.
+ * `cachedOnly` reads the shared caches and makes no request.
+ */
 export async function getBasemapLabelContext(
   viewer,
   service = defaultGeospatial,
-  { cachedOnly = false } = {},
+  { cachedOnly = false, previous = null } = {},
 ) {
-  const { reverseGeocodeCache, nearbyPlacesCache } = cachesFor(service);
-  const samples = sampleViewportCartographics(viewer);
   const cameraHeightM = viewer.camera.positionCartographic.height;
   const target = getViewTargetCartographic(viewer);
   if (!target) {
@@ -2706,11 +2717,77 @@ export async function getBasemapLabelContext(
       placeLabels: [],
       streetLabels: [],
       nearbyPlaceLabels: [],
+      view: null,
+      lookup: null,
     };
   }
 
   const latitude = Number(Cesium.Math.toDegrees(target.latitude).toFixed(6));
   const longitude = Number(Cesium.Math.toDegrees(target.longitude).toFixed(6));
+  const view = placeLookupView({
+    latitude,
+    longitude,
+    rangeM: viewTargetRangeM(viewer, target, cameraHeightM),
+    fovRad: viewer.camera.frustum?.fov,
+    aspectRatio: viewer.camera.frustum?.aspectRatio,
+    tier: basemapLookupTier(cameraHeightM),
+  });
+  if (
+    !cachedOnly &&
+    previous?.lookup &&
+    !placeLookupViewChanged(previous.view, view)
+  ) {
+    // The same points again: what the last lookup got is a cache hit, and
+    // only what it did not (a timeout, a failure, an empty answer) is asked.
+    const labels = await basemapLabelsAt(previous.lookup, service, {
+      cachedOnly: false,
+    });
+    return { ...labels, view: previous.view, lookup: previous.lookup };
+  }
+  const samples = sampleViewportCartographics(viewer);
+  const lookup = {
+    latitude,
+    longitude,
+    cameraHeightM,
+    // Cache reads are free, so a cached-only host keeps every sample.
+    samples: cachedOnly
+      ? samples
+      : hudViewportSamples(samples, shouldReverseGeocode(cameraHeightM)),
+  };
+  return {
+    ...(await basemapLabelsAt(lookup, service, { cachedOnly })),
+    view,
+    lookup,
+  };
+}
+
+/** Which of the height-gated lookups a camera height calls for. */
+function basemapLookupTier(cameraHeightM) {
+  return [
+    shouldReverseGeocode(cameraHeightM),
+    shouldReverseGeocodeViewport(cameraHeightM) && cameraHeightM > 10000,
+    shouldFetchNearbyPlaces(cameraHeightM) &&
+      nearbyPlacesRadiusM(cameraHeightM),
+  ].join(':');
+}
+
+/** Camera distance to the view target, or the camera height without one. */
+function viewTargetRangeM(viewer, target, cameraHeightM) {
+  const position = viewer.camera.positionWC;
+  if (!position) return cameraHeightM;
+  const range = Cesium.Cartesian3.distance(
+    position,
+    Cesium.Cartographic.toCartesian(target),
+  );
+  return Number.isFinite(range) ? range : cameraHeightM;
+}
+
+async function basemapLabelsAt(
+  { latitude, longitude, cameraHeightM, samples },
+  service,
+  { cachedOnly },
+) {
+  const { reverseGeocodeCache, nearbyPlacesCache } = cachesFor(service);
   const cachedViewportPlaces = viewportPlacesFromCache(
     samples,
     cameraHeightM,
@@ -2748,7 +2825,6 @@ export async function getBasemapLabelContext(
     resolveWithin(placePromise, BASEMAP_CONTEXT_WAIT_MS, null),
     resolveWithin(nearbyPromise, BASEMAP_CONTEXT_WAIT_MS, []),
   ]);
-
   return {
     placeLabels: uniqueStrings([
       place?.formattedAddress,

src/voice/hudPlaceLabels.test.mjs

@@ -0,0 +1,359 @@
+// The HUD's passive place lookup spends paid Google requests on its own, so
+// it must look up the view center and one more point, and only again once the
+// view shows a different area.
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import * as Cesium from 'cesium';
+import { getBasemapLabelContext } from './gevActions.js';
+import {
+  hudViewportSamples,
+  placeLookupView,
+  placeLookupViewChanged,
+} from '../hudPlaceLookup.js';
+
+globalThis.window = globalThis.window || { setTimeout, clearTimeout };
+
+/**
+ * A looking-down camera `heightM` above the ellipsoid. Ellipsoid picks map
+ * screen pixels linearly to degrees; the view target sits on terrain
+ * `groundM` high under the camera.
+ */
+function createViewer({ latitude, longitude, heightM, groundM = 0 }) {
+  const state = { latitude, longitude, heightM, groundM };
+  const canvas = { clientWidth: 1200, clientHeight: 800 };
+  const degreesPerPixel = () => state.heightM / 111_000 / canvas.clientHeight;
+  const camera = {
+    heading: 0,
+    pitch: -Math.PI / 2,
+    frustum: { fov: Math.PI / 3, aspectRatio: 1.5 },
+    pickEllipsoid(point) {
+      return Cesium.Cartesian3.fromDegrees(
+        state.longitude +
+          (point.x - canvas.clientWidth / 2) * degreesPerPixel(),
+        state.latitude -
+          (point.y - canvas.clientHeight / 2) * degreesPerPixel(),
+      );
+    },
+  };
+  Object.defineProperties(camera, {
+    positionCartographic: {
+      get: () =>
+        Cesium.Cartographic.fromDegrees(
+          state.longitude,
+          state.latitude,
+          state.heightM,
+        ),
+    },
+    positionWC: {
+      get: () =>
+        Cesium.Cartesian3.fromDegrees(
+          state.longitude,
+          state.latitude,
+          state.heightM,
+        ),
+    },
+  });
+  const scene = {
+    canvas,
+    pickPositionSupported: true,
+    pickPosition: () =>
+      Cesium.Cartesian3.fromDegrees(
+        state.longitude,
+        state.latitude,
+        state.groundM,
+      ),
+  };
+  return { viewer: { camera, scene }, state, degreesPerPixel };
+}
+
+/** Answers every lookup with a label naming the point it was asked about. */
+function createService() {
+  const calls = { reverse: 0, nearby: 0 };
+  return {
+    calls,
+    async reverseGeocode(latitude, longitude) {
+      calls.reverse += 1;
+      const point = `${latitude.toFixed(4)},${longitude.toFixed(4)}`;
+      return { formattedAddress: `Place ${point}`, labels: [`Area ${point}`] };
+    },
+    async nearby() {
+      calls.nearby += 1;
+      return [{ name: `Nearby ${calls.nearby}` }];
+    },
+  };
+}
+
+test('a view counts as new after a quarter-width move or a doubled distance', () => {
+  const view = placeLookupView({ latitude: 30, longitude: -97, rangeM: 1000 });
+  // A 60° field of view at 1 km shows about 1155 m across.
+  assert.ok(Math.abs(view.spanM - 1154.7) < 1);
+  const near = placeLookupView({
+    latitude: 30.002,
+    longitude: -97,
+    rangeM: 1100,
+  });
+  assert.equal(
+    placeLookupViewChanged(view, near),
+    false,
+    '~220 m is under a quarter width',
+  );
+  const far = placeLookupView({
+    latitude: 30.003,
+    longitude: -97,
+    rangeM: 1000,
+  });
+  assert.equal(
+    placeLookupViewChanged(view, far),
+    true,
+    '~330 m is over a quarter width',
+  );
+  const closer = placeLookupView({ latitude: 30, longitude: -97, rangeM: 500 });
+  assert.equal(placeLookupViewChanged(view, closer), true);
+  const farther = placeLookupView({
+    latitude: 30,
+    longitude: -97,
+    rangeM: 2000,
+  });
+  assert.equal(placeLookupViewChanged(view, farther), true);
+  assert.equal(placeLookupViewChanged(null, view), true);
+  // The antimeridian is a short hop, not a world away.
+  const west = placeLookupView({
+    latitude: 0,
+    longitude: 179.9999,
+    rangeM: 1000,
+  });
+  const east = placeLookupView({
+    latitude: 0,
+    longitude: -179.9999,
+    rangeM: 1000,
+  });
+  assert.equal(placeLookupViewChanged(west, east), false);
+});
+
+test('a portrait screen measures its narrower width', () => {
+  const landscape = placeLookupView({
+    latitude: 0,
+    longitude: 0,
+    rangeM: 1000,
+    aspectRatio: 1.5,
+  });
+  const portrait = placeLookupView({
+    latitude: 0,
+    longitude: 0,
+    rangeM: 1000,
+    aspectRatio: 0.5,
+  });
+  assert.ok(Math.abs(landscape.spanM - 1154.7) < 1);
+  assert.ok(Math.abs(portrait.spanM - 577.4) < 1);
+});
+
+test('a view in another height tier is new however close it is', () => {
+  const a = placeLookupView({
+    latitude: 0,
+    longitude: 0,
+    rangeM: 1000,
+    tier: 'x',
+  });
+  const b = placeLookupView({
+    latitude: 0,
+    longitude: 0,
+    rangeM: 1000,
+    tier: 'y',
+  });
+  assert.equal(placeLookupViewChanged(a, b), true);
+});
+
+test('the HUD geocodes one viewport point besides the center', () => {
+  const samples = [{ i: 0 }, { i: 1 }, { i: 2 }];
+  assert.deepEqual(hudViewportSamples(samples, true), [{ i: 1 }]);
+  assert.deepEqual(hudViewportSamples(samples, false), [{ i: 0 }, { i: 1 }]);
+  assert.deepEqual(hudViewportSamples([], true), []);
+});
+
+test('a regional view spends two reverse geocodes and a nearby search', async () => {
+  const { viewer } = createViewer({
+    latitude: 30.26,
+    longitude: -97.74,
+    heightM: 20_000,
+  });
+  const service = createService();
+  const labels = await getBasemapLabelContext(viewer, service);
+  // Before: the center plus three viewport samples (the first of them the
+  // center again, which shares its cache key in this stub).
+  assert.deepEqual(service.calls, { reverse: 2, nearby: 1 });
+  assert.ok(labels.placeLabels.length > 0);
+});
+
+test('a small pan reuses the last lookup; a real move looks up again', async () => {
+  const { viewer, state } = createViewer({
+    latitude: 30.26,
+    longitude: -97.74,
+    heightM: 600,
+  });
+  const service = createService();
+  const first = await getBasemapLabelContext(viewer, service);
+  assert.deepEqual(service.calls, { reverse: 1, nearby: 1 });
+
+  state.latitude += 0.0005; // ~55 m at 600 m height
+  const panned = await getBasemapLabelContext(viewer, service, {
+    previous: first,
+  });
+  assert.deepEqual(
+    panned.placeLabels,
+    first.placeLabels,
+    'the same area keeps its labels',
+  );
+  assert.deepEqual(service.calls, { reverse: 1, nearby: 1 });
+
+  state.latitude += 0.002; // ~280 m from the first lookup
+  const moved = await getBasemapLabelContext(viewer, service, {
+    previous: panned,
+  });
+  assert.notDeepEqual(moved.placeLabels, first.placeLabels);
+  assert.deepEqual(service.calls, { reverse: 2, nearby: 2 });
+});
+
+test('over high terrain the visible width is measured from the ground', async () => {
+  // 100 m above a 3000 m plateau shows ~115 m across, not the ~3.6 km a
+  // 3100 m ellipsoid height would suggest.
+  const { viewer, state } = createViewer({
+    latitude: 30.26,
+    longitude: -97.74,
+    heightM: 3100,
+    groundM: 3000,
+  });
+  const service = createService();
+  const first = await getBasemapLabelContext(viewer, service);
+  state.latitude += 0.0045; // ~500 m
+  await getBasemapLabelContext(viewer, service, { previous: first });
+  assert.equal(service.calls.reverse, 2);
+});
+
+test('crossing into the Nearby Places height looks up again', async () => {
+  const { viewer, state } = createViewer({
+    latitude: 30.26,
+    longitude: -97.74,
+    heightM: 30_000,
+  });
+  const service = createService();
+  const high = await getBasemapLabelContext(viewer, service);
+  assert.equal(service.calls.nearby, 0);
+  state.heightM = 20_000; // a 1.5× zoom, under the distance rule
+  const low = await getBasemapLabelContext(viewer, service, { previous: high });
+  assert.equal(service.calls.nearby, 1);
+  assert.ok(low.nearbyPlaceLabels.length > 0);
+});
+
+test('a lookup that timed out is completed from the cache, not frozen', async () => {
+  const { viewer, state } = createViewer({
+    latitude: 30.26,
+    longitude: -97.74,
+    heightM: 600,
+  });
+  const service = createService();
+  let answer;
+  service.reverseGeocode = () => {
+    service.calls.reverse += 1;
+    return new Promise((resolve) => {
+      answer = resolve;
+    });
+  };
+  // Expire the 1.5 s wait at once.
+  const { setTimeout: wait } = globalThis.window;
+  globalThis.window.setTimeout = (fn) => wait(fn, 0);
+  let first;
+  try {
+    first = await getBasemapLabelContext(viewer, service);
+  } finally {
+    globalThis.window.setTimeout = wait;
+  }
+  assert.deepEqual(first.placeLabels, []);
+  assert.ok(
+    first.nearbyPlaceLabels.length > 0,
+    'the nearby answer arrived in time',
+  );
+
+  answer({ formattedAddress: 'Late place', labels: [] });
+  await new Promise((resolve) => setImmediate(resolve));
+  state.latitude += 0.0005;
+  const next = await getBasemapLabelContext(viewer, service, {
+    previous: first,
+  });
+  assert.deepEqual(next.placeLabels, ['Late place']);
+  assert.deepEqual(
+    service.calls,
+    { reverse: 1, nearby: 1 },
+    'the late answer is a cache hit',
+  );
+});
+
+test('an empty answer is asked again rather than held', async () => {
+  const { viewer, state } = createViewer({
+    latitude: 30.26,
+    longitude: -97.74,
+    heightM: 600,
+  });
+  const service = createService();
+  service.reverseGeocode = async () => {
+    service.calls.reverse += 1;
+    return null;
+  };
+  const empty = await getBasemapLabelContext(viewer, service);
+  state.latitude += 0.0005;
+  await getBasemapLabelContext(viewer, service, { previous: empty });
+  assert.deepEqual(
+    service.calls,
+    { reverse: 2, nearby: 1 },
+    'the cached nearby answer is not asked again',
+  );
+});
+
+test('a failed lookup is asked again once the provider recovers', async () => {
+  const { viewer, state } = createViewer({
+    latitude: 30.26,
+    longitude: -97.74,
+    heightM: 600,
+  });
+  const service = createService();
+  const working = service.reverseGeocode;
+  service.reverseGeocode = async () => {
+    service.calls.reverse += 1;
+    throw new Error('503');
+  };
+  const failed = await getBasemapLabelContext(viewer, service);
+  assert.deepEqual(failed.placeLabels, []);
+
+  service.reverseGeocode = working;
+  state.latitude += 0.0005;
+  const recovered = await getBasemapLabelContext(viewer, service, {
+    previous: failed,
+  });
+  assert.ok(recovered.placeLabels.length > 0);
+  assert.deepEqual(
+    service.calls,
+    { reverse: 2, nearby: 1 },
+    'only the failed geocode is asked again',
+  );
+});
+
+test('cached-only lookups read every cached viewport sample and never request', async () => {
+  const { viewer, state, degreesPerPixel } = createViewer({
+    latitude: 30.26,
+    longitude: -97.74,
+    heightM: 20_000,
+  });
+  const service = createService();
+  // Geocode view A's upper-left sample (screen x = 300).
+  const a = await getBasemapLabelContext(viewer, service);
+  const cachedLabel = a.placeLabels.find(
+    (label) => label.startsWith('Area') && label !== 'Area 30.2600,-97.7400',
+  );
+  assert.ok(cachedLabel, 'the upper-left sample was geocoded');
+  // View B puts that same point at its upper-right sample (screen x = 900),
+  // which only a read of every sample finds.
+  state.longitude -= 600 * degreesPerPixel();
+  const before = { ...service.calls };
+  const b = await getBasemapLabelContext(viewer, service, { cachedOnly: true });
+  assert.ok(b.placeLabels.includes(cachedLabel));
+  assert.deepEqual(service.calls, before);
+});

src/voice/realtimeConnection.js

@@ -376,6 +376,10 @@ export class RealtimeConnection {
       this.stream = null;
     }
     if (this.audioEl) {
+      // This session owns the element's remote media; peer closure is not track release.
+      const remoteStream = this.audioEl.srcObject;
+      this.audioEl.srcObject = null;
+      remoteStream?.getTracks?.().forEach((track) => track.stop());
       this.audioEl.remove();
       this.audioEl = null;
     }

src/voice/realtimeOwners.test.mjs

@@ -53,6 +53,10 @@ function browser(t) {
 test('retained peer and channel callbacks cannot act after stop or enter a replacement session', async (t) => {
   const { peers, streams } = browser(t);
   const actions = [];
+  const remote = () => {
+    const track = { stops: 0, readyState: 'live', stop() { this.stops++; this.readyState = 'ended'; } };
+    return { getTracks: () => [track], track };
+  };
   const controller = new GevRealtimeController({
     runner: async (name) => { actions.push(name); return { ok: true }; },
     backend: {
@@ -66,28 +70,38 @@ test('retained peer and channel callbacks cannot act after stop or enter a repla
   const old = peers[0];
   old.channel.handlers.get('open')();
   assert.equal(controller.status, 'listening');
+  const oldAudio = controller.audioEl;
+  const oldRemote = remote();
+  old.ontrack({ streams: [oldRemote] });
   const message = { data: JSON.stringify({ type: 'response.function_call_arguments.done', name: 'get_entity_context', call_id: 'stale', arguments: '{}' }) };
   controller.stop();
+  assert.equal(oldRemote.track.stops, 1, 'Stop releases its owned remote track');
+  assert.equal(oldRemote.track.readyState, 'ended');
+  assert.equal(oldAudio.srcObject, null);
   assert.doesNotThrow(() => old.ontrack({ streams: [{}] }));
   await old.channel.handlers.get('message')(message);
   await controller.start();
   const current = peers[1];
   current.channel.handlers.get('open')();
   const audio = controller.audioEl;
+  const incoming = remote();
+  current.ontrack({ streams: [incoming] });
   old.channel.readyState = 'open'; // Model an already queued callback from the old transport.
   old.channel.handlers.get('open')();
   await old.channel.handlers.get('message')(message);
-  old.ontrack({ streams: [{}] });
+  old.ontrack({ streams: [oldRemote] });
   old.onicecandidateerror({ errorText: 'stale error' });
   assert.equal(controller.status, 'listening');
   assert.equal(controller.pc, current);
   assert.equal(controller.audioEl, audio);
-  assert.equal(audio.srcObject, undefined);
+  assert.equal(audio.srcObject, incoming, 'a stale track cannot replace the current remote stream');
+  assert.equal(incoming.track.stops, 0, 'a stale callback cannot stop the current remote track');
   assert.deepEqual(actions, []);
-  const incoming = {};
-  current.ontrack({ streams: [incoming] });
-  assert.equal(audio.srcObject, incoming, 'the current peer still delivers audio');
   controller.stop();
+  controller.stop();
+  assert.equal(audio.srcObject, null);
+  assert.deepEqual([oldRemote, incoming].map(s => s.track.stops), [1, 1], 'repeated Stop does not restop remote tracks');
+  assert.equal(incoming.track.readyState, 'ended');
   assert.deepEqual(streams.map(s => s.track.stops), [1, 1]);
 });
 

src/voice/speech.js

@@ -963,7 +963,10 @@ export function progressStepLabel(step, label) {
     : step
       ? spokenLabel(step, 24)
       : t('Working');
-  return label ? `${base}: ${spokenLabel(label, 32)}` : base;
+  // The join is a catalog string so each language spaces its colon.
+  return label
+    ? t('{name}: {state}', { name: base, state: spokenLabel(label, 32) })
+    : base;
 }
 
 /**

src/voice/speech.test.mjs

@@ -9,6 +9,7 @@ import {
   spokenLabel,
 } from './speech.js';
 import { countWords, findHedges } from './speechLint.js';
+import { setLocale } from '../i18n/index.js';
 
 function envelope(name, result, args) {
   return attachVoiceResult(name, result, args);
@@ -459,3 +460,15 @@ test('labels are bounded and cleaned before they are spoken', () => {
     'background steps stay on screen',
   );
 });
+
+test('progress step labels join through the catalog colon', () => {
+  setLocale('fr');
+  try {
+    assert.equal(
+      progressStepLabel('resolve', 'Capitol'),
+      'Recherche de lieux\u202f: Capitol',
+    );
+  } finally {
+    setLocale('en');
+  }
+});