fix(street-level): sequence loads, playback and nearest-photo edge cases

From gekh's review of #768, each bug with a test that fails before:

- P2: a failed sequence load clears the previous sequence's cones, resets
  the selection and can be retried; a second click while loading starts no
  second lookup. sequences.js had no tests: sequences.test.mjs now covers
  failure and retry, a superseded late answer, the cache and clearSelection.
- P2: closing a photo stops MapillaryJS sequence playback, which kept the
  hidden viewer stepping and downloading images.
- openNearest without the panel reports it instead of loading forever, and
  stops if the layer (or its provider) went off during the lookup; the
  mesh sampler's misses are bounded and forgotten with its samples; the
  sequence count is the union of ids across tiles; a provider withdraws
  only its own error, so a sequence error cannot mask KEY REJECTED; hover
  stays on (throttled) under an orbiting camera and re-picks when it
  stops; "since N days" follows the clock in a long-open tab.
- A prewarm waits for one in flight and then builds if it gave up.
- New coverage for the layer core (credits, KEY REJECTED vs REQUIRED,
  switching a provider off), the refresh wiring of the tilted-view fix and
  the draped-to-cast swap completion.
- Cleanup: loading is derived from pending; freshStreet(); tile ranking
  computes distances once and shares one path for the date line; shared
  metresBetween / whenIdle / redrawTile; one NEAREST_RADIUS_M and one
  source method list; unused contract fields, exports, getImage and the
  decoder's image branch removed; PROVIDER_COLORS lists only Mapillary.

Co-Authored-By: Claude Opus 5.5 <[email protected]>

src/layers/streetLevel/index.test.mjs

@@ -1,57 +1,121 @@
 import assert from 'node:assert/strict';
 import test from 'node:test';
+import * as Cesium from 'cesium';
 import { createStreetLevelLayer } from './index.js';
+import { MAPILLARY_CREDIT_HTML } from './providers/mapillary/policy.js';
 
