Merge remote-tracking branch 'upstream/main' into core-rb2

# Conflicts:
#	CHANGELOG.md
#	build/vite.js
#	scripts/package-boundaries.json
#	server/standalone/vite.config.js
#	src/app/scene.js
#	src/layers/vessels/queries.js
#	src/standalone/application.js
#	src/tooling/viteBuild.test.mjs
#	src/ui/cockpitInstruments.js
#	src/ui/layerPanel.js
#	src/ui/panelPositionControls.js

src/app/catalog.js

@@ -4,6 +4,7 @@ const CONTROL_LAYER_IDS = Object.freeze({
   militaryFlightsLayer: 'military',
   satellitesLayer: 'satellites',
   cctvLayer: 'cctv',
+  streetLevelLayer: 'street-level',
   radioLayer: 'radio',
   bikeshareLayer: 'bikeshare',
   transitLayer: 'transit',

src/app/catalog.test.mjs

@@ -65,13 +65,28 @@ test('data setup seals the caller catalog before controls can restore and drains
         },
       },
     },
-    catalog: createLayerCatalog(layers, metadata(layers)),
+    catalog: {
+      ...createLayerCatalog(layers, metadata(layers)),
+      getSourceAvailability: (id) =>
+        id === 'one'
+          ? {
+              available: false,
+              reason: 'One: data source not configured',
+            }
+          : undefined,
+    },
     defer: (release) => releases.push(release),
     onData: (manager) => {
       observed = manager;
     },
   });
   assert.equal(observed, dataManager);
+  assert.equal(await dataManager.setEnabled('one', true), false);
+  assert.equal(dataManager.layers.get('one').initialized, false);
+  assert.equal(
+    dataManager.getAll().find(({ id }) => id === 'one').stats.error,
+    'One: data source not configured',
+  );
   assert.deepEqual(attached, [['one', 'two']]);
   assert.deepEqual([...dataManager.layers.keys()], ['one', 'two']);
   assert.throws(() => dataManager.register({ id: 'late' }), /finalized/);
@@ -93,6 +108,7 @@ test('controls bind catalog instances rather than similarly named defaults', ()
     'military-awareness',
     'military-installations',
     'rocket-launches',
+    'street-level',
     'local-adsb',
   ];
   const layers = ids.map((id) => ({ id }));
