Merge origin/main: keep the provider registry, slim it

main grew the Street Level provider registry while this branch removed it
(#982–#985: injected providers, an empty composition, the `r` switch field).
The registry, params, uiState and pick router come back as main has them and
the slimmed layer sits behind the provider contract:

- The core (index.js) drives providers as on main, without surface modes,
  ground casting, FOLLOW, prewarm and nearest-image lookups. A provider's key
  status is asked with a 10 s timeout and asked again on a switch-on while no
  key is known.
- Mapillary is mapillaryProvider.js over the slim coverage, sequences and
  viewer modules, which read the filter and the active flag from the provider
  context.
- The viewer host mounts one provider adapter at a time, no prewarm.
- The panel has a chip per provider again (the pill switches the layer);
  no legend, EXPAND stays the Fullscreen API.
- The contract drops what no provider implements: groundCaster, meshSampler,
  getSurface/setSurface, nearestImage, prewarm, reportError, the legend and
  surface fields of the UI snapshot.

Co-Authored-By: Claude Fable 5.1 <[email protected]>

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/);

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';
@@ -31,34 +32,6 @@ 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'],
-  mapillary: ['getStatus', 'getTile', 'getSequenceImages'],
-});
-
 /**
  * Hardware-local layers are registered like any other but never enter share
  * links or stored layer state: another browser cannot have this receiver.
@@ -85,6 +58,7 @@ export function createApplicationCatalog({
   vesselOptions,
   resolveAsset,
   nepalBoundaryResolver,
+  streetLevelProviders,
 }) {
   if (!signal?.addEventListener)
     throw new TypeError('An application lifetime signal is required');
@@ -92,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 = () => {
@@ -107,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,
@@ -151,7 +122,9 @@ export function createApplicationCatalog({
         }),
         createApplicationAlpr({ surface, source: sources.alpr }),
         createApplicationStreetLevel({
+          surface,
           sources: { mapillary: sources.mapillary },
+          providers: streetLevelProviders,
         }),
         satellites,
         createApplicationLaunches({ source: sources.launches, satellites }),
@@ -160,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({
@@ -202,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();
@@ -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/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

@@ -1,13 +1,23 @@
 import { createStreetLevelLayer } from '../../layers/streetLevel/index.js';
+import { createMapillaryProvider } from '../../layers/streetLevel/mapillaryProvider.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';
 
-/** The Street Level layer over the application's Mapillary source. */
-export function createApplicationStreetLevel({ sources }) {
+/**
+ * Inject providers, or use Mapillary only when its source is supplied.
+ * An explicit provider list replaces the default; an unused sources.mapillary
+ * is neither constructed nor validated, including when the list is empty.
+ */
+export function createApplicationStreetLevel({
+  sources = {},
+  providers = sources.mapillary == null
+    ? []
+    : [createMapillaryProvider({ source: sources.mapillary })],
+}) {
   return createStreetLevelLayer({
-    source: sources.mapillary,
+    providers,
     services: { sprites, picking, input, render },
   });
 }

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/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/codexOauthRealtime.test.mjs

@@ -0,0 +1,273 @@
+import assert from 'node:assert/strict';
+import { EventEmitter } from 'node:events';
+import test from 'node:test';
+import path from 'node:path';
+import {
+  codexAuthPath,
+  preferCodexOAuth,
+  readCodexOAuthAccessToken,
+  resolveCodexExecutable,
+  startCodexChatGptLogin,
+} from '../server/providers/openai/codex-auth.js';
+
+const nowMs = Date.UTC(2026, 8, 27);
+const jwt = (payload) =>
+  `${Buffer.from('{}').toString('base64url')}.${Buffer.from(JSON.stringify(payload)).toString('base64url')}.signature`;
+const auth = (token, extras = {}) =>
+  JSON.stringify({
+    auth_mode: 'chatgpt',
+    tokens: { access_token: token, refresh_token: 'refresh-fixture' },
+    ...extras,
+  });
+
+test('optional Codex OAuth pin fails closed on ambiguous values', () => {
+  assert.equal(preferCodexOAuth({}), false);
+  assert.equal(preferCodexOAuth({ GEV_PREFER_CODEX_OAUTH: 'true' }), true);
+  assert.equal(preferCodexOAuth({ GEV_PREFER_CODEX_OAUTH: 'off' }), false);
+  assert.throws(
+    () => preferCodexOAuth({ GEV_PREFER_CODEX_OAUTH: 'maybe' }),
+    /must be true or false/,
+  );
+});
+
+test('Codex auth path follows explicit auth file, CODEX_HOME, then home directory', () => {
+  assert.equal(
+    codexAuthPath({
+      environment: { CODEX_AUTH_JSON: '/tmp/custom-auth.json' },
+      home: '/home/fixture',
+    }),
+    path.resolve('/tmp/custom-auth.json'),
+  );
+  assert.equal(
+    codexAuthPath({
+      environment: { CODEX_HOME: '/tmp/codex-home' },
+      home: '/home/fixture',
+    }),
+    path.join(path.resolve('/tmp/codex-home'), 'auth.json'),
+  );
+  assert.equal(
+    codexAuthPath({ environment: {}, home: '/home/fixture' }),
+    path.join('/home/fixture', '.codex', 'auth.json'),
+  );
+});
+
+test('Codex OAuth reader accepts a current ChatGPT token and rejects unusable credentials', () => {
+  const current = jwt({ exp: nowMs / 1000 + 3600 });
+  assert.equal(
+    readCodexOAuthAccessToken({
+      authPath: '/unused',
+      nowMs,
+      readFile: () => auth(current),
+    }),
+    current,
+  );
+  assert.equal(
+    readCodexOAuthAccessToken({
+      authPath: '/unused',
+      nowMs,
+      readFile: () =>
+        JSON.stringify({
+          auth_mode: 'chatgpt',
+          tokens: { access_token: current },
+        }),
+    }),
+    current,
+    'GEV does not require or consume the vendor refresh token',
+  );
+  for (const readFile of [
+    () => '{bad json',
+    () => JSON.stringify({ tokens: {} }),
+    () => auth(current, { auth_mode: 'apikey' }),
+    () =>
+      JSON.stringify({
+        OPENAI_API_KEY: 'sk-fixture',
+        tokens: { access_token: current, refresh_token: 'refresh-fixture' },
+      }),
+    () => auth('opaque-token'),
+    () => auth('header.not-json.signature'),
+    () => auth(jwt({ exp: 'tomorrow' })),
+    () => {
+      throw new Error('missing');
+    },
+  ]) {
+    assert.throws(
+      () => readCodexOAuthAccessToken({ authPath: '/unused', readFile, nowMs }),
+      /ChatGPT sign-in is unavailable/,
+    );
+  }
+});
+
+test('Codex OAuth reader enforces expiry margin and bounds tokens without exp by file age', () => {
+  for (const exp of [nowMs / 1000 - 1, nowMs / 1000 + 59]) {
+    assert.throws(
+      () => {
+        readCodexOAuthAccessToken({
+          authPath: '/unused',
+          nowMs,
+          readFile: () => auth(jwt({ exp })),
+        });
+      },
+      (error) => {
+        assert.match(error.message, /sign-in has expired/);
+        assert.equal(error.code, 'CODEX_OAUTH_REAUTH_REQUIRED');
+        return true;
+      },
+    );
+  }
+  const noExp = jwt({ sub: 'fixture' });
+  const base = { authPath: '/unused', nowMs, readFile: () => auth(noExp) };
+  assert.equal(
+    readCodexOAuthAccessToken({
+      ...base,
+      statFile: () => ({ mtimeMs: nowMs }),
+    }),
+    noExp,
+  );
+  assert.throws(
+    () =>
+      readCodexOAuthAccessToken({
+        ...base,
+        statFile: () => ({ mtimeMs: nowMs - 3600_000 }),
+      }),
+    /sign-in has expired/,
+  );
+  assert.throws(
+    () =>
+      readCodexOAuthAccessToken({
+        ...base,
+        statFile: () => {
+          throw new Error('missing');
+        },
+      }),
+    /sign-in is unavailable/,
+  );
+});
+
+test('Codex login resolves an installed executable before PATH and starts browser auth detached', async () => {
+  const checked = [];
+  assert.equal(
+    resolveCodexExecutable({
+      environment: {},
+      home: '/home/fixture',
+      access(candidate) {
+        checked.push(candidate);
+        if (candidate.endsWith('/.local/bin/codex')) return;
+        throw new Error('missing');
+      },
+    }),
+    path.join('/home/fixture', '.local', 'bin', 'codex'),
+  );
+  assert.equal(checked.length, 1);
+
+  const child = new EventEmitter();
+  let unref = 0;
+  child.unref = () => {
+    unref += 1;
+  };
+  const calls = [];
+  const pending = startCodexChatGptLogin({
+    executable: '/fixture/codex',
+    home: '/home/fixture',
+    environment: {
+      PATH: '/fixture',
+      https_proxy: 'http://proxy.fixture:8080',
+      OPENAI_API_KEY: 'fixture-api-key',
+      GOOGLE_MAPS_SERVER_API_KEY: 'fixture-google-key',
+      OPENSKY_CLIENT_SECRET: 'fixture-opensky-secret',
+    },
+    spawnImpl(command, args, options) {
+      calls.push({ command, args, options });
+      queueMicrotask(() => child.emit('spawn'));
+      return child;
+    },
+  });
+  const login = await pending;
+  assert.equal(unref, 1);
+  assert.equal(calls[0].command, '/fixture/codex');
+  assert.deepEqual(calls[0].args, ['login']);
+  assert.equal(calls[0].options.detached, true);
+  assert.equal(calls[0].options.stdio, 'ignore');
+  assert.deepEqual(
+    calls[0].options.env,
+    {
+      PATH: '/fixture',
+      https_proxy: 'http://proxy.fixture:8080',
+      CODEX_HOME: path.join('/home/fixture', '.codex'),
+    },
+    'provider secrets stay out of the login process',
+  );
+  child.emit('exit', 1);
+  assert.deepEqual(await login.completion, { exitCode: 1 });
+});
+
+test('Codex login refuses a read/write storage mismatch before spawning', async () => {
+  await assert.rejects(
+    startCodexChatGptLogin({
+      environment: { CODEX_AUTH_JSON: '/tmp/another-auth.json' },
+      home: '/home/fixture',
+      executable: 'codex',
+      spawnImpl: () => assert.fail('mismatched storage must not launch login'),
+    }),
+    { code: 'CODEX_OAUTH_STORAGE_MISMATCH' },
+  );
+});
+
+test('Codex login resolves relative CODEX_HOME before changing the child directory', async () => {
+  const child = new EventEmitter();
+  const environment = { CODEX_HOME: './fixture-codex' };
+  const login = await startCodexChatGptLogin({
+    environment,
+    executable: 'codex',
+    spawnImpl(_command, _args, options) {
+      assert.equal(
+        options.env.CODEX_HOME,
+        path.resolve(environment.CODEX_HOME),
+      );
+      queueMicrotask(() => child.emit('spawn'));
+      return child;
+    },
+  });
+  assert.equal(
+    environment.CODEX_HOME,
+    './fixture-codex',
+    'caller environment is unchanged',
+  );
+  child.emit('exit', 0);
+  assert.deepEqual(await login.completion, { exitCode: 0 });
+});
+
+test('Codex login hides spawn errors and can cancel only its owned child', async () => {
+  const child = new EventEmitter();
+  await assert.rejects(
+    startCodexChatGptLogin({
+      executable: 'codex',
+      spawnImpl() {
+        queueMicrotask(() =>
+          child.emit('error', new Error('private-token-fixture')),
+        );
+        return child;
+      },
+    }),
+    (error) =>
+      error.code === 'CODEX_OAUTH_LOGIN_FAILED' &&
+      !error.message.includes('private-token-fixture'),
+  );
+
+  const running = new EventEmitter();
+  let cancelled = 0;
+  running.kill = (signal) => {
+    assert.equal(signal, 'SIGTERM');
+    cancelled += 1;
+    running.emit('exit', null);
+  };
+  const login = await startCodexChatGptLogin({
+    executable: 'codex',
+    spawnImpl() {
+      queueMicrotask(() => running.emit('spawn'));
+      return running;
+    },
+  });
+  login.cancel();
+  assert.equal(cancelled, 1);
+  assert.deepEqual(await login.completion, { exitCode: null });
+});

src/data/directions.js

@@ -1,3 +1,4 @@
+import { createDirectionsSource } from '../layers/directions/source.js';
 /**
  * @module directions
  * @description Service bundle for the Directions layer.
@@ -37,8 +38,10 @@ export const directionsServices = Object.freeze({
 });
 
 /** Construct one Directions layer over the application scene owners. */
-export function createApplicationDirectionsLayer() {
-  return createDirectionsLayer({ services: directionsServices });
+export function createApplicationDirectionsLayer({
+  source = createDirectionsSource(),
+} = {}) {
+  return createDirectionsLayer({ services: directionsServices, source });
 }
 
 export {

src/data/idSwitches.js

@@ -0,0 +1,63 @@
+const MAX_SWITCHES_LENGTH = 256;
+const ENTRY = /^([a-z][a-z0-9-]*)-([01])$/;
+
+/** Canonical, bounded boolean switches keyed by stable slugs. */
+export function normalizeIdSwitches(value, reservedIds = []) {
+  if (typeof value !== 'string' || value.length > MAX_SWITCHES_LENGTH)
+    return null;
+  if (!value) return '';
+  const entries = new Map();
+  for (const field of value.split('*')) {
+    const match = ENTRY.exec(field);
+    if (!match || reservedIds.includes(match[1]) || entries.has(match[1]))
+      return null;
+    entries.set(match[1], match[2] === '1');
+  }
+  return [...entries]
+    .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
+    .map(([id, on]) => `${id}-${on ? '1' : '0'}`)
+    .join('*');
+}
+
+/** Encode by stable IDs rather than registration order or generated tokens. */
+export function encodeIdSwitches(switches) {
+  const value = [...switches]
+    .map(([id, on]) => `${id}-${on === true ? '1' : '0'}`)
+    .join('*');
+  if (value.length > MAX_SWITCHES_LENGTH)
+    throw new RangeError(
+      `Switch IDs exceed the ${MAX_SWITCHES_LENGTH}-character share-link limit`,
+    );
+  const normalized = normalizeIdSwitches(value);
+  if (normalized === null) throw new TypeError('Invalid boolean switch IDs');
+  return normalized;
+}
+
+/** A Map keeps switch IDs separate from object prototype properties. */
+export function decodeIdSwitches(value) {
+  const normalized = normalizeIdSwitches(value);
+  return new Map(
+    normalized
+      ? normalized.split('*').map((entry) => {
+          const [, id, on] = ENTRY.exec(entry);
+          return [id, on === '1'];
+        })
+      : [],
+  );
+}
+
+/** Persist only explicitly requested switch IDs, not unrelated live changes. */
+export function patchRequestedIdSwitches(previous, applied, requested) {
+  const current = decodeIdSwitches(applied);
+  const next = new Map(
+    [...decodeIdSwitches(previous)].filter(([id]) => current.has(id)),
+  );
+  let changed = false;
+  for (const [id, on] of current) {
+    if (Object.hasOwn(requested, id) && typeof requested[id] === 'boolean') {
+      next.set(id, on);
+      changed = true;
+    }
+  }
+  return changed ? encodeIdSwitches(next) : undefined;
+}

src/data/layerState.js

@@ -1,3 +1,4 @@
+import { normalizeIdSwitches, patchRequestedIdSwitches } from './idSwitches.js';
 import reservationRows from './layerStateTokenReservations.json' with { type: 'json' };
 
 const VALID_DISPOSITIONS = new Set([
@@ -411,8 +412,17 @@ const OPTION_GROUPS = Object.freeze({
     booleanOption('viirs', 'v', false),
   ]),
   'street-level': Object.freeze([
-    // The Mapillary switch: off, the layer draws nothing.
+    // Preserve the published Mapillary token; custom switches use stable IDs.
     booleanOption('mapillary', 'm', true),
+    Object.freeze({
+      key: 'providerSwitches',
+      patchRequested: patchRequestedIdSwitches,
+      token: 'r',
+      defaultValue: '',
+      normalize: (value) => normalizeIdSwitches(value, ['mapillary']),
+      encode: normalizeIdSwitches,
+      decode: (value) => normalizeIdSwitches(value, ['mapillary']),
+    }),
     enumOption('pano', 'p', 'all', ['all', 'pano', 'flat'], {
       all: 'a',
       pano: 'p',

src/data/layerState.test.mjs

@@ -1,3 +1,4 @@
+import { encodeParams, decodeParams } from '../layers/streetLevel/params.js';
 import { readShellSource } from '../testSupport/readShellSource.mjs';
 import { expandApplicationHtml } from '../../build/application-html.js';
 import { readLayerSource } from '../testSupport/readLayerSource.mjs';
@@ -243,7 +244,11 @@ test('production registry is exact, canonical, and rejects incomplete contracts'
   }
   assert.equal(nextLayerStateToken(), '3');
   assert.equal(
-    nextLayerStateToken({ ...LAYER_STATE_TOKEN_RESERVATIONS, alpha: '3', bravo: '4' }),
+    nextLayerStateToken({
+      ...LAYER_STATE_TOKEN_RESERVATIONS,
+      alpha: '3',
+      bravo: '4',
+    }),
     '5',
   );
   const digitsExhausted = {
@@ -276,7 +281,9 @@ test('production registry is exact, canonical, and rejects incomplete contracts'
           [
             ...'0123456789',
             ...[...LAYER_STATE_TOKEN_ALPHABET].flatMap((first) =>
-              [...LAYER_STATE_TOKEN_ALPHABET].map((second) => `${first}${second}`),
+              [...LAYER_STATE_TOKEN_ALPHABET].map(
+                (second) => `${first}${second}`,
+              ),
             ),
           ].map((token, index) => [`occupied-${index}`, token]),
         ),
@@ -298,33 +305,37 @@ test('production registry is exact, canonical, and rejects incomplete contracts'
     true,
   );
   assert.equal(
-    validateLayerStateAllocations(
-      LAYER_STATE_TOKEN_RESERVATIONS,
-      { ...LAYER_STATE_TOKEN_RESERVATIONS, future: '3', next: '4' },
-    ),
+    validateLayerStateAllocations(LAYER_STATE_TOKEN_RESERVATIONS, {
+      ...LAYER_STATE_TOKEN_RESERVATIONS,
+      future: '3',
+      next: '4',
+    }),
     true,
   );
   assert.throws(
-    () => validateLayerStateAllocations(LAYER_STATE_TOKEN_RESERVATIONS, {
-      ...LAYER_STATE_TOKEN_RESERVATIONS,
-      future: '00',
-    }),
+    () =>
+      validateLayerStateAllocations(LAYER_STATE_TOKEN_RESERVATIONS, {
+        ...LAYER_STATE_TOKEN_RESERVATIONS,
+        future: '00',
+      }),
     /next free token 3/,
   );
   const beforeLastDigit = { ...digitsExhausted };
   delete beforeLastDigit['prior-9'];
   assert.equal(
-    validateLayerStateAllocations(
-      beforeLastDigit,
-      { ...beforeLastDigit, futurePair: '00', futureDigit: '9' },
-    ),
+    validateLayerStateAllocations(beforeLastDigit, {
+      ...beforeLastDigit,
+      futurePair: '00',
+      futureDigit: '9',
+    }),
     true,
   );
   assert.equal(
-    validateLayerStateAllocations(
-      digitsExhausted,
-      { ...digitsExhausted, pairB: '01', pairA: '00' },
-    ),
+    validateLayerStateAllocations(digitsExhausted, {
+      ...digitsExhausted,
+      pairB: '01',
+      pairA: '00',
+    }),
     true,
   );
   assert.throws(
@@ -2660,12 +2671,14 @@ test('Street Level: every option round-trips through a share link and stored sta
   state.enabledLayerIds = ['street-level'];
   state.options['street-level'] = {
     mapillary: false,
+    providerSwitches: '',
     pano: 'flat',
     sinceDays: MAX_SINCE_DAYS,
   };
   const decoded = decodeLayerStateParams(new URLSearchParams(encode(state)));
   assert.deepEqual(decoded.options['street-level'], {
     mapillary: false,
+    providerSwitches: '',
     pano: 'flat',
     sinceDays: MAX_SINCE_DAYS,
   });
@@ -2693,6 +2706,7 @@ test('Street Level: the link codec accepts exactly the windows the filter keeps'
 test('Street Level: a link without the provider switch keeps Mapillary on', () => {
   assert.deepEqual(streetLevelOptions(''), {
     mapillary: true,
+    providerSwitches: '',
     pano: 'all',
     sinceDays: 0,
   });
@@ -2703,3 +2717,73 @@ test('Street Level: a link without the provider switch keeps Mapillary on', () =
     true,
   );
 });
+
+test('explicit provider switches reach durable state without adopting unrelated live switches', () => {
+  const manager = new DataLayerManager({});
+  const providers = new Map([
+    ['mapillary', true],
+    ['alpha', true],
+    ['beta', true],
+  ]);
+  const filter = { pano: 'all', sinceDays: 0 };
+  for (const id of REGISTERED_LAYER_IDS) {
+    manager.register(
+      id === 'street-level'
+        ? {
+            ...fakeLayer(id),
+            getParams: () => encodeParams({ providers, filter }),
+            setParams(params) {
+              const decoded = decodeParams(params, {
+                providerIds: providers.keys(),
+                filter,
+              });
+              for (const [id, on] of decoded.providers) providers.set(id, on);
+              return true;
+            },
+          }
+        : fakeLayer(id),
+    );
+  }
+  manager.finalizeRegistrations(LAYER_STATE_REGISTRY);
+  const storage = memoryStorage();
+  const coordinator = new LayerStateCoordinator(manager, shareSink(), {
+    storage,
+  });
+  try {
+    providers.set('beta', false); // Passive state does not belong to the next action.
+    assert.equal(
+      manager.setLayerParams(
+        'street-level',
+        { alpha: false },
+        { origin: 'user' },
+      ),
+      true,
+    );
+    let saved = parseStoredLayerState(storage.getItem(LAYER_STATE_STORAGE_KEY));
+    assert.equal(saved.options['street-level'].providerSwitches, 'alpha-0');
+    const shared = decodeLayerStateParams(new URLSearchParams(encode(saved)));
+    const restored = decodeParams(shared.options['street-level'], {
+      providerIds: ['beta', 'alpha'],
+      filter,
+    });
+    assert.deepEqual([...restored.providers], [['alpha', false]]);
+    manager.setLayerParams('street-level', { beta: true }, { origin: 'user' });
+    saved = parseStoredLayerState(storage.getItem(LAYER_STATE_STORAGE_KEY));
+    assert.equal(
+      saved.options['street-level'].providerSwitches,
+      'alpha-0*beta-1',
+    );
+    manager.setLayerParams(
+      'street-level',
+      { alpha: true },
+      { origin: 'local-restore' },
+    );
+    saved = parseStoredLayerState(storage.getItem(LAYER_STATE_STORAGE_KEY));
+    assert.equal(
+      saved.options['street-level'].providerSwitches,
+      'alpha-0*beta-1',
+    );
+  } finally {
+    coordinator.destroy();
+  }
+});

src/data/layerStateCoordinator.js

@@ -255,8 +255,22 @@ export class LayerStateCoordinator {
       const explicitlyRequested = Object.hasOwn(requestedParams, spec.key);
       const implicitTrackingSync =
         !explicitlyRequested && spec.key === trackingOptionKey;
-      if (!explicitlyRequested && !implicitTrackingSync) continue;
-      const value = spec.normalize(change.params[spec.key]);
+      // Packed options can persist only the subkeys owned by this request.
+      const requestedValue =
+        explicitlyRequested || implicitTrackingSync
+          ? change.params[spec.key]
+          : spec.patchRequested?.(
+              nextOwnerOptions[spec.key],
+              change.params[spec.key],
+              requestedParams,
+            );
+      if (
+        !explicitlyRequested &&
+        !implicitTrackingSync &&
+        requestedValue === undefined
+      )
+        continue;
+      const value = spec.normalize(requestedValue);
       if (value === null) {
         if (implicitTrackingSync) {
           nextOwnerOptions[spec.key] = null;

src/data/layerStateTokenLedger.test.mjs

@@ -98,6 +98,12 @@ function withPublishedBase(
 }
 
 function writeCodecFixture(cwd, rows, entries) {
+  const providerCodec = path.join(cwd, 'src/data/idSwitches.js');
+  mkdirSync(path.dirname(providerCodec), { recursive: true });
+  writeFileSync(
+    providerCodec,
+    readFileSync(new URL('./idSwitches.js', import.meta.url)),
+  );
   const source = readFileSync(CODEC_SOURCE_PATH, 'utf8');
   const registryEnd = ']);\n\nexport const REGISTERED_LAYER_IDS';
   assert.equal(source.split(registryEnd).length, 2);

src/data/lifecycle.js

@@ -74,7 +74,11 @@ function refreshFailureFromStats(stats, label) {
  * for real-time data overlays on the CesiumJS globe.
  */
 export class LayerLifecycle {
-  constructor(viewer, { allowQaRegistration = false } = {}) {
+  constructor(
+    viewer,
+    { allowQaRegistration = false, getSourceAvailability } = {},
+  ) {
+    this._catalogSourceAvailability = getSourceAvailability;
     this.viewer = viewer;
     this._activityListeners = new Set();
     this.layers = new Map(); // id → { module, enabled, initialized, intervalId, lifecycleState, lifecycleUncertain }
@@ -228,6 +232,7 @@ export class LayerLifecycle {
 
   _normalizedStats(entry) {
     const moduleStats = this._moduleStats(entry);
+    const availability = this._sourceAvailability(entry.module.id);
     const lifecycleLoading =
       entry.lifecycleState === 'enabling' ||
       entry.lifecycleState === 'disabling';
@@ -235,6 +240,13 @@ export class LayerLifecycle {
       count: 0,
       lastUpdate: null,
       ...moduleStats,
+      ...(availability?.available === false
+        ? {
+            status: 'unavailable',
+            sourceUnavailable: true,
+            error: availability.reason,
+          }
+        : {}),
       loading: lifecycleLoading || moduleStats.loading === true,
       refreshing: entry.refreshing || moduleStats.refreshing === true,
       managerRefreshError: entry.managerRefreshError,
@@ -2282,7 +2294,17 @@ export class LayerLifecycle {
     }
   }
 
+  _sourceAvailability(layerId) {
+    return (
+      this._catalogSourceAvailability?.(layerId) ??
+      this.layers.get(layerId)?.module.getSourceAvailability?.()
+    );
+  }
+
   async _visibilityBlockReason(change) {
+    const availability = this._sourceAvailability(change.layerId);
+    if (change.enabled && availability?.available === false)
+      return availability.reason || 'Data source unavailable';
     for (const callback of this._visibilityGuards) {
       try {
         const result = await callback(change);

src/data/sharedOsmDisplays.test.mjs

@@ -7,6 +7,7 @@ import { createBhoteKoshiLocatorLayer } from './bhoteKoshiLocator.js';
 import { createWorldAnnotationRenderer } from '../annotations/worldAnnotationRenderer.js';
 import * as annotations from '../annotations/worldAnnotationRenderer.js';
 import { createDirectionsLayer } from '../layers/directions/index.js';
+import { createDirectionsSource } from '../layers/directions/source.js';
 import { createLifecycle as createCctvLifecycle } from '../layers/cctv/lifecycle.js';
 import * as input from './inputOwnership.js';
 import { createOverpassAlprSource } from '../layers/alpr/source.js';
@@ -64,7 +65,7 @@ test('voice route geometry introduces the shared OSM credit', (t) => {
 test('Directions introduces the shared OSM credit when the requested route draws', async (t) => {
   const v = viewer(t);
   t.mock.method(globalThis, 'fetch', async () => Response.json({ ok: true, geometry: [[0, 0], [0.01, 0.01]], steps: [] }));
-  const layer = createDirectionsLayer({ services: {
+  const layer = createDirectionsLayer({ source: createDirectionsSource(), services: {
     credits: { showOsmCredit, hideOsmCredit }, annotations, input, scenePick: {}, camera: {},
     overlays: { setOverlayEntries: noop, setOverlaySourceVisible: noop, clearOverlaySource: noop },
     render: { governorRequestRender: noop, holdContinuousRender: noop, releaseContinuousRender: noop },

src/keySetup.js

@@ -1,4 +1,8 @@
 import { createSurfaceKeyboard } from './ui/surfaceKeyboard.js';
+import {
+  readStoredCloudVoiceAuthMode,
+  writeStoredCloudVoiceAuthMode,
+} from './voice/cloudVoiceAuth.js';
 
 /**
  * The POWER UP surface — paste a key, get a power.
@@ -38,6 +42,52 @@ export function collectKeyUpdates(fields) {
   return updates;
 }
 
+function sleepWithSignal(ms, signal) {
+  return new Promise((resolve, reject) => {
+    if (signal?.aborted) {
+      reject(signal.reason || new DOMException('Aborted', 'AbortError'));
+      return;
+    }
+    const onAbort = () => {
+      clearTimeout(timer);
+      reject(signal.reason || new DOMException('Aborted', 'AbortError'));
+    };
+    const timer = setTimeout(() => {
+      signal?.removeEventListener('abort', onAbort);
+      resolve();
+    }, ms);
+    signal?.addEventListener('abort', onAbort, { once: true });
+  });
+}
+
+export async function waitForChatGptOAuth({
+  fetchImpl,
+  signal,
+  timeoutMs = 120_000,
+  pollMs = 1_000,
+  now = () => Date.now(),
+  sleep = sleepWithSignal,
+} = {}) {
+  const deadline = now() + Math.max(0, timeoutMs);
+  while (!signal?.aborted && now() <= deadline) {
+    const response = await fetchImpl('/api/realtime/oauth-status', {
+      cache: 'no-store',
+      signal,
+    });
+    const payload = await response.json().catch(() => ({}));
+    if (signal?.aborted) return false;
+    if (response.ok && payload.available) return true;
+    if (!response.ok || payload.loginFailed) {
+      throw new Error(
+        payload.error || 'Could not check ChatGPT sign-in. Try again.',
+      );
+    }
+    if (now() >= deadline) break;
+    await sleep(Math.max(0, pollMs), signal);
+  }
+  return false;
+}
+
 /**
  * After the FIRST Google key lands, the restart's reload should boot the
  * photoreal default — not faithfully restore the auto-selected keyless OSM
@@ -61,6 +111,21 @@ export function stripKeylessBasemapFromHash(hash) {
 
 const TIER_DOTS = Object.freeze({ metered: '🔴', free: '🟡' });
 
+function updateCloudVoiceAuthControl(auth, busy = false) {
+  const mode = readStoredCloudVoiceAuthMode();
+  const state = auth.querySelector('.key-setup-cloud-auth-state');
+  const toggle = auth.querySelector('[data-cloud-voice-auth-toggle]');
+  state.textContent =
+    mode === 'oauth' ? 'VOICE AUTH · CHATGPT OAUTH' : 'VOICE AUTH · API KEY';
+  toggle.textContent = mode === 'oauth' ? 'USE API KEY' : 'USE CHATGPT OAUTH';
+  toggle.title =
+    mode === 'oauth'
+      ? 'Use OPENAI_API_KEY for the next cloud voice session'
+      : 'Use the signed-in local ChatGPT/Codex OAuth session for the next cloud voice session';
+  // Keep the control focusable while the delegated handler blocks repeats.
+  toggle.setAttribute('aria-disabled', String(busy));
+}
+
 /** Build one key row. All content is our own registry text, set via textContent. */
 function buildRow(documentRef, key) {
   const row = documentRef.createElement('section');
@@ -144,6 +209,19 @@ function buildRow(documentRef, key) {
     }
     row.append(fields);
   }
+  if (key.id === 'openai') {
+    const auth = documentRef.createElement('div');
+    auth.className = 'key-setup-cloud-auth';
+    const state = documentRef.createElement('span');
+    state.className = 'key-setup-cloud-auth-state';
+    const toggle = documentRef.createElement('button');
+    toggle.type = 'button';
+    toggle.className = 'key-setup-cloud-auth-toggle';
+    toggle.dataset.cloudVoiceAuthToggle = 'true';
+    auth.append(state, toggle);
+    updateCloudVoiceAuthControl(auth);
+    row.append(auth);
+  }
   return row;
 }
 
@@ -224,8 +302,14 @@ export async function initKeySetup({
   const statusLine = root.querySelector('[data-key-setup-status]');
   const defaultStatusText = statusLine?.textContent || '';
   let busy = false;
+  let oauthBusy = false;
   let open = false;
 
+  const syncCloudVoiceAuth = () => {
+    for (const auth of rowsHost.querySelectorAll('.key-setup-cloud-auth'))
+      updateCloudVoiceAuthControl(auth, oauthBusy);
+  };
+
   const render = (nextStatus) => {
     if (disposed) return;
     status = nextStatus;
@@ -239,6 +323,7 @@ export async function initKeySetup({
     rowsHost.textContent = '';
     for (const key of status.keys || [])
       rowsHost.append(buildRow(documentRef, key));
+    syncCloudVoiceAuth();
   };
 
   const visible = () =>
@@ -367,6 +452,100 @@ export async function initKeySetup({
   applyButton?.addEventListener('click', onApply);
   // Remove buttons are rendered per row; delegate so re-renders stay wired.
   rowsHost?.addEventListener('click', (event) => {
+    const authButton = event.target?.closest?.(
+      '[data-cloud-voice-auth-toggle]',
+    );
+    if (authButton && !disposed) {
+      if (oauthBusy) return;
+      void (async () => {
+        const current = readStoredCloudVoiceAuthMode();
+        if (current === 'oauth') {
+          writeStoredCloudVoiceAuthMode('api-key');
+          syncCloudVoiceAuth();
+          say('Cloud voice will use OPENAI_API_KEY on the next session.');
+          return;
+        }
+        oauthBusy = true;
+        syncCloudVoiceAuth();
+        say('Checking local ChatGPT OAuth sign-in…');
+        try {
+          const response = await doFetch('/api/realtime/oauth-status', {
+            cache: 'no-store',
+            signal: lifetime.signal,
+          });
+          const payload = await response.json().catch(() => ({}));
+          if (lifetime.signal.aborted) return;
+          if (!response.ok)
+            throw new Error(
+              payload.error || 'Could not check ChatGPT sign-in.',
+            );
+          if (payload.available) {
+            writeStoredCloudVoiceAuthMode('oauth');
+            syncCloudVoiceAuth();
+            say(
+              'ChatGPT OAuth selected for cloud voice. Your API key stays saved and available.',
+            );
+            return;
+          }
+
+          say(
+            payload.code === 'CODEX_OAUTH_REAUTH_REQUIRED'
+              ? 'ChatGPT sign-in expired. Opening sign-in again…'
+              : 'Opening ChatGPT sign-in in your browser…',
+          );
+          const loginResponse = await doFetch('/api/realtime/oauth-login', {
+            method: 'POST',
+            cache: 'no-store',
+            signal: lifetime.signal,
+          });
+          const loginPayload = await loginResponse.json().catch(() => ({}));
+          if (lifetime.signal.aborted) return;
+          if (!loginResponse.ok) {
+            say(
+              loginPayload.error ||
+                payload.error ||
+                'Could not start ChatGPT sign-in on this machine.',
+            );
+            return;
+          }
+          if (loginPayload.available) {
+            writeStoredCloudVoiceAuthMode('oauth');
+            syncCloudVoiceAuth();
+            say(
+              'ChatGPT OAuth selected for cloud voice. Your API key stays saved and available.',
+            );
+            return;
+          }
+
+          say(
+            'Finish ChatGPT sign-in in the browser. Waiting for it to complete…',
+          );
+          const available = await waitForChatGptOAuth({
+            fetchImpl: doFetch,
+            signal: lifetime.signal,
+          });
+          if (lifetime.signal.aborted) return;
+          if (!available) {
+            say(
+              'ChatGPT sign-in timed out. Click USE CHATGPT OAUTH to try again.',
+            );
+            return;
+          }
+          writeStoredCloudVoiceAuthMode('oauth');
+          syncCloudVoiceAuth();
+          say(
+            'ChatGPT sign-in complete. OAuth will be used for the next cloud voice session.',
+          );
+        } catch (error) {
+          if (lifetime.signal.aborted) return;
+          say(`OAuth check failed: ${error?.message || error}`);
+        } finally {
+          oauthBusy = false;
+          if (!disposed) syncCloudVoiceAuth();
+        }
+      })();
+      return;
+    }
     const button = event.target?.closest?.('[data-key-setup-remove]');
     if (disposed || !button || busy) return;
     let envVars = [];

src/keySetup.test.mjs

@@ -5,6 +5,7 @@ import {
   keySetupChipLabel,
   stripKeylessBasemapFromHash,
   bindKeySetupPlacement,
+  waitForChatGptOAuth,
 } from './keySetup.js';
 
 test('setup placement moves the same button only in Cyber and disconnects on teardown', () => {
@@ -61,6 +62,64 @@ test('collectKeyUpdates keeps only non-empty trimmed values', () => {
   assert.deepEqual(collectKeyUpdates(null), {});
 });
 
+test('OAuth login polling stops as soon as local ChatGPT auth becomes available', async () => {
+  let checks = 0;
+  let clock = 0;
+  const available = await waitForChatGptOAuth({
+    fetchImpl: async () => {
+      checks += 1;
+      return {
+        ok: true,
+        json: async () => ({ available: checks >= 3 }),
+      };
+    },
+    timeoutMs: 10_000,
+    pollMs: 100,
+    now: () => clock,
+    sleep: async (ms) => {
+      clock += ms;
+    },
+  });
+  assert.equal(available, true);
+  assert.equal(checks, 3);
+});
+
+test('OAuth login polling stops on login or HTTP failure instead of waiting for timeout', async () => {
+  for (const result of [
+    { ok: true, payload: { available: false, loginFailed: true, error: 'Sign-in failed.' } },
+    { ok: false, payload: { error: 'Sign-in is local only.' } },
+  ]) {
+    let checks = 0;
+    await assert.rejects(waitForChatGptOAuth({
+      fetchImpl: async () => { checks += 1; return { ok: result.ok, json: async () => result.payload }; },
+      sleep: () => assert.fail('failed login must stop polling'),
+    }), { message: result.payload.error });
+    assert.equal(checks, 1);
+  }
+});
+
+test('OAuth login polling respects timeout and an aborted setup surface', async () => {
+  let clock = 0;
+  let checks = 0;
+  const poll = { fetchImpl: async () => { checks += 1; return { ok: true, json: async () => ({ available: false, pending: true }) }; } };
+  assert.equal(await waitForChatGptOAuth({ ...poll, timeoutMs: 100, pollMs: 100, now: () => clock, sleep: async (ms) => { clock += ms; } }), false);
+  assert.equal(checks, 2);
+  const controller = new AbortController();
+  controller.abort();
+  assert.equal(await waitForChatGptOAuth({ ...poll, signal: controller.signal }), false);
+  assert.equal(checks, 2, 'aborted polling does not fetch');
+});
+
+test('OAuth polling ignores a ready response received after the surface was aborted', async () => {
+  const controller = new AbortController();
+  const available = await waitForChatGptOAuth({
+    signal: controller.signal,
+    fetchImpl: async () => ({ ok: true, json: async () => { controller.abort(); return { available: true }; } }),
+    sleep: () => assert.fail('aborted polling must not continue'),
+  });
+  assert.equal(available, false);
+});
+
 test('the first Google key strips ONLY the keyless OSM basemap from the share hash', () => {
   const stripped = stripKeylessBasemapFromHash('lat=30.2&lon=-97.7&map=osm&style=normal');
   assert.ok(stripped !== null);

src/keySetupCore.mjs

@@ -55,7 +55,7 @@ export const KEY_SETUP_KEYS = Object.freeze([
   Object.freeze({
     id: 'openai',
     title: 'OPENAI',
-    unlocks: 'Voice control — talk to the planet',
+    unlocks: 'Voice control — API key or ChatGPT OAuth',
     getUrl: 'https://platform.openai.com/api-keys',
     envVars: Object.freeze(['OPENAI_API_KEY']),
     tier: 'metered',

src/layers/directions/index.js

@@ -452,10 +452,7 @@ export function createDirectionsStepOverlayEntry(index, position, copy) {
  * @param {{lat:number, lon:number}} b
  * @returns {string}
  */
-export function directionsRequestUrl(mode, a, b) {
-  const coords = `${a.lon.toFixed(6)},${a.lat.toFixed(6)};${b.lon.toFixed(6)},${b.lat.toFixed(6)}`;
-  return `/api/route?profile=${encodeURIComponent(mode)}&coords=${encodeURIComponent(coords)}&steps=1`;
-}
+export { directionsRequestUrl } from './source.js';
 
 /**
  * Validate a proxy payload into the route record the layer keeps, or null.
@@ -509,10 +506,12 @@ export function normalizeRoutePayload(payload, mode) {
  * route, the markers, the pointer claim or the flight this layer owns. The
  * shared services are injected, which is what keeps this module's own imports
  * down to Cesium and the pure step formatter.
- * @param {{services: object}} options
+ * @param {{services: object, source: {getRoute: Function}}} options
  * @returns {object} The layer module the data manager registers.
  */
-export function createDirectionsLayer({ services }) {
+export function createDirectionsLayer({ services, source }) {
+  if (typeof source?.getRoute !== 'function')
+    throw new TypeError('Directions require a route source');
   /**
    * Where the maneuver card is drawn. Defaults to the shared world-overlay host;
    * tests swap it. Resolved on use, not at import, because the services arrive
@@ -827,18 +826,12 @@ export function createDirectionsLayer({ services }) {
     _error = null;
     notifyRow();
     try {
-      const response = await fetch(directionsRequestUrl(mode, _a, _b), {
-        signal: controller.signal,
-        headers: { Accept: 'application/json' },
-      });
-      const payload = await response.json();
-      if (response.status === 429) {
-        throw new Error(
-          typeof payload?.error === 'string' && payload.error
-            ? `${payload.error} — try again in a moment`
-            : 'Routing is rate limited — try again in a moment',
-        );
-      }
+      const payload = await source.getRoute(
+        { mode, a: _a, b: _b },
+        {
+          signal: controller.signal,
+        },
+      );
       if (seq !== _routeSeq || !_enabled) return;
       const route = normalizeRoutePayload(payload, mode);
       if (!route) {

src/layers/directions/source.js

@@ -0,0 +1,34 @@
+/** Build the existing route-proxy query from geographic endpoints. */
+export function directionsRequestUrl(mode, a, b) {
+  const coords = `${a.lon.toFixed(6)},${a.lat.toFixed(6)};${b.lon.toFixed(6)},${b.lat.toFixed(6)}`;
+  return `/api/route?profile=${encodeURIComponent(mode)}&coords=${encodeURIComponent(coords)}&steps=1`;
+}
+
+/** Acquire route records using caller-owned transport and an optional endpoint. */
+export function createDirectionsSource({
+  fetchImpl = (...args) => globalThis.fetch(...args),
+  endpoint = '/api/route',
+} = {}) {
+  return {
+    async getRoute({ mode, a, b }, { signal } = {}) {
+      signal?.throwIfAborted();
+      const query = directionsRequestUrl(mode, a, b).split('?')[1];
+      const response = await fetchImpl(`${endpoint}?${query}`, {
+        signal,
+        headers: { Accept: 'application/json' },
+      });
+      const payload = await response.json();
+      signal?.throwIfAborted();
+      if (response.status === 429) {
+        throw new Error(
+          typeof payload?.error === 'string' && payload.error
+            ? `${payload.error} — try again in a moment`
+            : 'Routing is rate limited — try again in a moment',
+        );
+      }
+      if (!response.ok && !payload?.error)
+        throw new Error(`Routing unavailable (HTTP ${response.status})`);
+      return payload;
+    },
+  };
+}

src/layers/directions/source.test.mjs

@@ -0,0 +1,43 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { createDirectionsSource } from './source.js';
+
+const query = { mode: 'foot', a: { lon: 1, lat: 2 }, b: { lon: 3, lat: 4 } };
+
+test('route acquisition uses only the supplied transport and endpoint', async () => {
+  const controller = new AbortController();
+  const payload = { ok: true, geometry: [[1, 2], [3, 4]] };
+  const calls = [];
+  const source = createDirectionsSource({
+    endpoint: 'https://routes.example/route',
+    fetchImpl: async (...args) => { calls.push(args); return Response.json(payload); },
+  });
+  assert.deepEqual(await source.getRoute(query, { signal: controller.signal }), payload);
+  assert.equal(calls.length, 1);
+  const [url, init] = calls[0];
+  assert.equal(new URL(url).origin, 'https://routes.example');
+  assert.equal(new URL(url).searchParams.get('coords'), '1.000000,2.000000;3.000000,4.000000');
+  assert.equal(new URL(url).searchParams.get('profile'), 'foot');
+  assert.equal(init.signal, controller.signal);
+  assert.equal(init.headers.Accept, 'application/json');
+});
+
+test('aborting during route parsing discards the result', async () => {
+  const controller = new AbortController();
+  const source = createDirectionsSource({ fetchImpl: async () => ({
+    ok: true, json: async () => { controller.abort(); return { ok: true }; },
+  }) });
+  await assert.rejects(source.getRoute(query, { signal: controller.signal }), { name: 'AbortError' });
+});
+
+test('route failures are surfaced without fallback requests', async () => {
+  for (const status of [429, 503]) {
+    let calls = 0;
+    const source = createDirectionsSource({ fetchImpl: async () => {
+      calls++;
+      return Response.json({}, { status });
+    } });
+    await assert.rejects(source.getRoute(query), status === 429 ? /rate limited/ : /HTTP 503/);
+    assert.equal(calls, 1);
+  }
+});

src/layers/recentImagery/rendering.js

@@ -70,6 +70,8 @@ function admitTileRequests(provider, admission, requestRender, retry) {
  */
 export function createRecentImageryRenderer({
   cesium = Cesium,
+  tileTemplate = gibsTemplate,
+  credit = 'NASA GIBS',
   maxTileRequests = 6,
   requestRender = () => {},
   setTimeoutImpl = (fn, ms) => globalThis.setTimeout(fn, ms),
@@ -101,7 +103,7 @@ export function createRecentImageryRenderer({
   function createProvider(candidate, box) {
     const spec = PRODUCTS[candidate.product];
     const provider = new cesium.UrlTemplateImageryProvider({
-      url: gibsTemplate(candidate.product, candidate.day),
+      url: tileTemplate(candidate.product, candidate.day),
       subdomains: ['a', 'b', 'c'],
       minimumLevel: 0,
       maximumLevel: spec.maxLevel,
@@ -112,7 +114,7 @@ export function createRecentImageryRenderer({
         box.east,
         box.north,
       ),
-      credit: 'NASA GIBS',
+      credit,
       hasAlphaChannel: spec.format === 'png',
     });
     return admitTileRequests(provider, admission, requestRender, retry);

src/layers/recentImagery/rendering.test.mjs

@@ -53,10 +53,11 @@ const S30 = { key: 'S30:2026-09-18', product: 'S30', day: '2026-09-18' };
 const L30 = { key: 'L30:2026-09-16', product: 'L30', day: '2026-09-16' };
 const VIIRS = { key: 'VIIRS:2026-09-20', product: 'VIIRS', day: '2026-09-20' };
 
-function fixture({ requestImage, maxTileRequests } = {}) {
+function fixture({ requestImage, maxTileRequests, ...options } = {}) {
   const renders = [];
   const timers = manualTimers();
   const renderer = createRecentImageryRenderer({
+    ...options,
     cesium: fakeCesium(requestImage),
     maxTileRequests,
     requestRender: (reason) => renders.push(reason),
@@ -208,3 +209,21 @@ test('against the basemap slot a splits left with no second layer, and leaving t
   assert.equal(layer.splitDirection, 0);
   assert.deepEqual(renders, ['recent-imagery-show', 'recent-imagery-look']);
 });
+
+test('replacement imagery uses source-owned tile URLs and credit and tears down normally', () => {
+  const { renderer, globe } = fixture({
+    tileTemplate: (product, day) =>
+      `https://tiles.example/${product}/${day}/{z}/{x}/{y}`,
+    credit: 'Example imagery',
+  });
+  assert.equal(renderer.showSlot('a', S30, BOX), true);
+  const layer = globe.layers[0];
+  assert.equal(
+    layer.provider.options.url,
+    'https://tiles.example/S30/2026-09-18/{z}/{x}/{y}',
+  );
+  assert.equal(layer.provider.options.credit, 'Example imagery');
+  renderer.destroy();
+  assert.equal(globe.layers.length, 0);
+  assert.equal(layer.destroyed, true);
+});

src/layers/recentImagery/source.js

@@ -0,0 +1,32 @@
+import { searchHls } from './catalog.js';
+import { gibsTemplate, wvsSnapshotUrl } from './model.js';
+
+/** NASA-compatible imagery acquisition; transport and URL builders are replaceable. */
+export function createRecentImagerySource({
+  fetchImpl = (...args) => globalThis.fetch(...args),
+  search = searchHls,
+  thumbnailUrl = wvsSnapshotUrl,
+  tileTemplate = gibsTemplate,
+  credit = 'NASA GIBS',
+} = {}) {
+  return {
+    credit,
+    searchHls: (query) => search({ ...query, fetchImpl }),
+    async getThumbnail(candidate, box, { size = 256, signal } = {}) {
+      signal?.throwIfAborted();
+      const response = await fetchImpl(
+        thumbnailUrl({
+          product: candidate.product,
+          day: candidate.day,
+          box,
+          width: size,
+          height: size,
+        }),
+        { signal },
+      );
+      signal?.throwIfAborted();
+      return response;
+    },
+    getTileTemplate: (product, day) => tileTemplate(product, day),
+  };
+}

src/layers/recentImagery/source.test.mjs

@@ -0,0 +1,42 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { createRecentImagerySource } from './source.js';
+
+test('imagery source routes catalog, thumbnails and tiles through supplied adapters', async () => {
+  const controller = new AbortController();
+  const query = { box: { west: 0, east: 1, south: 0, north: 1 }, signal: controller.signal };
+  const candidate = { product: 'S30', day: '2026-10-01' };
+  const calls = [];
+  const fetchImpl = async (...args) => { calls.push(args); return new Response('image'); };
+  const source = createRecentImagerySource({
+    fetchImpl,
+    search: async (request) => {
+      assert.equal(request.fetchImpl, fetchImpl);
+      assert.equal(request.signal, controller.signal);
+      assert.equal(request.box, query.box);
+      return [candidate];
+    },
+    thumbnailUrl: ({ product, day, width }) => `https://imagery.example/${product}/${day}/${width}`,
+    tileTemplate: (product, day) => `https://tiles.example/${product}/${day}/{z}/{x}/{y}`,
+    credit: 'Example imagery',
+  });
+  assert.deepEqual(await source.searchHls(query), [candidate]);
+  assert.equal(await (await source.getThumbnail(candidate, query.box, { signal: controller.signal })).text(), 'image');
+  assert.equal(calls.length, 1);
+  assert.equal(calls[0][0], 'https://imagery.example/S30/2026-10-01/256');
+  assert.equal(calls[0][1].signal, controller.signal);
+  assert.equal(source.getTileTemplate(candidate.product, candidate.day), 'https://tiles.example/S30/2026-10-01/{z}/{x}/{y}');
+  assert.equal(source.credit, 'Example imagery');
+});
+
+test('cancelled thumbnail acquisition does not return stale responses or retry', async () => {
+  const controller = new AbortController();
+  let calls = 0;
+  const source = createRecentImagerySource({
+    thumbnailUrl: () => 'https://imagery.example/thumbnail',
+    fetchImpl: async () => { calls++; controller.abort(); return new Response('image'); },
+  });
+  await assert.rejects(source.getThumbnail({}, {}, { signal: controller.signal }), { name: 'AbortError' });
+  await assert.rejects(source.getThumbnail({}, {}, { signal: controller.signal }), { name: 'AbortError' });
+  assert.equal(calls, 1);
+});

src/layers/recentImagery/thumbnails.js

@@ -8,7 +8,8 @@
  * card on every render, so a read that counted would evict the visible cards
  * first). Eviction revokes the image only; what the probe proved is kept.
  */
-import { thumbnailOrder, wvsSnapshotUrl } from './model.js';
+import { thumbnailOrder } from './model.js';
+import { createRecentImagerySource } from './source.js';
 
 const EMPTY = Object.freeze({
   status: 'unknown',
@@ -22,6 +23,7 @@ const EMPTY = Object.freeze({
  */
 export function createThumbnailLoader({
   fetchImpl = globalThis.fetch?.bind(globalThis),
+  requestThumbnail = createRecentImagerySource({ fetchImpl }).getThumbnail,
   maxInFlight = 3,
   maxDecoded = 16,
   createObjectUrl = (blob) => URL.createObjectURL(blob),
@@ -90,14 +92,10 @@ export function createThumbnailLoader({
     let acquisitionTime = null;
     let cancelled = false;
     try {
-      const url = wvsSnapshotUrl({
-        product: entry.candidate.product,
-        day: entry.candidate.day,
-        box: entry.box,
-        width: size,
-        height: size,
+      const response = await requestThumbnail(entry.candidate, entry.box, {
+        size,
+        signal: controller.signal,
       });
-      const response = await fetchImpl(url, { signal: controller.signal });
       if (controller.signal.aborted) {
         cancelled = true;
       } else if (response?.ok) {

src/layers/recentImagery/thumbnails.test.mjs

@@ -315,3 +315,24 @@ test('a request queued behind an aborted fetch still starts once the abort settl
     tracked: 1,
   });
 });
+
+test('injected thumbnail acquisition owns requests while the loader releases object URLs', async () => {
+  const calls = [];
+  const { loader, fetch, revoked } = fixture({
+    requestThumbnail: async (...args) => {
+      calls.push(args);
+      return response({ headers: { 'Data-Present': 'true' } });
+    },
+  });
+  const entry = candidate('S30', '2026-09-18');
+  loader.request(entry, BOX, 0);
+  await settle();
+  assert.equal(fetch.calls.length, 0);
+  assert.equal(calls.length, 1);
+  assert.equal(calls[0][0], entry);
+  assert.deepEqual(calls[0][1], BOX);
+  assert.ok(calls[0][2].signal instanceof AbortSignal);
+  assert.equal(loader.get(entry.key).status, 'present');
+  loader.destroy();
+  assert.deepEqual(revoked, ['blob:1']);
+});

src/layers/streetLevel/coverage.js

@@ -1,7 +1,6 @@
 import * as Cesium from 'cesium';
 import { decodeCoverageTile } from './decode.js';
-import { passesImageryFilter, resolveFilter } from './filter.js';
-import { isActive } from './state.js';
+import { passesImageryFilter } from './filter.js';
 import { groundUnderCamera, viewFocus, visibleBbox } from './view.js';
 import { coverageZoomForHeight, tilesForBbox } from './tileMath.js';
 import {
@@ -96,7 +95,7 @@ export function createCoverage({ state, source }) {
 
   /** The imagery filter, resolved now: "since N days" moves with the clock. */
   function filter() {
-    return resolveFilter(state.filter);
+    return state.getFilter();
   }
 
   /**
@@ -320,7 +319,7 @@ export function createCoverage({ state, source }) {
   /** Recompute the tile set for the current camera and reconcile primitives. */
   function refresh() {
     const viewer = state.viewer;
-    if (!viewer || !isActive(state) || state.coverage.blocked) return;
+    if (!viewer || !state.isActive() || state.coverage.blocked) return;
     const { zoom, tiles, hint } = wantedTiles(viewer);
     if (hint) {
       state.coverage.hint = hint;
@@ -410,7 +409,7 @@ export function createCoverage({ state, source }) {
       // Waiting for the key status is loading too, not an empty view.
       loading:
         state.coverage.pending.size > 0 ||
-        (blocked === 'status' && isActive(state)),
+        (blocked === 'status' && state.isActive()),
       hint: state.coverage.hint,
       keyRequired: blocked === 'no-key' || blocked === 'rejected',
       keyRejected: blocked === 'rejected',

src/layers/streetLevel/coverage.test.mjs

@@ -3,6 +3,7 @@ import test from 'node:test';
 import * as Cesium from 'cesium';
 import { createCoverage, ZOOM_IN_HINT } from './coverage.js';
 import { freshCoverage } from './state.js';
+import { resolveFilter } from './filter.js';
 import { encodeCoverageTile } from './coverageFixture.mjs';
 import { rayCamera } from '../../testSupport/streetLevelFakes.mjs';
 import { COVERAGE_MAX_SEQUENCES, COVERAGE_MAX_TILES } from './policy.js';
@@ -93,6 +94,8 @@ function setup() {
     enabled: true,
     providerOn: true,
     filter: { pano: 'all', sinceDays: 0 },
+    getFilter: () => resolveFilter(state.filter),
+    isActive: () => state.enabled && state.providerOn,
     notify() {},
     coverage: {
       ...freshCoverage(),

src/layers/streetLevel/credits.js

@@ -0,0 +1,38 @@
+import * as Cesium from 'cesium';
+
+/**
+ * One static Cesium credit per active provider: CC BY-SA imagery needs
+ * visible attribution that goes away with the imagery.
+ */
+export function createCredits() {
+  /** @type {Map<string, object>} provider id → Cesium.Credit */
+  const shown = new Map();
+
+  function show(viewer, def) {
+    if (shown.has(def.id) || !viewer?.creditDisplay) return;
+    try {
+      const credit = new Cesium.Credit(def.credit.html, true);
+      viewer.creditDisplay.addStaticCredit(credit);
+      shown.set(def.id, credit);
+    } catch {
+      /* credit display unavailable */
+    }
+  }
+
+  function hide(viewer, def) {
+    const credit = shown.get(def.id);
+    if (!credit) return;
+    try {
+      viewer?.creditDisplay?.removeStaticCredit?.(credit);
+    } catch {
+      /* credit display already torn down */
+    }
+    shown.delete(def.id);
+  }
+
+  function hideAll(viewer) {
+    for (const id of [...shown.keys()]) hide(viewer, { id });
+  }
+
+  return { show, hide, hideAll };
+}

src/layers/streetLevel/index.js

@@ -1,61 +1,55 @@
-import * as Cesium from 'cesium';
 import { createState } from './state.js';
 import { createMarker } from './marker.js';
 import { createCameraFraming } from './cameraFraming.js';
+import { createCredits } from './credits.js';
+import { createPickRouter } from './pickRouter.js';
 import { createSelection } from './selection.js';
 import { createViewerHost } from './viewerHost.js';
-import { normalizeFilter, sameFilter } from './filter.js';
+import { requiresKeyIdFor, validateProviders } from './registry.js';
+import { normalizeFilter, resolveFilter, sameFilter } from './filter.js';
+import { decodeParams, encodeParams } from './params.js';
+import { composeUIState, summarizeCoverage } from './uiState.js';
 import {
   keyStatusLabel,
-  MAPILLARY_CREDIT_HTML,
-  MAPILLARY_KEY_ID,
+  POSITION_PICK_ID,
   STREET_LEVEL_LAYER_ID,
 } from './policy.js';
-import { createCoverage } from './coverage.js';
-import { createSequences } from './sequences.js';
-import { createMapillaryViewer } from './viewer.js';
 
 export { STREET_LEVEL_LAYER_ID } from './policy.js';
 
-/** Longest wait for the server's key status; past it, the bundle's token decides. */
+/** Longest wait for a provider's key status; past it, the provider decides. */
 const KEY_STATUS_TIMEOUT_MS = 10_000;
 
-/** Coverage as the panel sees it while the `mapillary` switch is off. */
-const COVERAGE_OFF = Object.freeze({
-  count: 0,
-  loading: false,
-  hint: '',
-  error: null,
-  keyRequired: false,
-  keyRejected: false,
-});
-
 /**
- * The Street Level layer: Mapillary coverage lines at street zoom, a selected
- * sequence's image cones, and the photo viewer in the panel.
- * @param {{source: object, services?: object, photoViewer?: object}} options
- *   `source` is source.js or a stand-in; `photoViewer` stands in for the
- *   MapillaryJS adapter (viewer.js).
+ * The Street Level layer over imagery providers (contract in registry.js).
+ * The core owns what they share: the filter and switches, the photo viewer
+ * host, the position marker and the click handler. Providers own coverage,
+ * sequences and their viewer.
+ * @param {{providers: Array<import('./registry.js').StreetLevelProvider>, services?: object}} options
  */
 export function createStreetLevelLayer({
-  source,
+  providers: definitions,
   services = {},
-  photoViewer = null,
 }) {
+  const defs = validateProviders(definitions);
   const state = createState({ services });
   const parts = {};
   const context = { state, parts };
+  parts.credits = createCredits();
   parts.marker = createMarker(context);
   parts.framing = createCameraFraming(context);
-  parts.coverage = createCoverage({ state, source });
-  parts.sequences = createSequences({ state, source, parts });
-  parts.viewerHost = createViewerHost({
-    state,
-    parts,
-    adapter:
-      photoViewer || createMapillaryViewer({ source, render: services.render }),
+  parts.router = createPickRouter(() => state.providers.values(), {
+    positionId: POSITION_PICK_ID,
   });
-  parts.openImage = openImage;
+  parts.viewerHost = createViewerHost(context);
+  parts.hasSelectedSequence = () =>
+    [...state.providers.values()].some(
+      (entry) => entry.instance.sequenceStats?.()?.selectedId,
+    );
+  parts.clearSequences = () => {
+    for (const entry of state.providers.values())
+      entry.instance.clearSequence?.();
+  };
   parts.selection = createSelection(context);
 
   let notifyQueued = false;
@@ -76,127 +70,184 @@ export function createStreetLevelLayer({
   }
   state.notify = notify;
 
-  /** The key-status request in flight; overlapping checks share it. */
-  let keyCheck = null;
-
-  /** Coverage waits for the key status: no tile requests without a key. */
-  function checkKey() {
-    keyCheck ||= (async () => {
-      let configured;
-      try {
-        // A hung server must not hold LOADING, or the next check, forever.
-        const signal = AbortSignal.timeout(KEY_STATUS_TIMEOUT_MS);
-        configured = (await source.getStatus({ signal }))?.configured === true;
-      } catch {
-        configured = source.hasToken?.() === true;
-      }
-      parts.coverage.setKeyStatus(configured);
-    })().finally(() => {
-      keyCheck = null;
+  function providerContext(entry) {
+    return Object.freeze({
+      services: state.services,
+      /** Resolved against now, so "since N days" keeps up with the clock. */
+      getFilter: () => resolveFilter(state.filter),
+      /** The layer and this provider's switch are both on. */
+      isActive: () => state.enabled && entry.on,
+      notify,
+      actions: {
+        openImage: (imageId) => openImage(entry.def.id, imageId),
+      },
     });
-    return keyCheck;
   }
 
-  /** The on-globe credit while the layer draws: CC BY-SA imagery needs it. */
-  let credit = null;
-  function showCredit(viewer) {
-    if (credit || !viewer?.creditDisplay) return;
-    credit = new Cesium.Credit(MAPILLARY_CREDIT_HTML, true);
-    viewer.creditDisplay.addStaticCredit(credit);
-  }
-  function hideCredit(viewer) {
-    if (!credit) return;
-    viewer?.creditDisplay?.removeStaticCredit?.(credit);
-    credit = null;
+  for (const def of defs) {
+    const entry = {
+      def,
+      instance: null,
+      on: true,
+      status: null,
+      /** The status request in flight; overlapping checks share it. */
+      statusCheck: null,
+    };
+    entry.instance = def.create(providerContext(entry));
+    state.providers.set(def.id, entry);
   }
 
-  function startDrawing() {
-    const viewer = state.viewer;
-    if (!viewer) return;
-    parts.sequences.setVisible(true);
-    parts.coverage.attach(viewer);
-    showCredit(viewer);
+  const activeEntries = () =>
+    [...state.providers.values()].filter((entry) => entry.on);
+
+  /** A provider's key status. A hung server must not hold LOADING, or the next check, forever. */
+  function checkStatus(entry) {
+    entry.statusCheck ||= (async () => {
+      try {
+        entry.status = await entry.instance.status({
+          signal: AbortSignal.timeout(KEY_STATUS_TIMEOUT_MS),
+        });
+      } catch {
+        entry.status = null;
+      }
+      notify();
+    })().finally(() => {
+      entry.statusCheck = null;
+    });
+    return entry.statusCheck;
+  }
+
+  function activate(entry) {
+    if (!state.viewer) return;
+    entry.instance.activate(state.viewer);
+    parts.credits.show(state.viewer, entry.def);
     // Without a known key, a switch-on asks again: the server may be back,
     // or have a key now.
-    if (['status', 'no-key'].includes(state.coverage.blocked)) checkKey();
+    if (entry.status?.configured !== true) checkStatus(entry);
   }
 
-  /** Close the photo, clear lines and cones, forget refusals. */
-  function stopDrawing() {
-    parts.viewerHost.unmount();
-    parts.coverage.detach();
-    parts.coverage.clear();
-    parts.coverage.unblock();
-    parts.sequences.clearSelection();
-    parts.sequences.setVisible(false);
-    hideCredit(state.viewer);
+  function deactivate(entry) {
+    parts.viewerHost.unmount(entry.def.id);
+    entry.instance.deactivate();
+    parts.credits.hide(state.viewer, entry.def);
   }
 
-  /** The share link's `mapillary` switch: off, the layer draws nothing. */
-  function setProviderOn(on) {
-    if (state.providerOn === on) return;
-    state.providerOn = on;
+  function openImage(providerId, imageId) {
+    return parts.viewerHost.open(providerId, imageId);
+  }
+
+  function setProviderEnabled(providerId, on) {
+    const entry = state.providers.get(providerId);
+    if (!entry) return false;
+    const next = on !== false;
+    if (entry.on === next) return true;
+    entry.on = next;
     if (state.enabled) {
-      if (on) startDrawing();
-      else stopDrawing();
+      if (next) activate(entry);
+      else deactivate(entry);
     }
     notify();
-  }
-
-  function openImage(imageId) {
-    return parts.viewerHost.open(imageId);
+    return true;
   }
 
   function setCoverageFilter(next) {
     const filter = normalizeFilter(next, state.filter);
     if (sameFilter(filter, state.filter)) return;
     state.filter = filter;
-    parts.coverage.rebuild();
-    parts.sequences.rerender();
+    const resolved = resolveFilter(filter);
+    for (const entry of state.providers.values())
+      entry.instance.setFilter(resolved);
     notify();
   }
 
-  function coverageStats() {
-    return state.providerOn ? parts.coverage.stats() : COVERAGE_OFF;
+  function providerSnapshots() {
+    return [...state.providers.values()].map((entry) => {
+      const stats = entry.instance.coverageStats();
+      return {
+        id: entry.def.id,
+        name: entry.def.name,
+        label: entry.def.label,
+        on: entry.on,
+        configured: entry.status ? entry.status.configured === true : null,
+        // A rejected key gates the provider exactly like a missing one.
+        keyRequired: stats.keyRequired === true || stats.keyRejected === true,
+        keyRejected: stats.keyRejected === true,
+        requiresKeyId: entry.def.requiresKeyId || null,
+        loading: stats.loading === true,
+        count: stats.count || 0,
+        hint: stats.hint || '',
+        error: stats.error || null,
+        color: entry.def.colors.coverage,
+      };
+    });
+  }
+
+  /** The selected sequence; the provider showing the open image answers first. */
+  function sequenceSnapshot() {
+    const owner = state.providers.get(state.street.providerId);
+    const candidates = owner
+      ? [owner, ...[...state.providers.values()].filter((e) => e !== owner)]
+      : [...state.providers.values()];
+    for (const entry of candidates) {
+      const stats = entry.instance.sequenceStats?.();
+      if (stats?.selectedId || stats?.loading || stats?.error)
+        return {
+          providerId: entry.def.id,
+          selectedId: stats.selectedId || null,
+          images: stats.images || 0,
+          loading: stats.loading === true,
+          error: stats.error || null,
+        };
+    }
+    return {
+      providerId: null,
+      selectedId: null,
+      images: 0,
+      loading: false,
+      error: null,
+    };
   }
 
   function getUIState() {
     const { host, ...street } = state.street;
-    const { keyRequired, keyRejected, ...coverage } = coverageStats();
-    return {
+    return composeUIState({
       enabled: state.enabled,
-      providerOn: state.providerOn,
-      // A rejected key gates the layer exactly like a missing one.
-      keyRequired,
-      keyRejected,
-      filter: { ...state.filter },
-      coverage,
-      sequence: {
-        selectedId: state.sequence.selectedId,
-        images: state.sequence.images.length,
-        loading: state.sequence.loading,
-        error: state.sequence.error,
-      },
+      filter: state.filter,
+      providers: providerSnapshots(),
       street,
-    };
+      sequence: sequenceSnapshot(),
+    });
   }
 
   const layer = {
     id: STREET_LEVEL_LAYER_ID,
     name: 'Street Level',
     icon: '📷',
-    source: 'Mapillary',
+    source: defs.map((def) => def.name).join(' · '),
     updateInterval: 0,
     statsRefreshInterval: 1000,
-    requiresKeyId: MAPILLARY_KEY_ID,
+    requiresKeyId: requiresKeyIdFor(defs),
+    /** Registered providers, in chip order. */
+    providerIds: defs.map((def) => def.id),
+    getSourceAvailability() {
+      const available = defs.length > 0;
+      return {
+        available,
+        source: STREET_LEVEL_LAYER_ID,
+        reason: available
+          ? null
+          : 'No street-level imagery providers configured',
+      };
+    },
 
     init(viewer) {
       state.viewer = viewer;
       parts.marker.ensure(viewer);
       parts.marker.setVisible(false);
-      parts.sequences.ensureCollections(viewer);
-      parts.sequences.setVisible(false);
-      checkKey();
+      for (const entry of state.providers.values()) {
+        entry.instance.init(viewer);
+        checkStatus(entry);
+      }
       console.log('[Data:StreetLevel] Initialized');
     },
 
@@ -205,13 +256,15 @@ export function createStreetLevelLayer({
       state.viewer = viewer;
       parts.marker.setVisible(true);
       parts.selection.install(viewer);
-      if (state.providerOn) startDrawing();
+      for (const entry of activeEntries()) activate(entry);
       notify();
     },
 
     disable() {
       state.enabled = false;
-      stopDrawing();
+      parts.viewerHost.unmount();
+      for (const entry of state.providers.values()) entry.instance.deactivate();
+      parts.credits.hideAll(state.viewer);
       parts.selection.uninstall();
       parts.marker.setVisible(false);
       notify();
@@ -223,7 +276,8 @@ export function createStreetLevelLayer({
 
     destroy(viewer = state.viewer) {
       layer.disable();
-      parts.sequences.destroy(viewer);
+      for (const entry of state.providers.values())
+        entry.instance.destroy(viewer);
       parts.marker.destroy(viewer);
       parts.framing.attachNavigation(null);
       state.listeners.clear();
@@ -231,7 +285,8 @@ export function createStreetLevelLayer({
     },
 
     getStats() {
-      const coverage = coverageStats();
+      // The lifecycle polls this every second: summarise, don't snapshot.
+      const coverage = summarizeCoverage(providerSnapshots());
       const keyLabel = keyStatusLabel(coverage);
       let loadingLabel = '';
       if (keyLabel) loadingLabel = keyLabel;
@@ -252,26 +307,22 @@ export function createStreetLevelLayer({
       parts.framing.attachNavigation(navigation);
     },
 
-    /**
-     * Share-link and stored state, in the codec's keys (src/data/layerState.js):
-     * the `mapillary` switch plus the filter.
-     */
+    /** Share-link and stored state: provider switches plus the filter. */
     getParams() {
-      return {
-        mapillary: state.providerOn,
-        pano: state.filter.pano,
-        sinceDays: state.filter.sinceDays,
-      };
+      return encodeParams({
+        providers: [...state.providers].map(([id, entry]) => [id, entry.on]),
+        filter: state.filter,
+      });
     },
 
-    /** Unknown keys and malformed values are ignored, so any link applies. */
+    /** Unknown providers and malformed values are ignored, so any link applies. */
     setParams(params = {}) {
-      const input = params && typeof params === 'object' ? params : {};
-      if (typeof input.mapillary === 'boolean') setProviderOn(input.mapillary);
-      const next = {};
-      if ('pano' in input) next.pano = input.pano;
-      if ('sinceDays' in input) next.sinceDays = input.sinceDays;
-      setCoverageFilter(next);
+      const decoded = decodeParams(params, {
+        providerIds: state.providers.keys(),
+        filter: state.filter,
+      });
+      for (const [id, on] of decoded.providers) setProviderEnabled(id, on);
+      setCoverageFilter(decoded.filter);
       return true;
     },
 
@@ -282,15 +333,16 @@ export function createStreetLevelLayer({
       return () => state.listeners.delete(listener);
     },
     getUIState,
-    /** The DOM element the photo viewer renders into. */
+    /** The DOM element provider viewers render into. */
     attachViewerHost(element) {
       parts.viewerHost.attach(element);
     },
+    setProviderEnabled,
     openImage,
     /** Close the image and deselect its sequence on the map. */
     closeViewer() {
       parts.viewerHost.close();
-      parts.sequences.clearSelection();
+      parts.clearSequences();
     },
     setViewerRenderMode: (mode) => parts.viewerHost.setRenderMode(mode),
     resizeViewer: () => parts.viewerHost.resize(),

src/layers/streetLevel/index.test.mjs

@@ -2,6 +2,7 @@ import assert from 'node:assert/strict';
 import test from 'node:test';
 import * as Cesium from 'cesium';
 import { createStreetLevelLayer } from './index.js';
+import { createMapillaryProvider } from './mapillaryProvider.js';
 import { MAPILLARY_CREDIT_HTML } from './policy.js';
 import {
   fakeCesiumViewer,
@@ -18,6 +19,7 @@ async function startLayer(
   {
     source = fakeMapillarySource(),
     photoViewer = fakePhotoViewer(),
+    providers = [createMapillaryProvider({ source, photoViewer })],
     view = false,
     enable = true,
   } = {},
@@ -32,7 +34,7 @@ async function startLayer(
     async () => {},
   );
   const viewer = fakeCesiumViewer({ view });
-  const layer = createStreetLevelLayer({ source, photoViewer });
+  const layer = createStreetLevelLayer({ providers });
   layer.init(viewer);
   if (enable) layer.enable(viewer);
   t.after(() => {
@@ -181,13 +183,13 @@ test('a rejected key gates the layer as KEY REJECTED until it goes off', async (
 test('switching Mapillary off clears coverage and closes the image it shows', async (t) => {
   const { layer, photoViewer } = await startLayer(t);
   layer.attachViewerHost({});
-  assert.equal(await layer.openImage('img1'), true);
+  assert.equal(await layer.openImage('mapillary', 'img1'), true);
   assert.deepEqual(photoViewer.calls.open, ['img1']);
   assert.equal(layer.getUIState().street.open, true);
   layer.setParams({ mapillary: false });
   assert.equal(photoViewer.calls.unmount, 1, 'its viewer is released');
   assert.equal(layer.getUIState().street.open, false);
-  assert.equal(layer.getUIState().providerOn, false);
+  assert.equal(layer.getUIState().providers[0].on, false);
 });
 
 test('a sequence that fails to load reports it apart from the photo, and the error goes with it', async (t) => {
@@ -202,7 +204,7 @@ test('a sequence that fails to load reports it apart from the photo, and the err
   });
   const { layer } = await startLayer(t, { source, photoViewer });
   layer.attachViewerHost({});
-  assert.equal(await layer.openImage('img1'), true);
+  assert.equal(await layer.openImage('mapillary', 'img1'), true);
   await settle();
   let ui = layer.getUIState();
   assert.equal(ui.sequence.error, 'Sequence images unavailable');
@@ -217,17 +219,17 @@ test('closing the photo, switching the layer off or destroying it stops the fram
     photoViewer: posingViewer(),
   });
   layer.attachViewerHost({});
-  assert.equal(await layer.openImage('img1'), true);
+  assert.equal(await layer.openImage('mapillary', 'img1'), true);
   assert.equal(viewer.flights.started, 1, 'the photo is framed');
   layer.closeViewer();
   assert.equal(viewer.flights.cancelled, 1, 'closed');
 
-  await layer.openImage('img2');
+  await layer.openImage('mapillary', 'img2');
   layer.disable();
   assert.equal(viewer.flights.cancelled, 2, 'layer off');
 
   layer.enable(viewer);
-  await layer.openImage('img3');
+  await layer.openImage('mapillary', 'img3');
   layer.destroy();
   assert.equal(viewer.flights.cancelled, 3, 'destroyed');
 });
@@ -264,7 +266,7 @@ test('setParams ignores unknown keys and malformed values', async (t) => {
   });
 });
 
-test('switching Mapillary on while the layer is off draws nothing (M01)', async (t) => {
+test('switching Mapillary on while the layer is off draws nothing', async (t) => {
   const { layer, viewer, source, photoViewer } = await startLayer(t, {
     view: true,
     enable: false,
@@ -276,10 +278,24 @@ test('switching Mapillary on while the layer is off draws nothing (M01)', async
   assert.equal(source.calls.tiles.length, 0, 'no coverage drawn');
   assert.deepEqual(viewer.credits, [], 'no credit shown');
   assert.equal(photoViewer.calls.mount, 0, 'no viewer stood up');
-  assert.equal(layer.getUIState().providerOn, true, 'the switch is kept');
+  assert.equal(layer.getUIState().providers[0].on, true, 'the switch is kept');
   // Enabling the layer is what draws it.
   layer.enable(viewer);
   await settle();
   assert.ok(source.calls.tiles.length > 0);
   assert.equal(viewer.credits.length, 1);
 });
+
+test('an empty provider composition enables and tears down without acquiring imagery', async (t) => {
+  const { layer, viewer } = await startLayer(t, { providers: [] });
+  assert.deepEqual(layer.providerIds, []);
+  assert.deepEqual(layer.getUIState().providers, []);
+  assert.equal(layer.getUIState().keyRequired, false);
+  assert.match(
+    layer.getUIState().coverage.hint,
+    /No street-level imagery providers/,
+  );
+  layer.disable();
+  layer.enable(viewer);
+  assert.deepEqual(layer.getUIState().providers, []);
+});

src/layers/streetLevel/mapillaryProvider.js

@@ -0,0 +1,145 @@
+import { freshCoverage } from './state.js';
+import { createCoverage, sequenceIdFromPick } from './coverage.js';
+import { createSequences } from './sequences.js';
+import { createMapillaryViewer } from './viewer.js';
+import {
+  COLORS,
+  MAPILLARY_CREDIT_HTML,
+  MAPILLARY_KEY_ID,
+  MAPILLARY_LABEL,
+  MAPILLARY_NAME,
+  MAPILLARY_PROVIDER_ID,
+  MAPILLARY_SOURCE_METHODS,
+  PICK_PREFIX,
+} from './policy.js';
+
+/** Per-provider mutable state; coverage and sequences share it. */
+function createProviderState(context) {
+  return {
+    services: context.services,
+    getFilter: context.getFilter,
+    isActive: context.isActive,
+    notify: context.notify,
+    viewer: null,
+    coverage: freshCoverage(),
+    sequence: {
+      selectedId: null,
+      images: [],
+      collection: null,
+      loading: false,
+      /** Why the selected sequence's images could not load, until it goes. */
+      error: null,
+      abort: null,
+    },
+  };
+}
+
+/**
+ * The Mapillary provider: coverage lines from vector tiles, image cones from
+ * the Graph API and the MapillaryJS viewer.
+ * @param {{source: object, photoViewer?: object}} options  `source` is
+ *   source.js or a stand-in; `photoViewer` stands in for the viewer adapter.
+ * @returns {import('./registry.js').StreetLevelProvider}
+ */
+export function createMapillaryProvider({ source, photoViewer = null }) {
+  if (
+    !MAPILLARY_SOURCE_METHODS.every(
+      (method) => typeof source?.[method] === 'function',
+    )
+  )
+    throw new TypeError('A Mapillary source is required');
+
+  return Object.freeze({
+    id: MAPILLARY_PROVIDER_ID,
+    name: MAPILLARY_NAME,
+    label: MAPILLARY_LABEL,
+    requiresKeyId: MAPILLARY_KEY_ID,
+    pickPrefix: PICK_PREFIX.root,
+    colors: COLORS,
+    credit: Object.freeze({ html: MAPILLARY_CREDIT_HTML }),
+
+    create(context) {
+      const state = createProviderState(context);
+      const parts = {};
+      parts.coverage = createCoverage({ state, source });
+      parts.sequences = createSequences({ state, source, parts });
+
+      return {
+        /** Coverage waits for the answer: no tile requests without a key. */
+        async status({ signal } = {}) {
+          let configured;
+          try {
+            configured =
+              (await source.getStatus({ signal }))?.configured === true;
+          } catch {
+            configured = source.hasToken?.() === true;
+          }
+          parts.coverage.setKeyStatus(configured);
+          return { configured };
+        },
+
+        init(viewer) {
+          state.viewer = viewer;
+          parts.sequences.ensureCollections(viewer);
+          parts.sequences.setVisible(false);
+        },
+
+        activate(viewer) {
+          state.viewer = viewer;
+          parts.sequences.setVisible(true);
+          parts.coverage.attach(viewer);
+        },
+
+        /** Clear lines and cones, forget refusals. */
+        deactivate() {
+          parts.coverage.detach();
+          parts.coverage.clear();
+          parts.coverage.unblock();
+          parts.sequences.clearSelection();
+          parts.sequences.setVisible(false);
+        },
+
+        destroy(viewer) {
+          parts.coverage.detach();
+          parts.coverage.clear();
+          parts.sequences.destroy(viewer);
+        },
+
+        /** The filter changed: redraw. Each draw reads it from the context. */
+        setFilter() {
+          parts.coverage.rebuild();
+          parts.sequences.rerender();
+        },
+
+        coverageStats: () => parts.coverage.stats(),
+
+        /** A line selects its sequence; a cone opens its image. */
+        handlePick(pickId) {
+          const sequenceId = sequenceIdFromPick(pickId);
+          if (sequenceId) {
+            parts.sequences.select(sequenceId);
+            return true;
+          }
+          if (pickId.startsWith(PICK_PREFIX.image)) {
+            context.actions.openImage(pickId.slice(PICK_PREFIX.image.length));
+            return true;
+          }
+          return false;
+        },
+
+        selectSequence: (sequenceId) => parts.sequences.select(sequenceId),
+        clearSequence: () => parts.sequences.clearSelection(),
+        sequenceStats: () => ({
+          selectedId: state.sequence.selectedId,
+          images: state.sequence.images.length,
+          loading: state.sequence.loading,
+          error: state.sequence.error,
+        }),
+
+        viewer:
+          photoViewer ||
+          createMapillaryViewer({ source, render: context.services?.render }),
+      };
+    },
+  });
+}

src/layers/streetLevel/mapillaryProvider.test.mjs

@@ -0,0 +1,172 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import * as Cesium from 'cesium';
+import { createMapillaryProvider } from './mapillaryProvider.js';
+import { mapillaryImageUrl } from './policy.js';
+import { sequenceIdFromPick } from './coverage.js';
+import { thinImages } from './sequences.js';
+import { validateProviders } from './registry.js';
+import {
+  fakeMapillarySource,
+  rayCamera,
+} from '../../testSupport/streetLevelFakes.mjs';
+
+function fakeContext(filter = { pano: 'all', sinceMs: null }) {
+  const opened = [];
+  return {
+    opened,
+    services: {},
+    getFilter: () => filter,
+    isActive: () => true,
+    notify: () => {},
+    actions: { openImage: (id) => opened.push(id) },
+  };
+}
+
+test('the definition satisfies the Street Level provider contract', () => {
+  const def = createMapillaryProvider({ source: fakeMapillarySource() });
+  assert.doesNotThrow(() => validateProviders([def]));
+  assert.equal(def.id, 'mapillary');
+  assert.equal(def.label, 'MAPILLARY');
+  assert.equal(def.requiresKeyId, 'mapillary');
+  assert.equal(def.pickPrefix, 'mly:');
+  assert.match(def.credit.html, /CC BY-SA 4\.0/);
+  // One colour per source: Mapillary is green everywhere it draws.
+  assert.equal(def.colors.coverage, '#05cb63');
+  assert.throws(() => createMapillaryProvider({ source: {} }), /source/);
+});
+
+test('image deep links match the mapillary.com share format', () => {
+  assert.equal(
+    mapillaryImageUrl(1814275685699406),
+    'https://www.mapillary.com/app/?pKey=1814275685699406&focus=photo',
+  );
+  assert.equal(mapillaryImageUrl('  '), 'https://www.mapillary.com/app/');
+});
+
+test('picks route sequences to selection and images to the core opener', () => {
+  const context = fakeContext();
+  const instance = createMapillaryProvider({
+    source: fakeMapillarySource(),
+  }).create(context);
+  assert.equal(instance.handlePick('mly:img:77'), true);
+  assert.deepEqual(context.opened, ['77']);
+  assert.equal(instance.handlePick('cctv:1'), false);
+  assert.deepEqual(instance.sequenceStats(), {
+    selectedId: null,
+    images: 0,
+    loading: false,
+    error: null,
+  });
+});
+
+test('a line pick names its sequence; anything else is not a sequence', () => {
+  assert.equal(sequenceIdFromPick('mly:seq:abc'), 'abc');
+  assert.equal(sequenceIdFromPick('mly:img:abc'), null);
+  assert.equal(sequenceIdFromPick(null), null);
+});
+
+test('cone thinning across the date line drops images metres apart', () => {
+  const image = (id, lon) => ({ id, lon, lat: 0 });
+  // A sequence driving east over ±180° with images ~1 m apart, then ~11 m on.
+  const kept = thinImages(
+    [
+      image('a', 179.99999),
+      image('b', -179.99999), // ~2 m from a, across the date line
+      image('c', -179.9999), // ~11 m from a
+    ],
+    3,
+  );
+  assert.deepEqual(
+    kept.map(({ id }) => id),
+    ['a', 'c'],
+  );
+});
+
+/** A viewer looking straight down on downtown Sacramento from 900 m. */
+function streetViewer() {
+  const collection = () => ({
+    add: (item) => item,
+    remove: () => true,
+    contains: () => false,
+    get length() {
+      return 0;
+    },
+  });
+  const event = () => ({ addEventListener: () => () => {} });
+  const camera = Object.assign(
+    rayCamera({
+      lon: -121.4944,
+      lat: 38.5816,
+      altitude: 900,
+      pitch: -90,
+      width: 100,
+      height: 100,
+    }),
+    { changed: event(), moveEnd: event() },
+  );
+  return {
+    camera,
+    scene: {
+      canvas: { clientWidth: 100, clientHeight: 100 },
+      globe: { show: false, ellipsoid: Cesium.Ellipsoid.WGS84 },
+      primitives: collection(),
+      groundPrimitives: collection(),
+      preRender: event(),
+      postRender: event(),
+      requestRender() {},
+    },
+  };
+}
+
+test('coverage asks for no tiles before the key status is known, and none without a key', async (t) => {
+  // Skip Cesium's one-time terrain table download for draped lines.
+  t.mock.method(
+    Cesium.GroundPolylinePrimitive,
+    'initializeTerrainHeights',
+    async () => {},
+  );
+  for (const configured of [false, true]) {
+    let answer;
+    const tiles = [];
+    const source = fakeMapillarySource({
+      hasToken: () => configured,
+      getStatus: () => new Promise((resolve) => (answer = resolve)),
+      getTile: (...args) => {
+        tiles.push(args);
+        return new Promise(() => {});
+      },
+    });
+    const instance = createMapillaryProvider({ source }).create(fakeContext());
+    const viewer = streetViewer();
+    instance.init(viewer);
+    const status = instance.status();
+    instance.activate(viewer);
+    assert.equal(tiles.length, 0, 'nothing before the status answers');
+    answer({ configured });
+    assert.deepEqual(await status, { configured });
+    if (configured)
+      assert.ok(tiles.length > 0, 'coverage loads as soon as the key is known');
+    else {
+      assert.equal(tiles.length, 0, 'a key-less install never asks');
+      assert.equal(instance.coverageStats().keyRequired, true);
+    }
+    instance.destroy(viewer);
+  }
+});
+
+test('a status the server never answers falls back to the bundled token once the core gives up', async () => {
+  const source = fakeMapillarySource({
+    hasToken: () => false,
+    getStatus: ({ signal } = {}) =>
+      new Promise((_, reject) =>
+        signal?.addEventListener('abort', () => reject(signal.reason)),
+      ),
+  });
+  const instance = createMapillaryProvider({ source }).create(fakeContext());
+  const controller = new AbortController();
+  const status = instance.status({ signal: controller.signal });
+  controller.abort(new Error('timed out'));
+  assert.deepEqual(await status, { configured: false });
+  assert.equal(instance.coverageStats().keyRequired, true);
+});

src/layers/streetLevel/params.js

@@ -0,0 +1,43 @@
+import { normalizeFilter } from './filter.js';
+import { encodeIdSwitches, decodeIdSwitches } from '../../data/idSwitches.js';
+
+/**
+ * Provider params plus the filter. Custom switches share a stable ID-based
+ * field; Mapillary retains its existing boolean and share token.
+ * @param {{providers: Iterable<[string, boolean]>, filter: {pano: string, sinceDays: number}}} input
+ */
+export function encodeParams({ providers, filter }) {
+  const params = {};
+  const entries = [...providers];
+  for (const [id, on] of entries) params[id] = on === true;
+  const switches = encodeIdSwitches(
+    entries.filter(([id]) => id !== 'mapillary'),
+  );
+  if (switches) params.providerSwitches = switches;
+  params.pano = filter.pano;
+  params.sinceDays = filter.sinceDays;
+  return params;
+}
+
+/**
+ * Read params back, ignoring unknown providers and malformed values so a link
+ * from a build with more providers still applies.
+ * @param {object} params
+ * @param {{providerIds: Iterable<string>, filter: {pano: string, sinceDays: number}}} current
+ * @returns {{providers: Map<string, boolean>, filter: {pano: string, sinceDays: number}}}
+ */
+export function decodeParams(params, { providerIds, filter }) {
+  const providers = new Map();
+  const source = params && typeof params === 'object' ? params : {};
+  const switches = decodeIdSwitches(source.providerSwitches);
+  switches.delete('mapillary');
+  for (const id of providerIds) {
+    if (switches.has(id)) providers.set(id, switches.get(id));
+    else if (Object.hasOwn(source, id) && typeof source[id] === 'boolean')
+      providers.set(id, source[id]);
+  }
+  const next = {};
+  if ('pano' in source) next.pano = source.pano;
+  if ('sinceDays' in source) next.sinceDays = source.sinceDays;
+  return { providers, filter: normalizeFilter(next, filter) };
+}

src/layers/streetLevel/params.test.mjs

@@ -0,0 +1,64 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import { decodeParams, encodeParams } from './params.js';
+
+test('encodeParams writes one boolean per provider plus the filter', () => {
+  assert.deepEqual(
+    encodeParams({
+      providers: [
+        ['mapillary', true],
+        ['panoramax', false],
+      ],
+      filter: { pano: 'flat', sinceDays: 365 },
+    }),
+    {
+      mapillary: true,
+      panoramax: false,
+      providerSwitches: 'panoramax-0',
+      pano: 'flat',
+      sinceDays: 365,
+    },
+  );
+});
+
+test('decodeParams round-trips and ignores unknown or malformed keys', () => {
+  const current = { pano: 'all', sinceDays: 0 };
+  const decoded = decodeParams(
+    { mapillary: false, kartaview: true, pano: 'pano', sinceDays: 730, x: 1 },
+    { providerIds: ['mapillary'], filter: current },
+  );
+  assert.deepEqual([...decoded.providers], [['mapillary', false]]);
+  assert.deepEqual(decoded.filter, { pano: 'pano', sinceDays: 730 });
+
+  const partial = decodeParams(
+    { mapillary: '1', pano: 'weird' },
+    { providerIds: ['mapillary'], filter: { pano: 'flat', sinceDays: 5 } },
+  );
+  assert.equal(partial.providers.size, 0, 'a string is not a switch');
+  assert.deepEqual(partial.filter, { pano: 'flat', sinceDays: 5 });
+
+  const empty = decodeParams(null, {
+    providerIds: ['mapillary'],
+    filter: current,
+  });
+  assert.equal(empty.providers.size, 0);
+  assert.deepEqual(empty.filter, current);
+});
+
+test('decodeParams applies "any date" (0 days) over a current window (share-link defaults)', () => {
+  const decoded = decodeParams(
+    { sinceDays: 0 },
+    { providerIds: ['mapillary'], filter: { pano: 'flat', sinceDays: 365 } },
+  );
+  assert.deepEqual(decoded.filter, { pano: 'flat', sinceDays: 0 });
+  // The provider switch off is a value too, not an absence.
+  assert.deepEqual(
+    [
+      ...decodeParams(
+        { mapillary: false },
+        { providerIds: ['mapillary'], filter: { pano: 'all', sinceDays: 0 } },
+      ).providers,
+    ],
+    [['mapillary', false]],
+  );
+});

src/layers/streetLevel/pickRouter.js

@@ -0,0 +1,21 @@
+/**
+ * Route picked ids to the provider whose prefix they carry; the registry
+ * guarantees prefixes never overlap.
+ * @param {() => Iterable<{def: {id: string, pickPrefix: string}, instance: object}>} getProviders
+ * @param {{positionId?: string}} [options]  Id of the core-owned position marker.
+ */
+export function createPickRouter(getProviders, { positionId = null } = {}) {
+  function resolve(id) {
+    if (typeof id !== 'string' || !id) return null;
+    if (positionId && id === positionId)
+      return { providerId: null, instance: null, id };
+    for (const entry of getProviders())
+      if (id.startsWith(entry.def.pickPrefix))
+        return { providerId: entry.def.id, instance: entry.instance, id };
+    return null;
+  }
+  return {
+    ownsPick: (id) => resolve(id) !== null,
+    resolve,
+  };
+}

src/layers/streetLevel/pickRouter.test.mjs

@@ -0,0 +1,36 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import { createPickRouter } from './pickRouter.js';
+
+const providers = [
+  { def: { id: 'mapillary', pickPrefix: 'mly:' }, instance: { name: 'm' } },
+  { def: { id: 'panoramax', pickPrefix: 'pnx:' }, instance: { name: 'p' } },
+];
+
+test('ids are routed by prefix to their provider instance', () => {
+  const router = createPickRouter(() => providers, { positionId: 'sl:pos' });
+  assert.deepEqual(router.resolve('mly:seq:1'), {
+    providerId: 'mapillary',
+    instance: providers[0].instance,
+    id: 'mly:seq:1',
+  });
+  assert.equal(router.resolve('pnx:img:9').providerId, 'panoramax');
+  assert.equal(router.ownsPick('mly:img:2'), true);
+});
+
+test('the core-owned marker is owned but routes to no provider', () => {
+  const router = createPickRouter(() => providers, { positionId: 'sl:pos' });
+  assert.deepEqual(router.resolve('sl:pos'), {
+    providerId: null,
+    instance: null,
+    id: 'sl:pos',
+  });
+  assert.equal(router.ownsPick('sl:pos'), true);
+});
+
+test('foreign and malformed ids are not ours', () => {
+  const router = createPickRouter(() => providers);
+  for (const id of ['cctv:1', '', null, undefined, 42, {}])
+    assert.equal(router.ownsPick(id), false, String(id));
+  assert.equal(router.resolve('sl:pos'), null, 'no marker id configured');
+});

src/layers/streetLevel/policy.js

@@ -1,8 +1,18 @@
-/** Identity and tuning for the Street Level layer and its Mapillary imagery. */
+/** Identity and tuning for the Street Level layer and its Mapillary provider. */
 export const STREET_LEVEL_LAYER_ID = 'street-level';
+export const MAPILLARY_PROVIDER_ID = 'mapillary';
+export const MAPILLARY_NAME = 'Mapillary';
+export const MAPILLARY_LABEL = 'MAPILLARY';
 export const MAPILLARY_KEY_ID = 'mapillary';
 export const MAPILLARY_GRAPH_HOST = 'https://graph.mapillary.com';
 
+/** What the provider needs from its source (source.js or a stand-in). */
+export const MAPILLARY_SOURCE_METHODS = Object.freeze([
+  'getStatus',
+  'getTile',
+  'getSequenceImages',
+]);
+
 /** Pick id of the viewer position marker. */
 export const POSITION_PICK_ID = 'sl:pos';
 

src/layers/streetLevel/providerSwitches.test.mjs

@@ -0,0 +1,153 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { encodeParams, decodeParams } from './params.js';
+import {
+  normalizeIdSwitches,
+  patchRequestedIdSwitches,
+  decodeIdSwitches,
+  encodeIdSwitches,
+} from '../../data/idSwitches.js';
+import {
+  createDefaultLayerState,
+  encodeLayerStateParams,
+  decodeLayerStateParams,
+  serializeStoredLayerState,
+  parseStoredLayerState,
+} from '../../data/layerState.js';
+import { validateProviders } from './registry.js';
+import { fakeStreetLevelProvider } from '../../testSupport/streetLevelFakes.mjs';
+
+const filter = { pano: 'flat', sinceDays: 365 };
+
+test('custom switches survive sharing and storage without depending on provider order', () => {
+  const providers = [
+    ['panoramax', false],
+    ['example', true],
+    ['mapillary', false],
+  ];
+  const options = encodeParams({ providers, filter });
+  assert.equal(options.providerSwitches, 'example-1*panoramax-0');
+  assert.equal(
+    encodeParams({ providers: [...providers].reverse(), filter })
+      .providerSwitches,
+    options.providerSwitches,
+  );
+  const state = createDefaultLayerState();
+  state.enabledLayerIds = ['street-level'];
+  state.options['street-level'] = options;
+  const params = new URLSearchParams({ v: '2' });
+  encodeLayerStateParams(params, state);
+  assert.match(params.get('lo'), /0\.m\.0/);
+  assert.match(params.get('lo'), /0\.r\.example-1\*panoramax-0/);
+  assert.ok(
+    params.toString().includes('0.r.example-1*panoramax-0'),
+    'custom switches need no percent escaping',
+  );
+  for (const restored of [
+    decodeLayerStateParams(params),
+    parseStoredLayerState(serializeStoredLayerState(state)),
+  ]) {
+    const decoded = decodeParams(restored.options['street-level'], {
+      providerIds: ['example', 'mapillary', 'panoramax'],
+      filter: { pano: 'all', sinceDays: 0 },
+    });
+    assert.deepEqual(
+      [...decoded.providers],
+      [
+        ['example', true],
+        ['mapillary', false],
+        ['panoramax', false],
+      ],
+    );
+    assert.deepEqual(decoded.filter, filter);
+    assert.deepEqual(
+      [
+        ...decodeParams(restored.options['street-level'], {
+          providerIds: ['panoramax'],
+          filter,
+        }).providers,
+      ],
+      [['panoramax', false]],
+    );
+    assert.equal(
+      decodeParams(restored.options['street-level'], {
+        providerIds: [],
+        filter,
+      }).providers.size,
+      0,
+    );
+  }
+});
+
+test('legacy links retain Mapillary semantics and leave custom defaults alone', () => {
+  for (const [lo, on] of [
+    ['', true],
+    ['0.m.0', false],
+  ]) {
+    const state = decodeLayerStateParams(
+      new URLSearchParams({ v: '2', l: '0', lo }),
+    );
+    const restored = decodeParams(state.options['street-level'], {
+      providerIds: ['mapillary', 'example'],
+      filter,
+    });
+    assert.deepEqual([...restored.providers], [['mapillary', on]]);
+  }
+});
+
+test('switches reject ambiguous or oversized fields and cannot override the legacy token', () => {
+  for (const value of [
+    'example-0*example-1',
+    'mapillary-0',
+    '__proto__-1',
+    'a-2',
+    'a-1*',
+    'a.b-1',
+    'a_b-0',
+    `${'a'.repeat(255)}-1`,
+    null,
+    {},
+  ]) {
+    assert.equal(normalizeIdSwitches(value, ['mapillary']), null);
+  }
+  assert.equal(normalizeIdSwitches('constructor-0'), 'constructor-0');
+  assert.throws(
+    () => encodeIdSwitches([['a'.repeat(255), true]]),
+    /share-link/,
+  );
+  assert.throws(
+    () => validateProviders([fakeStreetLevelProvider({ id: 'a'.repeat(255) })]),
+    /share-link/,
+  );
+  const decoded = decodeParams(
+    { providerSwitches: 'mapillary-0', mapillary: true },
+    { providerIds: ['mapillary'], filter },
+  );
+  assert.equal(decoded.providers.get('mapillary'), true);
+});
+
+test('neutral switch codec preserves hyphens and numeric suffixes in IDs', () => {
+  const switches = [
+    ['provider-0', false],
+    ['provider-1', true],
+    ['a-b-c', true],
+  ];
+  const encoded = encodeIdSwitches(switches);
+  assert.equal(encoded, 'a-b-c-1*provider-0-0*provider-1-1');
+  const decoded = decodeIdSwitches(encoded);
+  for (const [id, on] of switches) assert.equal(decoded.get(id), on);
+  assert.equal(decodeIdSwitches('valid-1*broken').size, 0);
+});
+
+test('editing a receiving composition drops unknown IDs before enforcing the share bound', () => {
+  const previous = `${'x'.repeat(254)}-1`;
+  assert.equal(normalizeIdSwitches(previous), previous);
+  assert.equal(
+    patchRequestedIdSwitches(previous, 'alpha-0*beta-0', { alpha: false }),
+    'alpha-0',
+  );
+  assert.equal(
+    patchRequestedIdSwitches(previous, 'alpha-0', { pano: 'flat' }),
+    undefined,
+  );
+});

src/layers/streetLevel/registry.js

@@ -0,0 +1,141 @@
+import { encodeIdSwitches } from '../../data/idSwitches.js';
+
+/**
+ * The contract an imagery provider registers with the Street Level layer.
+ *
+ * @typedef {object} StreetLevelProvider
+ * @property {string} id            Stable id, e.g. 'mapillary'; also the share-link option key.
+ * @property {string} name          Human name for captions, e.g. 'Mapillary'.
+ * @property {string} label         Chip text and link label, e.g. 'MAPILLARY'.
+ * @property {string|null} requiresKeyId  Key-setup id the provider needs, or null when keyless.
+ * @property {string} pickPrefix    Every primitive id the provider creates starts with it.
+ * @property {{coverage: string}} colors   The source's one colour.
+ * @property {{html: string}} credit   On-globe attribution while the provider is active.
+ * @property {(context: ProviderContext) => ProviderInstance} create
+ *
+ * @typedef {object} ProviderContext   Handed to `create()` once by the core.
+ * @property {object} services         Scene services: picking, input, render, sprites.
+ * @property {() => {pano: string, sinceMs: number|null}} getFilter   Filter resolved against now; read it on every use so "since N days" keeps up.
+ * @property {() => boolean} isActive  Layer enabled and this provider switched on.
+ * @property {() => void} notify       Ask the core to publish a new UI snapshot.
+ * @property {{openImage: (imageId: string) => Promise<boolean>}} actions
+ *
+ * @typedef {object} ProviderInstance
+ * @property {(options?: {signal?: AbortSignal}) => Promise<{configured: boolean}>} status   Whether a usable key is set; the core gives up on a hung answer through `signal`.
+ * @property {(viewer: object) => void} init         Create collections, hidden.
+ * @property {(viewer: object) => void} activate     Start drawing coverage for the camera.
+ * @property {() => void} deactivate                 Detach, clear coverage and selection, hide.
+ * @property {(viewer: object) => void} destroy
+ * @property {(filter: {pano: string, sinceMs: number|null}) => void} setFilter   The filter changed: redraw (reading `getFilter()`).
+ * @property {() => {count: number, loading: boolean, hint: string, error: string|null, keyRequired: boolean, keyRejected?: boolean}} coverageStats
+ * @property {(pickId: string) => boolean} handlePick   The id carries the provider's own prefix.
+ * @property {(sequenceId: string) => Promise<void>} [selectSequence]
+ * @property {() => void} [clearSequence]
+ * @property {() => {selectedId: string|null, images: number, loading: boolean, error?: string|null}} [sequenceStats]
+ * @property {ViewerAdapter} viewer
+ *
+ * @typedef {object} ViewerAdapter
+ * @property {(host: HTMLElement) => Promise<void>} mount     Idempotent; may lazy-load a library.
+ * @property {(imageId: string) => Promise<void>} open        Resolves once the image is on screen and a pose was emitted.
+ * @property {() => void} close                               Drop the image, keep the instance warm.
+ * @property {() => void} unmount                             Destroy the instance (host handed to another provider).
+ * @property {() => void} resize
+ * @property {(mode: 'letterbox'|'fill') => void} [setRenderMode]
+ * @property {(listener: (pose: StreetPose) => void) => () => void} onPose
+ *
+ * @typedef {object} StreetPose
+ * @property {string} imageId
+ * @property {{lon: number, lat: number}} position
+ * @property {number|null} bearing
+ * @property {number|null} altitude
+ * @property {boolean} isPano
+ * @property {number|null} capturedAt   Epoch milliseconds.
+ * @property {string|null} creator
+ * @property {string|null} sequenceId
+ * @property {string} externalUrl      Deep link to the image on the provider's site.
+ */
+
+const REQUIRED = Object.freeze([
+  'id',
+  'name',
+  'label',
+  'pickPrefix',
+  'colors',
+  'credit',
+  'create',
+]);
+
+const ID_GRAMMAR = /^[a-z][a-z0-9-]*$/;
+
+/**
+ * Validate providers and freeze their order, which is also the chip order.
+ * @param {Array<StreetLevelProvider>} providers
+ * @returns {ReadonlyArray<StreetLevelProvider>}
+ */
+export function validateProviders(providers) {
+  if (!Array.isArray(providers))
+    throw new TypeError('Street Level providers must be an array');
+  const ids = new Set();
+  const prefixes = [];
+  for (const provider of providers) {
+    const label = provider?.id ?? '(unnamed)';
+    for (const key of REQUIRED)
+      if (provider?.[key] === undefined || provider?.[key] === null)
+        throw new TypeError(`Street Level provider ${label} lacks ${key}`);
+    if (typeof provider.id !== 'string' || !ID_GRAMMAR.test(provider.id))
+      throw new TypeError(`Street Level provider id ${label} is not a slug`);
+    if (ids.has(provider.id))
+      throw new TypeError(`Duplicate Street Level provider ${provider.id}`);
+    if (typeof provider.create !== 'function')
+      throw new TypeError(
+        `Street Level provider ${label}: create is not a function`,
+      );
+    if (typeof provider.pickPrefix !== 'string' || !provider.pickPrefix)
+      throw new TypeError(`Street Level provider ${label} needs a pick prefix`);
+    for (const other of prefixes)
+      if (
+        other.startsWith(provider.pickPrefix) ||
+        provider.pickPrefix.startsWith(other)
+      )
+        throw new TypeError(
+          `Street Level provider ${label}: pick prefix ${provider.pickPrefix} overlaps ${other}`,
+        );
+    if (!provider.credit?.html)
+      throw new TypeError(`Street Level provider ${label} needs a credit`);
+    if (
+      typeof provider.colors?.coverage !== 'string' ||
+      !provider.colors.coverage
+    )
+      throw new TypeError(
+        `Street Level provider ${label} needs a coverage colour`,
+      );
+    ids.add(provider.id);
+    prefixes.push(provider.pickPrefix);
+  }
+  // Validate the complete bounded share field once, before any instance exists.
+  try {
+    encodeIdSwitches(
+      providers
+        .filter(({ id }) => id !== 'mapillary')
+        .map(({ id }) => [id, true]),
+    );
+  } catch (error) {
+    if (!(error instanceof RangeError)) throw error;
+    throw new RangeError(
+      'Street Level provider IDs cannot fit in the 256-character share-link field; use shorter IDs or fewer providers',
+    );
+  }
+  return Object.freeze([...providers]);
+}
+
+/**
+ * The key id every provider shares, or null if any is keyless or they differ
+ * (then each chip reports its own need).
+ * @param {ReadonlyArray<StreetLevelProvider>} providers
+ * @returns {string|null}
+ */
+export function requiresKeyIdFor(providers) {
+  const keys = new Set(providers.map((p) => p.requiresKeyId || null));
+  if (keys.size !== 1) return null;
+  return [...keys][0];
+}

src/layers/streetLevel/registry.test.mjs

@@ -0,0 +1,103 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import { requiresKeyIdFor, validateProviders } from './registry.js';
+
+const def = (overrides = {}) => ({
+  id: 'mapillary',
+  name: 'Mapillary',
+  label: 'MAPILLARY',
+  requiresKeyId: 'mapillary',
+  pickPrefix: 'mly:',
+  colors: { coverage: '#05cb63' },
+  credit: { html: 'Mapillary' },
+  create: () => ({}),
+  ...overrides,
+});
+
+test('a valid list is frozen in registration order', () => {
+  const list = validateProviders([
+    def(),
+    def({ id: 'panoramax', pickPrefix: 'pnx:', requiresKeyId: null }),
+  ]);
+  assert.ok(Object.isFrozen(list));
+  assert.deepEqual(
+    list.map((p) => p.id),
+    ['mapillary', 'panoramax'],
+  );
+});
+
+test('an empty provider list is valid and has no key requirement', () => {
+  assert.deepEqual(validateProviders([]), []);
+  assert.ok(Object.isFrozen(validateProviders([])));
+  assert.equal(requiresKeyIdFor([]), null);
+});
+
+test('non-arrays, duplicate ids and malformed ids are rejected', () => {
+  assert.throws(() => validateProviders(null), /array/);
+  assert.throws(() => validateProviders([def(), def()]), /Duplicate/);
+  assert.throws(() => validateProviders([def({ id: 'Bad Id' })]), /slug/);
+});
+
+test('every required field is checked by name', () => {
+  for (const key of [
+    'name',
+    'label',
+    'pickPrefix',
+    'colors',
+    'credit',
+    'create',
+  ])
+    assert.throws(
+      () => validateProviders([def({ [key]: undefined })]),
+      new RegExp(`lacks ${key}`),
+      key,
+    );
+  assert.throws(() => validateProviders([def({ create: 1 })]), /create/);
+  assert.throws(() => validateProviders([def({ credit: {} })]), /credit/);
+  assert.throws(
+    () => validateProviders([def({ colors: { pano: '#f0f' } })]),
+    /coverage colour/,
+  );
+  assert.throws(
+    () => validateProviders([def({ pickPrefix: '' })]),
+    /pick prefix/,
+  );
+});
+
+test('overlapping pick prefixes are rejected either way round', () => {
+  assert.throws(
+    () => validateProviders([def(), def({ id: 'other', pickPrefix: 'mly:x' })]),
+    /overlaps/,
+  );
+  assert.throws(
+    () =>
+      validateProviders([def({ pickPrefix: 'mly:x' }), def({ id: 'other' })]),
+    /overlaps/,
+  );
+  assert.doesNotThrow(() =>
+    validateProviders([def(), def({ id: 'other', pickPrefix: 'ml:' })]),
+  );
+});
+
+test('requiresKeyIdFor is the shared key, or null once providers differ', () => {
+  assert.equal(requiresKeyIdFor([def()]), 'mapillary');
+  assert.equal(
+    requiresKeyIdFor([def(), def({ id: 'b', pickPrefix: 'b:' })]),
+    'mapillary',
+  );
+  assert.equal(
+    requiresKeyIdFor([
+      def(),
+      def({ id: 'b', pickPrefix: 'b:', requiresKeyId: null }),
+    ]),
+    null,
+  );
+  assert.equal(
+    requiresKeyIdFor([
+      def(),
+      def({ id: 'b', pickPrefix: 'b:', requiresKeyId: 'google-maps' }),
+    ]),
+    null,
+  );
+  assert.equal(requiresKeyIdFor([def({ requiresKeyId: null })]), null);
+});

src/layers/streetLevel/selection.js

@@ -1,37 +1,22 @@
 import * as Cesium from 'cesium';
-import {
-  PICK_PREFIX,
-  POSITION_PICK_ID,
-  STREET_LEVEL_LAYER_ID,
-} from './policy.js';
-import { sequenceIdFromPick } from './coverage.js';
+import { STREET_LEVEL_LAYER_ID } from './policy.js';
 
-/** One click handler for coverage lines, image cones and the marker. */
+/** One click handler for every provider's lines and cones, and the marker. */
 export function createSelection({ state, parts }) {
   const { picking, input } = state.services;
 
-  /** Lines and cones (`mly:`) and the position marker are this layer's. */
-  function ownsPick(id) {
-    return (
-      typeof id === 'string' &&
-      (id === POSITION_PICK_ID || id.startsWith(PICK_PREFIX.root))
-    );
-  }
-
-  /** A line selects its sequence; a cone opens its image. */
+  /** The id carries a provider's prefix: that provider handles the pick. */
   function onClick(click) {
     const viewer = state.viewer;
-    if (!viewer || !state.enabled || !state.providerOn) return;
+    if (!viewer || !state.enabled) return;
     if (input?.isPointerFree && !input.isPointerFree()) return;
     const picked = viewer.scene.pick(click.position);
     const id = picking?.resolvePickId
       ? picking.resolvePickId(picked)
       : picked?.id;
-    if (typeof id !== 'string') return;
-    const sequenceId = sequenceIdFromPick(id);
-    if (sequenceId) parts.sequences.select(sequenceId);
-    else if (id.startsWith(PICK_PREFIX.image))
-      parts.openImage(id.slice(PICK_PREFIX.image.length));
+    const hit = parts.router.resolve(id);
+    // The position marker is the core's own: nothing to select.
+    if (hit?.instance) hit.instance.handlePick(hit.id);
   }
 
   /**
@@ -49,9 +34,9 @@ export function createSelection({ state, parts }) {
       )
     )
       return;
-    if (!state.sequence.selectedId) return;
+    if (!parts.hasSelectedSequence()) return;
     event.preventDefault();
-    parts.sequences.clearSelection();
+    parts.clearSequences();
   }
 
   function install(viewer) {
@@ -64,7 +49,7 @@ export function createSelection({ state, parts }) {
       Cesium.ScreenSpaceEventType.LEFT_CLICK,
     );
     document.addEventListener('keydown', onKeyDown);
-    picking?.registerPickOwner?.(STREET_LEVEL_LAYER_ID, ownsPick);
+    picking?.registerPickOwner?.(STREET_LEVEL_LAYER_ID, parts.router.ownsPick);
   }
 
   function uninstall() {
@@ -76,5 +61,5 @@ export function createSelection({ state, parts }) {
     picking?.unregisterPickOwner?.(STREET_LEVEL_LAYER_ID);
   }
 
-  return { install, uninstall, ownsPick };
+  return { install, uninstall, ownsPick: parts.router.ownsPick };
 }

src/layers/streetLevel/selection.test.mjs

@@ -2,6 +2,7 @@ import assert from 'node:assert/strict';
 import test from 'node:test';
 import * as Cesium from 'cesium';
 import { createSelection } from './selection.js';
+import { createPickRouter } from './pickRouter.js';
 
 /** The selection installed on a stand-in viewer, with what its clicks reach. */
 function harness({ selected = false } = {}) {
@@ -38,28 +39,36 @@ function harness({ selected = false } = {}) {
   const state = {
     viewer,
     enabled: true,
-    providerOn: true,
     clickHandler: null,
     services: { picking: null, input: null },
-    sequence: {
-      get selectedId() {
-        return sequences.selected ? 'seq-1' : null;
-      },
+    providers: new Map([
+      [
+        'mapillary',
+        {
+          def: { id: 'mapillary', pickPrefix: 'mly:' },
+          instance: {
+            handlePick(id) {
+              if (id.startsWith('mly:seq:'))
+                sequences.selects.push(id.slice(8));
+              else if (id.startsWith('mly:img:')) opened.push(id.slice(8));
+              return true;
+            },
+          },
+        },
+      ],
+    ]),
+  };
+  const parts = {
+    router: createPickRouter(() => state.providers.values(), {
+      positionId: 'sl:pos',
+    }),
+    hasSelectedSequence: () => sequences.selected,
+    clearSequences() {
+      sequences.cleared++;
+      sequences.selected = false;
     },
   };
-  const selection = createSelection({
-    state,
-    parts: {
-      sequences: {
-        select: (id) => sequences.selects.push(id),
-        clearSelection() {
-          sequences.cleared++;
-          sequences.selected = false;
-        },
-      },
-      openImage: (id) => opened.push(id),
-    },
-  });
+  const selection = createSelection({ state, parts });
   selection.install(viewer);
   const action = (type) =>
     state.clickHandler.getInputAction(Cesium.ScreenSpaceEventType[type]);
@@ -103,11 +112,6 @@ test('a click on a line selects its sequence, on a cone opens its image, elsewhe
       h.click();
     }
     assert.deepEqual([h.sequences.selects, h.opened], [['abc'], ['42']]);
-    // Mapillary switched off under a layer that is on: lines are not drawn.
-    h.state.providerOn = false;
-    h.scene.under = 'mly:seq:abc';
-    h.click();
-    assert.deepEqual(h.sequences.selects, ['abc']);
   } finally {
     h.restore();
   }

src/layers/streetLevel/sequences.js

@@ -1,6 +1,6 @@
 import * as Cesium from 'cesium';
 import { imageConeGlyph } from './glyphs.js';
-import { passesImageryFilter, resolveFilter } from './filter.js';
+import { passesImageryFilter } from './filter.js';
 import { createHorizonCull, metresBetween } from './view.js';
 import {
   COLORS,
@@ -89,7 +89,7 @@ export function createSequences({ state, source, parts }) {
       pano: true,
     });
     // Resolved now, so a "since N days" window keeps up with the clock.
-    const filter = resolveFilter(state.filter);
+    const filter = state.getFilter();
     for (const image of images) {
       if (!passesImageryFilter(image, filter)) continue;
       const billboard = collection.add({

src/layers/streetLevel/sequences.test.mjs

@@ -1,6 +1,7 @@
 import assert from 'node:assert/strict';
 import test from 'node:test';
 import * as Cesium from 'cesium';
+import { resolveFilter } from './filter.js';
 import { createSequences } from './sequences.js';
 
 const settle = () => new Promise((resolve) => setTimeout(resolve, 0));
@@ -56,6 +57,7 @@ function setup() {
     services: {},
     viewer: {},
     filter: { pano: 'all', sinceDays: 0 },
+    getFilter: () => resolveFilter(state.filter),
     notify() {},
     sequence: {
       selectedId: null,

src/layers/streetLevel/state.js

@@ -7,6 +7,9 @@ import { FILTER_DEFAULT } from './policy.js';
 export function freshStreet() {
   return {
     open: false,
+    providerId: null,
+    providerName: null,
+    providerLabel: null,
     imageId: null,
     position: null,
     bearing: null,
@@ -21,7 +24,7 @@ export function freshStreet() {
   };
 }
 
-/** Coverage bookkeeping, before the first refresh. */
+/** A provider's coverage bookkeeping, before the first refresh. */
 export function freshCoverage() {
   return {
     zoom: null,
@@ -34,7 +37,7 @@ export function freshCoverage() {
     lastError: null,
     /**
      * Why tile requests are paused, or null: 'status' until the key status
-     * answers, 'no-key', 'rejected' (until the layer goes off) or
+     * answers, 'no-key', 'rejected' (until the provider goes off) or
      * 'rate-limited' (until `blockTimer` fires).
      */
     blocked: 'status',
@@ -46,7 +49,7 @@ export function freshCoverage() {
   };
 }
 
-/** Mutable layer state, created once per layer instance. */
+/** Mutable core state, created once per layer instance. */
 export function createState({ services }) {
   return {
     services,
@@ -54,10 +57,10 @@ export function createState({ services }) {
     enabled: false,
     listeners: new Set(),
     notify: null,
-    /** The share link's `mapillary` switch: off draws nothing. */
-    providerOn: true,
-    /** Imagery filter, in the stored (relative-days) form. */
+    /** Shared imagery filter, in the stored (relative-days) form. */
     filter: { ...FILTER_DEFAULT },
+    /** @type {Map<string, {def: object, instance: object, on: boolean, status: object|null}>} */
+    providers: new Map(),
 
     street: {
       host: null,
@@ -66,23 +69,7 @@ export function createState({ services }) {
       ...freshStreet(),
     },
 
-    coverage: freshCoverage(),
-    sequence: {
-      selectedId: null,
-      images: [],
-      collection: null,
-      loading: false,
-      /** Why the selected sequence's images could not load, until it goes. */
-      error: null,
-      abort: null,
-    },
-
     marker: { collection: null, billboard: null },
     clickHandler: null,
   };
 }
-
-/** Coverage, cones and lookups run only while the layer and its switch are on. */
-export function isActive(state) {
-  return state.enabled && state.providerOn;
-}

src/layers/streetLevel/uiState.js

@@ -0,0 +1,65 @@
+/**
+ * @typedef {object} ProviderSnapshot
+ * @property {string} id
+ * @property {string} name
+ * @property {string} label
+ * @property {boolean} on
+ * @property {boolean|null} configured   null until the status call answers
+ * @property {boolean} keyRequired   no usable key: missing or rejected
+ * @property {boolean} [keyRejected] the provider refused the configured key
+ * @property {string|null} requiresKeyId
+ * @property {boolean} loading
+ * @property {number} count
+ * @property {string} hint
+ * @property {string|null} error
+ * @property {string} color   The source's one colour.
+ */
+
+/**
+ * Totals over switched-on providers. Key-gated only when every one lacks its
+ * key; `keyRejected` when that is because a key was refused.
+ * @param {Array<ProviderSnapshot>} providers
+ */
+export function summarizeCoverage(providers) {
+  const active = providers.filter((p) => p.on);
+  return {
+    count: active.reduce((sum, p) => sum + (p.count || 0), 0),
+    loading: active.some((p) => p.loading),
+    hint:
+      providers.length === 0
+        ? 'No street-level imagery providers configured'
+        : active.find((p) => p.hint)?.hint || '',
+    error: active.find((p) => p.error)?.error || null,
+    keyRequired:
+      active.length > 0 && active.every((p) => p.keyRequired === true),
+    keyRejected:
+      active.length > 0 &&
+      active.every((p) => p.keyRequired === true) &&
+      active.some((p) => p.keyRejected === true),
+  };
+}
+
+/**
+ * The panel snapshot from core state and provider snapshots.
+ * @param {{enabled: boolean, filter: object, providers: Array<ProviderSnapshot>, street: object, sequence: object}} input
+ */
+export function composeUIState({
+  enabled,
+  filter,
+  providers,
+  street,
+  sequence,
+}) {
+  const { keyRequired, keyRejected, ...coverage } =
+    summarizeCoverage(providers);
+  return {
+    enabled,
+    keyRequired,
+    keyRejected,
+    filter: { ...filter },
+    providers: providers.map((p) => ({ ...p })),
+    coverage,
+    sequence: { ...sequence },
+    street: { ...street },
+  };
+}

src/layers/streetLevel/uiState.test.mjs

@@ -0,0 +1,100 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import { composeUIState, summarizeCoverage } from './uiState.js';
+import { providerSnapshot } from '../../testSupport/streetLevelFakes.mjs';
+
+const provider = (overrides = {}) =>
+  providerSnapshot({ count: 10, ...overrides });
+const base = {
+  enabled: true,
+  filter: { pano: 'all', sinceDays: 0 },
+  street: { open: false },
+  sequence: { selectedId: null, images: 0, loading: false },
+};
+
+test('counts add up across active providers only', () => {
+  const ui = composeUIState({
+    ...base,
+    providers: [
+      provider(),
+      provider({ id: 'panoramax', name: 'Panoramax', count: 5, on: false }),
+      provider({ id: 'kartaview', name: 'KartaView', count: 7, loading: true }),
+    ],
+  });
+  assert.equal(ui.coverage.count, 17);
+  assert.equal(ui.coverage.loading, true);
+});
+
+test('the layer is key-gated only when every switched-on provider lacks its key', () => {
+  const gated = composeUIState({
+    ...base,
+    providers: [provider({ keyRequired: true })],
+  });
+  assert.equal(gated.keyRequired, true);
+  const mixed = composeUIState({
+    ...base,
+    providers: [
+      provider({ keyRequired: true }),
+      provider({ id: 'panoramax', name: 'Panoramax', requiresKeyId: null }),
+    ],
+  });
+  assert.equal(mixed.keyRequired, false, 'a keyless provider still draws');
+  const offOnly = composeUIState({
+    ...base,
+    providers: [provider({ keyRequired: true, on: false })],
+  });
+  assert.equal(offOnly.keyRequired, false, 'nothing switched on to gate');
+});
+
+test('hint and error come from the first active provider that has one', () => {
+  const ui = composeUIState({
+    ...base,
+    providers: [
+      provider({ hint: '', error: null }),
+      provider({ id: 'b', name: 'B', hint: 'Look down', error: 'boom' }),
+    ],
+  });
+  assert.equal(ui.coverage.hint, 'Look down');
+  assert.equal(ui.coverage.error, 'boom');
+  assert.deepEqual(ui.filter, base.filter);
+  assert.notEqual(ui.filter, base.filter, 'snapshot copies the filter');
+});
+
+test('summarizeCoverage is what getStats reports, without building a snapshot', () => {
+  assert.deepEqual(
+    summarizeCoverage([
+      provider({ count: 4, hint: 'Look down' }),
+      provider({ id: 'b', name: 'B', count: 6, loading: true, error: 'boom' }),
+      provider({ id: 'c', name: 'C', count: 99, on: false, keyRequired: true }),
+    ]),
+    {
+      count: 10,
+      loading: true,
+      hint: 'Look down',
+      error: 'boom',
+      keyRequired: false,
+      keyRejected: false,
+    },
+  );
+  assert.equal(summarizeCoverage([]).keyRequired, false);
+});
+
+test('a rejected key gates like a missing one and is named as rejected', () => {
+  const rejected = provider({
+    keyRequired: true,
+    keyRejected: true,
+    error: 'Mapillary rejected MAPILLARY_CLIENT_TOKEN',
+  });
+  const summary = summarizeCoverage([rejected]);
+  assert.equal(summary.keyRequired, true);
+  assert.equal(summary.keyRejected, true);
+  assert.equal(summary.error, 'Mapillary rejected MAPILLARY_CLIENT_TOKEN');
+  const state = composeUIState({ ...base, providers: [rejected] });
+  assert.equal(state.keyRequired, true);
+  assert.equal(state.keyRejected, true);
+  // A provider that is merely missing its key is not "rejected".
+  assert.equal(
+    summarizeCoverage([provider({ keyRequired: true })]).keyRejected,
+    false,
+  );
+});

src/layers/streetLevel/viewerHost.js

@@ -1,10 +1,13 @@
 import { freshStreet } from './state.js';
 
-/** The panel's photo viewer: its poses update `state.street` and the marker. */
-export function createViewerHost({ state, parts, adapter }) {
-  /** Set once mounted, until `unmount`. */
-  let unsubscribe = null;
-  /** The mount in flight, shared by concurrent opens. */
+/**
+ * The panel's photo viewer element and the provider adapter mounted in it.
+ * Adapter poses update `state.street` and the marker.
+ */
+export function createViewerHost({ state, parts }) {
+  /** @type {{id: string, adapter: object, unsubscribe: () => void}|null} */
+  let active = null;
+  /** The mount in flight, shared by concurrent opens. @type {{id: string, promise: Promise<object>}|null} */
   let mounting = null;
   let openSeq = 0;
 
@@ -13,7 +16,7 @@ export function createViewerHost({ state, parts, adapter }) {
   }
 
   function applyPose(pose) {
-    if (!unsubscribe || !state.street.open) return;
+    if (!active || !state.street.open) return;
     const previousSequence = state.street.sequenceId;
     Object.assign(state.street, {
       imageId: pose.imageId,
@@ -35,43 +38,57 @@ export function createViewerHost({ state, parts, adapter }) {
   }
 
   function selectCurrentSequence() {
-    const { sequenceId } = state.street;
-    if (!sequenceId || !state.enabled) return;
-    if (state.sequence.selectedId !== sequenceId)
-      parts.sequences.select(sequenceId);
+    const { sequenceId, providerId } = state.street;
+    const entry = state.providers.get(providerId);
+    if (!sequenceId || !entry?.instance.selectSequence || !state.enabled)
+      return;
+    if (entry.instance.sequenceStats?.()?.selectedId !== sequenceId)
+      entry.instance.selectSequence(sequenceId);
   }
 
   /**
-   * Mount the viewer. It counts as mounted only on success, so a failed
-   * mount is retried on the next open; concurrent opens share one.
+   * Mount a provider's adapter, releasing another provider's first. It
+   * counts as mounted only on success, so a failed mount is retried on the
+   * next open; concurrent opens share one.
    */
-  function mount() {
-    if (unsubscribe) return Promise.resolve();
-    if (mounting) return mounting;
+  function mount(entry) {
+    const id = entry.def.id;
+    if (active?.id === id) return Promise.resolve(active.adapter);
+    if (mounting?.id === id) return mounting.promise;
+    if (active) {
+      active.adapter.close();
+      active.unsubscribe();
+      active.adapter.unmount();
+      active = null;
+    }
+    const adapter = entry.instance.viewer;
     const promise = (async () => {
       await adapter.mount(state.street.host);
-      if (mounting !== promise) {
-        // Unmounted (layer off) while loading. A newer mount shares the
-        // viewer: tearing it down here would leave that mount without one.
-        if (!mounting && !unsubscribe) adapter.unmount();
+      if (mounting?.promise !== promise) {
+        // Unmounted (layer off, provider switched) while loading. A newer
+        // mount of this provider shares the adapter: tearing it down here
+        // would leave that mount without a viewer.
+        if (active?.id !== id && mounting?.id !== id) adapter.unmount();
         throw new Error('Street-level viewer was closed');
       }
       // Listen only once current: an outdated mount releasing the same
       // `applyPose` would otherwise unhook the mount that replaced it.
-      unsubscribe = adapter.onPose(applyPose);
+      active = { id, adapter, unsubscribe: adapter.onPose(applyPose) };
       adapter.setRenderMode?.(state.street.renderMode);
+      return adapter;
     })();
-    mounting = promise;
+    mounting = { id, adapter, promise };
     const settle = () => {
-      if (mounting === promise) mounting = null;
+      if (mounting?.promise === promise) mounting = null;
     };
     promise.then(settle, settle);
     return promise;
   }
 
   /** Open an image: true once its first pose is in, false if it failed or was overtaken. */
-  async function open(imageId) {
-    if (!imageId) return false;
+  async function open(providerId, imageId) {
+    const entry = state.providers.get(providerId);
+    if (!entry || !imageId) return false;
     if (!state.street.host) {
       state.street.error = 'Open the Street Level panel to view imagery';
       notify();
@@ -81,10 +98,17 @@ export function createViewerHost({ state, parts, adapter }) {
     const current = () => seq === openSeq;
     // Claimed now, honoured after loading only if nothing newer took the camera.
     const ticket = parts.framing.begin();
-    Object.assign(state.street, { loading: true, error: null, open: true });
+    Object.assign(state.street, {
+      loading: true,
+      error: null,
+      open: true,
+      providerId,
+      providerName: entry.def.name,
+      providerLabel: entry.def.label,
+    });
     notify();
     try {
-      await mount();
+      const adapter = await mount(entry);
       if (!current()) return false;
       await adapter.open(String(imageId));
       if (!current()) return false;
@@ -101,11 +125,11 @@ export function createViewerHost({ state, parts, adapter }) {
     return true;
   }
 
-  /** Close the image and stop any framing flight; the viewer stays mounted. */
+  /** Close the image and stop any framing flight; the adapter stays mounted. */
   function close() {
     openSeq++;
     parts.framing.cancel();
-    if (unsubscribe) adapter.close();
+    active?.adapter.close();
     Object.assign(state.street, freshStreet());
     parts.marker.clear();
     notify();
@@ -117,22 +141,29 @@ export function createViewerHost({ state, parts, adapter }) {
   }
 
   function resize() {
-    if (unsubscribe) adapter.resize();
+    active?.adapter.resize();
   }
 
   function setRenderMode(mode) {
     state.street.renderMode = mode === 'fill' ? 'fill' : 'letterbox';
-    if (unsubscribe) adapter.setRenderMode?.(state.street.renderMode);
+    active?.adapter.setRenderMode?.(state.street.renderMode);
     notify();
   }
 
-  /** Close the image and destroy the viewer (and its WebGL context). */
-  function unmount() {
+  /**
+   * Close the image and destroy the viewer (and its WebGL context): every
+   * provider's, or only `providerId`'s. A mount still in flight is told too,
+   * so it builds nothing when its library lands.
+   */
+  function unmount(providerId) {
+    if (providerId && active?.id !== providerId && mounting?.id !== providerId)
+      return;
     close();
+    const pending = mounting;
     mounting = null;
-    unsubscribe?.();
-    unsubscribe = null;
-    adapter.unmount();
+    active?.unsubscribe();
+    (active?.adapter ?? pending?.adapter)?.unmount();
+    active = null;
   }
 
   return { attach, open, close, resize, setRenderMode, unmount };

src/layers/streetLevel/viewerHost.test.mjs

@@ -35,13 +35,29 @@ const { createMapillaryViewer } = await import('./viewer.js');
  * `selected` every sequence the layer was asked to select.
  */
 function harness(adapter) {
+  const selected = [];
   const state = {
     enabled: true,
     notify() {},
     street: { host: {}, renderMode: 'letterbox' },
     sequence: { selectedId: null },
+    providers: new Map([
+      [
+        'mapillary',
+        {
+          def: { id: 'mapillary', name: 'Mapillary', label: 'MAPILLARY' },
+          instance: {
+            viewer: adapter,
+            selectSequence(id) {
+              selected.push(id);
+              state.sequence.selectedId = id;
+            },
+            sequenceStats: () => ({ selectedId: state.sequence.selectedId }),
+          },
+        },
+      ],
+    ]),
   };
-  const selected = [];
   const framing = { begun: 0, started: 0, cancelled: 0 };
   const marker = [];
   const parts = {
@@ -55,12 +71,6 @@ function harness(adapter) {
       frame: (ticket) => ticket && framing.started++,
       cancel: () => framing.cancelled++,
     },
-    sequences: {
-      select(id) {
-        selected.push(id);
-        state.sequence.selectedId = id;
-      },
-    },
   };
   return {
     state,
@@ -71,7 +81,7 @@ function harness(adapter) {
     clearSequence() {
       state.sequence.selectedId = null;
     },
-    host: createViewerHost({ state, parts, adapter }),
+    host: createViewerHost({ state, parts }),
   };
 }
 
@@ -132,10 +142,10 @@ function fakeAdapter({ failMounts = 0, gate = null, openGate = null } = {}) {
 test('a failed mount is retried on the next open instead of being cached', async () => {
   const adapter = fakeAdapter({ failMounts: 1 });
   const { state, host } = harness(adapter);
-  await host.open('a');
+  await host.open('mapillary', 'a');
   assert.equal(state.street.error, 'library failed to load');
   assert.equal(adapter.calls.listeners, 0, 'the pose listener was released');
-  await host.open('b');
+  await host.open('mapillary', 'b');
   assert.equal(state.street.error, null);
   assert.equal(adapter.calls.mount, 2);
   assert.deepEqual(adapter.calls.open, ['b']);
@@ -146,7 +156,7 @@ test('a failed mount is retried on the next open instead of being cached', async
 test('concurrent opens share one mount and one pose listener', async () => {
   const adapter = fakeAdapter();
   const { host } = harness(adapter);
-  await Promise.all([host.open('a'), host.open('b')]);
+  await Promise.all([host.open('mapillary', 'a'), host.open('mapillary', 'b')]);
   assert.equal(adapter.calls.mount, 1);
   assert.equal(adapter.calls.listeners, 1);
 });
@@ -154,14 +164,14 @@ test('concurrent opens share one mount and one pose listener', async () => {
 test('unmounting while a mount is in flight does not leave it active', async () => {
   const adapter = fakeAdapter();
   const { state, host } = harness(adapter);
-  const opening = host.open('a');
+  const opening = host.open('mapillary', 'a');
   host.unmount();
   await opening;
   assert.equal(adapter.calls.listeners, 0);
   assert.equal(adapter.calls.unmount, 2, 'layer off, then the late mount');
   assert.equal(state.street.open, false);
   // Not left active: the next open mounts again.
-  await host.open('b');
+  await host.open('mapillary', 'b');
   assert.equal(adapter.calls.mount, 2);
   assert.equal(state.street.imageId, 'b');
 });
@@ -169,7 +179,7 @@ test('unmounting while a mount is in flight does not leave it active', async ()
 test('a pose that arrives after the photo was closed does not bring it back', async () => {
   const adapter = fakeAdapter();
   const { state, host } = harness(adapter);
-  await host.open('a');
+  await host.open('mapillary', 'a');
   host.close();
   const before = { ...state.street };
   // The library's `image` event for a photo that was still loading.
@@ -193,7 +203,7 @@ const settle = () => new Promise((resolve) => setTimeout(resolve, 0));
 test('every pose the viewer reports moves the marker; only the open frames the camera', async () => {
   const adapter = fakeAdapter();
   const { host, marker, framing } = harness(adapter);
-  await host.open('a');
+  await host.open('mapillary', 'a');
   assert.deepEqual(marker, [{ position: { lon: 1, lat: 2 }, bearing: 90 }]);
   // The user walks on: the marker goes along, the globe camera stays.
   adapter.emitPose('b', { position: { lon: 3, lat: 4 }, bearing: 180 });
@@ -211,7 +221,7 @@ test('a pose on another sequence selects it, but not while the image still loads
   const openGate = deferred();
   const adapter = fakeAdapter({ openGate });
   const { state, host, selected, clearSequence } = harness(adapter);
-  const opening = host.open('a');
+  const opening = host.open('mapillary', 'a');
   await settle();
   assert.equal(state.street.loading, true, 'the image is downloading');
   assert.equal(state.street.sequenceId, 'seq-a', 'its pose is in');
@@ -234,7 +244,7 @@ test('a pose on another sequence selects it, but not while the image still loads
 test('closing the photo clears the marker', async () => {
   const adapter = fakeAdapter();
   const { host, marker } = harness(adapter);
-  await host.open('a');
+  await host.open('mapillary', 'a');
   assert.notEqual(marker.at(-1), null);
   host.close();
   assert.equal(marker.at(-1), null);
@@ -244,7 +254,7 @@ test('an open still mounting when the photo is closed does nothing when the moun
   const gate = deferred();
   const adapter = fakeAdapter({ gate });
   const { state, host, framing, selected } = harness(adapter);
-  const opening = host.open('a'); // MapillaryJS still loading
+  const opening = host.open('mapillary', 'a'); // MapillaryJS still loading
   await settle();
   host.close();
   gate.resolve();
@@ -257,7 +267,7 @@ test('an open still mounting when the photo is closed does nothing when the moun
     [false, false, null],
   );
   // The mounted viewer serves the next open.
-  assert.equal(await host.open('b'), true);
+  assert.equal(await host.open('mapillary', 'b'), true);
   assert.equal(state.street.imageId, 'b');
 });
 
@@ -265,7 +275,7 @@ test('an image still opening when the photo is closed is neither framed nor sele
   const openGate = deferred();
   const adapter = fakeAdapter({ openGate });
   const { state, host, framing, selected } = harness(adapter);
-  const opening = host.open('a');
+  const opening = host.open('mapillary', 'a');
   await settle();
   assert.deepEqual(adapter.calls.open, ['a'], 'the image is downloading');
   host.close();
@@ -343,16 +353,16 @@ test('the Mapillary viewer survives the layer going off and on during its first
   const { gate, viewers } = fakeLibrary();
   const adapter = createMapillaryViewer({ source: { token: 't' } });
   const { state, host } = harness(adapter);
-  const first = host.open('img1');
+  const first = host.open('mapillary', 'img1');
   await Promise.resolve();
   host.unmount();
-  const second = host.open('img2');
+  const second = host.open('mapillary', 'img2');
   await Promise.resolve();
   gate.resolve();
   await Promise.all([first, second]);
   assert.equal(state.street.error, null);
   assert.equal(state.street.imageId, 'img2');
-  await host.open('img3');
+  await host.open('mapillary', 'img3');
   assert.equal(state.street.error, null, 'later opens are not stuck');
   assert.equal(state.street.imageId, 'img3');
   assert.equal(viewers.live, 1);
@@ -379,7 +389,7 @@ test('closing the photo stops sequence playback in the hidden viewer', async ()
   gate.resolve();
   const adapter = createMapillaryViewer({ source: { token: 't' } });
   const { host } = harness(adapter);
-  await host.open('img1');
+  await host.open('mapillary', 'img1');
   const [viewer] = viewers.instances;
   assert.equal(viewer.playback.stops, 0);
   host.close();
@@ -455,7 +465,7 @@ test('a photo asks for the camera when it starts opening and frames with that ti
   const openGate = deferred();
   const adapter = fakeAdapter({ openGate });
   const { host, framing } = harness(adapter);
-  const opening = host.open('a');
+  const opening = host.open('mapillary', 'a');
   assert.equal(framing.begun, 1, 'claimed before the download');
   await settle();
   assert.equal(framing.started, 0);

src/layers/vessels/ingestion.js

@@ -109,7 +109,7 @@ export function createIngestion({
     feed.acceptedRowCount = snapshot.acceptedRowCount;
     feed.partial = payload?.complete === false;
 
-    if (snapshot.acceptedRowCount === 0) {
+    if (snapshot.acceptedRowCount === 0 && !snapshot.emptyCoverage) {
       feed.count = readCount();
       feed.stale = feed.count > 0 || Boolean(payload?.refreshing);
       if (isDefinitiveTransportFailure(snapshot.transportStatus)) {

src/layers/vessels/ownership.test.mjs

@@ -361,3 +361,47 @@ test('partial vessel snapshots preserve freshness and recover after a complete u
   layer.destroy();
   assert.equal(layer.getStats().partial, false);
 });
+
+test('authoritative empty coverage clears old contacts without declaring an outage', async () => {
+  let current = snapshot([observation('111')]);
+  const { layer } = setup({
+    async getSnapshot() {
+      return current;
+    },
+  });
+  await layer.update();
+  current = snapshot([], { observedAtMs: null, lastMessageAt: 500 });
+  await layer.update();
+  assert.ok(!layer.hasContact('111'));
+  assert.equal(layer.getStats().count, 0);
+  assert.equal(layer.getStats().error, null);
+  assert.equal(layer.getStats().stale, false);
+  assert.equal(layer.getStats().lastUpdate, null);
+});
+
+test('empty coverage cannot hide stale, incomplete or rejected source data', async () => {
+  for (const patch of [
+    { freshness: 'unknown' },
+    { freshness: 'stale' },
+    { complete: false },
+    { rawRowCount: 1 },
+    { transportStatus: 'stale' },
+    { lastMessageAt: null },
+  ]) {
+    let current = snapshot([observation('111')]);
+    const { layer } = setup({
+      async getSnapshot() {
+        return current;
+      },
+    });
+    await layer.update();
+    current = snapshot([], {
+      observedAtMs: null,
+      lastMessageAt: 500,
+      ...patch,
+    });
+    await layer.update();
+    assert.equal(layer.hasContact('111'), true, JSON.stringify(patch));
+    assert.ok(layer.getStats().error, JSON.stringify(patch));
+  }
+});

src/layers/vessels/queries.js

@@ -119,7 +119,16 @@ export function createQueries({
       typeof payload?.status === 'string' ? payload.status : null;
     const lastMessageAt = payload?.lastMessageAt ?? null;
     const acceptedRowCount = acceptedRows.length;
+    const emptyCoverage =
+      rawRows.length === 0 &&
+      payload?.rawRowCount === 0 &&
+      payload?.complete === true &&
+      payload?.freshness === 'current' &&
+      AIS_HEALTHY_STATUSES.has(transportStatus) &&
+      Number.isFinite(Number(lastMessageAt)) &&
+      Number(lastMessageAt) > 0;
     return {
+      emptyCoverage,
       transportStatus,
       lastMessageAt,
       rawRows,
@@ -130,9 +139,10 @@ export function createQueries({
           ? payload.rawRowCount
           : rawRows.length,
       acceptedRowCount,
-      error:
-        deriveAisFeedError(payload, acceptedRowCount) ||
-        (acceptedRowCount === 0 ? 'awaiting usable AIS positions…' : null),
+      error: emptyCoverage
+        ? null
+        : deriveAisFeedError(payload, acceptedRowCount) ||
+          (acceptedRowCount === 0 ? 'awaiting usable AIS positions…' : null),
     };
   }
 

src/setupDoctor.test.mjs

@@ -274,6 +274,13 @@ test('doctor describes the credential ladder without exposing values', () => {
   );
   assert.match(capabilities.map, /Bing and world-terrain stacks/);
   assert.equal(capabilities.voice, 'available');
+  assert.equal(
+    buildCapabilitySummary({
+      ...credentials,
+      OPENAI_API_KEY: { configured: false },
+    }).voice,
+    'off until an OpenAI key is added, or a Codex ChatGPT sign-in is selected in Provider Settings (experimental)',
+  );
   assert.match(capabilities.missions, /token allowance/);
   assert.equal(
     capabilities.flights,

src/sources/openFreeMap.js

@@ -214,11 +214,18 @@ function decodeLayers(bytes, z, x, y, layerNames) {
   return { roads, military };
 }
 
-/** Construct an immutable-version road/military tile source without starting I/O. */
+/**
+ * Construct an immutable-version road/military tile source without starting I/O.
+ *
+ * `allowedOrigin` is deliberately not set here: `createVectorTileSource`
+ * derives it from whichever `tileJsonUrl` is in effect, so a caller that
+ * repoints only `tileJsonUrl` gets tiles from that host or a named error —
+ * never a silent fall back to the default host (#933). Passing
+ * `allowedOrigin` explicitly still overrides both.
+ */
 export function createOpenFreeMapSource(options = {}) {
   return createVectorTileSource({
     tileJsonUrl: 'https://tiles.openfreemap.org/planet',
-    allowedOrigin: 'https://tiles.openfreemap.org',
     decode: decodeOpenFreeMapTile,
     maxEntries: 192,
     maxCacheBytes: 64 * 1024 * 1024,

src/sources/openFreeMap.test.mjs

@@ -320,3 +320,41 @@ test('Capitol, greenbelt and commercial property fixtures exclude non-public dri
     assert.ok(records.some((r) => r.area === area && !r.drivable));
   }
 });
+
+test('repointing tileJsonUrl at a mirror never falls back to the default tile host', async () => {
+  const urls = [];
+  const mirror = 'http://127.0.0.1:12348';
+  const source = createOpenFreeMapSource({
+    fetchImpl: async (url) => {
+      urls.push(url);
+      return url.endsWith('/planet')
+        ? Response.json({ tiles: [`${mirror}/planet/v/{z}/{x}/{y}.pbf`] })
+        : new Response(fixture('ofm-austin-14-3743-6745.pbf'));
+    },
+    tileJsonUrl: `${mirror}/planet`,
+  });
+  await source.fetchBounds(
+    { south: 30.264, north: 30.271, west: -97.75, east: -97.74 },
+    { zoom: 14 },
+  );
+  assert.ok(urls.length > 1, 'tiles were fetched');
+  assert.deepEqual(
+    urls.filter((url) => !url.startsWith(mirror)),
+    [],
+    'a repointed source must not fetch from tiles.openfreemap.org',
+  );
+});
+
+test('a mirror that serves the default host TileJSON verbatim fails loudly', async () => {
+  // A transparent caching proxy returns upstream's TileJSON unchanged, whose
+  // tiles[0] is an absolute upstream URL. That must be an error, not 100% of
+  // tile traffic quietly leaving the configured mirror.
+  const source = createOpenFreeMapSource({
+    fetchImpl: async () =>
+      Response.json({
+        tiles: ['https://tiles.openfreemap.org/planet/v/{z}/{x}/{y}.pbf'],
+      }),
+    tileJsonUrl: 'http://127.0.0.1:12348/planet',
+  });
+  await assert.rejects(source.getMetadata(), { retryable: false });
+});

src/sources/tle.js

@@ -1,6 +1,6 @@
 /**
  * Parse three-line TLE catalog text into `{ name, line1, line2 }` entries.
- * Blocks whose second and third lines are not TLE lines 1 and 2 are skipped.
+ * Malformed sets are skipped without dropping the valid sets that follow.
  */
 export function parseTleText(text) {
   const lines = String(text)
@@ -9,12 +9,13 @@ export function parseTleText(text) {
     .map((line) => line.trim())
     .filter((line) => line.length > 0);
   const result = [];
-  for (let i = 0; i < lines.length - 2; i += 3) {
+  for (let i = 0; i < lines.length - 2; i++) {
     const name = lines[i];
     const line1 = lines[i + 1];
     const line2 = lines[i + 2];
     if (line1.startsWith('1 ') && line2.startsWith('2 ')) {
       result.push({ name, line1, line2 });
+      i += 2;
     }
   }
   return result;

src/sources/vectorTiles.js

@@ -16,11 +16,27 @@ export function validTileBounds(box) {
   );
 }
 
+/**
+ * The origin a configured TileJSON is served from, or undefined when there is
+ * no absolute URL to read one off. Deriving `allowedOrigin` from it means
+ * repointing `tileJsonUrl` at a mirror cannot silently keep loading tiles from
+ * the old host: the origin check below then names the mismatch instead of
+ * passing it (#933).
+ */
+function tileJsonOrigin(tileJsonUrl) {
+  if (typeof tileJsonUrl !== 'string') return undefined;
+  try {
+    return new URL(tileJsonUrl).origin;
+  } catch {
+    return undefined;
+  }
+}
+
 /** A decoded XYZ cache with bounded workers, reads, retained bytes and request lifetimes. */
 export function createVectorTileSource({
   tileJsonUrl,
   template,
-  allowedOrigin,
+  allowedOrigin = tileJsonOrigin(tileJsonUrl),
   decode,
   fetchImpl = (...args) => globalThis.fetch(...args),
   maxTiles = 16,

src/sources/vectorTiles.test.mjs

@@ -203,3 +203,45 @@ test('polygon-selected tiles keep nearest-first order and cached revisits issue
     'over-budget selection is rejected before fetching',
   );
 });
+
+test('a configured tileJsonUrl sets the tile origin, and a foreign tiles[0] is still refused', async () => {
+  // Without an explicit allowedOrigin the mirror's own TileJSON is honoured…
+  const mirrored = createVectorTileSource({
+    tileJsonUrl: 'http://127.0.0.1:12348/planet',
+    decode: () => [],
+    fetchImpl: async () =>
+      Response.json({ tiles: ['http://127.0.0.1:12348/p/{z}/{x}/{y}.pbf'] }),
+  });
+  assert.equal(
+    (await mirrored.getMetadata()).template,
+    'http://127.0.0.1:12348/p/{z}/{x}/{y}.pbf',
+  );
+
+  // …while a TileJSON that names a different host is refused rather than
+  // silently fetched, which is what the origin check is for.
+  const foreign = createVectorTileSource({
+    tileJsonUrl: 'http://127.0.0.1:12348/planet',
+    decode: () => [],
+    fetchImpl: async () =>
+      Response.json({
+        tiles: ['https://tiles.example/planet/{z}/{x}/{y}.pbf'],
+      }),
+  });
+  await assert.rejects(foreign.getMetadata(), { retryable: false });
+});
+
+test('an explicit allowedOrigin still wins over the one derived from tileJsonUrl', async () => {
+  const source = createVectorTileSource({
+    tileJsonUrl: 'http://127.0.0.1:12348/planet',
+    allowedOrigin: 'https://tiles.example',
+    decode: () => [],
+    fetchImpl: async () =>
+      Response.json({
+        tiles: ['https://tiles.example/planet/{z}/{x}/{y}.pbf'],
+      }),
+  });
+  assert.equal(
+    (await source.getMetadata()).template,
+    'https://tiles.example/planet/{z}/{x}/{y}.pbf',
+  );
+});

src/standalone/application.js

@@ -17,6 +17,8 @@ export function createStandaloneApplication({
   cesiumToken,
   geospatial = {},
   voice = {},
+  sources = {},
+  streetLevelProviders,
   allowQaRegistration = false,
 }) {
   if (constructed)
@@ -47,6 +49,8 @@ export function createStandaloneApplication({
         loaderStatus,
       });
       catalog = createStandaloneCatalog({
+        sources,
+        streetLevelProviders,
         nepalBoundaryResolver: (signal) =>
           scene.operations.annotationResolver.resolveRegionRingForQuery(
             'Nepal',

src/standalone/catalog.js

@@ -7,6 +7,8 @@ export { createStandaloneReferenceSources } from './layerSources.js';
 /** Create fresh layer instances using the existing standalone source choices. */
 export function createStandaloneCatalog({
   nepalBoundaryResolver,
+  sources = {},
+  streetLevelProviders,
   signal = new AbortController().signal,
   surface = createSurfaceServices({
     terrainSource: createApplicationRequestServices().terrain,
@@ -16,7 +18,8 @@ export function createStandaloneCatalog({
   return createApplicationCatalog({
     nepalBoundaryResolver,
     surface,
-    sources: createStandaloneLayerSources(),
+    sources: createStandaloneLayerSources(sources),
+    streetLevelProviders,
     signal,
     vesselOptions: {
       maxRows: import.meta.env?.VITE_AIS_LIVE_MAX_ROWS,

src/standalone/layerSources.js

@@ -1,3 +1,5 @@
+import { createDirectionsSource } from '../layers/directions/source.js';
+import { createRecentImagerySource } from '../layers/recentImagery/source.js';
 import { createOpenFreeMapSource } from '../sources/openFreeMap.js';
 import {
   createFlightSource,
@@ -22,10 +24,14 @@ import { createReferenceSources } from '../sources/reference.js';
 export { createReferenceSources as createStandaloneReferenceSources } from '../sources/reference.js';
 
 /** Select standalone providers without starting their acquisition. */
-export function createStandaloneLayerSources() {
+export function createStandaloneLayerSources(overrides = {}) {
+  if (!overrides || typeof overrides !== 'object' || Array.isArray(overrides))
+    throw new TypeError('Source overrides must be an object');
   const mapTiles = createOpenFreeMapSource();
-  return {
+  const defaults = {
     ...createReferenceSources(),
+    directions: createDirectionsSource(),
+    'recent-imagery': createRecentImagerySource(),
     flights: createFlightSource(),
     military: createMilitarySource(),
     vessels: createVesselSource({
@@ -51,4 +57,9 @@ export function createStandaloneLayerSources() {
       token: import.meta.env?.MAPILLARY_CLIENT_TOKEN || '',
     }),
   };
+  for (const name of Object.keys(overrides)) {
+    if (!Object.hasOwn(defaults, name))
+      throw new TypeError(`Unknown source: ${name}`);
+  }
+  return { ...defaults, ...overrides };
 }

src/streetLevelMarkup.test.mjs

@@ -46,6 +46,9 @@ test('the key gate holds every filter, with the error line outside it', () => {
   assert.match(gate, /data-sl-pano="all"/);
   assert.match(gate, /id="sl-since"/);
   assert.ok(html.indexOf('id="sl-error"') < start);
+  // The chips stay outside the gate, so their key tooltip is reachable.
+  assert.match(html, /<div id="sl-provider-chips" class="sl-chips"><\/div>/);
+  assert.doesNotMatch(gate, /sl-provider-chips/);
   assert.match(html, /id="sl-error"[^>]*role="alert"/);
 });
 

src/testSupport/streetLevelFakes.mjs

@@ -1,10 +1,85 @@
-/** Shared Street Level test stand-ins: Mapillary source, photo viewer, Cesium viewer, ray-casting camera. */
+/** Shared Street Level test stand-ins: provider snapshot and provider, Mapillary source, photo viewer, Cesium viewer, ray-casting camera. */
 import * as Cesium from 'cesium';
+import { MAPILLARY_CREDIT_HTML } from '../layers/streetLevel/policy.js';
 
 const RAD = Math.PI / 180;
 
+/** One provider as `getUIState().providers` lists it. */
+export function providerSnapshot(overrides = {}) {
+  return {
+    id: 'mapillary',
+    name: 'Mapillary',
+    label: 'MAPILLARY',
+    on: true,
+    configured: true,
+    keyRequired: false,
+    requiresKeyId: 'mapillary',
+    loading: false,
+    count: 0,
+    hint: '',
+    error: null,
+    color: '#05cb63',
+    ...overrides,
+  };
+}
+
 /**
- * A Mapillary source for the layer: a configured key, empty tiles, and the
+ * The smallest provider the core accepts. Mutate `stats` to change what
+ * coverageStats() answers; `calls`, `filters` and `context()` record use.
+ */
+export function fakeStreetLevelProvider({
+  id = 'mapillary',
+  pickPrefix = 'mly:',
+  html = MAPILLARY_CREDIT_HTML,
+} = {}) {
+  const calls = { activate: 0, deactivate: 0, mount: 0, open: [], unmount: 0 };
+  const filters = [];
+  const stats = {
+    count: 0,
+    loading: false,
+    hint: '',
+    error: null,
+    keyRequired: false,
+  };
+  let context = null;
+  return {
+    calls,
+    filters,
+    stats,
+    context: () => context,
+    id,
+    name: 'Mapillary',
+    label: 'MAPILLARY',
+    requiresKeyId: null,
+    pickPrefix,
+    colors: { coverage: '#05cb63' },
+    credit: { html },
+    create: (providerContext) => {
+      context = providerContext;
+      return {
+        status: async () => ({ configured: true }),
+        init() {},
+        activate: () => calls.activate++,
+        deactivate: () => calls.deactivate++,
+        destroy() {},
+        setFilter: (filter) => filters.push(filter),
+        coverageStats: () => ({ ...stats }),
+        handlePick: () => false,
+        viewer: {
+          mount: async () => calls.mount++,
+          open: async (imageId) => calls.open.push(imageId),
+          close() {},
+          unmount: () => calls.unmount++,
+          resize() {},
+          onPose: () => () => {},
+        },
+      };
+    },
+  };
+}
+
+/**
+ * A Mapillary source for the provider: a configured key, empty tiles, and the
  * given lookups; `calls` records tile requests.
  */
 export function fakeMapillarySource(overrides = {}) {

src/tooling/localServices.test.mjs

@@ -41,6 +41,7 @@ function request(
     url = '/',
     body = '',
     origin = 'http://localhost:4173',
+    remoteAddress = '127.0.0.1',
   } = {},
 ) {
   return new Promise((resolve, reject) => {
@@ -53,7 +54,7 @@ function request(
         origin,
         'content-type': 'application/json',
       },
-      socket: { remoteAddress: '127.0.0.1' },
+      socket: { remoteAddress },
     });
     const headers = {};
     const res = {
@@ -199,6 +200,386 @@ test('Realtime handler preserves tools and default instructions, isolates suppli
   assert.equal(sent[0].session.instructions, sent[2].session.instructions);
 });
 
+test('Realtime handler keeps API key as default and uses OAuth only when requested', async (t) => {
+  env(t, 'GEV_RATELIMIT_OPENAI_PER_MIN', undefined);
+  let oauthReads = 0;
+  const authorizations = [];
+  const routes = install(
+    openAiRealtimeProxy({
+      realtime: {
+        resolveApiKey: () => 'fixture-api-key',
+        resolveOAuthAccessToken: () => {
+          oauthReads += 1;
+          return 'fixture-oauth-token';
+        },
+        fetchImpl: async (_url, options) => {
+          authorizations.push(options.headers.Authorization);
+          return Response.json({ value: 'fixture-ephemeral' });
+        },
+      },
+    }),
+  );
+  const token = routes.get('/api/realtime/token');
+
+  const apiResponse = await request(token);
+  assert.equal(apiResponse.status, 200);
+  assert.equal(apiResponse.headers['x-gev-voice-auth'], 'env');
+  assert.equal(oauthReads, 0, 'default cloud voice does not read OAuth');
+  assert.equal(authorizations.at(-1), 'Bearer fixture-api-key');
+
+  const oauthResponse = await request(token, { url: '/?auth=oauth' });
+  assert.equal(oauthResponse.status, 200);
+  assert.equal(oauthResponse.headers['x-gev-voice-auth'], 'codex-oauth');
+  assert.equal(oauthReads, 1);
+  assert.equal(authorizations.at(-1), 'Bearer fixture-oauth-token');
+});
+
+test('a Codex OAuth pin refuses API-key minting without silently switching modes', async (t) => {
+  env(t, 'GEV_RATELIMIT_OPENAI_PER_MIN', undefined);
+  const authorizations = [];
+  const routes = install(
+    openAiRealtimeProxy({
+      realtime: {
+        environment: { GEV_PREFER_CODEX_OAUTH: 'true' },
+        resolveApiKey: () => assert.fail('pinned OAuth cannot read an API key'),
+        resolveOAuthAccessToken: () => 'fixture-oauth-token',
+        fetchImpl: async (_url, options) => {
+          authorizations.push(options.headers.Authorization);
+          return Response.json({ value: 'fixture-ephemeral' });
+        },
+      },
+    }),
+  );
+  const token = routes.get('/api/realtime/token');
+  const refused = await request(token);
+  assert.equal(refused.status, 503);
+  assert.equal(refused.json().code, 'CODEX_OAUTH_REQUIRED');
+  assert.equal(authorizations.length, 0);
+  assert.equal((await request(token, { url: '/?auth=oauth' })).status, 200);
+  assert.deepEqual(authorizations, ['Bearer fixture-oauth-token']);
+});
+
+test('OAuth status and token minting never expose local OAuth to remote clients', async () => {
+  let oauthReads = 0;
+  const routes = install(
+    openAiRealtimeProxy({
+      realtime: {
+        resolveOAuthAccessToken: () => {
+          oauthReads += 1;
+          return 'must-not-be-read-remotely';
+        },
+        fetchImpl: () =>
+          assert.fail('remote OAuth request must not reach OpenAI'),
+      },
+    }),
+  );
+  const remote = { remoteAddress: '192.168.1.20' };
+  assert.equal(
+    (await request(routes.get('/api/realtime/oauth-status'), remote)).status,
+    403,
+  );
+  assert.equal(
+    (
+      await request(routes.get('/api/realtime/token'), {
+        ...remote,
+        url: '/?auth=oauth',
+      })
+    ).status,
+    403,
+  );
+  assert.equal(oauthReads, 0);
+});
+
+test('OAuth status reports local sign-in availability without returning the token', async () => {
+  const routes = install(
+    openAiRealtimeProxy({
+      realtime: { resolveOAuthAccessToken: () => 'fixture-oauth-secret' },
+    }),
+  );
+  const response = await request(routes.get('/api/realtime/oauth-status'));
+  assert.equal(response.status, 200);
+  assert.deepEqual(response.json(), { available: true });
+  assert.equal(response.body.includes('fixture-oauth-secret'), false);
+});
+
+test('OAuth status and token minting report expired sign-in as re-auth required', async () => {
+  const expired = () => {
+    const error = new Error('ChatGPT sign-in has expired.');
+    error.code = 'CODEX_OAUTH_REAUTH_REQUIRED';
+    throw error;
+  };
+  const routes = install(
+    openAiRealtimeProxy({
+      realtime: {
+        resolveOAuthAccessToken: expired,
+        fetchImpl: () => assert.fail('expired OAuth must not reach OpenAI'),
+      },
+    }),
+  );
+
+  const status = await request(routes.get('/api/realtime/oauth-status'));
+  assert.equal(status.status, 200);
+  assert.deepEqual(status.json(), {
+    available: false,
+    error: 'ChatGPT sign-in has expired.',
+    code: 'CODEX_OAUTH_REAUTH_REQUIRED',
+    reauthRequired: true,
+  });
+
+  const token = await request(routes.get('/api/realtime/token'), {
+    url: '/?auth=oauth',
+  });
+  assert.equal(token.status, 503);
+  assert.equal(token.json().code, 'CODEX_OAUTH_REAUTH_REQUIRED');
+});
+
+test('OAuth login endpoint shares pending attempts and never exposes credentials', async (t) => {
+  t.mock.timers.enable({ apis: ['setTimeout'] });
+  let starts = 0;
+  let spawnReady;
+  let exit;
+  const plugin = openAiRealtimeProxy({
+    realtime: {
+      resolveOAuthAccessToken: () => {
+        throw new Error('not signed in');
+      },
+      startOAuthLogin: async () => {
+        starts += 1;
+        await new Promise((resolve) => {
+          spawnReady = resolve;
+        });
+        return {
+          completion: new Promise((resolve) => {
+            exit = resolve;
+          }),
+          cancel() {},
+        };
+      },
+    },
+  });
+  t.after(plugin.closeBundle);
+  const routes = install(plugin);
+  const handler = routes.get('/api/realtime/oauth-login');
+
+  const firstRequest = request(handler, { method: 'POST' });
+  const concurrent = await request(handler, { method: 'POST' });
+  assert.equal(concurrent.status, 202);
+  assert.equal(concurrent.json().started, false);
+  assert.equal(starts, 1, 'reserve the attempt before awaiting spawn');
+  spawnReady();
+  const started = await firstRequest;
+  assert.equal(started.status, 202);
+  assert.deepEqual(started.json(), {
+    available: false,
+    started: true,
+    pending: true,
+  });
+  assert.equal(starts, 1);
+
+  t.mock.timers.tick(31_000);
+  const duplicate = await request(handler, { method: 'POST' });
+  assert.equal(duplicate.status, 202);
+  assert.equal(duplicate.json().pending, true);
+  assert.equal(starts, 1, 'rapid retries must not spawn another login');
+
+  const remote = await request(handler, {
+    method: 'POST',
+    remoteAddress: '192.168.1.20',
+  });
+  assert.equal(remote.status, 403);
+  assert.equal(starts, 1);
+
+  const crossOrigin = await request(handler, {
+    method: 'POST',
+    origin: 'https://example.com',
+  });
+  assert.equal(crossOrigin.status, 403);
+  assert.equal(starts, 1);
+
+  exit({ exitCode: 1 });
+  await Promise.resolve();
+  const failed = await request(routes.get('/api/realtime/oauth-status'));
+  assert.equal(failed.json().loginFailed, true);
+  assert.equal(failed.json().code, 'CODEX_OAUTH_LOGIN_FAILED');
+});
+
+test('OAuth status follows process completion, permits retry, and checks credential storage', async (t) => {
+  let token = null;
+  let exit;
+  let starts = 0;
+  const plugin = openAiRealtimeProxy({
+    realtime: {
+      resolveOAuthAccessToken: () => token,
+      startOAuthLogin: async () => {
+        starts += 1;
+        return {
+          completion: new Promise((resolve) => {
+            exit = resolve;
+          }),
+          cancel() {},
+        };
+      },
+    },
+  });
+  t.after(plugin.closeBundle);
+  const routes = install(plugin);
+  const launch = () =>
+    request(routes.get('/api/realtime/oauth-login'), { method: 'POST' });
+  const status = () => request(routes.get('/api/realtime/oauth-status'));
+  await launch();
+  exit({ exitCode: 0 });
+  await Promise.resolve();
+  assert.equal(
+    (await status()).json().code,
+    'CODEX_OAUTH_STORAGE_UNAVAILABLE',
+    'exit success alone is not usable sign-in',
+  );
+  await launch();
+  assert.equal(starts, 2, 'failed attempts can be retried immediately');
+  token = 'fixture-private-token';
+  exit({ exitCode: 0 });
+  await Promise.resolve();
+  const ready = await status();
+  assert.deepEqual(ready.json(), { available: true });
+  assert.equal(ready.body.includes(token), false);
+});
+
+test('OAuth login timeout and server shutdown cancel the owned process', async () => {
+  let timeout;
+  let cancelled = 0;
+  let cleared = 0;
+  const plugin = openAiRealtimeProxy({
+    realtime: {
+      resolveOAuthAccessToken: () => null,
+      startOAuthLogin: async () => ({
+        completion: new Promise(() => {}),
+        cancel() {
+          cancelled += 1;
+        },
+      }),
+      setTimer(callback, duration) {
+        timeout = callback;
+        assert.equal(duration, 120_000);
+        return 1;
+      },
+      clearTimer() {
+        cleared += 1;
+      },
+    },
+  });
+  const routes = install(plugin);
+  const launch = () =>
+    request(routes.get('/api/realtime/oauth-login'), { method: 'POST' });
+  await launch();
+  timeout();
+  assert.equal(cancelled, 1);
+  const status = await request(routes.get('/api/realtime/oauth-status'));
+  assert.equal(status.json().code, 'CODEX_OAUTH_LOGIN_TIMEOUT');
+  await launch();
+  plugin.closeBundle();
+  plugin.closeBundle();
+  assert.equal(cancelled, 2, 'shutdown is idempotent');
+  assert.equal(cleared, 2);
+});
+
+test('OAuth launch errors are safe and cross-origin status requests cannot read credentials', async () => {
+  let reads = 0;
+  const routes = install(
+    openAiRealtimeProxy({
+      realtime: {
+        resolveOAuthAccessToken() {
+          reads += 1;
+          return null;
+        },
+        startOAuthLogin: async () => {
+          throw new Error('private-token-fixture');
+        },
+      },
+    }),
+  );
+  const remote = await request(routes.get('/api/realtime/oauth-status'), {
+    origin: 'https://example.com',
+  });
+  assert.equal(remote.status, 403);
+  assert.equal(reads, 0);
+  const failed = await request(routes.get('/api/realtime/oauth-login'), {
+    method: 'POST',
+  });
+  assert.equal(failed.status, 503);
+  assert.equal(failed.json().code, 'CODEX_OAUTH_LOGIN_FAILED');
+  assert.equal(failed.body.includes('private-token-fixture'), false);
+});
+
+test('a login that spawns after timeout is cancelled and cannot replace a retry', async (t) => {
+  let timeout;
+  let releaseSpawn;
+  let cancelled = 0;
+  let launches = 0;
+  const plugin = openAiRealtimeProxy({
+    realtime: {
+      resolveOAuthAccessToken: () => null,
+      startOAuthLogin: async () => {
+        launches += 1;
+        if (launches === 1)
+          await new Promise((resolve) => {
+            releaseSpawn = resolve;
+          });
+        return {
+          completion: new Promise(() => {}),
+          cancel() {
+            cancelled += 1;
+          },
+        };
+      },
+      setTimer(callback) {
+        timeout = callback;
+        return 1;
+      },
+      clearTimer() {},
+    },
+  });
+  t.after(plugin.closeBundle);
+  const routes = install(plugin);
+  const launch = () =>
+    request(routes.get('/api/realtime/oauth-login'), { method: 'POST' });
+  const first = launch();
+  timeout();
+  await launch();
+  releaseSpawn();
+  await first;
+  assert.equal(launches, 2);
+  assert.equal(cancelled, 1, 'late process must not become an orphan');
+  const status = (
+    await request(routes.get('/api/realtime/oauth-status'))
+  ).json();
+  assert.equal(status.pending, true);
+  assert.equal(
+    status.loginFailed,
+    undefined,
+    'the older attempt cannot fail the retry',
+  );
+});
+
+test('OAuth login endpoint selects an existing local sign-in without launching Codex', async () => {
+  const handler = install(
+    openAiRealtimeProxy({
+      realtime: {
+        resolveOAuthAccessToken: () => 'fixture-existing-secret',
+        startOAuthLogin: () =>
+          assert.fail('existing auth must not launch login'),
+      },
+    }),
+  ).get('/api/realtime/oauth-login');
+  const response = await request(handler, { method: 'POST' });
+  assert.equal(response.status, 200);
+  assert.deepEqual(response.json(), {
+    available: true,
+    started: false,
+    pending: false,
+  });
+  assert.equal(response.body.includes('fixture-existing-secret'), false);
+});
+
 test('caption transcription is on by default, reported to the client meter, and can be turned off', async (t) => {
   env(t, 'OPENAI_API_KEY', 'fixture-upstream-secret');
   env(t, 'GEV_RATELIMIT_OPENAI_PER_MIN', undefined);

src/tools/queries/space.test.mjs

@@ -30,6 +30,27 @@ test('TLE text parses into named entries with catalog numbers', () => {
   assert.equal(tleCatalogNumber('1 xx'), null);
 });
 
+for (const missingLine of [1, 2]) {
+  test(`TLE parsing resumes after a set missing line ${missingLine}`, () => {
+    const sets = Array.from({ length: 8 }, (_, i) => {
+      const lines = TLE.trim().split('\n').slice(0, 3);
+      lines[0] = `SAT ${i}`;
+      return lines;
+    });
+    sets[1].splice(missingLine, 1);
+    const entries = parseTleText(sets.flat().join('\r\n'));
+    assert.deepEqual(
+      entries.map((entry) => entry.name),
+      ['SAT 0', 'SAT 2', 'SAT 3', 'SAT 4', 'SAT 5', 'SAT 6', 'SAT 7'],
+    );
+    assert.ok(
+      entries.every(
+        (entry) => entry.line1.startsWith('1 ') && entry.line2.startsWith('2 '),
+      ),
+    );
+  });
+}
+
 test('the next pass defaults to the ISS and reports times, peak and direction', async () => {
   const catalog = composeCatalog({
     tools: coreTools,

src/ui/layerPanel.js

@@ -588,7 +588,12 @@ export class LayerPanel {
   }
 
   _syncToggleButton(button, layer) {
-    const feedState = layer.enabled ? layerFeedState(layer.stats) : 'off';
+    const unavailable = layer.stats?.sourceUnavailable === true;
+    const feedState = unavailable
+      ? 'unavailable'
+      : layer.enabled
+        ? layerFeedState(layer.stats)
+        : 'off';
     const transitioning =
       layer.lifecycleState === 'enabling' ||
       layer.lifecycleState === 'disabling';
@@ -601,7 +606,7 @@ export class LayerPanel {
     for (const state of Object.keys(FEED_STATE_LABELS)) {
       button.classList.toggle(
         `feed-${state}`,
-        layer.enabled && !uncertain && feedState === state,
+        (layer.enabled || unavailable) && !uncertain && feedState === state,
       );
     }
     button.dataset.feedState = transitioning
@@ -613,16 +618,21 @@ export class LayerPanel {
     // click guard above prevents repeat activation without the focus loss caused
     // by native `disabled`.
     button.disabled = false;
-    button.setAttribute('aria-disabled', String(transitioning));
+    button.setAttribute(
+      'aria-disabled',
+      String(transitioning || (unavailable && !layer.enabled)),
+    );
     button.setAttribute('aria-busy', String(transitioning));
     button.textContent = transitioning
       ? layer.lifecycleState.toUpperCase()
       : uncertain
         ? 'UNCERTAIN'
-        : layer.enabled
+        : layer.enabled || unavailable
           ? FEED_STATE_LABELS[feedState]
           : 'OFF';
-    const keyGuidance = layerKeyRequirementTooltip(layer);
+    const keyGuidance = unavailable
+      ? String(layer.stats.error || 'Data source unavailable')
+      : layerKeyRequirementTooltip(layer);
     // Name the missing key on the control itself: a row reading KEY REQUIRED
     // without saying WHICH key leaves a dead control and no next step. Empty
     // when the layer needs no key, or already has one.

src/ui/layerPanel.test.mjs

@@ -228,3 +228,33 @@ test('the Recent Imagery readout mounts in its rail body like the weather readou
     globalThis.document = previousDocument;
   }
 });
+
+test('an omitted source is visibly unavailable and cannot be toggled on', async () => {
+  const { LayerPanel } = await import('./layerPanel.js');
+  const attrs = new Map();
+  const button = {
+    classList: { toggle() {} },
+    dataset: {},
+    setAttribute: (key, value) => attrs.set(key, value),
+  };
+  const layer = {
+    id: 'flights',
+    name: 'Flights',
+    enabled: false,
+    stats: {
+      sourceUnavailable: true,
+      status: 'unavailable',
+      error: 'Data source not configured: flights',
+    },
+  };
+  LayerPanel.prototype._syncToggleButton(button, layer);
+  assert.equal(button.textContent, 'UNAVAILABLE');
+  assert.equal(attrs.get('aria-disabled'), 'true');
+  assert.match(button.title, /not configured/);
+  LayerPanel.prototype._syncToggleButton(button, { ...layer, enabled: true });
+  assert.equal(
+    attrs.get('aria-disabled'),
+    'false',
+    'an active layer can always be switched off',
+  );
+});

src/ui/streetLevelControls.js

@@ -1,4 +1,5 @@
 import { isExplicitLayerStateOrigin } from '../data/layerState.js';
+import { syncChipGroup } from './chipGroup.js';
 import {
   presentStreetLevelPanel,
   SINCE_STOPS,
@@ -24,8 +25,8 @@ const setAttr = (node, key, value) => {
 };
 
 /**
- * Fills the Street Level panel body: filters and viewer. The panel chrome
- * itself belongs to the application shell.
+ * Fills the Street Level panel body: provider chips, filters and viewer. The
+ * panel chrome itself belongs to the application shell.
  */
 export class StreetLevelControls {
   constructor({ root, layer, actions }) {
@@ -36,6 +37,7 @@ export class StreetLevelControls {
     this.listeners = new AbortController();
     this._unsubscribe = null;
     this._state = null;
+    this._view = null;
     this._wasEnabled = null;
     this._wasOpen = false;
     // Whether the last switch-on was explicit (user, voice, tool), not a restore.
@@ -53,6 +55,7 @@ export class StreetLevelControls {
     ];
     return {
       status: byId('sl-status'),
+      providerChips: byId('sl-provider-chips'),
       controls: byId('sl-controls'),
       error: byId('sl-error'),
       errorText: byId('sl-error-text'),
@@ -85,6 +88,17 @@ export class StreetLevelControls {
     this.layer.attachViewerHost?.(el.viewer);
 
     this.listen(el.status, 'click', () => this._toggleEnabled());
+    this.listen(el.providerChips, 'click', (event) => {
+      const button = event.target?.closest?.('.data-toggle-chip');
+      if (!button || button.disabled) return;
+      // Without a key the chips stay focusable for their tooltip; a click
+      // says the same thing rather than switching on a layer that cannot draw.
+      if (this._view?.controlsDisabled) {
+        if (button.title) this.actions.showToast?.(button.title);
+        return;
+      }
+      this._toggleProvider(button.dataset.chipId);
+    });
     for (const button of el.panoButtons) {
       this.listen(button, 'click', () =>
         this._setParams({ pano: button.dataset.slPano }),
@@ -192,12 +206,6 @@ export class StreetLevelControls {
 
   async _toggleEnabled() {
     const enabled = this.actions.isEnabled?.() === true;
-    // The pill is the only switch: it also brings back Mapillary that a link
-    // or tool switched off under a layer that is on.
-    if (this._state?.providerOn === false) {
-      this._setParams({ mapillary: true });
-      if (enabled) return;
-    }
     try {
       await this.actions.setEnabled?.(!enabled);
     } catch (error) {
@@ -205,6 +213,45 @@ export class StreetLevelControls {
     }
   }
 
+  async _ensureEnabled() {
+    if (this.actions.isEnabled?.()) return true;
+    try {
+      await this.actions.setEnabled?.(true);
+    } catch (error) {
+      this.actions.showToast?.(
+        error?.message || 'Street Level could not start',
+      );
+      return false;
+    }
+    return this.actions.isEnabled?.() === true;
+  }
+
+  /**
+   * Lighting a chip turns the layer on; darkening the last lit one turns the
+   * layer off but keeps the provider on, so the layer comes back with it.
+   */
+  async _toggleProvider(providerId) {
+    const chip = this._view?.providers.find((entry) => entry.id === providerId);
+    if (!chip) return;
+    if (!chip.active) {
+      this._setParams({ [providerId]: true });
+      await this._ensureEnabled();
+      return;
+    }
+    const othersLit = this._view.providers.some(
+      (entry) => entry.id !== providerId && entry.active,
+    );
+    if (othersLit) {
+      this._setParams({ [providerId]: false });
+      return;
+    }
+    try {
+      await this.actions.setEnabled?.(false);
+    } catch (error) {
+      this.actions.showToast?.(error?.message || 'Street Level toggle failed');
+    }
+  }
+
   /** Through the data manager, so saved state and share links record it. */
   _setParams(params) {
     this.actions.setParams(params, { origin: 'user' });
@@ -315,8 +362,10 @@ export class StreetLevelControls {
     if (this.destroyed || !state || !this.root) return;
     this._state = state;
     const view = presentStreetLevelPanel(state);
+    this._view = view;
     this._renderHeader(view);
     setProp(this._elements.controls, 'disabled', view.controlsDisabled);
+    syncChipGroup(this._elements.providerChips, view.providers);
     this._renderError(view);
     this._renderFilters(view);
     this._renderViewer(view);

src/ui/streetLevelControls.test.mjs

@@ -2,6 +2,7 @@ import assert from 'node:assert/strict';
 import test from 'node:test';
 import { StreetLevelControls } from './streetLevelControls.js';
 import { createStreetLevelLayer } from '../layers/streetLevel/index.js';
+import { createMapillaryProvider } from '../layers/streetLevel/mapillaryProvider.js';
 import { DataLayerManager } from '../data/manager.js';
 import { LayerStateCoordinator } from '../data/layerStateCoordinator.js';
 import {
@@ -9,7 +10,10 @@ import {
   REGISTERED_LAYER_IDS,
   encodeLayerStateParams,
 } from '../data/layerState.js';
-import { fakeMapillarySource } from '../testSupport/streetLevelFakes.mjs';
+import {
+  fakeMapillarySource,
+  providerSnapshot,
+} from '../testSupport/streetLevelFakes.mjs';
 
 /* ── A small DOM: just what the panel controls touch ───────────────────── */
 
@@ -94,6 +98,23 @@ class FakeNode {
       if (current === this) return true;
     return false;
   }
+  closest(selector) {
+    for (let current = this; current; current = current.parent)
+      if (current.matches?.(selector)) return current;
+    return null;
+  }
+  insertBefore(child, before) {
+    child.parent?.children.splice(child.parent.children.indexOf(child), 1);
+    child.parent = this;
+    const at = before ? this.children.indexOf(before) : -1;
+    if (at === -1) this.children.push(child);
+    else this.children.splice(at, 0, child);
+    return child;
+  }
+  remove() {
+    this.parent?.children.splice(this.parent.children.indexOf(this), 1);
+    this.parent = null;
+  }
   focus() {
     this.ownerDocument.activeElement = this;
   }
@@ -182,6 +203,7 @@ function panelDom({ fullscreen = true, popover = false } = {}) {
   const add = (parent, tag, options) =>
     parent.appendChild(new FakeNode(document, tag, options));
   add(root, 'button', { id: 'sl-status' });
+  add(root, 'div', { id: 'sl-provider-chips' });
   const wrap = add(root, 'div', { id: 'sl-viewer-wrap' });
   if (fullscreen) wrap.requestFullscreen = async () => fullscreenTo(wrap);
   if (popover) {
@@ -280,7 +302,9 @@ const memoryStorage = () => {
 
 /** The production path: controls → dataManager → layer → durable layer state. */
 async function productionPanel(dom) {
-  const layer = createStreetLevelLayer({ source: fakeMapillarySource() });
+  const layer = createStreetLevelLayer({
+    providers: [createMapillaryProvider({ source: fakeMapillarySource() })],
+  });
   const manager = new DataLayerManager({});
   for (const id of REGISTERED_LAYER_IDS)
     manager.register(id === 'street-level' ? layer : plainLayer(id));
@@ -390,7 +414,7 @@ function uiState({
 } = {}) {
   return {
     enabled,
-    providerOn: on,
+    providers: [providerSnapshot({ on, keyRequired })],
     keyRequired,
     keyRejected: false,
     filter: { pano, sinceDays: 0 },
@@ -408,7 +432,7 @@ function uiState({
 
 function stubPanel(dom, state, extraActions = {}) {
   const layer = stubLayer();
-  const calls = { setParams: [], setEnabled: [], collapsed: [] };
+  const calls = { setParams: [], setEnabled: [], collapsed: [], toasts: [] };
   let enabled = state.enabled;
   /** Reports a switch-on request's origin, as the data manager does. */
   let announce = null;
@@ -425,7 +449,7 @@ function stubPanel(dom, state, extraActions = {}) {
       setParams: (params, options) => calls.setParams.push([params, options]),
       setPanelCollapsed: (collapsed, options) =>
         calls.collapsed.push([collapsed, options]),
-      showToast() {},
+      showToast: (message) => calls.toasts.push(message),
       subscribeEnableRequests: (listener) => {
         announce = listener;
         return () => {
@@ -442,44 +466,66 @@ function stubPanel(dom, state, extraActions = {}) {
     controls,
     announce: (origin) => announce?.(origin),
     subscribed: () => announce !== null,
+    chip: () => dom.root.querySelector('#sl-provider-chips').children[0],
   };
 }
 
-test('the header pill switches the layer, bringing back Mapillary switched off elsewhere', () =>
+test('the header pill switches the layer; provider switches are left alone', () =>
   withDom(async (dom) => {
     const status = dom.root.querySelector('#sl-status');
-    const on = stubPanel(dom, uiState());
+    const { calls, controls } = stubPanel(dom, uiState());
     status.click();
     await settle();
-    assert.deepEqual(on.calls.setEnabled, [false]);
-    assert.deepEqual(on.calls.setParams, [], 'switching off keeps the switch');
-    on.controls.destroy();
-    const dark = stubPanel(dom, uiState({ enabled: false, on: false }));
-    status.click();
-    await settle();
-    assert.deepEqual(dark.calls.setParams, [
-      [{ mapillary: true }, { origin: 'user' }],
-    ]);
-    assert.deepEqual(dark.calls.setEnabled, [true]);
-    dark.controls.destroy();
+    assert.deepEqual(calls.setEnabled, [false]);
+    assert.deepEqual(calls.setParams, []);
+    controls.destroy();
   }));
 
-test('a layer that is on with Mapillary switched off reads OFF, and the pill brings Mapillary back', () =>
+test('darkening the only lit chip turns the layer off and keeps the provider switched on', () =>
   withDom(async (dom) => {
-    const status = dom.root.querySelector('#sl-status');
-    const { calls, controls } = stubPanel(dom, uiState({ on: false }));
-    assert.equal(status.textContent, 'OFF');
-    assert.equal(status.getAttribute('aria-pressed'), 'false');
-    assert.match(
-      dom.root.querySelector('#sl-coverage-meta').textContent,
-      /Mapillary is off in this view/,
+    const { calls, chip, controls } = stubPanel(dom, uiState());
+    assert.equal(chip().dataset.chipId, 'mapillary');
+    assert.equal(chip().getAttribute('aria-pressed'), 'true');
+    chip().click();
+    await settle();
+    assert.deepEqual(calls.setEnabled, [false]);
+    assert.deepEqual(calls.setParams, [], 'the provider switch is untouched');
+    controls.destroy();
+  }));
+
+test('lighting a dark chip switches the provider on as a user params request, then the layer', () =>
+  withDom(async (dom) => {
+    const { calls, chip, controls } = stubPanel(
+      dom,
+      uiState({ enabled: false, on: false }),
     );
-    status.click();
+    assert.equal(chip().getAttribute('aria-pressed'), 'false');
+    chip().click();
     await settle();
     assert.deepEqual(calls.setParams, [
       [{ mapillary: true }, { origin: 'user' }],
     ]);
-    assert.deepEqual(calls.setEnabled, [], 'the layer itself stays on');
+    assert.deepEqual(calls.setEnabled, [true]);
+    controls.destroy();
+  }));
+
+test('under KEY REQUIRED the provider chip stays live and explains the key instead of toggling', () =>
+  withDom(async (dom) => {
+    const { calls, chip, controls } = stubPanel(
+      dom,
+      uiState({ keyRequired: true }),
+    );
+    assert.equal(
+      dom.root.querySelector('#sl-controls').contains(chip()),
+      false,
+      'the chip is outside the disabled fieldset',
+    );
+    chip().click();
+    await settle();
+    assert.deepEqual(calls.setEnabled, []);
+    assert.deepEqual(calls.setParams, []);
+    assert.equal(calls.toasts.length, 1);
+    assert.match(calls.toasts[0], /^Mapillary: Needs /);
     controls.destroy();
   }));
 

src/ui/streetLevelPresentation.js

@@ -54,11 +54,8 @@ function formatDate(ms) {
   }
 }
 
-/** Whether the layer draws: on, and Mapillary not switched off by a link or tool. */
-const drawing = (state) => state.enabled === true && state.providerOn !== false;
-
 function presentStatus(state) {
-  const pressed = drawing(state);
+  const pressed = state.enabled === true;
   const title = pressed ? 'Turn Street Level off' : 'Turn Street Level on';
   const key = keyStatusLabel(state);
   if (key) return { text: key, tone: 'warn', pressed, title };
@@ -69,10 +66,44 @@ function presentStatus(state) {
     : { text: 'OFF', tone: '', pressed, title };
 }
 
-/** How to add the missing Mapillary key. */
-function keyHint() {
-  const requirement = keySetupRequirement('mapillary');
-  return requirement ? `Mapillary: ${requirement}` : null;
+/** A chip is lit only while the layer and its provider are both on. */
+function presentProviders(state) {
+  const enabled = state.enabled === true;
+  return (state.providers || []).map((provider) => {
+    const keyRequired = provider.keyRequired === true;
+    const on = enabled && provider.on === true;
+    let title = `${provider.name} imagery ${on ? 'on' : 'off'}`;
+    if (provider.keyRejected && provider.error)
+      title = `${provider.name}: ${provider.error}`;
+    else if (keyRequired && provider.requiresKeyId)
+      title = `${provider.name}: ${keySetupRequirement(provider.requiresKeyId)}`;
+    else if (provider.error) title = `${provider.name}: ${provider.error}`;
+    return {
+      id: provider.id,
+      label: provider.label,
+      color: provider.color || null,
+      title,
+      active: on,
+      disabled: false,
+      state: keyRequired
+        ? 'error'
+        : on && provider.loading
+          ? 'loading'
+          : on
+            ? 'active'
+            : 'idle',
+      busy: on && provider.loading === true,
+    };
+  });
+}
+
+/** How to add the key the first switched-on provider is missing. */
+function keyHint(state) {
+  const provider = (state.providers || []).find(
+    (p) => p.on && p.keyRequired && p.requiresKeyId,
+  );
+  const requirement = provider && keySetupRequirement(provider.requiresKeyId);
+  return requirement ? `${provider.name}: ${requirement}` : null;
 }
 
 function presentViewer(state) {
@@ -89,14 +120,16 @@ function presentViewer(state) {
     captionLeft: street.creator ? `Image by ${street.creator}` : '',
     captionRight: right.join(' · '),
     link: street.externalUrl || null,
-    linkLabel: street.externalUrl ? 'MAPILLARY ↗' : '',
+    linkLabel: street.providerLabel ? `${street.providerLabel} ↗` : '',
   };
 }
 
 function presentMeta(state) {
+  const providers = state.providers || [];
+  if (providers.length === 0) return state.coverage.hint || '';
   if (!state.enabled) return 'Switch Street Level on to draw its coverage.';
-  if (!drawing(state))
-    return 'Mapillary is off in this view. Switch Street Level on to show it.';
+  if (!providers.some((p) => p.on))
+    return 'Every provider is switched off: light a chip to draw its coverage.';
   if (state.sequence.selectedId)
     return state.sequence.loading
       ? 'Loading this sequence…'
@@ -110,20 +143,23 @@ function presentMeta(state) {
   const filter = state.filter || {};
   return (filter.pano || 'all') !== 'all' || Number(filter.sinceDays) > 0
     ? 'No sequences in view match the filter'
-    : 'No Mapillary coverage in view';
+    : 'No coverage in view';
 }
 
 /** @param {{now?: number}} [options] Clock for the SINCE readout. */
 export function presentStreetLevelPanel(state, { now = Date.now() } = {}) {
+  const keyRequired = state.keyRequired === true;
   const filter = state.filter || { pano: 'all', sinceDays: 0 };
   // A missing key says how to add it; a rejected key's own error names the fix.
-  const keyMissing = state.keyRequired === true && state.keyRejected !== true;
+  const keyMissing = keyRequired && state.keyRejected !== true;
   return {
     enabled: state.enabled === true,
+    keyRequired,
     status: presentStatus(state),
-    controlsDisabled: state.keyRequired === true,
+    controlsDisabled: keyRequired || (state.providers || []).length === 0,
+    providers: presentProviders(state),
     error: keyMissing
-      ? keyHint()
+      ? keyHint(state)
       : state.street.error ||
         state.sequence.error ||
         state.coverage.error ||

src/ui/streetLevelPresentation.test.mjs

@@ -4,10 +4,36 @@ import {
   presentStreetLevelPanel,
   sinceStopIndex,
 } from './streetLevelPresentation.js';
+import { providerSnapshot } from '../testSupport/streetLevelFakes.mjs';
+
+const provider = providerSnapshot;
+
+test('an empty composition explains unavailable imagery even while disabled', () => {
+  for (const enabled of [false, true]) {
+    const view = presentStreetLevelPanel(
+      snapshot({
+        enabled,
+        providers: [],
+        coverage: { hint: 'No street-level imagery providers configured' },
+      }),
+    );
+    assert.equal(view.controlsDisabled, true);
+    assert.equal(view.keyRequired, false);
+    assert.deepEqual(view.providers, []);
+    assert.equal(view.meta, 'No street-level imagery providers configured');
+  }
+});
+
 function snapshot(overrides = {}) {
   const base = {
     enabled: false,
-    providerOn: true,
+    // The one provider's key state follows the summary the test asks for.
+    providers: [
+      provider({
+        keyRequired: overrides.keyRequired === true,
+        keyRejected: overrides.keyRejected === true,
+      }),
+    ],
     keyRequired: false,
     keyRejected: false,
     filter: { pano: 'all', sinceDays: 0 },
@@ -17,6 +43,7 @@ function snapshot(overrides = {}) {
       open: false,
       loading: false,
       error: null,
+      providerLabel: null,
       imageId: null,
       position: null,
       bearing: null,
@@ -204,7 +231,7 @@ test('the meta line never mixes the visible-sequence count with the selected seq
 test('an empty view says so, and whether the filter emptied it', () => {
   const meta = (overrides) =>
     presentStreetLevelPanel(snapshot({ enabled: true, ...overrides })).meta;
-  assert.equal(meta({}), 'No Mapillary coverage in view');
+  assert.equal(meta({}), 'No coverage in view');
   assert.equal(
     meta({ filter: { pano: 'flat', sinceDays: 0 } }),
     'No sequences in view match the filter',
@@ -225,6 +252,7 @@ test('viewer caption reads "Image by" left, date right, and links to Mapillary',
       enabled: true,
       street: {
         open: true,
+        providerLabel: 'MAPILLARY',
         imageId: '1814275685699406',
         creator: 'mapfool',
         capturedAt: Date.UTC(2023, 9, 8),

src/ui/styles/provider-settings.css

@@ -300,6 +300,43 @@
   color: rgba(148, 178, 188, 0.42);
 }
 
+.key-setup-cloud-auth {
+  display: flex;
+  align-items: center;
+  gap: 0.5rem;
+}
+
+.key-setup-cloud-auth-state {
+  color: rgba(190, 214, 222, 0.7);
+  font-family: var(--font-mono);
+  font-size: 0.56rem;
+  letter-spacing: 0.05rem;
+}
+
+.key-setup-cloud-auth-toggle {
+  margin-left: auto;
+  padding: 0.28rem 0.55rem;
+  color: rgba(54, 220, 255, 0.9);
+  font-family: var(--font-mono);
+  font-size: 0.55rem;
+  letter-spacing: 0.06rem;
+  background: rgba(54, 220, 255, 0.08);
+  border: 1px solid rgba(54, 220, 255, 0.28);
+  border-radius: 0.32rem;
+  cursor: pointer;
+}
+
+.key-setup-cloud-auth-toggle:hover,
+.key-setup-cloud-auth-toggle:focus-visible {
+  border-color: rgba(54, 220, 255, 0.65);
+  outline: none;
+}
+
+.key-setup-cloud-auth-toggle[aria-disabled='true'] {
+  cursor: wait;
+  opacity: 0.5;
+}
+
 .key-setup-footer {
   margin-top: 0.85rem;
 }

src/ui/styles/street-level.css

@@ -110,6 +110,56 @@
   pointer-events: none;
 }
 
+/* ── Providers ───────────────────────────────────────────────────────────── */
+.sl-providers {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  flex-wrap: wrap;
+}
+
+.sl-chips {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 4px;
+}
+
+/* `--chip-color` comes from the provider. */
+.sl-chips .data-toggle-chip {
+  display: inline-flex;
+  align-items: center;
+  gap: 5px;
+}
+
+.sl-chips .data-toggle-chip::before {
+  content: '';
+  width: 7px;
+  height: 7px;
+  border-radius: 50%;
+  background: var(--chip-color, currentColor);
+  opacity: 0.45;
+  flex: none;
+}
+
+.sl-chips .data-toggle-chip.active {
+  color: var(--chip-color, var(--accent));
+  border-color: var(--chip-color, var(--accent));
+  background: color-mix(
+    in srgb,
+    var(--chip-color, var(--accent)) 14%,
+    transparent
+  );
+}
+
+.sl-chips .data-toggle-chip.active::before {
+  opacity: 1;
+}
+
+.sl-chips .data-toggle-chip.chip-error {
+  color: #ffb300;
+  border-color: rgba(255, 179, 0, 0.55);
+}
+
 /* ── Errors ──────────────────────────────────────────────────────────────── */
 .sl-error {
   font-family: var(--font-sans);

src/ui/templates/layer-panels.html

@@ -107,8 +107,13 @@
             </span>
           </div>
         </div>
+        <div class="sl-providers" role="group" aria-label="Imagery providers">
+          <span class="cctv-summary-label">PROVIDERS</span>
+          <div id="sl-provider-chips" class="sl-chips"></div>
+        </div>
         <div id="sl-error" class="sl-error" role="alert" hidden><span aria-hidden="true">⚠</span> <span id="sl-error-text"></span></div>
-        <!-- A missing key gates the filters; the line above says how to add it. -->
+        <!-- A missing key gates the filters only: the chips above stay
+             focusable so their tooltip can say how to add the key. -->
         <fieldset id="sl-controls" class="sl-controls">
           <div class="sl-filters" role="group" aria-label="Imagery filters">
             <span class="cctv-summary-label">IMAGERY</span>

src/voice/cloudVoiceAuth.js

@@ -0,0 +1,41 @@
+export const CLOUD_VOICE_AUTH_MODES = Object.freeze(['api-key', 'oauth']);
+export const DEFAULT_CLOUD_VOICE_AUTH_MODE = 'api-key';
+export const CLOUD_VOICE_AUTH_STORAGE_KEY = 'godsEyeView.voice.cloudAuth';
+
+function storageRef(storage) {
+  if (storage) return storage;
+  try {
+    return typeof localStorage === 'undefined' ? null : localStorage;
+  } catch {
+    return null;
+  }
+}
+
+export function normalizeCloudVoiceAuthMode(mode) {
+  const normalized = String(mode || '')
+    .trim()
+    .toLowerCase();
+  return CLOUD_VOICE_AUTH_MODES.includes(normalized)
+    ? normalized
+    : DEFAULT_CLOUD_VOICE_AUTH_MODE;
+}
+
+export function readStoredCloudVoiceAuthMode(storage) {
+  try {
+    return normalizeCloudVoiceAuthMode(
+      storageRef(storage)?.getItem(CLOUD_VOICE_AUTH_STORAGE_KEY),
+    );
+  } catch {
+    return DEFAULT_CLOUD_VOICE_AUTH_MODE;
+  }
+}
+
+export function writeStoredCloudVoiceAuthMode(mode, storage) {
+  const resolved = normalizeCloudVoiceAuthMode(mode);
+  try {
+    storageRef(storage)?.setItem(CLOUD_VOICE_AUTH_STORAGE_KEY, resolved);
+  } catch {
+    /* best effort */
+  }
+  return resolved;
+}

src/voice/cloudVoiceAuth.test.mjs

@@ -0,0 +1,29 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import {
+  CLOUD_VOICE_AUTH_STORAGE_KEY,
+  readStoredCloudVoiceAuthMode,
+  writeStoredCloudVoiceAuthMode,
+} from './cloudVoiceAuth.js';
+
+function memoryStorage(seed = {}) {
+  const values = new Map(Object.entries(seed));
+  return {
+    getItem: (key) => values.get(key) ?? null,
+    setItem: (key, value) => values.set(key, value),
+  };
+}
+
+test('cloud voice auth defaults to API key and persists OAuth independently', () => {
+  const storage = memoryStorage();
+  assert.equal(readStoredCloudVoiceAuthMode(storage), 'api-key');
+  assert.equal(writeStoredCloudVoiceAuthMode('oauth', storage), 'oauth');
+  assert.equal(readStoredCloudVoiceAuthMode(storage), 'oauth');
+  assert.equal(writeStoredCloudVoiceAuthMode('unknown', storage), 'api-key');
+  assert.equal(
+    readStoredCloudVoiceAuthMode(
+      memoryStorage({ [CLOUD_VOICE_AUTH_STORAGE_KEY]: 'oauth' }),
+    ),
+    'oauth',
+  );
+});

src/voice/gevRealtime.test.mjs

@@ -3195,6 +3195,54 @@ test('F1: the toggle still records the next-session preference while live', () =
   assert.match(ui.tierButton.title, /this session stays on/i);
 });
 
+test('OAuth cloud sessions report unknown cost and usage without tripping the API spend guard', () => {
+  const { controller, ui } = costControllerHarness();
+  controller.status = 'listening';
+  controller._cost.cloudVoiceAuth = 'oauth';
+  controller._cost.sessionCloudVoiceAuth = 'oauth';
+  controller.syncCostUi();
+  const before = controller.costTracker.state();
+  assert.equal(ui.costValue.hidden, false);
+  assert.equal(ui.costValue.textContent, 'COST UNKNOWN');
+  assert.deepEqual(controller.recordUsage(usdUsage(100)), {
+    responses: 1,
+    input: 0,
+    output: 1562500,
+    captions: 0,
+    costKnown: false,
+  });
+  const after = controller.costTracker.state();
+  assert.equal(after.totalUsd, before.totalUsd);
+  assert.equal(controller.costCapStopped, false);
+  assert.match(ui.costValue.title, /1 response\(s\).*1562500 output tokens/);
+  controller.dc = {};
+  controller.responseActive = true;
+  controller.stop();
+  assert.match(ui.costValue.title, /Usage is incomplete/);
+});
+
+test('OAuth cloud sessions count caption transcriptions without pricing them into the API cap', () => {
+  const { controller, ui } = costControllerHarness();
+  controller.status = 'listening';
+  controller._cost.cloudVoiceAuth = 'oauth';
+  controller._cost.sessionCloudVoiceAuth = 'oauth';
+  controller._cost.bindTranscriptionModel('gpt-4o-mini-transcribe');
+  const before = controller.costTracker.state();
+  // Priced, this much caption audio would cross the $5 cap.
+  const result = controller.recordTranscriptionUsage({
+    type: 'duration',
+    seconds: 3_600_000,
+  });
+  assert.equal(result.captions, 1);
+  assert.equal(result.costKnown, false);
+  const after = controller.costTracker.state();
+  assert.equal(after.totalUsd, before.totalUsd);
+  assert.equal(after.capReached, false);
+  assert.equal(controller.costCapStopped, false);
+  assert.equal(ui.costValue.textContent, 'COST UNKNOWN');
+  assert.match(ui.costValue.title, /1 caption transcription\(s\)/);
+});
+
 test('F1: when idle, toggling does re-price the preview meter', () => {
   const { controller } = costControllerHarness();
   controller.status = 'idle';

src/voice/realtimeBackend.js

@@ -15,11 +15,19 @@ export function createRealtimeBackend({
     );
   return Object.freeze({
     protocol: 'openai-realtime',
-    async requestToken({ tier = DEFAULT_VOICE_TIER, signal } = {}) {
+    async requestToken({
+      tier = DEFAULT_VOICE_TIER,
+      authMode = 'api-key',
+      signal,
+    } = {}) {
       signal = scoped(signal);
       signal.throwIfAborted();
       const separator = tokenEndpoint.includes('?') ? '&' : '?';
-      const url = `${tokenEndpoint}${separator}tier=${encodeURIComponent(resolveVoiceModel(tier).tier)}`;
+      const query = new URLSearchParams({
+        tier: resolveVoiceModel(tier).tier,
+      });
+      if (authMode === 'oauth') query.set('auth', 'oauth');
+      const url = `${tokenEndpoint}${separator}${query}`;
       const response = await tokenTransport(url, {
         signal,
         cache: 'no-store',

src/voice/realtimeBackend.test.mjs

@@ -41,6 +41,22 @@ test('separate configured token and SDP transports preserve model metadata and c
   ]);
 });
 
+test('OAuth is an additive token query while API key stays the default', async () => {
+  const calls = [];
+  const backend = createRealtimeBackend({
+    tokenTransport: async (input) => {
+      calls.push(input);
+      return tokenReply();
+    },
+  });
+  await backend.requestToken();
+  await backend.requestToken({ authMode: 'oauth' });
+  assert.deepEqual(calls, [
+    '/api/realtime/token?tier=standard',
+    '/api/realtime/token?tier=standard&auth=oauth',
+  ]);
+});
+
 test('denied tokens never negotiate or retry; reconnect requests a fresh token', async () => {
   let requests = 0;
   const backend = createRealtimeBackend({

src/voice/realtimeConnection.js

@@ -82,6 +82,7 @@ export class RealtimeConnection {
     this.debugLog('session.starting', {
       epoch,
       tier: this.cost.voiceTier,
+      authMode: this.cost.sessionCloudVoiceAuth,
       connection: this.connectionDiagnostics(),
     });
     let localStream = null;
@@ -89,6 +90,7 @@ export class RealtimeConnection {
     try {
       const minted = await this.backend.requestToken({
         tier: this.cost.voiceTier,
+        authMode: this.cost.sessionCloudVoiceAuth,
         signal,
       });
       const token = minted.token;

src/voice/realtimeController.js

@@ -374,7 +374,10 @@ export class GevRealtimeController extends RealtimeFacade {
       status: this.status,
       connection: this.connectionDiagnostics(),
     });
-    if (this.dc && this.responseActive) this.costTracker.markIncomplete();
+    if (this.dc && this.responseActive) {
+      this.costTracker.markIncomplete();
+      this.syncCostUi();
+    }
     this._metrics.flush('stop');
     this._connection.closeTransport();
     this.stopVoiceVisualizer();

src/voice/realtimeCost.js

@@ -4,6 +4,7 @@ import {
   writeStoredVoiceTier,
   writeStoredVoiceLimits,
 } from './realtimePreferences.js';
+import { readStoredCloudVoiceAuthMode } from './cloudVoiceAuth.js';
 import {
   createVoiceCostTracker,
   resolveVoiceModel,
@@ -17,6 +18,9 @@ export class RealtimeCost {
     Object.assign(this, { readUi, readStatus }, operations);
     this.voiceTier = readStoredVoiceTier();
     this.voiceLimits = readStoredVoiceLimits();
+    this.cloudVoiceAuth = readStoredCloudVoiceAuthMode();
+    this.sessionCloudVoiceAuth = null;
+    this.oauthUsage = { responses: 0, input: 0, output: 0, captions: 0 };
     this.transcribeModel = null;
     this.costTracker = createVoiceCostTracker({
       tier: this.voiceTier,
@@ -58,6 +62,21 @@ export class RealtimeCost {
             }; applies next session`;
     }
     if (this.ui?.costValue) {
+      const liveAuth = this.sessionCloudVoiceAuth || this.cloudVoiceAuth;
+      if (liveAuth === 'oauth') {
+        const { responses, input, output, captions } = this.oauthUsage;
+        this.ui.costValue.hidden = false;
+        this.ui.costValue.textContent = 'COST UNKNOWN';
+        this.ui.costValue.dataset.level = 'unknown';
+        this.ui.costValue.title =
+          `ChatGPT OAuth session: ${responses} response(s), ${input} input and ${output} output tokens, ${captions} caption transcription(s) reported. ` +
+          'USD cost and the API spend cap are unavailable for this auth mode.' +
+          (state.incomplete
+            ? ' Usage is incomplete because a response was still in flight when the session ended.'
+            : '');
+        return;
+      }
+      this.ui.costValue.hidden = false;
       this.ui.costValue.textContent = state.display;
       this.ui.costValue.dataset.level = state.level;
       this.ui.costValue.title =
@@ -138,6 +157,15 @@ export class RealtimeCost {
    */
   recordUsage(usage) {
     if (!usage) return null;
+    if (this.sessionCloudVoiceAuth === 'oauth') {
+      const count = (value) =>
+        Number.isFinite(value) && value > 0 ? value : 0;
+      this.oauthUsage.responses += 1;
+      this.oauthUsage.input += count(usage.input_tokens);
+      this.oauthUsage.output += count(usage.output_tokens);
+      this.syncCostUi();
+      return { ...this.oauthUsage, costKnown: false };
+    }
     return this.applyCost(this.costTracker.record(usage));
   }
 
@@ -148,6 +176,13 @@ export class RealtimeCost {
    */
   recordTranscriptionUsage(usage) {
     if (!usage) return null;
+    // An OAuth session has no API-dollar meter, so captions are counted
+    // rather than priced into the API-key warning and cap.
+    if (this.sessionCloudVoiceAuth === 'oauth') {
+      this.oauthUsage.captions += 1;
+      this.syncCostUi();
+      return { ...this.oauthUsage, costKnown: false };
+    }
     return this.applyCost(
       this.costTracker.recordUsd(
         estimateTranscriptionCostUsd(usage, this.transcribeModel),
@@ -213,6 +248,9 @@ export class RealtimeCost {
   prepareSession() {
     this.voiceTier = readStoredVoiceTier();
     this.voiceLimits = readStoredVoiceLimits();
+    this.cloudVoiceAuth = readStoredCloudVoiceAuthMode();
+    this.sessionCloudVoiceAuth = this.cloudVoiceAuth;
+    this.oauthUsage = { responses: 0, input: 0, output: 0, captions: 0 };
     this.costCapStopped = false;
     // Provisional meter (tier-priced) so the readout shows $0.00 while
     // connecting. It is REPLACED below with one bound to the model the server