-/** The smallest provider the core accepts; nothing here touches a viewer. */
-function fakeProvider() {
+/**
+ * The smallest provider the core accepts. `stats` is what coverageStats()
+ * answers; `calls` counts what the core asked of the provider and its viewer.
+ */
+function fakeProvider({
+  id = 'mapillary',
+  pickPrefix = 'mly:',
+  html = MAPILLARY_CREDIT_HTML,
+  nearestImage = async () => null,
+} = {}) {
+  const calls = { activate: 0, deactivate: 0, mount: 0, open: [], unmount: 0 };
+  const stats = {
+    count: 0,
+    zoom: null,
+    kind: null,
+    loading: false,
+    hint: '',
+    error: null,
+    keyRequired: false,
+  };
+  let context = null;
   return {
-    id: 'mapillary',
+    calls,
+    stats,
+    context: () => context,
+    id,
     name: 'Mapillary',
     label: 'MAPILLARY',
     requiresKeyId: null,
-    pickPrefix: 'mly:',
+    pickPrefix,
     colors: { coverage: '#05cb63' },
-    credit: { key: 'mapillary', html: 'Mapillary' },
-    capabilities: {
-      coverage: 'tiles',
-      sequences: false,
-      pano: true,
-      capturedAt: true,
-      creator: true,
-      follow: true,
+    credit: { html },
+    create: (providerContext) => {
+      context = providerContext;
+      return {
+        status: async () => ({ configured: true }),
+        init() {},
+        activate: () => calls.activate++,
+        deactivate: () => calls.deactivate++,
+        destroy() {},
+        refreshCoverage() {},
+        setFilter() {},
+        coverageStats: () => ({ ...stats }),
+        handlePick: () => false,
+        nearestImage,
+        viewer: {
+          mount: async () => calls.mount++,
+          open: async (imageId) => calls.open.push(imageId),
+          close() {},
+          unmount: () => calls.unmount++,
+          resize() {},
+          onPose: () => () => {},
+        },
+      };
     },
-    externalUrl: (id) => `https://example.test/${id}`,
-    create: () => ({
-      status: async () => ({ configured: true }),
-      init() {},
-      activate() {},
-      deactivate() {},
-      destroy() {},
-      refreshCoverage() {},
-      setFilter() {},
-      coverageStats: () => ({
-        count: 0,
-        zoom: null,
-        kind: null,
-        loading: false,
-        hint: '',
-        error: null,
-        keyRequired: false,
-      }),
-      handlePick: () => false,
-      nearestImage: async () => null,
-      viewer: {
-        mount: async () => {},
-        open: async () => {},
-        close() {},
-        unmount() {},
-        resize() {},
-        onPose: () => () => {},
-      },
-    }),
   };
 }
 
+/**
+ * A stand-in Cesium viewer the layer can be enabled on: a canvas for the
+ * click handler, camera events, a primitive list and a credit display.
+ */
+function fakeViewer() {
+  const credits = [];
+  const canvas = Object.assign(new EventTarget(), {
+    style: {},
+    // Keep Cesium's handler on the canvas; there is no real document here.
+    disableRootEvents: true,
+    onwheel: null,
+  });
+  return {
+    credits,
+    scene: { canvas, primitives: { add: (p) => p, remove() {} } },
+    camera: {
+      changed: new Cesium.Event(),
+      moveStart: new Cesium.Event(),
+      moveEnd: new Cesium.Event(),
+    },
+    creditDisplay: {
+      addStaticCredit: (credit) => credits.push(credit),
+      removeStaticCredit: (credit) =>
+        credits.splice(credits.indexOf(credit), 1),
+    },
+  };
+}
+
+/** A layer over `providers`, initialised and enabled on a stand-in viewer. */
+async function enabledLayer(t, providers = [fakeProvider()]) {
+  const saved = globalThis.document;
+  globalThis.document = new EventTarget();
+  const viewer = fakeViewer();
+  const layer = createStreetLevelLayer({ providers });
+  layer.init(viewer);
+  layer.enable(viewer);
+  t.after(() => {
+    layer.destroy();
+    globalThis.document = saved;
+  });
+  await settle();
+  return { layer, viewer };
+}
+
+const settle = () => new Promise((resolve) => setTimeout(resolve, 0));
+
+function deferred() {
+  let resolve;
+  const promise = new Promise((done) => {
+    resolve = done;
+  });
+  return { promise, resolve };
+}
+
 /** A map stack controller that can be switched between stacks. */
 function fakeMapStack(initial) {
   let active = initial;
@@ -110,3 +174,113 @@ test('the layer lets go of the map stack when destroyed or re-attached', () => {
   layer.destroy();
   assert.equal(second.listenerCount(), 0);
 });
+
+test('the CC BY-SA credit shows while a provider is on and goes with it', async (t) => {
+  const { layer, viewer } = await enabledLayer(t);
+  const shown = () => viewer.credits.map((credit) => credit.html);
+  assert.deepEqual(shown(), [MAPILLARY_CREDIT_HTML], 'shown on activate');
+  assert.match(shown()[0], /CC BY-SA 4\.0/);
+  layer.setProviderEnabled('mapillary', false);
+  assert.deepEqual(shown(), [], 'hidden with the provider');
+  layer.setProviderEnabled('mapillary', true);
+  assert.deepEqual(shown(), [MAPILLARY_CREDIT_HTML]);
+  layer.disable();
+  assert.deepEqual(shown(), [], 'every credit goes with the layer');
+});
+
+test('getStats tells a rejected key from a missing one', async (t) => {
+  const provider = fakeProvider();
+  const { layer } = await enabledLayer(t, [provider]);
+  provider.stats.loading = true;
+  assert.equal(layer.getStats().loadingLabel, 'loading coverage...');
+  assert.equal(layer.getStats().keyRequired, false);
+
+  provider.stats.keyRequired = true;
+  assert.deepEqual(
+    [layer.getStats().loadingLabel, layer.getStats().error],
+    ['KEY REQUIRED', 'KEY REQUIRED'],
+  );
+
+  // A rejected key gates the provider exactly like a missing one.
+  provider.stats.keyRequired = false;
+  provider.stats.keyRejected = true;
+  provider.stats.error = 'Mapillary rejected MAPILLARY_CLIENT_TOKEN';
+  const stats = layer.getStats();
+  assert.equal(stats.keyRequired, true);
+  assert.equal(stats.loadingLabel, 'KEY REJECTED');
+  assert.equal(stats.error, 'Mapillary rejected MAPILLARY_CLIENT_TOKEN');
+  const ui = layer.getUIState();
+  assert.equal(ui.keyRequired, true);
+  assert.equal(ui.keyRejected, true);
+  assert.equal(ui.providers[0].keyRequired, true);
+});
+
+test('switching a provider off deactivates it and closes the image it shows', async (t) => {
+  const provider = fakeProvider();
+  const { layer } = await enabledLayer(t, [provider]);
+  layer.attachViewerHost({});
+  assert.equal(await layer.openImage('mapillary', 'img1'), true);
+  assert.deepEqual(provider.calls.open, ['img1']);
+  assert.equal(layer.getUIState().street.open, true);
+  layer.setProviderEnabled('mapillary', false);
+  assert.equal(provider.calls.deactivate, 1);
+  assert.equal(provider.calls.unmount, 1, 'its viewer is released');
+  assert.equal(layer.getUIState().street.open, false);
+  assert.equal(layer.getUIState().street.providerId, null);
+});
+
+test('openNearest without the panel reports it instead of loading forever (review P3)', async (t) => {
+  const provider = fakeProvider({ nearestImage: async () => 'img1' });
+  const { layer } = await enabledLayer(t, [provider]);
+  assert.equal(await layer.openNearest({ lat: 38.58, lon: -121.49 }), false);
+  const { street } = layer.getUIState();
+  assert.equal(street.loading, false);
+  assert.match(street.error, /Open the Street Level panel/);
+  assert.equal(provider.calls.mount, 0);
+});
+
+test('openNearest opens nothing once the layer went off during the lookup (review P3)', async (t) => {
+  const answer = deferred();
+  const provider = fakeProvider({ nearestImage: () => answer.promise });
+  const { layer } = await enabledLayer(t, [provider]);
+  layer.attachViewerHost({});
+  const opening = layer.openNearest({ lat: 38.58, lon: -121.49 });
+  layer.disable();
+  answer.resolve('img1');
+  assert.equal(await opening, false);
+  assert.equal(provider.calls.mount, 0, 'no viewer was stood up');
+  const { street } = layer.getUIState();
+  assert.equal(street.open, false);
+  assert.equal(street.loading, false);
+  assert.equal(street.error, null);
+});
+
+test('openNearest skips a provider switched off during its lookup (review P3)', async (t) => {
+  const answer = deferred();
+  const provider = fakeProvider({ nearestImage: () => answer.promise });
+  const { layer } = await enabledLayer(t, [provider]);
+  layer.attachViewerHost({});
+  const opening = layer.openNearest({ lat: 38.58, lon: -121.49 });
+  layer.setProviderEnabled('mapillary', false);
+  answer.resolve('img1');
+  assert.equal(await opening, false);
+  assert.deepEqual(provider.calls.open, []);
+  assert.equal(layer.getUIState().street.loading, false);
+});
+
+test('a provider withdraws only the error it reported (review P3)', async (t) => {
+  const provider = fakeProvider();
+  const { layer } = await enabledLayer(t, [provider]);
+  const { actions } = provider.context();
+  actions.reportError('Sequence images unavailable');
+  assert.equal(layer.getUIState().street.error, 'Sequence images unavailable');
+  actions.reportError(null);
+  assert.equal(layer.getUIState().street.error, null, 'withdrawn');
+
+  // The viewer's own error is not the provider's to clear.
+  layer.attachViewerHost(null);
+  actions.reportError('Sequence images unavailable');
+  await layer.openImage('mapillary', 'img1');
+  actions.reportError(null);
+  assert.match(layer.getUIState().street.error, /Open the Street Level panel/);
+});