Bring comments in line with the single application and the Navara capabilities

src/app/catalog.js

@@ -70,8 +70,8 @@ export function catalogControlServices(catalog) {
 }
 
 /**
- * Layer roles for controls on a page without data layers (the experimental
+ * Layer roles for controls on a page without data layers: one empty object
- * Navara engine): one empty object per role, so the shell's optional calls
+ * per role, so the shell's optional calls
  * (`layer.method?.()`) do nothing.
  */
 export function absentLayerControlServices() {

src/app/navaraMode.js

@@ -408,10 +408,10 @@ export async function createNavaraScene({
 
 /**
  * The tools without a viewer (the experimental Navara engine), attached to
- * one Navara scene: the render governor on the engine, hidden-tab handling,
+ * one Navara scene: the render governor, hidden-tab handling, imagery box,
- * the imagery box, the engine notice and voice on the engine. The shell
+ * engine notice, annotations, Draw, Import, scope mask and voice. The shared
- * shows which features are unavailable. Returns its annotations (none) and
+ * tools keep their session state across engines. Returns the annotation
- * voice.
+ * board (null without a Navara view) and voice commands.
  */
 export function attachViewerlessTools(
   { engine, mapStackController = null },
@@ -497,8 +497,8 @@ export function attachViewerlessTools(
   attachNavaraDraw(tools, { ...context, annotations }, { signal, defer });
   attachNavaraGeoImport(tools, context, { signal, defer });
   attachNavaraScopeMask(tools, context, { signal, defer });
-  // Voice on the engine (phase 3, Task 9): the W1 tools drive the engine;
+  // Voice uses the engine and shared session services; each action checks
-  // the Director uses the shared session; viewer-only tools declare availability.
+  // the capabilities it needs on the attached scene.
   const voiceCommands = attachSessionVoice({
     layerSession,
     voice,

src/app/tools.js

@@ -29,10 +29,9 @@ import {
  * handle belong to the application; the tools bound to one globe (render
  * governor, release trim, scope mask, imagery box, tracking and visibility
  * listeners, embedded views, the debug handle's globe fields) attach to each
- * engine the page shows (src/app/sceneParts.js). Without a viewer (the
+ * engine the page shows (src/app/sceneParts.js). Navara attaches the shared
- * experimental Navara engine) the viewer-bound tools are not attached and
+ * annotation board, Draw, Import, scope mask and voice through its engine
- * their handles are null; voice runs on the engine there
+ * adapters (src/app/navaraMode.js); the Director follows the attached engine.
- * (src/app/navaraMode.js).
  */
 export async function createApplicationTools({
   scene,

src/app/viewerlessTools.test.mjs

@@ -110,7 +110,7 @@ test('without a viewer the tools run the governor on the engine, show the notice
   assert.equal(tools.annotations, null);
   assert.ok(tools.voiceCommands, 'voice runs on the engine');
   assert.equal(window.__gevVoiceCommands, tools.voiceCommands);
-  // The W1 tools drive the engine; the viewer-only ones refuse.
+  // View queries use the engine, and scene commands use the shared Director.
   const view = await voice.runner('get_current_view_state');
   assert.equal(view.ok, true);
   const scene = await voice.runner('control_scene', {

src/globe/contract.js

@@ -1,5 +1,5 @@
 // The engine-neutral globe contract. The application shell talks to a globe
-// engine (Cesium today, Navara next) only through these small capability
+// engine (Cesium or Navara) only through these small capability
 // objects. Positions are src/geo values in Earth-fixed metres, angles are
 // radians and screen coordinates are CSS pixels from the canvas's top-left
 // corner. This module and src/globe/testing/** never import cesium, three or

src/globe/navara/lines/index.js

@@ -1,8 +1,8 @@
 // engine.lines on Navara: each line is a ribbon (lineMesh.js) in gev's
 // overlay (overlay.js: drawn after tone mapping, so its colour is exact). Geodesic arcs are densified on the CPU (src/globe/lines.js)
 // since the ribbon draws straight segments. Every change asks for one frame;
-// nothing animates on its own, so an idle view stays idle. Lines are not
+// nothing animates on its own, so an idle view stays idle. Shown lines with
-// pickable on Navara yet (trails never take a click; see phase 3 Task 4).
+// a pickId participate in the engine's CPU picks; trails omit a pickId.
 
 import { createLineRegistry, densifyGeodesic } from '../../lines.js';
 import { createLineMesh } from './lineMesh.js';

src/scenes/director.js

@@ -1450,7 +1450,7 @@ export class SceneDirector {
     return travel;
   }
 
-  /** Publish a travel phase only after Cesium has accepted the camera flight. */
+  /** Publish a travel phase only after the globe engine has accepted the camera flight. */
   _publishShotTravel(scene, shot, cameraTravel) {
     const states = this._layerStatesForShot(scene, shot, { cameraTravel });
     for (const [layerId, state] of Object.entries(states)) {

src/standalone/engineSwitch.js

@@ -57,8 +57,8 @@ export function createEngineSwitch({
 }) {
   // The engine whose session is live, null while none is.
   let current = kind;
-  // The engine whose application exists or is starting: what a history visit
+  // The engine attached to the application or starting to attach: what a
-  // would leave.
+  // history visit would leave.
   let live = kind;
   // The last engine that started successfully: the rollback target.
   let working = kind;

src/ui/layerBindings.js

@@ -82,7 +82,7 @@ export class LayerBindings {
       window,
       this._worldRequestFocusHandler,
     );
-    // Entity tracking is the viewer's (no viewer on the Navara engine).
+    // Cesium's trackedEntity changes announce navigation through this event.
     if (this.viewer)
       this._navigationOwnerChangedRemover =
         this.viewer.trackedEntityChanged.addEventListener((entity) => {

src/ui/radioControls.js

@@ -166,7 +166,7 @@ export class RadioControls {
     document
       .getElementById('title-bar')
       ?.classList.remove('radio-broadcasting');
-    // The Navara engine's stand-in radio layer has no tuner.
+    // A catalog without the radio layer supplies a stand-in with no tuner.
     this.radio.endTuning?.();
   }
 }

src/voice/gevActions.js

@@ -238,7 +238,7 @@ const FRAME_TARGETS = new Map([
 /** A tool's required capability is missing from the attached scene. */
 export const UNAVAILABLE_ON_ENGINE = 'UNAVAILABLE_ON_ENGINE';
 
-/** What each refused tool is, for the refusal's message. */
+/** Feature labels for capability refusals; these actions can run on either engine. */
 export const UNAVAILABLE_FEATURES = Object.freeze({
   control_scene: 'The scene director',
   annotate_map: 'Map annotation',