@@ -101,7 +117,7 @@ test('controls bind catalog instances rather than similarly named defaults', ()
   assert.equal(services.flightsLayer, layers[1]);
   assert.equal(services.transitLayer, layers[7]);
   assert.equal(services.aisLiveVesselsLayer, layers[8]);
-  assert.equal(services.localAdsbLayer, layers[12]);
+  assert.equal(services.localAdsbLayer, layers[13]);
   assert.equal(new Set(Object.values(services)).size, layers.length);
   assert.throws(
     () => catalogControlServices(createLayerCatalog([], [])),

src/app/constructCatalog.js

@@ -1,3 +1,4 @@
+import { resolveCatalogSources } from './sourceComposition.js';
 import { createWeatherClock } from '../layers/weather/clock.js';
 import { createWeatherLayer } from '../layers/weather/index.js';
 import { createCyclonesLayer } from '../layers/cyclones/index.js';
@@ -25,38 +26,12 @@ import { createApplicationFirms } from './layers/firms.js';
 import { createApplicationEarthquakes } from './layers/earthquakes.js';
 import { createApplicationFirePerimeters } from './layers/perimeters.js';
 import { createApplicationCables } from './layers/submarineCables.js';
+import { createApplicationStreetLevel } from './layers/streetLevel.js';
 import { createInfrastructureLayers } from '../data/infrastructure.js';
 import { localGeoJsonServices } from './localGeojsonServices.js';
 import { createBhoteKoshiEventLayer } from '../data/bhoteKoshiEvent.js';
 import { createBhoteKoshiLocatorLayer } from '../data/bhoteKoshiLocator.js';
 
-const SOURCE_METHODS = Object.freeze({
-  flights: ['getSnapshot'],
-  military: ['getSnapshot'],
-  vessels: ['getSnapshot'],
-  cctv: ['getCatalog', 'getHealth', 'getFrameUrl', 'getMediaUrl'],
-  radio: ['getDirectory', 'recordClick'],
-  traffic: [
-    'requestRoads',
-    'getStatus',
-    'fetchFlowForBounds',
-    'getFlowSessionStats',
-    'resetFlowTileCache',
-  ],
-  bikeshare: ['getStations'],
-  installations: ['getMappedSites', 'searchNearby'],
-  satellites: ['readGroup'],
-  launches: ['getLaunches', 'getActiveTle'],
-  alpr: ['fetch'],
-  firms: ['getSnapshot'],
-  wind: ['getSnapshot'],
-  weather: ['getSnapshot'],
-  cyclones: ['getSnapshot'],
-  earthquakes: ['getSnapshot'],
-  'fire-perimeters': ['getSnapshot'],
-  cables: ['fetch'],
-});
-
 /**
  * Hardware-local layers are registered like any other but never enter share
  * links or stored layer state: another browser cannot have this receiver.
@@ -83,6 +58,7 @@ export function createApplicationCatalog({
   vesselOptions,
   resolveAsset,
   nepalBoundaryResolver,
+  streetLevelProviders,
 }) {
   if (!signal?.addEventListener)
     throw new TypeError('An application lifetime signal is required');
@@ -90,12 +66,8 @@ export function createApplicationCatalog({
   if (!surface?.groundFloor || !surface?.terrain)
     throw new TypeError('Application surface services are required');
 
-  for (const [name, methods] of Object.entries(SOURCE_METHODS)) {
-    if (
-      methods.some((method) => typeof sources?.[name]?.[method] !== 'function')
-    )
-      throw new TypeError(`Invalid catalog source: ${name}`);
-  }
+  const sourceComposition = resolveCatalogSources(sources);
+  sources = sourceComposition.sources;
   const militaryRegistry = createMilitaryRegistry();
   const weatherClock = createWeatherClock();
   const dispose = () => {
@@ -105,7 +77,8 @@ export function createApplicationCatalog({
   };
   signal.addEventListener('abort', dispose, { once: true });
   try {
-    militaryRegistry.configureSource(sources.military, { signal });
+    if (sourceComposition.isConfigured('military'))
+      militaryRegistry.configureSource(sources.military, { signal });
     const flights = createApplicationFlights({
       surface,
       source: sources.flights,
@@ -148,6 +121,11 @@ export function createApplicationCatalog({
           source: sources['fire-perimeters'],
         }),
         createApplicationAlpr({ surface, source: sources.alpr }),
+        createApplicationStreetLevel({
+          surface,
+          sources: { mapillary: sources.mapillary },
+          providers: streetLevelProviders,
+        }),
         satellites,
         createApplicationLaunches({ source: sources.launches, satellites }),
         createApplicationTraffic({ source: sources.traffic, surface }),
@@ -155,8 +133,8 @@ export function createApplicationCatalog({
         createApplicationRadio({ surface, source: sources.radio }),
         createApplicationTransit({ surface, source: sources.transit }),
         createApplicationBikeshare({ source: sources.bikeshare }),
-        createApplicationDirections(),
-        createApplicationRecentImagery(),
+        createApplicationDirections({ source: sources.directions }),
+        createApplicationRecentImagery({ source: sources['recent-imagery'] }),
         vessels,
         installations,
         createApplicationAwareness({
@@ -197,6 +175,9 @@ export function createApplicationCatalog({
     );
     return Object.freeze({
       ...catalog,
+      getSourceAvailability: sourceComposition.createAvailabilityLookup(
+        catalog.layers,
+      ),
       militaryRegistry,
       surface,
       weatherClock,

src/app/constructCatalog.test.mjs

@@ -5,6 +5,7 @@ import { createApplicationCatalog } from './constructCatalog.js';
 import { createStandaloneLayerSources } from '../standalone/layerSources.js';
 import { catalogControlServices } from './catalog.js';
 import { LayerLifecycle } from '../data/lifecycle.js';
+import { fakeStreetLevelProvider } from '../testSupport/streetLevelFakes.mjs';
 
 function fixtureSources(ids, calls) {
   const sources = createStandaloneLayerSources();
@@ -39,7 +40,7 @@ test('catalogs construct distinct layers and classification from their supplied
     signal: b.signal,
     surface: fixtureSurface(b.signal),
   });
-  assert.equal(first.layers.length, 29);
+  assert.equal(first.layers.length, 30);
   assert.ok(first.get('local-adsb'), 'Local ADS-B is registered');
   assert.deepEqual(
     first.metadata.find(({ id }) => id === 'local-adsb'),
@@ -116,7 +117,7 @@ test('invalid or already cancelled construction fails before classification can
   assert.throws(
     () =>
       createApplicationCatalog({
-        sources: {},
+        sources: { flights: {} },
         signal: lifetime.signal,
         surface: fixtureSurface(lifetime.signal),
       }),
@@ -140,3 +141,53 @@ function fixtureSurface(signal) {
     eventTarget: null,
   });
 }
+
+test('Mapillary can be omitted or replaced without changing catalog membership', (t) => {
+  const lifetime = new AbortController();
+  t.after(() => lifetime.abort());
+  const sources = fixtureSources([], []);
+  delete sources.mapillary;
+  const options = {
+    sources,
+    signal: lifetime.signal,
+    surface: fixtureSurface(lifetime.signal),
+  };
+  const catalog = createApplicationCatalog(options);
+  assert.equal(catalog.layers.length, 30);
+  assert.deepEqual(catalog.get('street-level').providerIds, []);
+  assert.equal(
+    catalogControlServices(catalog).streetLevelLayer,
+    catalog.get('street-level'),
+  );
+  assert.match(
+    catalog.get('street-level').getUIState().coverage.hint,
+    /No street-level imagery providers/,
+  );
+  const provider = fakeStreetLevelProvider({
+    id: 'example',
+    pickPrefix: 'example:',
+  });
+  const replacement = createApplicationCatalog({
+    ...options,
+    streetLevelProviders: [provider],
+  });
+  assert.deepEqual(replacement.get('street-level').providerIds, ['example']);
+  assert.deepEqual(replacement.metadata, catalog.metadata);
+  assert.equal(provider.calls.activate, 0, 'construction must not acquire');
+  assert.deepEqual(
+    createApplicationCatalog({
+      ...options,
+      sources: fixtureSources([], []),
+      streetLevelProviders: [],
+    }).get('street-level').providerIds,
+    [],
+  );
+  assert.throws(
+    () =>
+      createApplicationCatalog({
+        ...options,
+        sources: { ...sources, mapillary: {} },
+      }),
+    /Mapillary source/,
+  );
+});

src/app/data.js

@@ -13,6 +13,7 @@ export function createApplicationData({
   // Initialize data layer manager
   const dataManager = new LayerLifecycle(viewer, {
     allowQaRegistration,
+    getSourceAvailability: catalog?.getSourceAvailability,
   });
   defer(async () => {
     await dataManager.destroyAll();

src/app/embed.js

@@ -0,0 +1,305 @@
+/**
+ * Embed mode and views in the running app.
+ *
+ * With `?embed=1` the app shows only the globe: clean view, with the HUD,
+ * welcome and setup prompts hidden. A page that frames it changes what it
+ * shows by posting `{ type: 'gev:view', id, view }`; the app applies the view
+ * through its own actions and answers `{ type: 'gev:view-applied', id, ok,
+ * steps }`. It announces `{ type: 'gev:ready' }` once it can take views.
+ *
+ * Annotations in a share link are drawn once the link has been restored,
+ * embedded or not.
+ */
+
+import * as Cesium from 'cesium';
+import { announceNavigationAuthority } from '../navigationPolicy.js';
+import { annotationsFromParams, createView } from '../view/index.js';
+
+export const EMBED_VIEW_MESSAGE = 'gev:view';
+export const EMBED_APPLIED_MESSAGE = 'gev:view-applied';
+export const EMBED_READY_MESSAGE = 'gev:ready';
+
+const FOLLOW_LAYERS = {
+  aircraft: 'flights',
+  military_aircraft: 'military',
+  satellite: 'satellites',
+};
+const FOLLOW_ATTEMPTS = 20;
+const FOLLOW_RETRY_MS = 1000;
+const FLIGHT_SECONDS = 2;
+
+/**
+ * Whether this page shows the app embedded: `?embed=1` when another page
+ * frames it, or inline when a panel page loads the app into itself and sets
+ * `globalThis.GEV_EMBED_INLINE` first.
+ */
+export function isEmbedded(location = globalThis.location) {
+  return (
+    isEmbeddedInline() ||
+    new URLSearchParams(location?.search || '').get('embed') === '1'
+  );
+}
+
+/** Whether a panel page loaded the app into itself. */
+export function isEmbeddedInline() {
+  return globalThis.GEV_EMBED_INLINE === true;
+}
+
+// A panel keeps drawing at about this rate when its host stops animation
+// frames; see keepPanelRendering.
+const PANEL_FRAME_MS = 33;
+const MISSED_FRAMES_MS = 250;
+
+/** A render error's details, including the plain objects workers report. */
+function describeError(error) {
+  if (error instanceof Error)
+    return `${error.name}: ${error.message}\n${error.stack}`;
+  try {
+    return JSON.stringify(error, Object.getOwnPropertyNames(error ?? {}));
+  } catch {
+    return String(error);
+  }
+}
+
+/**
+ * Keep the globe drawing in an inline panel. Some hosts report a panel on
+ * screen as hidden, which stops the browser's animation frames and with them
+ * Cesium's render loop; while frames stop arriving, draw from a timer.
+ * Returns a function that stops it.
+ */
+export function keepPanelRendering(
+  viewer,
+  { windowRef = globalThis.window, now = () => performance.now() } = {},
+) {
+  let lastFrame = now();
+  let frameRequest = null;
+  const onFrame = () => {
+    lastFrame = now();
+    frameRequest = windowRef.requestAnimationFrame(onFrame);
+  };
+  frameRequest = windowRef.requestAnimationFrame(onFrame);
+  // Cesium stops drawing after a render error, and so does the timer.
+  // Report the error in full: workers report plain objects, which Cesium
+  // prints as [object Object].
+  let failed = false;
+  const removeErrorListener = viewer.scene?.renderError?.addEventListener(
+    (_scene, error) => {
+      failed = true;
+      console.error(
+        "[God's Eye View panel] render error:",
+        describeError(error),
+      );
+    },
+  );
+  const timer = windowRef.setInterval(() => {
+    if (
+      failed ||
+      now() - lastFrame < MISSED_FRAMES_MS ||
+      viewer.isDestroyed?.()
+    )
+      return;
+    viewer.resize();
+    viewer.render();
+  }, PANEL_FRAME_MS);
+  return () => {
+    windowRef.clearInterval(timer);
+    windowRef.cancelAnimationFrame(frameRequest);
+    removeErrorListener?.();
+  };
+}
+
+const delay = (ms, signal) =>
+  new Promise((resolve) => {
+    const timer = setTimeout(resolve, ms);
+    signal?.addEventListener(
+      'abort',
+      () => {
+        clearTimeout(timer);
+        resolve();
+      },
+      { once: true },
+    );
+  });
+
+/** Fly the camera to a view's camera and resolve when the flight ends. */
+function flyTo(viewer, camera) {
+  announceNavigationAuthority('embed-view');
+  return new Promise((resolve) => {
+    viewer.camera.flyTo({
+      destination: Cesium.Cartesian3.fromDegrees(
+        camera.lon,
+        camera.lat,
+        camera.altitude_m,
+      ),
+      orientation: {
+        heading: Cesium.Math.toRadians(camera.heading_deg),
+        pitch: Cesium.Math.toRadians(camera.pitch_deg),
+        roll: 0,
+      },
+      duration: FLIGHT_SECONDS,
+      complete: () => resolve(true),
+      cancel: () => resolve(false),
+    });
+  });
+}
+
+/**
+ * Make the app show a view: style and map, exactly the view's layers,
+ * annotations, the camera, and the followed entity. Each step runs through the
+ * app's own actions (`run(name, args)`); a failed step is reported and the
+ * rest still run. Resolves to the steps and whether each succeeded.
+ */
+export async function applyView(
+  view,
+  { viewer, dataManager, run, signal, retryMs = FOLLOW_RETRY_MS },
+) {
+  const steps = [];
+  const act = async (name, args) => {
+    let result = null;
+    try {
+      result = await run(name, args);
+    } catch (error) {
+      result = { ok: false, error: error?.message || String(error) };
+    }
+    steps.push({
+      step: name,
+      ok: result?.ok !== false,
+      ...(result?.error ? { error: result.error } : {}),
+    });
+    return result;
+  };
+  if (view.style) await act('set_visual_style', { style: view.style });
+  if (view.map) await act('set_map_stack', { stack: view.map });
+  const wanted = new Set(view.layers);
+  for (const layer of dataManager.getAll()) {
+    if (layer.enabled && !wanted.has(layer.id))
+      await act('set_layer_visibility', { layerId: layer.id, enabled: false });
+  }
+  for (const layerId of view.layers) {
+    if (!dataManager.isEnabled(layerId))
+      await act('set_layer_visibility', { layerId, enabled: true });
+  }
+  if (!view.follow) await act('stop_tracking', {});
+  // Annotations go first: drawing them may frame the marks, and the view's
+  // own camera should have the last word.
+  await act('clear_annotations', {});
+  if (view.annotations.length)
+    await act('annotate_map', { annotations: [...view.annotations] });
+  if (!view.follow) {
+    steps.push({ step: 'camera', ok: await flyTo(viewer, view.camera) });
+    return steps;
+  }
+  // A followed entity owns the camera, and a camera flight would end the
+  // follow, so fly to the view only while the entity is not there yet. It
+  // appears once its layer has data; retry until then.
+  const layerId = FOLLOW_LAYERS[view.follow.kind];
+  const follow = async () => {
+    try {
+      return (
+        (await run('track_entity', { query: view.follow.id, layerId }))?.ok ===
+        true
+      );
+    } catch {
+      return false;
+    }
+  };
+  let followed = await follow();
+  if (!followed) {
+    steps.push({ step: 'camera', ok: await flyTo(viewer, view.camera) });
+    for (let attempt = 1; attempt < FOLLOW_ATTEMPTS && !followed; attempt++) {
+      if (signal?.aborted) break;
+      await delay(retryMs, signal);
+      followed = await follow();
+    }
+  }
+  steps.push({ step: 'follow', ok: followed });
+  if (followed && view.follow.cockpit)
+    await act('control_cockpit', { action: 'enter', targetLayer: layerId });
+  return steps;
+}
+
+/**
+ * Install embed mode when the page asks for it, and draw any annotations the
+ * opening link carries. Returns a function that removes the message handler.
+ */
+export function installViews({
+  shell,
+  viewer,
+  dataManager,
+  run,
+  signal,
+  location = globalThis.location,
+  windowRef = globalThis.window,
+}) {
+  const ready = Promise.resolve(shell.initialRestorePromise).catch(() => {});
+  const linked = annotationsFromParams(
+    new URLSearchParams(String(location?.hash || '').replace(/^#/, '')),
+  );
+  if (linked.length)
+    void ready.then(() => {
+      if (!signal?.aborted) void run('annotate_map', { annotations: linked });
+    });
+  if (!isEmbedded(location)) return () => {};
+
+  windowRef.document.body.classList.add('ui-embed');
+  shell.setCleanView?.(true);
+  const stopRendering = isEmbeddedInline()
+    ? keepPanelRendering(viewer, { windowRef })
+    : () => {};
+  // A framing page talks to the app across frames; an inline panel shares
+  // the page with it and talks through the page's own window.
+  const peer = isEmbeddedInline() ? windowRef : windowRef.parent;
+  // Answers go back only to the origin that asked. An inline panel posts to
+  // its own window, and a sandboxed framing page has no origin to name.
+  const post = (message, origin = '*') => {
+    if (peer && (peer !== windowRef || isEmbeddedInline()))
+      peer.postMessage(message, origin);
+  };
+  // Views apply one at a time, in the order they arrive.
+  let queue = ready;
+  const onMessage = (event) => {
+    if (event.source !== peer || event.data?.type !== EMBED_VIEW_MESSAGE)
+      return;
+    const { id = null } = event.data;
+    const replyOrigin =
+      isEmbeddedInline() || !event.origin || event.origin === 'null'
+        ? '*'
+        : event.origin;
+    let view;
+    try {
+      view = createView(event.data.view);
+    } catch (error) {
+      post(
+        {
+          type: EMBED_APPLIED_MESSAGE,
+          id,
+          ok: false,
+          error: error.message,
+        },
+        replyOrigin,
+      );
+      return;
+    }
+    queue = queue.then(async () => {
+      if (signal?.aborted) return;
+      const steps = await applyView(view, { viewer, dataManager, run, signal });
+      post(
+        {
+          type: EMBED_APPLIED_MESSAGE,
+          id,
+          ok: steps.every((step) => step.ok),
+          steps,
+        },
+        replyOrigin,
+      );
+    });
+  };
+  windowRef.addEventListener('message', onMessage);
+  void ready.then(() => {
+    if (!signal?.aborted) post({ type: EMBED_READY_MESSAGE });
+  });
+  return () => {
+    stopRendering();
+    windowRef.removeEventListener('message', onMessage);
+  };
+}

src/app/embed.test.mjs

@@ -0,0 +1,325 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import {
+  applyView,
+  installViews,
+  isEmbedded,
+  keepPanelRendering,
+} from './embed.js';
+import { createView } from '../view/index.js';
+
+const fakeViewer = () => {
+  const flights = [];
+  return {
+    flights,
+    camera: {
+      flyTo(options) {
+        flights.push(options);
+        options.complete();
+      },
+    },
+  };
+};
+const fakeLayers = (enabled) => ({
+  getAll: () =>
+    ['flights', 'earthquakes', 'ais-live-vessels'].map((id) => ({
+      id,
+      enabled: enabled.has(id),
+    })),
+  isEnabled: (id) => enabled.has(id),
+});
+const recorder = (answers = {}) => {
+  const calls = [];
+  const run = async (name, args) => {
+    calls.push([name, args]);
+    const answer = answers[name];
+    return typeof answer === 'function'
+      ? answer(calls)
+      : (answer ?? { ok: true });
+  };
+  return { calls, run };
+};
+
+test('embed mode is opt-in by query parameter', () => {
+  assert.equal(isEmbedded({ search: '?embed=1' }), true);
+  assert.equal(isEmbedded({ search: '?welcome=0' }), false);
+});
+
+test('a view is applied through the app actions in order', async () => {
+  const viewer = fakeViewer();
+  const { calls, run } = recorder();
+  const view = createView({
+    camera: { lat: 25, lon: 121, altitude_m: 300000, pitch_deg: -40 },
+    layers: ['ais-live-vessels'],
+    style: 'thermal',
+    map: 'osm',
+    annotations: [{ type: 'pin', target: 'Taipei 101' }],
+  });
+  const steps = await applyView(view, {
+    viewer,
+    dataManager: fakeLayers(new Set(['earthquakes'])),
+    run,
+  });
+  assert.deepEqual(
+    calls.map(([name, args]) => [
+      name,
+      args.layerId ?? args.style ?? args.stack ?? null,
+      args.enabled ?? null,
+    ]),
+    [
+      ['set_visual_style', 'thermal', null],
+      ['set_map_stack', 'osm', null],
+      ['set_layer_visibility', 'earthquakes', false],
+      ['set_layer_visibility', 'ais-live-vessels', true],
+      ['stop_tracking', null, null],
+      ['clear_annotations', null, null],
+      ['annotate_map', null, null],
+    ],
+  );
+  assert.equal(viewer.flights.length, 1);
+  assert.ok(steps.every((step) => step.ok));
+  assert.ok(steps.some((step) => step.step === 'camera'));
+});
+
+test('a followed entity is retried until its layer has it', async () => {
+  let tries = 0;
+  const { run } = recorder({
+    track_entity: () => ({ ok: ++tries >= 3 }),
+  });
+  const view = createView({
+    camera: { lat: 0, lon: 0 },
+    follow: { kind: 'aircraft', id: 'abc123' },
+  });
+  const steps = await applyView(view, {
+    viewer: fakeViewer(),
+    dataManager: fakeLayers(new Set()),
+    run,
+    retryMs: 1,
+  });
+  assert.equal(tries, 3);
+  assert.deepEqual(steps.at(-1), { step: 'follow', ok: true });
+});
+
+test('an embedded page takes views only from its parent and answers it', async () => {
+  const posted = [];
+  const targets = [];
+  const parent = {
+    postMessage: (message, target) => {
+      posted.push(message);
+      targets.push(target);
+    },
+  };
+  const windowRef = new EventTarget();
+  windowRef.parent = parent;
+  windowRef.document = { body: { classList: new Set() } };
+  windowRef.document.body.classList.add = Set.prototype.add;
+  const shell = {
+    initialRestorePromise: Promise.resolve(),
+    clean: null,
+    setCleanView(value) {
+      this.clean = value;
+    },
+  };
+  const { calls, run } = recorder();
+  const remove = installViews({
+    shell,
+    viewer: fakeViewer(),
+    dataManager: fakeLayers(new Set()),
+    run,
+    location: { search: '?embed=1', hash: '' },
+    windowRef,
+  });
+  await new Promise((resolve) => setTimeout(resolve, 0));
+  assert.equal(shell.clean, true);
+  assert.deepEqual(posted, [{ type: 'gev:ready' }]);
+  const send = (source, data, origin = 'https://host.example') => {
+    const event = new Event('message');
+    Object.assign(event, { source, data, origin });
+    windowRef.dispatchEvent(event);
+  };
+  send({}, { type: 'gev:view', id: 1, view: { camera: { lat: 1, lon: 2 } } });
+  send(parent, { type: 'gev:view', id: 2, view: { camera: {} } });
+  send(parent, {
+    type: 'gev:view',
+    id: 3,
+    view: { camera: { lat: 1, lon: 2 }, layers: ['flights'] },
+  });
+  await new Promise((resolve) => setTimeout(resolve, 10));
+  assert.deepEqual(posted[1], {
+    type: 'gev:view-applied',
+    id: 2,
+    ok: false,
+    error: 'A view needs a camera lat and lon',
+  });
+  assert.equal(posted[2].id, 3);
+  assert.equal(posted[2].ok, true);
+  assert.ok(
+    calls.some(
+      ([name, args]) =>
+        name === 'set_layer_visibility' && args.layerId === 'flights',
+    ),
+  );
+  assert.equal(posted.filter((message) => message.id === 1).length, 0);
+  // Ready names no data and goes to any parent; answers go only to the
+  // origin that asked.
+  assert.deepEqual(targets, [
+    '*',
+    'https://host.example',
+    'https://host.example',
+  ]);
+  remove();
+});
+
+test('an app loaded inline into a panel page talks through its own window', async () => {
+  const posted = [];
+  const windowRef = new EventTarget();
+  windowRef.parent = windowRef;
+  windowRef.postMessage = (message) => posted.push(message);
+  windowRef.document = { body: { classList: new Set() } };
+  windowRef.document.body.classList.add = Set.prototype.add;
+  Object.assign(windowRef, {
+    requestAnimationFrame: () => 1,
+    cancelAnimationFrame() {},
+    setInterval: () => 1,
+    clearInterval() {},
+  });
+  globalThis.GEV_EMBED_INLINE = true;
+  try {
+    assert.equal(isEmbedded({ search: '' }), true);
+    const remove = installViews({
+      shell: { initialRestorePromise: Promise.resolve() },
+      viewer: fakeViewer(),
+      dataManager: fakeLayers(new Set()),
+      run: recorder().run,
+      location: { search: '', hash: '' },
+      windowRef,
+    });
+    await new Promise((resolve) => setTimeout(resolve, 0));
+    assert.deepEqual(posted, [{ type: 'gev:ready' }]);
+    const event = new Event('message');
+    Object.assign(event, {
+      source: windowRef,
+      data: { type: 'gev:view', id: 7, view: { camera: { lat: 1, lon: 2 } } },
+    });
+    windowRef.dispatchEvent(event);
+    await new Promise((resolve) => setTimeout(resolve, 10));
+    assert.equal(posted[1].id, 7);
+    assert.equal(posted[1].ok, true);
+    remove();
+  } finally {
+    delete globalThis.GEV_EMBED_INLINE;
+  }
+});
+
+test('annotations in a link are drawn after it restores, embedded or not', async () => {
+  const { calls, run } = recorder();
+  const an = encodeURIComponent(
+    JSON.stringify([{ type: 'pin', target: 'Austin' }]),
+  );
+  installViews({
+    shell: { initialRestorePromise: Promise.resolve() },
+    viewer: fakeViewer(),
+    dataManager: fakeLayers(new Set()),
+    run,
+    location: { search: '', hash: `#v=2&lat=1&lon=2&an=${an}` },
+    windowRef: new EventTarget(),
+  });
+  await new Promise((resolve) => setTimeout(resolve, 0));
+  assert.deepEqual(calls, [
+    ['annotate_map', { annotations: [{ type: 'pin', target: 'Austin' }] }],
+  ]);
+});
+
+test('a panel keeps drawing from a timer while animation frames stop', () => {
+  let clock = 0;
+  let tick = null;
+  let frame = null;
+  const windowRef = {
+    requestAnimationFrame: (fn) => ((frame = fn), 1),
+    cancelAnimationFrame: () => (frame = null),
+    setInterval: (fn) => ((tick = fn), 1),
+    clearInterval: () => (tick = null),
+  };
+  const drawn = [];
+  const viewer = {
+    resize: () => drawn.push('resize'),
+    render: () => drawn.push('render'),
+  };
+  const stop = keepPanelRendering(viewer, { windowRef, now: () => clock });
+  // Frames arrive: the render loop draws, so the timer does nothing.
+  clock = 100;
+  frame();
+  tick();
+  assert.deepEqual(drawn, []);
+  // Frames stop, as in a panel its host reports hidden: the timer draws.
+  clock = 400;
+  tick();
+  assert.deepEqual(drawn, ['resize', 'render']);
+  stop();
+  assert.equal(tick, null);
+  assert.equal(frame, null);
+});
+
+test('a panel reports a render error in full and stops drawing', () => {
+  let listener = null;
+  let tick = null;
+  const windowRef = {
+    requestAnimationFrame: () => 1,
+    cancelAnimationFrame() {},
+    setInterval: (fn) => ((tick = fn), 1),
+    clearInterval() {},
+  };
+  const drawn = [];
+  const viewer = {
+    resize() {},
+    render: () => drawn.push('render'),
+    scene: {
+      renderError: {
+        addEventListener: (fn) => ((listener = fn), () => (listener = null)),
+      },
+    },
+  };
+  const logged = [];
+  const original = console.error;
+  console.error = (...args) => logged.push(args.join(' '));
+  try {
+    let clock = 0;
+    const stop = keepPanelRendering(viewer, { windowRef, now: () => clock });
+    listener(viewer.scene, { name: 'RuntimeError', message: 'worker failed' });
+    assert.match(logged[0], /render error: .*"message":"worker failed"/);
+    clock = 1000;
+    tick();
+    assert.deepEqual(drawn, []);
+    stop();
+    assert.equal(listener, null);
+  } finally {
+    console.error = original;
+  }
+});
+
+test('a followed aircraft owns the camera, and cockpit view is entered after it', async () => {
+  const viewer = fakeViewer();
+  const { calls, run } = recorder();
+  const steps = await applyView(
+    createView({
+      camera: { lat: 32.7, lon: -117.2 },
+      follow: { kind: 'military_aircraft', id: 'AE1234', cockpit: true },
+    }),
+    { viewer, dataManager: fakeLayers(new Set()), run, retryMs: 0 },
+  );
+  // Following worked at once, so no camera flight ended it.
+  assert.equal(viewer.flights.length, 0);
+  assert.deepEqual(calls.slice(-2), [
+    ['track_entity', { query: 'ae1234', layerId: 'military' }],
+    ['control_cockpit', { action: 'enter', targetLayer: 'military' }],
+  ]);
+  assert.ok(steps.every((step) => step.ok));
+  assert.throws(
+    () =>
+      createView({
+        camera: { lat: 0, lon: 0 },
+        follow: { kind: 'satellite', id: '25544', cockpit: true },
+      }),
+    /no cockpit view/,
+  );
+});

src/app/globePanelRuntime.js

@@ -0,0 +1,662 @@
+/**
+ * The God's Eye View panel's script, run inside the panel page a host shows.
+ * It is sent as source text (see src/tools/globePanel.js), so it must not use
+ * imports or anything outside the function.
+ *
+ * The page lives on the host's site, and hosts may refuse other addresses,
+ * such as a server on the user's machine. So the panel never requests the
+ * app's server itself: every request for the app's own paths goes to the
+ * panel's MCP server as a call to `config.toolName`, which requests the path
+ * from the app's server. The app's built page, scripts, styles, images and
+ * data all arrive that way; map imagery from providers loads directly.
+ */
+export function panelRuntime(config) {
+  const status = document.getElementById('status');
+  const open = document.getElementById('open');
+  const expand = document.getElementById('expand');
+  const say = (text) => {
+    if (status.isConnected) status.textContent = text;
+  };
+  let blocked = null;
+  document.addEventListener('securitypolicyviolation', (event) => {
+    blocked = `${event.effectiveDirective} blocked ${event.blockedURI || 'a resource'}`;
+  });
+
+  // JSON-RPC with the host.
+  let nextId = 1;
+  const pending = new Map();
+  const send = (message) =>
+    window.parent.postMessage({ jsonrpc: '2.0', ...message }, '*');
+  const request = (method, params) =>
+    new Promise((resolve, reject) => {
+      const id = nextId++;
+      pending.set(id, { resolve, reject });
+      send({ id, method, params });
+    });
+  const notify = (method, params) => send({ method, params });
+
+  // Requests to the app's server, through the MCP server.
+  const MAX_CALLS = 6;
+  let calls = 0;
+  const waiting = [];
+  async function callTool(args) {
+    if (calls >= MAX_CALLS) await new Promise((go) => waiting.push(go));
+    calls += 1;
+    try {
+      const result = await request('tools/call', {
+        name: config.toolName,
+        // The server refuses the panel's requests without its key.
+        arguments: { ...args, key: config.panelKey },
+      });
+      if (result?.isError || !result?.structuredContent)
+        throw new Error(result?.content?.[0]?.text || 'The request failed');
+      return result.structuredContent;
+    } finally {
+      calls -= 1;
+      waiting.shift()?.();
+    }
+  }
+  const toBase64 = (bytes) => {
+    let binary = '';
+    for (let start = 0; start < bytes.length; start += 0x8000)
+      binary += String.fromCharCode(...bytes.subarray(start, start + 0x8000));
+    return btoa(binary);
+  };
+  const fromBase64 = (text) =>
+    Uint8Array.from(atob(text), (char) => char.charCodeAt(0));
+  async function bodyBytes(body) {
+    if (body == null) return null;
+    if (typeof body === 'string') return new TextEncoder().encode(body);
+    if (body instanceof ArrayBuffer) return new Uint8Array(body);
+    if (ArrayBuffer.isView(body))
+      return new Uint8Array(body.buffer, body.byteOffset, body.byteLength);
+    return new Uint8Array(await new Response(body).arrayBuffer());
+  }
+  const NULL_BODY = new Set([101, 204, 205, 304]);
+  const held = new Map();
+
+  /** Request a path on the app's server; resolves to a Response. */
+  function appFetch(path, init = {}) {
+    const method = (init.method || 'GET').toUpperCase();
+    // Built files never change while the panel runs, so each loads once.
+    const shared = method === 'GET' && path.startsWith(config.panelBase);
+    if (shared && held.has(path)) return held.get(path).then(respond);
+    const loading = (async () => {
+      const headers = {};
+      new Headers(init.headers || {}).forEach((value, name) => {
+        headers[name] = value;
+      });
+      const bytes = await bodyBytes(init.body);
+      let part = await callTool({
+        path,
+        method,
+        headers,
+        ...(bytes ? { body: toBase64(bytes) } : {}),
+      });
+      const parts = [fromBase64(part.body)];
+      while (part.nextOffset !== undefined) {
+        if (init.signal?.aborted) break;
+        part = await callTool({ id: part.id, offset: part.nextOffset });
+        parts.push(fromBase64(part.body));
+      }
+      let body = new Blob(parts);
+      if (part.encoding === 'gzip')
+        body = await new Response(
+          body.stream().pipeThrough(new DecompressionStream('gzip')),
+        ).blob();
+      return {
+        body: await body.arrayBuffer(),
+        status: part.status,
+        statusText: part.statusText,
+        headers: part.headers,
+      };
+    })();
+    if (shared) {
+      held.set(path, loading);
+      loading.catch(() => held.delete(path));
+    }
+    const result = loading.then(respond);
+    if (!init.signal) return result;
+    return Promise.race([
+      result,
+      new Promise((_, reject) => {
+        const abort = () =>
+          reject(new DOMException('The request was aborted', 'AbortError'));
+        if (init.signal.aborted) abort();
+        init.signal.addEventListener('abort', abort, { once: true });
+      }),
+    ]);
+  }
+  function respond({ body, status, statusText, headers }) {
+    return new Response(NULL_BODY.has(status) ? null : body.slice(0), {
+      status,
+      statusText,
+      headers,
+    });
+  }
+
+  // The app's own paths: relative ones, absolute ones on this page's site
+  // (matched by scheme and host, since a host may use its own scheme), and
+  // ones under the app's address in the page, an https address for code
+  // that needs one (`config.appBaseUrl`).
+  const page = new URL(document.baseURI);
+  const appOrigin = new URL(config.appBaseUrl).origin;
+  function appPath(value) {
+    let url;
+    try {
+      url = new URL(String(value), document.baseURI);
+    } catch {
+      return null;
+    }
+    const own =
+      url.origin === appOrigin ||
+      (url.protocol === page.protocol && url.host === page.host);
+    return own ? url.pathname + url.search : null;
+  }
+  const fileUrls = new Map();
+  /**
+   * A data: URL holding an app file, for elements that load by URL. Hosts
+   * allow data: images where some refuse blob: ones. Files of the panel
+   * build never change and are kept; others, such as live camera frames
+   * that change address on every refresh, are not.
+   */
+  function appFileUrl(path) {
+    if (fileUrls.has(path)) return fileUrls.get(path);
+    const loading = appFetch(path)
+      .then((response) => response.blob())
+      .then(
+        (blob) =>
+          new Promise((resolve, reject) => {
+            const reader = new FileReader();
+            reader.onload = () => resolve(reader.result);
+            reader.onerror = () => reject(reader.error);
+            reader.readAsDataURL(blob);
+          }),
+      );
+    if (path.startsWith(config.panelBase)) {
+      fileUrls.set(path, loading);
+      loading.catch(() => fileUrls.delete(path));
+    }
+    return loading;
+  }
+
+  function installRequests() {
+    const nativeFetch = window.fetch.bind(window);
+    window.fetch = async (input, init = {}) => {
+      const isRequest = input instanceof Request;
+      const path = appPath(isRequest ? input.url : input);
+      if (path === null) return nativeFetch(input, init);
+      if (!isRequest) return appFetch(path, init);
+      return appFetch(path, {
+        method: init.method || input.method,
+        headers: init.headers || input.headers,
+        body:
+          init.body ??
+          (['GET', 'HEAD'].includes(input.method)
+            ? undefined
+            : await input.arrayBuffer()),
+        signal: init.signal || input.signal,
+      });
+    };
+
+    // XMLHttpRequest for app paths: answered from appFetch, with the
+    // instance's state replaced, and the usual events dispatched.
+    const xhr = XMLHttpRequest.prototype;
+    const nativeOpen = xhr.open;
+    const nativeSend = xhr.send;
+    const nativeHeader = xhr.setRequestHeader;
+    const nativeAbort = xhr.abort;
+    xhr.open = function (method, url, ...rest) {
+      const path = appPath(url);
+      if (path === null) {
+        this.__gev = null;
+        return nativeOpen.call(this, method, url, ...rest);
+      }
+      this.__gev = { method, path, headers: {}, controller: null };
+      setState(this, { readyState: 1 });
+      this.dispatchEvent(new Event('readystatechange'));
+    };
+    xhr.setRequestHeader = function (name, value) {
+      if (!this.__gev) return nativeHeader.call(this, name, value);
+      this.__gev.headers[name] = value;
+    };
+    xhr.abort = function () {
+      if (!this.__gev) return nativeAbort.call(this);
+      this.__gev.controller?.abort();
+    };
+    xhr.send = function (body) {
+      const state = this.__gev;
+      if (!state) return nativeSend.call(this, body);
+      state.controller = new AbortController();
+      appFetch(state.path, {
+        method: state.method,
+        headers: state.headers,
+        body,
+        signal: state.controller.signal,
+      })
+        .then(async (response) => {
+          const type = this.responseType;
+          const value =
+            type === 'arraybuffer'
+              ? await response.arrayBuffer()
+              : type === 'blob'
+                ? await response.blob()
+                : await response.text();
+          const text = typeof value === 'string' ? value : null;
+          let parsed = value;
+          if (type === 'json') {
+            try {
+              parsed = JSON.parse(text);
+            } catch {
+              parsed = null;
+            }
+          } else if (type === 'document')
+            parsed = new DOMParser().parseFromString(text, 'text/html');
+          const headers = [...response.headers]
+            .map(([name, val]) => `${name}: ${val}`)
+            .join('\r\n');
+          setState(this, {
+            readyState: 4,
+            status: response.status,
+            statusText: response.statusText,
+            response: parsed,
+            responseText: type === '' || type === 'text' ? text : '',
+            responseURL: new URL(state.path, document.baseURI).href,
+            getAllResponseHeaders: () => headers,
+            getResponseHeader: (name) => response.headers.get(name),
+          });
+          for (const name of ['readystatechange', 'load', 'loadend'])
+            this.dispatchEvent(
+              name === 'readystatechange'
+                ? new Event(name)
+                : new ProgressEvent(name),
+            );
+        })
+        .catch((error) => {
+          setState(this, { readyState: 4, status: 0 });
+          const name = error?.name === 'AbortError' ? 'abort' : 'error';
+          for (const event of ['readystatechange', name, 'loadend'])
+            this.dispatchEvent(
+              event === 'readystatechange'
+                ? new Event(event)
+                : new ProgressEvent(event),
+            );
+        });
+    };
+    function setState(target, values) {
+      for (const [name, value] of Object.entries(values))
+        Object.defineProperty(target, name, {
+          configurable: true,
+          ...(typeof value === 'function' ? { value } : { get: () => value }),
+        });
+    }
+
+    const nativeBeacon = navigator.sendBeacon?.bind(navigator);
+    if (nativeBeacon)
+      navigator.sendBeacon = (url, data) => {
+        const path = appPath(url);
+        if (path === null) return nativeBeacon(url, data);
+        appFetch(path, { method: 'POST', body: data }).catch(() => {});
+        return true;
+      };
+
+    // Images name app files by URL; give them the file as a data: URL.
+    const image = Object.getOwnPropertyDescriptor(
+      HTMLImageElement.prototype,
+      'src',
+    );
+    Object.defineProperty(HTMLImageElement.prototype, 'src', {
+      ...image,
+      set(value) {
+        const path = appPath(value);
+        if (path === null) return image.set.call(this, value);
+        appFileUrl(path).then(
+          (url) => image.set.call(this, url),
+          () => this.dispatchEvent(new Event('error')),
+        );
+      },
+    });
+
+    // Workers on the app's server start from a small worker here that is
+    // handed the script once it has loaded; messages wait until then.
+    const NativeWorker = window.Worker;
+    const BOOT =
+      'const early=[];let ready=false;' +
+      "addEventListener('message',e=>{if(e.data&&e.data.__gevScript){" +
+      'const go=()=>{ready=true;for(const d of early)dispatchEvent(new MessageEvent("message",{data:d}))};' +
+      'if(e.data.module)import(e.data.__gevScript).then(go);else{importScripts(e.data.__gevScript);go()}' +
+      'e.stopImmediatePropagation();return}' +
+      'if(!ready){early.push(e.data);e.stopImmediatePropagation()}});';
+    window.Worker = function Worker(url, options) {
+      const path = appPath(url);
+      if (path === null || String(url).startsWith('blob:'))
+        return new NativeWorker(url, options);
+      const worker = new NativeWorker(
+        URL.createObjectURL(new Blob([BOOT], { type: 'text/javascript' })),
+        options,
+      );
+      appFetch(path)
+        .then((response) => response.blob())
+        .then((blob) => URL.createObjectURL(blob))
+        .then((script) =>
+          worker.postMessage({
+            __gevScript: script,
+            module: options?.type === 'module',
+          }),
+        );
+      return worker;
+    };
+    window.Worker.prototype = NativeWorker.prototype;
+
+    // Some hosts drop the GPU contents of a panel's 2D canvases while they
+    // consider the panel off screen, and the overlays then cover the globe
+    // in black. Keep 2D canvases in memory instead, which hosts do not drop.
+    const getContext = HTMLCanvasElement.prototype.getContext;
+    HTMLCanvasElement.prototype.getContext = function (type, options) {
+      return type === '2d'
+        ? getContext.call(this, type, { ...options, willReadFrequently: true })
+        : getContext.call(this, type, options);
+    };
+
+    // Markup the app adds as HTML text would request its images from this
+    // page's site at once; hold their addresses until the files are here.
+    const htmlWithHeldImages = (html) =>
+      String(html).replace(
+        /(<(?:img|source)\b[^>]*?\s)src=(["'])([^"']*)\2/gi,
+        (tag, before, quote, value) =>
+          appPath(value) === null
+            ? tag
+            : `${before}data-gev-src=${quote}${value}${quote}`,
+      );
+    const fillHeldImages = (root) => {
+      for (const element of root?.querySelectorAll?.('[data-gev-src]') ?? []) {
+        const path = appPath(element.getAttribute('data-gev-src'));
+        element.removeAttribute('data-gev-src');
+        appFileUrl(path).then((url) => element.setAttribute('src', url));
+      }
+    };
+    const innerHtml = Object.getOwnPropertyDescriptor(
+      Element.prototype,
+      'innerHTML',
+    );
+    Object.defineProperty(Element.prototype, 'innerHTML', {
+      ...innerHtml,
+      set(value) {
+        innerHtml.set.call(this, htmlWithHeldImages(value));
+        fillHeldImages(this);
+      },
+    });
+    const insertHtml = Element.prototype.insertAdjacentHTML;
+    Element.prototype.insertAdjacentHTML = function (position, html) {
+      insertHtml.call(this, position, htmlWithHeldImages(html));
+      fillHeldImages(this.parentNode ?? this);
+    };
+
+    // Markup and styles the app adds later name app files too.
+    new MutationObserver((records) => {
+      for (const record of records)
+        for (const node of record.addedNodes) {
+          if (node.nodeType !== 1) continue;
+          if (node.nodeName === 'STYLE') void inlineStyleUrls(node);
+          for (const element of [node, ...node.querySelectorAll('img[src]')]) {
+            if (element.nodeName !== 'IMG') continue;
+            const path = appPath(element.getAttribute('src'));
+            if (path !== null)
+              appFileUrl(path).then((url) => element.setAttribute('src', url));
+          }
+        }
+    }).observe(document.documentElement, { childList: true, subtree: true });
+  }
+
+  /** Replace url() references to app files in CSS with data: URLs. */
+  async function cssWithFiles(text, baseUrl) {
+    const found = new Map();
+    for (const match of text.matchAll(/url\(\s*(['"]?)([^'")]+)\1\s*\)/g)) {
+      const reference = match[2];
+      if (/^(data|blob):/.test(reference)) continue;
+      const path = appPath(new URL(reference, baseUrl).href);
+      if (path !== null && !found.has(reference))
+        found.set(
+          reference,
+          appFileUrl(path).catch(() => null),
+        );
+    }
+    let result = text;
+    for (const [reference, loading] of found) {
+      const url = await loading;
+      if (url) result = result.split(reference).join(url);
+    }
+    return result;
+  }
+  async function inlineStyleUrls(style) {
+    if (!/url\(/.test(style.textContent)) return;
+    style.textContent = await cssWithFiles(style.textContent, document.baseURI);
+  }
+
+  async function addStylesheet(href) {
+    const path = appPath(href);
+    const style = document.createElement('style');
+    document.head.appendChild(style);
+    if (path === null) {
+      const link = document.createElement('link');
+      link.rel = 'stylesheet';
+      link.href = href;
+      style.replaceWith(link);
+      return;
+    }
+    const text = await (await appFetch(path)).text();
+    style.textContent = await cssWithFiles(
+      text,
+      new URL(path, document.baseURI).href,
+    );
+  }
+
+  function runScript(text, type) {
+    const script = document.createElement('script');
+    if (type) script.type = type;
+    script.textContent = text;
+    document.body.appendChild(script);
+  }
+
+  /**
+   * Load God's Eye View into this page from the app's panel build, in
+   * inline embed mode, starting at the first view as its link would.
+   */
+  async function startApp(url, view) {
+    window.GEV_EMBED_INLINE = true;
+    window.GEV_APP_BASE_URL = config.appBaseUrl;
+    try {
+      history.replaceState(
+        null,
+        '',
+        location.href.split('#')[0] + new URL(url).hash,
+      );
+      // The app restores this view from its link, following included, so
+      // it needs applying again only for what links cannot carry: cockpit.
+      if (queued === view && !view.follow?.cockpit) queued = null;
+    } catch {
+      // The view still arrives once the app is ready.
+    }
+    installRequests();
+    const response = await appFetch(config.panelBase);
+    if (!response.ok)
+      throw new Error(
+        response.status === 404
+          ? 'the app has no panel build (npm run build:panel)'
+          : `the app answered ${response.status}`,
+      );
+    const built = new DOMParser().parseFromString(
+      await response.text(),
+      'text/html',
+    );
+    window.CESIUM_BASE_URL = `${config.panelBase}cesium/`;
+    const [prelude] = await Promise.all([
+      appFetch(config.panelBase + config.workerPreludePath).then((r) =>
+        r.text(),
+      ),
+      ...[...built.head.querySelectorAll('link[rel="stylesheet"]')].map(
+        (link) => addStylesheet(link.getAttribute('href')),
+      ),
+    ]);
+    // Cesium's script sets CESIUM_WORKERS, its workers as one script it
+    // starts from memory. Workers request files themselves, which this page
+    // cannot answer, so the prelude, holding those files, runs ahead of it.
+    let workers;
+    Object.defineProperty(window, 'CESIUM_WORKERS', {
+      configurable: true,
+      get: () => workers,
+      set: (script) => {
+        workers = prelude + script;
+      },
+    });
+    // Images in the markup load their files once added; give them the
+    // files instead of letting them request this page's site.
+    const images = [];
+    for (const image of built.body.querySelectorAll('img[src]')) {
+      const path = appPath(image.getAttribute('src'));
+      if (path === null) continue;
+      image.removeAttribute('src');
+      images.push([image, path]);
+    }
+    for (const node of [...built.body.childNodes]) {
+      if (node.nodeName !== 'SCRIPT')
+        document.body.insertBefore(document.adoptNode(node), status);
+    }
+    for (const [image, path] of images)
+      appFileUrl(path).then((url) => image.setAttribute('src', url));
+    const scripts = await Promise.all(
+      [...built.querySelectorAll('script')].map(async (script) => ({
+        type: script.type,
+        text: script.getAttribute('src')
+          ? await (await appFetch(appPath(script.getAttribute('src')))).text()
+          : script.textContent,
+      })),
+    );
+    for (const { type, text } of scripts) runScript(text, type);
+    // Browsers cap live 3D contexts across pages and take one back when
+    // there are too many; say so rather than show no map.
+    document.addEventListener(
+      'webglcontextlost',
+      () => {
+        const notice = document.createElement('div');
+        notice.id = 'status';
+        notice.textContent =
+          "This panel lost its 3D graphics, likely because other God's Eye " +
+          "View panels in this conversation hold them. Use Open in God's " +
+          'Eye View above, or show it in a new conversation.';
+        document.body.appendChild(notice);
+      },
+      { capture: true, once: true },
+    );
+  }
+
+  // Tool results: the first view starts the app, later ones move it.
+  let started = false;
+  let ready = false;
+  let queued = null;
+  let currentUrl = null;
+  const postView = (view) =>
+    window.postMessage({ type: 'gev:view', id: nextId++, view }, '*');
+  function show(result) {
+    const data = result?.structuredContent;
+    const view = data?.view;
+    const url = data?.url || view?.url;
+    if (!view || !url) return;
+    currentUrl = url;
+    open.hidden = false;
+    if (ready) return postView(view);
+    queued = view;
+    if (started) return;
+    started = true;
+    say("Loading God's Eye View…");
+    startApp(url, view).catch((error) =>
+      say(`God's Eye View could not load here: ${error?.message || error}.`),
+    );
+    setTimeout(() => {
+      if (!ready)
+        say(
+          "God's Eye View did not load here" +
+            (blocked ? ` (${blocked})` : '') +
+            ". Use Open in God's Eye View above.",
+        );
+    }, config.loadTimeoutMs);
+  }
+
+  window.addEventListener('message', (event) => {
+    const message = event.data;
+    if (event.source === window) {
+      if (message?.type === 'gev:ready') {
+        ready = true;
+        status.remove();
+        if (queued) postView(queued);
+        queued = null;
+      }
+      return;
+    }
+    if (event.source !== window.parent || message?.jsonrpc !== '2.0') return;
+    if (
+      message.id !== undefined &&
+      pending.has(message.id) &&
+      !message.method
+    ) {
+      const { resolve, reject } = pending.get(message.id);
+      pending.delete(message.id);
+      if (message.error) reject(message.error);
+      else resolve(message.result);
+      return;
+    }
+    if (message.method === 'ui/notifications/tool-result') show(message.params);
+    if (message.method === 'ui/notifications/host-context-changed')
+      showDisplayMode(message.params);
+  });
+
+  // Fullscreen, where the host offers it, gives the globe the room.
+  let displayMode = 'inline';
+  const showDisplayMode = (context) => {
+    if (context?.displayMode) displayMode = context.displayMode;
+    if (context?.availableDisplayModes)
+      expand.hidden = !context.availableDisplayModes.includes('fullscreen');
+    expand.textContent = displayMode === 'fullscreen' ? 'Collapse' : 'Expand';
+  };
+  expand.addEventListener('click', () => {
+    request('ui/request-display-mode', {
+      mode: displayMode === 'fullscreen' ? 'inline' : 'fullscreen',
+    }).then(
+      (result) => showDisplayMode({ displayMode: result?.mode }),
+      () => {},
+    );
+  });
+
+  open.addEventListener('click', () => {
+    if (!currentUrl) return;
+    request('ui/open-link', { url: currentUrl }).catch(() =>
+      window.open(currentUrl, '_blank', 'noopener'),
+    );
+  });
+
+  // The handshake the MCP Apps SDK's App.connect performs: hosts validate
+  // these parameters, and keep a view hidden until it is initialized.
+  request('ui/initialize', {
+    appCapabilities: { availableDisplayModes: ['inline', 'fullscreen'] },
+    appInfo: {
+      name: 'gods-eye-view',
+      title: "God's Eye View",
+      version: '1.0.0',
+    },
+    protocolVersion: config.protocolVersion,
+  }).then(
+    (result) => {
+      showDisplayMode(result?.hostContext);
+      send({ method: 'ui/notifications/initialized' });
+      notify('ui/notifications/size-changed', {
+        width: document.body.clientWidth,
+        height: config.panelHeight,
+      });
+    },
+    (error) =>
+      say(
+        "This client did not accept the God's Eye View panel" +
+          (error?.message ? `: ${error.message}` : '.'),
+      ),
+  );
+}

src/app/layers/directions.js

@@ -1,12 +1,6 @@
 import { createApplicationDirectionsLayer } from '../../data/directions.js';
 
-/**
- * Construct one Directions layer using the application scene owners.
- *
- * It takes no data source: a route is fetched from `/api/route` when the
- * operator places both endpoints, so there is nothing to supply up front.
- * @returns {object} A fresh layer instance for this catalog.
- */
-export function createApplicationDirections() {
-  return createApplicationDirectionsLayer();
+/** Construct Directions with application scene owners and an explicit route source. */
+export function createApplicationDirections({ source }) {
+  return createApplicationDirectionsLayer({ source });
 }

src/app/layers/recentImagery.js

@@ -3,17 +3,17 @@ import { createRecentImageryRenderer } from '../../layers/recentImagery/renderin
 import { createThumbnailLoader } from '../../layers/recentImagery/thumbnails.js';
 import { governorRequestRender } from '../../renderGovernor.js';
 
-/**
- * Construct the Recent Imagery layer with the real GIBS renderer and the
- * browser thumbnail loader. It takes no data source: the catalog is NASA
- * CMR and the tiles are GIBS, both browser-direct and keyless.
- * @returns {object} A fresh layer instance for this catalog.
- */
-export function createApplicationRecentImagery() {
+/** Construct imagery presentation over one explicitly supplied acquisition source. */
+export function createApplicationRecentImagery({ source }) {
   return createRecentImageryLayer({
+    catalog: { searchHls: (...args) => source.searchHls(...args) },
     renderer: createRecentImageryRenderer({
       requestRender: governorRequestRender,
+      tileTemplate: (...args) => source.getTileTemplate(...args),
+      credit: source.credit || source.label || 'Imagery',
+    }),
+    thumbnails: createThumbnailLoader({
+      requestThumbnail: (...args) => source.getThumbnail(...args),
     }),
-    thumbnails: createThumbnailLoader(),
   });
 }

src/app/layers/streetLevel.js

@@ -0,0 +1,32 @@
+import { createStreetLevelLayer } from '../../layers/streetLevel/index.js';
+import { createMapillaryProvider } from '../../layers/streetLevel/providers/mapillary/index.js';
+import * as sprites from '../../data/spriteOrder.js';
+import * as picking from '../../data/pickRegistry.js';
+import * as input from '../../data/inputOwnership.js';
+import * as render from '../../renderGovernor.js';
+
+/**
+ * Inject providers, or use Mapillary only when its source is supplied.
+ * An explicit provider list replaces the default; unused sources.mapillary is
+ * neither constructed nor validated, including when the list is empty.
+ */
+export function createApplicationStreetLevel({
+  surface,
+  sources = {},
+  providers = sources.mapillary == null
+    ? []
+    : [createMapillaryProvider({ source: sources.mapillary })],
+}) {
+  return createStreetLevelLayer({
+    providers,
+    services: {
+      sprites,
+      picking,
+      input,
+      render,
+      ground: surface?.groundFloor ?? null,
+      meshFloor: surface?.meshFloor ?? null,
+      terrain: surface?.terrain ?? null,
+    },
+  });
+}

src/app/layers/streetLevel.test.mjs

@@ -0,0 +1,29 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import { createApplicationStreetLevel } from './streetLevel.js';
+import { fakeStreetLevelProvider } from '../../testSupport/streetLevelFakes.mjs';
+
+test('explicit providers replace the default source and an empty list removes it', () => {
+  const sources = { mapillary: {} };
+  const provider = fakeStreetLevelProvider({
+    id: 'example',
+    pickPrefix: 'example:',
+  });
+  const layer = createApplicationStreetLevel({
+    sources,
+    providers: [provider],
+  });
+  assert.deepEqual(layer.providerIds, ['example']);
+  assert.deepEqual(
+    createApplicationStreetLevel({ sources, providers: [] }).providerIds,
+    [],
+  );
+  assert.throws(
+    () => createApplicationStreetLevel({ sources }),
+    /Mapillary source/,
+  );
+  assert.throws(
+    () => createApplicationStreetLevel({ providers: null }),
+    /array/,
+  );
+});

src/app/scene.js

@@ -20,6 +20,7 @@ import { t } from '../i18n/index.js';
 export async function createApplicationScene({
   requestServices,
   googleApiKey,
+  googleTokens = null,
   cesiumToken,
   credits,
   MapController = MapStackController,
@@ -60,11 +61,12 @@ export async function createApplicationScene({
   registerDataCredits(viewer, credits);
   configureCreditKeyboardAccess(document);
   loaderStatus.textContent =
-    googleApiKey || cesiumToken
+    googleApiKey || googleTokens || cesiumToken
       ? t('shell.loading.status.tilesGoogle')
       : t('shell.loading.status.tilesKeyless');
   const photoreal = await loadPhotorealisticTileset(Cesium, {
     googleApiKey,
+    googleTokens,
     cesiumToken,
   });
   const tileset = photoreal.tileset;

src/app/sourceComposition.js

@@ -0,0 +1,113 @@
+const contract = (layers, methods) =>
+  Object.freeze({
+    layers: Object.freeze(layers),
+    methods: Object.freeze(methods),
+  });
+
+/** Acquisition contracts and their consumers; records remain family-specific. */
+export const CATALOG_SOURCE_CONTRACTS = Object.freeze({
+  directions: contract(['directions'], ['getRoute']),
+  'recent-imagery': contract(
+    ['recent-imagery'],
+    ['searchHls', 'getThumbnail', 'getTileTemplate'],
+  ),
+  flights: contract(['flights'], ['getSnapshot']),
+  military: contract(['military'], ['getSnapshot']),
+  vessels: contract(['ais-live-vessels'], ['getSnapshot']),
+  cctv: contract(
+    ['cctv'],
+    ['getCatalog', 'getHealth', 'getFrameUrl', 'getMediaUrl'],
+  ),
+  radio: contract(['radio'], ['getDirectory', 'recordClick']),
+  traffic: contract(
+    ['traffic'],
+    [
+      'requestRoads',
+      'getStatus',
+      'fetchFlowForBounds',
+      'getFlowSessionStats',
+      'resetFlowTileCache',
+    ],
+  ),
+  bikeshare: contract(['bikeshare'], ['getStations']),
+  installations: contract(
+    ['military-installations'],
+    ['getMappedSites', 'searchNearby'],
+  ),
+  satellites: contract(['satellites'], ['readGroup']),
+  launches: contract(['rocket-launches'], ['getLaunches', 'getActiveTle']),
+  alpr: contract(['alpr-cameras'], ['fetch']),
+  firms: contract(['local-firms'], ['getSnapshot']),
+  wind: contract(['wind'], ['getSnapshot']),
+  weather: contract(
+    ['weather-radar', 'weather-satellite', 'weather-lightning'],
+    ['getSnapshot'],
+  ),
+  cyclones: contract(['weather-cyclones'], ['getSnapshot']),
+  earthquakes: contract(['earthquakes'], ['getSnapshot']),
+  'fire-perimeters': contract(['fire-perimeters'], ['getSnapshot']),
+  cables: contract(['telegeography-submarine-cables'], ['fetch']),
+  transit: contract(['transit'], ['requestSnapshot', 'getHistory']),
+});
+
+/** An omitted provider is unavailable, never an authoritative empty dataset. */
+export class SourceUnavailableError extends Error {
+  constructor(name) {
+    super(`Data source not configured: ${name}`);
+    this.name = 'SourceUnavailableError';
+    this.code = 'unavailable';
+    this.unavailable = true;
+    this.retryable = false;
+  }
+}
+
+/** Validate supplied contracts and keep omitted sources inert during construction. */
+export function resolveCatalogSources(supplied = {}) {
+  if (!supplied || typeof supplied !== 'object' || Array.isArray(supplied))
+    throw new TypeError('Catalog sources must be an object');
+  const sources = { ...supplied };
+  const missing = new Set();
+  for (const [name, { methods }] of Object.entries(CATALOG_SOURCE_CONTRACTS)) {
+    const source = sources[name];
+    if (source == null) {
+      missing.add(name);
+      const unavailable = () => {
+        throw new SourceUnavailableError(name);
+      };
+      sources[name] = Object.freeze({
+        label: name,
+        ...Object.fromEntries(methods.map((method) => [method, unavailable])),
+      });
+    } else if (methods.some((method) => typeof source[method] !== 'function')) {
+      throw new TypeError(`Invalid catalog source: ${name}`);
+    }
+  }
+  return {
+    sources,
+    isConfigured: (name) => !missing.has(name),
+    createAvailabilityLookup(layers) {
+      const byId = new Map(layers.map((layer) => [layer.id, layer]));
+      const availability = new Map();
+      for (const [name, { layers: ids }] of Object.entries(
+        CATALOG_SOURCE_CONTRACTS,
+      )) {
+        for (const id of ids) {
+          const layer = byId.get(id);
+          if (!layer) throw new Error(`Missing source consumer: ${id}`);
+          availability.set(
+            id,
+            Object.freeze({
+              available: !missing.has(name),
+              source: name,
+              reason: missing.has(name)
+                ? `${layer.name || id}: data source not configured`
+                : null,
+            }),
+          );
+        }
+      }
+      return (id) =>
+        availability.get(id) ?? byId.get(id)?.getSourceAvailability?.();
+    },
+  };
+}

src/app/sourceComposition.test.mjs

@@ -0,0 +1,156 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import {
+  resolveCatalogSources,
+  CATALOG_SOURCE_CONTRACTS,
+} from './sourceComposition.js';
+import { createApplicationCatalog } from './constructCatalog.js';
+import { createSurfaceServices } from './surfaceServices.js';
+import { createStandaloneLayerSources } from '../standalone/layerSources.js';
+import { LayerLifecycle } from '../data/lifecycle.js';
+
+function catalog(sources, t) {
+  const lifetime = new AbortController();
+  t.after(() => lifetime.abort());
+  return createApplicationCatalog({
+    sources,
+    signal: lifetime.signal,
+    surface: createSurfaceServices({
+      terrainSource: { getHeights: async () => [] },
+      signal: lifetime.signal,
+      eventTarget: null,
+    }),
+  });
+}
+
+test('every acquisition source can be omitted without losing catalog membership', (t) => {
+  const baseline = catalog(createStandaloneLayerSources(), t);
+  for (const name of Object.keys(CATALOG_SOURCE_CONTRACTS)) {
+    const sources = createStandaloneLayerSources({ [name]: null });
+    const actual = catalog(sources, t);
+    assert.deepEqual(actual.metadata, baseline.metadata, name);
+    for (const id of CATALOG_SOURCE_CONTRACTS[name].layers) {
+      assert.equal(actual.getSourceAvailability(id).available, false, id);
+    }
+  }
+});
+
+test('all acquisition sources may be absent, and enable fails before initializing or fetching', async (t) => {
+  const actual = catalog({}, t);
+  assert.equal(actual.layers.length, 30);
+  const manager = new LayerLifecycle(
+    {},
+    { getSourceAvailability: actual.getSourceAvailability },
+  );
+  for (const layer of actual.layers) manager.register(layer);
+  for (const { layers: ids } of Object.values(CATALOG_SOURCE_CONTRACTS)) {
+    for (const id of ids) {
+      assert.equal(await manager.setEnabled(id, true), false, id);
+      assert.equal(manager.layers.get(id).initialized, false, id);
+      const row = manager.getAll().find((entry) => entry.id === id);
+      assert.equal(row.enabled, false);
+      assert.equal(row.stats.status, 'unavailable');
+      assert.match(row.stats.error, /data source not configured/);
+    }
+  }
+});
+
+test('configured sources retain identity; invalid implementations never become unavailable silently', () => {
+  const source = { getSnapshot: async () => [] };
+  assert.equal(
+    resolveCatalogSources({ earthquakes: source }).sources.earthquakes,
+    source,
+  );
+  for (const name of Object.keys(CATALOG_SOURCE_CONTRACTS)) {
+    assert.throws(
+      () => resolveCatalogSources({ [name]: {} }),
+      /Invalid catalog source/,
+    );
+  }
+  const missing = resolveCatalogSources({}).sources.earthquakes;
+  assert.throws(() => missing.getSnapshot(), { code: 'unavailable' });
+});
+
+test('standalone defaults allow exact replacements and explicit removal, and reject typos', () => {
+  const source = { getSnapshot: async () => [] };
+  const sources = createStandaloneLayerSources({
+    flights: source,
+    military: null,
+  });
+  assert.equal(sources.flights, source);
+  assert.equal(sources.military, null);
+  assert.equal(typeof sources.cctv.getCatalog, 'function');
+  assert.throws(
+    () => createStandaloneLayerSources({ fligts: source }),
+    /Unknown source/,
+  );
+});
+
+test('empty Street Level uses the shared unavailable lifecycle without initialization', async (t) => {
+  const actual = catalog({}, t);
+  const manager = new LayerLifecycle(
+    {},
+    { getSourceAvailability: actual.getSourceAvailability },
+  );
+  manager.register(actual.get('street-level'));
+  assert.equal(await manager.setEnabled('street-level', true), false);
+  assert.equal(manager.layers.get('street-level').initialized, false);
+  const row = manager.getAll()[0];
+  assert.equal(row.stats.status, 'unavailable');
+  assert.equal(row.stats.error, 'No street-level imagery providers configured');
+  assert.equal(await manager.setEnabled('street-level', false), true);
+  const configured = catalog(createStandaloneLayerSources(), t);
+  assert.equal(
+    configured.get('street-level').getSourceAvailability().available,
+    true,
+  );
+});
+
+test('availability lookup accepts frozen layers and uses their display names', () => {
+  const composition = resolveCatalogSources({});
+  const layers = Object.values(CATALOG_SOURCE_CONTRACTS)
+    .flatMap(({ layers }) => layers)
+    .map((id) =>
+      Object.freeze({
+        id,
+        name: id === 'fire-perimeters' ? 'Fire perimeters' : id,
+      }),
+    );
+  const lookup = composition.createAvailabilityLookup(layers);
+  assert.equal(
+    lookup('fire-perimeters').reason,
+    'Fire perimeters: data source not configured',
+  );
+  assert.equal(Object.hasOwn(layers[0], 'getSourceAvailability'), false);
+  const manager = new LayerLifecycle({}, { getSourceAvailability: lookup });
+  manager.register(layers.find(({ id }) => id === 'fire-perimeters'));
+  assert.equal(
+    manager.getAll()[0].stats.error,
+    'Fire perimeters: data source not configured',
+  );
+});
+
+test('absent military acquisition does not poll, suppress flights, or erase supplied classification', async (t) => {
+  let fetches = 0;
+  t.mock.method(globalThis, 'fetch', async () => {
+    fetches++;
+    throw new Error('Unexpected fallback acquisition');
+  });
+  const actual = catalog(createStandaloneLayerSources({ military: null }), t);
+  const registry = actual.militaryRegistry;
+  assert.equal(actual.getSourceAvailability('flights').available, true);
+  assert.equal(registry.isMilitaryLayerActive(), false);
+  assert.equal(registry.isMilitaryIcao('abc123'), false);
+  registry.registerMilitaryIcaos([' ABC123 ']);
+  await registry.refreshMilitaryRegistryIfStale();
+  assert.equal(registry.isMilitaryIcao('abc123'), true);
+  assert.equal(registry.isMilitaryIcao('def456'), false);
+  const manager = new LayerLifecycle(
+    {},
+    { getSourceAvailability: actual.getSourceAvailability },
+  );
+  manager.register(actual.get('military'));
+  assert.equal(await manager.setEnabled('military', true), false);
+  assert.equal(registry.isMilitaryLayerActive(), false);
+  assert.equal(fetches, 0);
+});

src/app/tools.js

@@ -4,6 +4,7 @@ import { initDrawTool } from '../annotations/drawTool.js';
 import { initImageryBoxTool } from '../ui/imageryBoxTool.js';
 import { createRecentImageryPanel } from '../ui/recentImagery.js';
 import { initGevVoiceCommands } from '../voice/gevRealtime.js';
+import { installViews, isEmbeddedInline } from './embed.js';
 import { installScopeMask, destroyScopeMask } from '../scopeMask.js';
 import {
   installRenderGovernor,
@@ -118,7 +119,9 @@ export function createApplicationTools({
   // GPU. Holder/data state is untouched, so return is seamless: restore
   // the loop, refresh the one DOM surface we gated, render a frame.
   const syncVisibilitySuspension = () => {
-    const hidden = document.hidden;
+    // A panel's host may report it hidden while it is on screen; the panel
+    // keeps drawing itself (see keepPanelRendering in embed.js).
+    const hidden = document.hidden && !isEmbeddedInline();
     viewer.useDefaultRenderLoop = !hidden;
     cockpitCloudEffects?.setSuspended?.(hidden);
     if (!hidden) {
@@ -176,5 +179,14 @@ export function createApplicationTools({
       delete window.__gevVoiceCommands;
   });
   debug.voiceCommands = voiceCommands;
+  defer(
+    installViews({
+      shell: styleManager,
+      viewer,
+      dataManager,
+      run: (name, args) => voiceCommands.runner(name, args, { signal }),
+      signal,
+    }),
+  );
   return { sceneDirector, annotations, voiceCommands };
 }