Merge origin/main: Google Street View, KartaView and Panoramax on the slim Street Level

Main gained three imagery providers (Google Street View, KartaView,
Panoramax), shared line-coverage, cone and photo-viewer modules, one source
lit at a time and the translated interface. Their shared modules still
carried what this branch removes, so the merge ports them onto it:

- lineCoverage.js is this branch's coverage.js made provider-neutral
  (draped lines near the ground only, the selection drawn over them, key
  and rate-limit blocking); sequenceCones.js is sequences.js the same way.
  Mapillary, KartaView and Panoramax all build on them; Mapillary moves
  back to providers/mapillary/ beside the others.
- No ground casting, mesh sampling, surface modes, FOLLOW, legend, prewarm,
  orbit overview points (Panoramax's density dots included), stale-tile
  swaps or water-filled point budget come back.
- Kept from main because the new providers need them: requiresMapStack and
  attachMapStackController (Street View on Google 3D only), ground clicks,
  openNearest with an optional provider nearestImage, openImage {frame},
  reportError, the view-cone marker (now an SVG glyph), filters /
  coverageLabel / sinceBasis, OPEN STREET VIEW, keyAlternatives and i18n.
- photoViewer.js treats the viewer as expanded when its wrap is full screen
  or the iPhone popover, as EXPAND now is.
- The fixture browser gate keeps its 8 steps and adds one each for
  KartaView and Panoramax; catalogs, docs, boundaries and format scope
  follow.

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

src/layers/streetLevel/glyphs.js

@@ -1,4 +1,4 @@
-/** Billboard glyphs as SVG data URLs: the image cone, the 360° ring and the position marker. */
+/** Billboard glyphs as SVG data URLs: the image cone, the 360° ring and the position markers. */
 
 const px = (n) => Number(n.toFixed(2));
 
@@ -46,6 +46,16 @@ export function imageConeGlyph({
   );
 }
 
+/** Street View-style marker: a field-of-view cone from a white-ringed dot. */
+export function viewConeMarkerGlyph({ size = 56, color = '#4285f4' } = {}) {
+  return svg(
+    size,
+    wedge(size, size * 0.48, 0.62, color, 0.38) +
+      wedge(size, size * 0.3, 0.62, color, 0.3) +
+      dot(size, size * 0.13, color, '#ffffff', Math.max(2, size * 0.05)),
+  );
+}
+
 /** Marker for the image the viewer currently shows. */
 export function positionMarkerGlyph({ size = 44, color = '#ffb300' } = {}) {
   return svg(

src/layers/streetLevel/groundClick.js

@@ -0,0 +1,46 @@
+import * as Cesium from 'cesium';
+import { GROUND_CLICK_MAX_HEIGHT_M } from './policy.js';
+import { cameraHeightAboveGround } from './view.js';
+
+/** Whether the camera is low enough for a click on the ground to mean a street. */
+export function groundClickHeightOk(viewer) {
+  if (!viewer?.camera?.positionCartographic) return false;
+  return cameraHeightAboveGround(viewer) <= GROUND_CLICK_MAX_HEIGHT_M;
+}
+
+/**
+ * A click on the map itself at street zoom opens the nearest image of the
+ * active `groundClick` providers, without moving the camera. The height is
+ * measured at the click, not read from the cached flag.
+ * @param {{state: object, openNearest: Function, isAvailable: (entry: object) => boolean}} options
+ * @returns {(screenPosition: {x: number, y: number}, picked?: object) => Promise<boolean>|false}
+ */
+export function createGroundClick({ state, openNearest, isAvailable }) {
+  return function openAtGround(screenPosition, picked) {
+    const scenePick = state.services.scenePick;
+    if (!state.enabled || !state.viewer || !scenePick?.pickGroundPosition)
+      return false;
+    if (!scenePick.isSurfacePick(picked) || !groundClickHeightOk(state.viewer))
+      return false;
+    const providerIds = [...state.providers.values()]
+      .filter(
+        (entry) =>
+          entry.on &&
+          entry.def.groundClick &&
+          entry.status?.configured &&
+          isAvailable(entry),
+      )
+      .map((entry) => entry.def.id);
+    if (!providerIds.length) return false;
+    const position = scenePick.pickGroundPosition(state.viewer, screenPosition);
+    const carto = position && Cesium.Cartographic.fromCartesian(position);
+    if (!carto) return false;
+    return openNearest(
+      {
+        lon: Cesium.Math.toDegrees(carto.longitude),
+        lat: Cesium.Math.toDegrees(carto.latitude),
+      },
+      { providerIds, frame: false },
+    );
+  };
+}

src/layers/streetLevel/groundClick.test.mjs

@@ -0,0 +1,133 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import * as Cesium from 'cesium';
+import { createGroundClick, groundClickHeightOk } from './groundClick.js';
+import * as scenePick from '../../data/scenePick.js';
+
+const GROUND = Cesium.Cartesian3.fromDegrees(-121.4944, 38.5816, 10);
+const TILESET = { isCesium3DTileset: true };
+
+/**
+ * A layer state with providers `{id, on, groundClick, configured, available}`;
+ * `picked` is where the depth buffer lands, `ellipsoid` the fallback hit.
+ */
+function harness({
+  providers = [
+    { id: 'mapillary', groundClick: false },
+    { id: 'google', groundClick: true },
+  ],
+  height = 400,
+  enabled = true,
+  picked = GROUND,
+  ellipsoid = undefined,
+} = {}) {
+  const opened = [];
+  const state = {
+    enabled,
+    services: { scenePick },
+    providers: new Map(
+      providers.map(
+        ({
+          id,
+          on = true,
+          groundClick,
+          configured = true,
+          available = true,
+        }) => [
+          id,
+          { on, def: { id, groundClick }, status: { configured }, available },
+        ],
+      ),
+    ),
+    viewer: {
+      scene: { pickPositionSupported: true, pickPosition: () => picked },
+      camera: {
+        pickEllipsoid: () => ellipsoid,
+        positionCartographic: Cesium.Cartographic.fromDegrees(
+          -121.4944,
+          38.5816,
+          height,
+        ),
+      },
+    },
+  };
+  const openAtGround = createGroundClick({
+    state,
+    openNearest: (point, options) => {
+      opened.push({ point, options });
+      return Promise.resolve(true);
+    },
+    isAvailable: (entry) => entry.available,
+  });
+  return { opened, openAtGround };
+}
+
+const near = (point) =>
+  Math.abs(point.lon - -121.4944) < 1e-9 &&
+  Math.abs(point.lat - 38.5816) < 1e-9;
+
+test('a click on the map opens the click-to-open providers there, without moving the camera', () => {
+  for (const picked of [undefined, { primitive: TILESET }, { content: {} }]) {
+    const { opened, openAtGround } = harness();
+    openAtGround({ x: 10, y: 20 }, picked);
+    assert.equal(opened.length, 1, JSON.stringify(picked));
+    assert.ok(near(opened[0].point));
+    assert.deepEqual(opened[0].options, {
+      providerIds: ['google'],
+      frame: false,
+    });
+  }
+});
+
+test('where the depth buffer names no place, the ellipsoid answers', () => {
+  const { opened, openAtGround } = harness({
+    picked: new Cesium.Cartesian3(500, 0, 0),
+    ellipsoid: GROUND,
+  });
+  openAtGround({ x: 1, y: 1 });
+  assert.ok(near(opened[0].point));
+});
+
+test('nothing opens over another layer’s object, the sky, from high up, off its map stack, or with the provider off', () => {
+  const cases = [
+    { picked: { id: { id: 'flight:1' } }, label: 'an entity' },
+    { picked: { id: 'cctv:7', primitive: TILESET }, label: 'an id on a tile' },
+    { options: { picked: null, ellipsoid: undefined }, label: 'the sky' },
+    { options: { height: 5000 }, label: 'high up' },
+    {
+      options: {
+        providers: [{ id: 'google', groundClick: true, available: false }],
+      },
+      label: 'not Google 3D',
+    },
+    {
+      options: { providers: [{ id: 'google', groundClick: true, on: false }] },
+      label: 'off',
+    },
+    {
+      options: {
+        providers: [{ id: 'google', groundClick: true, configured: false }],
+      },
+      label: 'no key',
+    },
+    { options: { enabled: false }, label: 'layer off' },
+  ];
+  for (const { picked, options = {}, label } of cases) {
+    const { opened, openAtGround } = harness(options);
+    assert.equal(openAtGround({ x: 1, y: 1 }, picked), false, label);
+    assert.equal(opened.length, 0, label);
+  }
+});
+
+test('street zoom is measured above the ground under the camera', () => {
+  const viewer = (height) => ({
+    camera: {
+      positionCartographic: Cesium.Cartographic.fromDegrees(0, 0, height),
+    },
+    scene: { globe: { getHeight: () => 1500 } },
+  });
+  // 1,500 m up a plateau, 2,000 m above it: still a street.
+  assert.equal(groundClickHeightOk(viewer(3500)), true);
+  assert.equal(groundClickHeightOk(viewer(5000)), false);
+  assert.equal(groundClickHeightOk(null), false);
+});

src/layers/streetLevel/imageSize.js

@@ -0,0 +1,64 @@
+/**
+ * An image's pixel size read from its header, before anything decodes it:
+ * a picture host can serve a small file that declares enormous dimensions,
+ * and a decode of it alone can take the tab (or the GPU process) down.
+ * JPEG (SOFn), PNG (IHDR), WebP (VP8, VP8L, VP8X) and GIF; null for any
+ * other format, or a header this does not reach.
+ * @param {Uint8Array} bytes   The start of the file (a JPEG's EXIF can push its SOF past 64 kB).
+ * @returns {{width: number, height: number}|null}
+ */
+export function imageSize(bytes) {
+  if (!bytes || bytes.length < 12) return null;
+  const b = bytes;
+  const be16 = (i) => (b[i] << 8) | b[i + 1];
+  const le16 = (i) => b[i] | (b[i + 1] << 8);
+  const le24 = (i) => b[i] | (b[i + 1] << 8) | (b[i + 2] << 16);
+  const ascii = (i, text) =>
+    [...text].every((char, k) => b[i + k] === char.charCodeAt(0));
+  // JPEG: walk the markers to the first start-of-frame.
+  if (b[0] === 0xff && b[1] === 0xd8) {
+    let i = 2;
+    while (i + 9 < b.length) {
+      if (b[i] !== 0xff) return null;
+      const marker = b[i + 1];
+      // Fill bytes, and markers with no length.
+      if (marker === 0xff) {
+        i++;
+        continue;
+      }
+      if (marker === 0x01 || (marker >= 0xd0 && marker <= 0xd9)) {
+        i += 2;
+        continue;
+      }
+      const isFrame =
+        marker >= 0xc0 &&
+        marker <= 0xcf &&
+        marker !== 0xc4 &&
+        marker !== 0xc8 &&
+        marker !== 0xcc;
+      if (isFrame) return { width: be16(i + 7), height: be16(i + 5) };
+      i += 2 + be16(i + 2);
+    }
+    return null;
+  }
+  // PNG: IHDR is the first chunk.
+  if (b[0] === 0x89 && ascii(1, 'PNG') && ascii(12, 'IHDR')) {
+    const u32 = (i) =>
+      ((b[i] << 24) | (b[i + 1] << 16) | (b[i + 2] << 8) | b[i + 3]) >>> 0;
+    return { width: u32(16), height: u32(20) };
+  }
+  if (ascii(0, 'RIFF') && ascii(8, 'WEBP') && b.length >= 30) {
+    if (ascii(12, 'VP8 '))
+      return { width: le16(26) & 0x3fff, height: le16(28) & 0x3fff };
+    if (ascii(12, 'VP8L'))
+      return {
+        width: 1 + (((b[22] & 0x3f) << 8) | b[21]),
+        height:
+          1 + (((b[24] & 0x0f) << 10) | (b[23] << 2) | ((b[22] & 0xc0) >> 6)),
+      };
+    if (ascii(12, 'VP8X')) return { width: 1 + le24(24), height: 1 + le24(27) };
+    return null;
+  }
+  if (ascii(0, 'GIF8')) return { width: le16(6), height: le16(8) };
+  return null;
+}

src/layers/streetLevel/imageSize.test.mjs

@@ -0,0 +1,82 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import { imageSize } from './imageSize.js';
+
+const bytes = (...parts) =>
+  Uint8Array.from(
+    parts.flat().map((v) => (typeof v === 'string' ? v.charCodeAt(0) : v)),
+  );
+const ascii = (text) => [...text];
+
+test('a JPEG’s size is read from its first frame, past an EXIF segment', () => {
+  const exif = [0xff, 0xe1, 0x00, 0x10, ...new Array(14).fill(0)];
+  const sof = [0xff, 0xc0, 0x00, 0x11, 0x08, 0x0b, 0xc0, 0x0f, 0xc0];
+  const jpeg = bytes([0xff, 0xd8], exif, sof, new Array(20).fill(0));
+  assert.deepEqual(imageSize(jpeg), { width: 0x0fc0, height: 0x0bc0 });
+  // Progressive (SOF2) too; a DHT (C4) is not a frame.
+  const dht = [0xff, 0xc4, 0x00, 0x04, 0, 0];
+  const sof2 = [0xff, 0xc2, 0x00, 0x11, 0x08, 0x00, 0x10, 0x00, 0x20];
+  assert.deepEqual(
+    imageSize(bytes([0xff, 0xd8], dht, sof2, new Array(10).fill(0))),
+    {
+      width: 32,
+      height: 16,
+    },
+  );
+});
+
+test('PNG, WebP (lossy, lossless, extended) and GIF sizes', () => {
+  const png = bytes(
+    [0x89],
+    ascii('PNG'),
+    [0x0d, 0x0a, 0x1a, 0x0a, 0, 0, 0, 13],
+    ascii('IHDR'),
+    [0, 0, 0x10, 0, 0, 0, 0x08, 0],
+  );
+  assert.deepEqual(imageSize(png), { width: 4096, height: 2048 });
+  const riff = (chunk, rest) =>
+    bytes(ascii('RIFF'), [0, 0, 0, 0], ascii('WEBP'), ascii(chunk), rest);
+  const vp8 = riff('VP8 ', [...new Array(10).fill(0), 0x00, 0x08, 0x00, 0x04]);
+  assert.deepEqual(imageSize(vp8), { width: 2048, height: 1024 });
+  // VP8L: 14-bit width-1 and height-1 packed after the 0x2f signature.
+  const w = 99;
+  const h = 49;
+  const packed = w | (h << 14);
+  const vp8l = riff('VP8L', [
+    0,
+    0,
+    0,
+    0,
+    0x2f,
+    packed & 0xff,
+    (packed >> 8) & 0xff,
+    (packed >> 16) & 0xff,
+    (packed >> 24) & 0xff,
+    0,
+    0,
+    0,
+    0,
+    0,
+    0,
+  ]);
+  assert.deepEqual(imageSize(vp8l), { width: 100, height: 50 });
+  const vp8x = riff(
+    'VP8X',
+    [0, 0, 0, 0, 0, 0, 0, 0, 0xff, 0x0f, 0x00, 0xff, 0x07, 0x00],
+  );
+  assert.deepEqual(imageSize(vp8x), { width: 4096, height: 2048 });
+  const gif = bytes(ascii('GIF89a'), [0x40, 0x01, 0xf0, 0x00], [0, 0]);
+  assert.deepEqual(imageSize(gif), { width: 320, height: 240 });
+});
+
+test('anything else, or a header cut short, has no size', () => {
+  assert.equal(imageSize(null), null);
+  assert.equal(imageSize(new Uint8Array(4)), null);
+  assert.equal(imageSize(bytes(ascii('<html><body>'))), null);
+  assert.equal(
+    imageSize(
+      bytes([0xff, 0xd8, 0xff, 0xe1, 0xff, 0xff], new Array(8).fill(0)),
+    ),
+    null,
+  );
+});

src/layers/streetLevel/index.js

@@ -1,3 +1,4 @@
+import * as Cesium from 'cesium';
 import { createState } from './state.js';
 import { createMarker } from './marker.js';
 import { createCameraFraming } from './cameraFraming.js';
@@ -5,12 +6,21 @@ import { createCredits } from './credits.js';
 import { createPickRouter } from './pickRouter.js';
 import { createSelection } from './selection.js';
 import { createViewerHost } from './viewerHost.js';
-import { requiresKeyIdFor, validateProviders } from './registry.js';
+import { filtersOf, 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 {
+  composeUIState,
+  keyAlternatives,
+  summarizeCoverage,
+} from './uiState.js';
+import { viewCentre } from './view.js';
+import { createGroundClick, groundClickHeightOk } from './groundClick.js';
+import { msg, t, translateKnown } from '../../i18n/index.js';
+import {
+  AIM_AT_GROUND_MESSAGE,
   keyStatusLabel,
+  NEAREST_RADIUS_M,
   POSITION_PICK_ID,
   STREET_LEVEL_LAYER_ID,
 } from './policy.js';
@@ -23,8 +33,9 @@ const KEY_STATUS_TIMEOUT_MS = 10_000;
 /**
  * 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.
+ * host, the position marker, the click handler and nearest-image lookups.
+ * Providers own coverage, sequences and their viewer. One source is lit at
+ * a time.
  * @param {{providers: Array<import('./registry.js').StreetLevelProvider>, services?: object}} options
  */
 export function createStreetLevelLayer({
@@ -51,6 +62,11 @@ export function createStreetLevelLayer({
       entry.instance.clearSequence?.();
   };
   parts.selection = createSelection(context);
+  parts.openAtGround = createGroundClick({
+    state,
+    openNearest: (point, options) => layer.openNearest(point, options),
+    isAvailable: (entry) => providerAvailable(entry),
+  });
 
   let notifyQueued = false;
   function notify() {
@@ -79,24 +95,92 @@ export function createStreetLevelLayer({
       isActive: () => state.enabled && entry.on,
       notify,
       actions: {
-        openImage: (imageId) => openImage(entry.def.id, imageId),
+        /** `{frame: false}` opens it without moving the camera. */
+        openImage: (imageId, options) =>
+          openImage(entry.def.id, imageId, options),
+        /** This provider's image nearest a point the user picked on the map. */
+        openNearest: (point) =>
+          layer.openNearest(point, {
+            providerIds: [entry.def.id],
+            frame: false,
+          }),
+        /**
+         * Show a provider error, or withdraw it (null). A withdrawal clears
+         * only this provider's own error, never a newer one from elsewhere.
+         */
+        reportError: (message) => {
+          if (message) {
+            state.street.error = entry.reportedError = message;
+          } else {
+            if (!entry.reportedError) return;
+            if (state.street.error === entry.reportedError)
+              state.street.error = null;
+            entry.reportedError = null;
+          }
+          notify();
+        },
       },
     });
   }
 
+  // One source at a time: the first provider that defaults on.
+  const startsOn = defs.find((def) => def.defaultOn !== false);
   for (const def of defs) {
     const entry = {
       def,
       instance: null,
-      on: true,
+      on: def === startsOn,
       status: null,
       /** The status request in flight; overlapping checks share it. */
       statusCheck: null,
+      /** The error this provider last reported, until it withdraws it. */
+      reportedError: null,
     };
     entry.instance = def.create(providerContext(entry));
     state.providers.set(def.id, entry);
   }
 
+  let mapStack = null;
+  let unsubscribeMapStack = null;
+
+  /** Usable only on its map stack (Google's terms: Street View on Google 3D only). */
+  function providerAvailable(entry) {
+    const required = entry.def.requiresMapStack;
+    return !required || mapStack?.getActiveId?.() === required;
+  }
+
+  /** Leaving a provider's map stack closes its image, viewer and credit. */
+  function syncProviderAvailability() {
+    const owner = state.providers.get(state.street.providerId);
+    if (state.street.open && owner && !providerAvailable(owner))
+      layer.closeViewer();
+    for (const entry of state.providers.values()) {
+      if (!entry.def.requiresMapStack) continue;
+      if (state.enabled && entry.on && providerAvailable(entry))
+        parts.credits.show(state.viewer, entry.def);
+      else {
+        parts.credits.hide(state.viewer, entry.def);
+        parts.viewerHost.unmount(entry.def.id);
+      }
+    }
+    notify();
+  }
+
+  /** Whether a ground click can open an image: the camera is at street zoom. */
+  function syncGroundClickReady() {
+    const ready = state.enabled && groundClickHeightOk(state.viewer);
+    if (ready === state.groundClickReady) return;
+    state.groundClickReady = ready;
+    notify();
+  }
+
+  let removeCameraListener = null;
+  function watchCamera(viewer) {
+    removeCameraListener?.();
+    removeCameraListener =
+      viewer?.camera?.moveEnd?.addEventListener(syncGroundClickReady) || null;
+  }
+
   const activeEntries = () =>
     [...state.providers.values()].filter((entry) => entry.on);
 
@@ -120,10 +204,10 @@ export function createStreetLevelLayer({
   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 (entry.status?.configured !== true) checkStatus(entry);
+    if (providerAvailable(entry)) parts.credits.show(state.viewer, entry.def);
   }
 
   function deactivate(entry) {
@@ -132,24 +216,111 @@ export function createStreetLevelLayer({
     parts.credits.hide(state.viewer, entry.def);
   }
 
-  function openImage(providerId, imageId) {
-    return parts.viewerHost.open(providerId, imageId);
+  /** The nearest-image lookup in flight; any newer user action aborts it. */
+  let nearestLookup = null;
+
+  function abortNearest() {
+    nearestLookup?.abort();
+    nearestLookup = null;
   }
 
+  /** Ground under the screen centre; null for sky, undefined when it cannot aim. */
+  function screenCentreGround() {
+    const canvas = state.viewer?.scene?.canvas;
+    const pick = state.services.scenePick?.pickGroundPosition;
+    if (!pick || !canvas?.clientWidth || !canvas?.clientHeight)
+      return undefined;
+    const position = pick(state.viewer, {
+      x: canvas.clientWidth / 2,
+      y: canvas.clientHeight / 2,
+    });
+    const carto = position && Cesium.Cartographic.fromCartesian(position);
+    return carto
+      ? {
+          lon: Cesium.Math.toDegrees(carto.longitude),
+          lat: Cesium.Math.toDegrees(carto.latitude),
+        }
+      : null;
+  }
+
+  /** `frame: false` keeps the camera where it is (the user picked the spot). */
+  function openImage(providerId, imageId, { frame = true } = {}) {
+    abortNearest();
+    const entry = state.providers.get(providerId);
+    if (entry && !providerAvailable(entry)) {
+      state.street.loading = false;
+      state.street.error = unavailableReason(entry);
+      notify();
+      return Promise.resolve(false);
+    }
+    return parts.viewerHost.open(providerId, imageId, { frame });
+  }
+
+  function unavailableReason(entry) {
+    return t('{name} needs the Google 3D map: choose it under MAP SOURCE', {
+      name: translateKnown(entry.def.name),
+    });
+  }
+
+  /** One imagery source at a time: lighting a provider darkens the others. */
   function setProviderEnabled(providerId, on) {
     const entry = state.providers.get(providerId);
     if (!entry) return false;
+    const before = litIds();
     const next = on !== false;
-    if (entry.on === next) return true;
-    entry.on = next;
-    if (state.enabled) {
-      if (next) activate(entry);
-      else deactivate(entry);
-    }
+    if (next)
+      for (const other of state.providers.values())
+        if (other !== entry && other.on) switchProvider(other, false);
+    switchProvider(entry, next);
+    sourceChanged(before);
     notify();
     return true;
   }
 
+  const litIds = () =>
+    [...state.providers]
+      .filter(([, entry]) => entry.on)
+      .map(([id]) => id)
+      .join();
+
+  /**
+   * After a chip, voice or a link changed the lit source: a lookup still
+   * running and its spinner or error were about the source switched away
+   * (an open photo keeps its own state).
+   */
+  function sourceChanged(before) {
+    if (litIds() === before) return;
+    abortNearest();
+    if (state.street.open) return;
+    state.street.error = null;
+    state.street.loading = false;
+  }
+
+  function switchProvider(entry, on) {
+    if (entry.on === on) return;
+    entry.on = on;
+    if (!state.enabled) return;
+    if (on) activate(entry);
+    else deactivate(entry);
+  }
+
+  /**
+   * The one provider params leave lit: of those they switch on, the one
+   * already on (reapplying never flips), else the first; with none, the lit
+   * one unless they switch it off.
+   */
+  function litByParams(switches) {
+    const asked = [...state.providers.keys()].filter(
+      (id) => switches.get(id) === true,
+    );
+    const current = [...state.providers]
+      .filter(([, entry]) => entry.on)
+      .map(([id]) => id);
+    if (asked.length)
+      return asked.find((id) => current.includes(id)) ?? asked[0];
+    return current.find((id) => switches.get(id) !== false) ?? null;
+  }
+
   function setCoverageFilter(next) {
     const filter = normalizeFilter(next, state.filter);
     if (sameFilter(filter, state.filter)) return;
@@ -160,8 +331,21 @@ export function createStreetLevelLayer({
     notify();
   }
 
+  /** The hint a ground-click provider shows, or the provider's own. */
+  function hintFor(entry, stats) {
+    if (entry.def.groundClick && stats.hint && !state.groundClickReady)
+      return t('zoom in to a street to open {name}', {
+        name: translateKnown(entry.def.name),
+      });
+    return stats.hint || '';
+  }
+
+  /** Providers usable on this map stack; the others are not shown at all. */
+  const listedEntries = () =>
+    [...state.providers.values()].filter((entry) => providerAvailable(entry));
+
   function providerSnapshots() {
-    return [...state.providers.values()].map((entry) => {
+    return listedEntries().map((entry) => {
       const stats = entry.instance.coverageStats();
       return {
         id: entry.def.id,
@@ -175,9 +359,13 @@ export function createStreetLevelLayer({
         requiresKeyId: entry.def.requiresKeyId || null,
         loading: stats.loading === true,
         count: stats.count || 0,
-        hint: stats.hint || '',
+        hint: hintFor(entry, stats),
         error: stats.error || null,
         color: entry.def.colors.coverage,
+        coverageLabel: entry.def.coverageLabel || null,
+        sinceBasis: entry.def.sinceBasis === 'upload' ? 'upload' : 'capture',
+        groundClick: entry.def.groundClick === true,
+        filters: [...filtersOf(entry.def)],
       };
     });
   }
@@ -210,23 +398,40 @@ export function createStreetLevelLayer({
 
   function getUIState() {
     const { host, ...street } = state.street;
-    return composeUIState({
+    const ui = composeUIState({
       enabled: state.enabled,
+      groundClickReady: state.groundClickReady,
       filter: state.filter,
       providers: providerSnapshots(),
       street,
       sequence: sequenceSnapshot(),
     });
+    // The lit source cannot run on this map: say so, not a blank panel.
+    const stranded = [...state.providers.values()].find(
+      (entry) => entry.on && !providerAvailable(entry),
+    );
+    if (stranded && !ui.providers.some((p) => p.on))
+      ui.coverage.hint = unavailableReason(stranded);
+    return ui;
   }
 
   const layer = {
     id: STREET_LEVEL_LAYER_ID,
     name: 'Street Level',
     icon: '📷',
-    source: defs.map((def) => def.name).join(' · '),
+    /** The sources usable on this map (Street View only on Google 3D). */
+    get source() {
+      return listedEntries()
+        .map((entry) => entry.def.name)
+        .join(' · ');
+    },
     updateInterval: 0,
     statsRefreshInterval: 1000,
-    requiresKeyId: requiresKeyIdFor(defs),
+    /** The key the switched-on providers share (or null), for the layer row. */
+    get requiresKeyId() {
+      const on = activeEntries();
+      return requiresKeyIdFor(on.length ? on.map((entry) => entry.def) : defs);
+    },
     /** Registered providers, in chip order. */
     providerIds: defs.map((def) => def.id),
     getSourceAvailability() {
@@ -257,13 +462,19 @@ export function createStreetLevelLayer({
       parts.marker.setVisible(true);
       parts.selection.install(viewer);
       for (const entry of activeEntries()) activate(entry);
+      watchCamera(viewer);
+      syncGroundClickReady();
       notify();
     },
 
     disable() {
       state.enabled = false;
+      abortNearest();
+      removeCameraListener?.();
+      removeCameraListener = null;
       parts.viewerHost.unmount();
       for (const entry of state.providers.values()) entry.instance.deactivate();
+      syncGroundClickReady();
       parts.credits.hideAll(state.viewer);
       parts.selection.uninstall();
       parts.marker.setVisible(false);
@@ -280,24 +491,35 @@ export function createStreetLevelLayer({
         entry.instance.destroy(viewer);
       parts.marker.destroy(viewer);
       parts.framing.attachNavigation(null);
+      unsubscribeMapStack?.();
+      unsubscribeMapStack = null;
+      mapStack = null;
       state.listeners.clear();
       state.viewer = null;
     },
 
     getStats() {
       // The lifecycle polls this every second: summarise, don't snapshot.
-      const coverage = summarizeCoverage(providerSnapshots());
+      // English data: the layer panel translates these through translateKnown.
+      const snapshots = providerSnapshots();
+      const coverage = summarizeCoverage(snapshots);
       const keyLabel = keyStatusLabel(coverage);
       let loadingLabel = '';
       if (keyLabel) loadingLabel = keyLabel;
-      else if (coverage.loading) loadingLabel = 'loading coverage...';
+      else if (coverage.loading) loadingLabel = msg('loading coverage...');
       else if (coverage.hint && state.enabled) loadingLabel = coverage.hint;
       return {
+        source: layer.source,
         count: coverage.count,
         loading: coverage.loading,
         keyRequired: coverage.keyRequired,
+        keyAlternatives: keyAlternatives(snapshots),
         // A rejected key's message names the fix; a missing one says so.
-        error: keyLabel && !coverage.keyRejected ? keyLabel : coverage.error,
+        error: keyLabel
+          ? coverage.keyRejected
+            ? coverage.error || keyLabel
+            : keyLabel
+          : coverage.error,
         loadingLabel,
       };
     },
@@ -307,6 +529,15 @@ export function createStreetLevelLayer({
       parts.framing.attachNavigation(navigation);
     },
 
+    /** The application map stack; Street View is usable only on Google 3D. */
+    attachMapStackController(controller) {
+      unsubscribeMapStack?.();
+      mapStack = controller || null;
+      unsubscribeMapStack =
+        mapStack?.subscribe?.(syncProviderAvailability) || null;
+      syncProviderAvailability();
+    },
+
     /** Share-link and stored state: provider switches plus the filter. */
     getParams() {
       return encodeParams({
@@ -321,7 +552,13 @@ export function createStreetLevelLayer({
         providerIds: state.providers.keys(),
         filter: state.filter,
       });
-      for (const [id, on] of decoded.providers) setProviderEnabled(id, on);
+      const lit = litByParams(decoded.providers);
+      const before = litIds();
+      for (const [id, entry] of state.providers)
+        if (id !== lit) switchProvider(entry, false);
+      if (lit) switchProvider(state.providers.get(lit), true);
+      sourceChanged(before);
+      notify();
       setCoverageFilter(decoded.filter);
       return true;
     },
@@ -339,8 +576,89 @@ export function createStreetLevelLayer({
     },
     setProviderEnabled,
     openImage,
+    /**
+     * Open the nearest image of the active providers (or `providerIds`) near
+     * a point, else the view centre, or with `aim: 'screen-centre'` the ground
+     * under the screen centre (sky: nothing). Providers without
+     * `nearestImage` are skipped.
+     */
+    async openNearest(
+      point,
+      { providerIds = null, frame = true, aim = 'view' } = {},
+    ) {
+      let view = point;
+      if (!view && aim === 'screen-centre') {
+        view = screenCentreGround();
+        if (view === null) {
+          abortNearest();
+          state.street.loading = false;
+          state.street.error = AIM_AT_GROUND_MESSAGE;
+          notify();
+          return false;
+        }
+      }
+      view ||= viewCentre(state.viewer);
+      if (!Number.isFinite(view?.lat) || !Number.isFinite(view?.lon))
+        return false;
+      abortNearest();
+      const lookup = new AbortController();
+      nearestLookup = lookup;
+      const { signal } = lookup;
+      state.street.loading = true;
+      state.street.error = null;
+      notify();
+      let lastError = null;
+      const asked = (entry) =>
+        (!providerIds || providerIds.includes(entry.def.id)) &&
+        typeof entry.instance.nearestImage === 'function' &&
+        providerAvailable(entry);
+      const entries = activeEntries().filter(asked);
+      for (const entry of entries) {
+        let imageId = null;
+        try {
+          imageId = await entry.instance.nearestImage(
+            { lat: view.lat, lon: view.lon },
+            { signal },
+          );
+        } catch (error) {
+          // Overtaken: whatever replaced it owns the panel, errors included.
+          if (signal.aborted) return false;
+          // One provider failing (no key, offline) must not hide the others.
+          lastError = error;
+          continue;
+        }
+        if (signal.aborted) return false;
+        if (!state.enabled) break;
+        // Switched off, or its map left, while it looked: try the next.
+        if (!imageId || !entry.on || !providerAvailable(entry)) continue;
+        nearestLookup = null;
+        return openImage(entry.def.id, imageId, { frame });
+      }
+      if (nearestLookup === lookup) nearestLookup = null;
+      // Switched off while it looked: nothing to open, nothing to report.
+      const stillOn = entries.some(
+        (entry) => entry.on && providerAvailable(entry),
+      );
+      // A provider's own refusal is English data that the panel translates;
+      // the core's refusal is built here, for the panel only, in the language.
+      if (state.enabled && stillOn)
+        state.street.error =
+          lastError?.message ||
+          (point
+            ? t('No street-level imagery within {radius} m of that point', {
+                radius: NEAREST_RADIUS_M,
+              })
+            : t(
+                'No street-level imagery within {radius} m of the view centre',
+                { radius: NEAREST_RADIUS_M },
+              ));
+      state.street.loading = false;
+      notify();
+      return false;
+    },
     /** Close the image and deselect its sequence on the map. */
     closeViewer() {
+      abortNearest();
       parts.viewerHost.close();
       parts.clearSequences();
     },

src/layers/streetLevel/index.test.mjs

@@ -2,13 +2,16 @@ 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 { MAPILLARY_CREDIT_HTML } from './providers/mapillary/policy.js';
+import { createMapillaryProvider } from './providers/mapillary/index.js';
+import { createKartaViewProvider } from './providers/kartaview/index.js';
 import {
   fakeCesiumViewer,
   fakeMapillarySource,
   fakePhotoViewer,
+  fakeStreetLevelProvider as fakeProvider,
 } from '../../testSupport/streetLevelFakes.mjs';
+import { setLocale } from '../../i18n/index.js';
 
 /**
  * A layer over `source` and `photoViewer`, initialised on a stand-in viewer
@@ -299,3 +302,759 @@ test('an empty provider composition enables and tears down without acquiring ima
   layer.enable(viewer);
   assert.deepEqual(layer.getUIState().providers, []);
 });
+
+// ── Several providers: one source at a time, Google 3D, nearest lookups ──
+
+/**
+ * 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 = [];
+  /** Cesium's flight bookkeeping: a new flight cancels the current one. */
+  let flight = null;
+  const flights = { started: 0, cancelled: 0 };
+  const stopFlight = () => {
+    const current = flight;
+    flight = null;
+    current?.cancel?.();
+    return Boolean(current);
+  };
+  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,
+    flights,
+    scene: {
+      canvas,
+      primitives: { add: (p) => p, remove() {} },
+      // Enough of a scene for the position marker to clamp to the ground.
+      frameState: { mode: Cesium.SceneMode.SCENE3D },
+      updateHeight: () => () => {},
+      getHeight: () => undefined,
+    },
+    camera: {
+      changed: new Cesium.Event(),
+      moveStart: new Cesium.Event(),
+      moveEnd: new Cesium.Event(),
+      flyToBoundingSphere(sphere, options = {}) {
+        stopFlight();
+        flight = options;
+        flights.started++;
+      },
+      cancelFlight() {
+        if (stopFlight()) flights.cancelled++;
+      },
+    },
+    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;
+  // A pose moves the position marker, whose glyph is drawn on a canvas.
+  const drawing = new Proxy({}, { get: () => () => ({ addColorStop() {} }) });
+  globalThis.document = Object.assign(new EventTarget(), {
+    createElement: () => ({ getContext: () => drawing }),
+  });
+  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 };
+}
+
+function posingProvider(options) {
+  const provider = fakeProvider(options);
+  const create = provider.create;
+  provider.create = (context) => {
+    const instance = create(context);
+    let emit = null;
+    instance.viewer.onPose = (listener) => {
+      emit = listener;
+      return () => {
+        emit = null;
+      };
+    };
+    instance.viewer.open = async (imageId) => {
+      provider.calls.open.push(imageId);
+      emit?.({
+        providerId: 'mapillary',
+        imageId,
+        position: { lon: -121.49, lat: 38.58 },
+        bearing: 90,
+      });
+    };
+    return instance;
+  };
+  return provider;
+}
+
+/** nearestImage lookups that answer when the test says, with their signals. */
+function slowLookups() {
+  const lookups = [];
+  const nearestImage = (point, { signal } = {}) => {
+    const answer = deferred();
+    lookups.push({ point, signal, answer });
+    return answer.promise;
+  };
+  return { lookups, nearestImage };
+}
+
+/** A map stack controller that can be switched between stacks. */
+function fakeMapStack(initial) {
+  let active = initial;
+  const listeners = new Set();
+  return {
+    getActiveId: () => active,
+    subscribe(listener) {
+      listeners.add(listener);
+      return () => listeners.delete(listener);
+    },
+    switchTo(id) {
+      active = id;
+      for (const listener of listeners) listener();
+    },
+    listenerCount: () => listeners.size,
+  };
+}
+test('the layer lets go of the map stack when destroyed or re-attached', () => {
+  const layer = createStreetLevelLayer({ providers: [fakeProvider()] });
+  const first = fakeMapStack('photoreal');
+  layer.attachMapStackController(first);
+  assert.equal(first.listenerCount(), 1);
+  const second = fakeMapStack('photoreal');
+  layer.attachMapStackController(second);
+  assert.equal(first.listenerCount(), 0);
+  assert.equal(second.listenerCount(), 1);
+  layer.destroy();
+  assert.equal(second.listenerCount(), 0);
+});
+
+test('openNearest without the panel reports it instead of loading forever', 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', 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', 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', 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/);
+});
+test('an older nearest lookup that answers late cannot replace a newer one', async (t) => {
+  const { lookups, nearestImage } = slowLookups();
+  const provider = fakeProvider({ nearestImage });
+  const { layer } = await enabledLayer(t, [provider]);
+  layer.attachViewerHost({});
+  const older = layer.openNearest({ lat: 38.58, lon: -121.49 });
+  const newer = layer.openNearest({ lat: 38.59, lon: -121.48 });
+  lookups[1].answer.resolve('newer');
+  assert.equal(await newer, true);
+  lookups[0].answer.resolve('older');
+  assert.equal(await older, false);
+  assert.deepEqual(provider.calls.open, ['newer']);
+  assert.equal(lookups[0].signal?.aborted, true, 'its request was aborted');
+  assert.equal(lookups[1].signal?.aborted, false);
+});
+
+test('an image picked during a nearest lookup wins over its late answer', async (t) => {
+  const { lookups, nearestImage } = slowLookups();
+  const provider = fakeProvider({ nearestImage });
+  const { layer } = await enabledLayer(t, [provider]);
+  layer.attachViewerHost({});
+  const lookup = layer.openNearest({ lat: 38.58, lon: -121.49 });
+  // A cone click goes through the provider's openImage action.
+  assert.equal(await provider.context().actions.openImage('picked'), true);
+  lookups[0].answer.resolve('nearest');
+  assert.equal(await lookup, false);
+  assert.deepEqual(provider.calls.open, ['picked']);
+  assert.equal(lookups[0].signal?.aborted, true);
+});
+
+test('closing the viewer or switching the layer off retires a nearest lookup', async (t) => {
+  const { lookups, nearestImage } = slowLookups();
+  const provider = fakeProvider({ nearestImage });
+  const { layer, viewer } = await enabledLayer(t, [provider]);
+  layer.attachViewerHost({});
+
+  const closed = layer.openNearest({ lat: 38.58, lon: -121.49 });
+  layer.closeViewer();
+  // The aborted fetch rejects, as fetch does; that is not the user's error.
+  lookups[0].answer.reject(new DOMException('aborted', 'AbortError'));
+  assert.equal(await closed, false);
+  let { street } = layer.getUIState();
+  assert.deepEqual(
+    [street.open, street.loading, street.error],
+    [false, false, null],
+  );
+  assert.equal(lookups[0].signal?.aborted, true, 'closing aborts the request');
+
+  const disabled = layer.openNearest({ lat: 38.58, lon: -121.49 });
+  layer.disable();
+  layer.enable(viewer);
+  lookups[1].answer.resolve('img1');
+  assert.equal(await disabled, false, 'nor does it open once back on');
+  assert.deepEqual(provider.calls.open, []);
+  ({ street } = layer.getUIState());
+  assert.deepEqual(
+    [street.open, street.loading, street.error],
+    [false, false, null],
+  );
+  assert.equal(lookups[1].signal?.aborted, true, 'layer off aborts it too');
+});
+
+function initialisedLayer(t, providers) {
+  const saved = globalThis.document;
+  const drawing = new Proxy({}, { get: () => () => ({ addColorStop() {} }) });
+  globalThis.document = Object.assign(new EventTarget(), {
+    createElement: () => ({ getContext: () => drawing }),
+  });
+  const viewer = fakeViewer();
+  const layer = createStreetLevelLayer({ providers });
+  layer.init(viewer);
+  t.after(() => {
+    layer.destroy();
+    globalThis.document = saved;
+  });
+  return { layer, viewer };
+}
+
+test('switching a provider on while the layer is off activates nothing (M01)', async (t) => {
+  const provider = fakeProvider();
+  const prewarmed = [];
+  const create = provider.create;
+  provider.create = (context) => {
+    const instance = create(context);
+    instance.viewer.prewarm = async (host) => prewarmed.push(host);
+    return instance;
+  };
+  const { layer, viewer } = initialisedLayer(t, [provider]);
+  layer.attachViewerHost({});
+  layer.setProviderEnabled('mapillary', false);
+  layer.setProviderEnabled('mapillary', true);
+  layer.setParams({ mapillary: false });
+  layer.setParams({ mapillary: true });
+  await new Promise((resolve) => setTimeout(resolve, 40)); // past whenIdle
+  assert.equal(provider.calls.activate, 0, 'no coverage drawn');
+  assert.deepEqual(viewer.credits, [], 'no credit shown');
+  assert.deepEqual(prewarmed, [], 'no viewer stood up');
+  assert.equal(layer.getUIState().providers[0].on, true, 'the switch is kept');
+  // Enabling the layer is what activates it, once.
+  layer.enable(viewer);
+  assert.equal(provider.calls.activate, 1);
+  assert.equal(viewer.credits.length, 1);
+});
+
+/** The real Google provider over the Street View fakes, beside a Mapillary stand-in. */
+async function withStreetView(
+  t,
+  { mapStack = 'photoreal', nearest, mapillaryKeyless = false } = {},
+) {
+  const { createGoogleProvider } = await import('./providers/google/index.js');
+  const { fakeHost, fakeMapsLoader, fakeStreetViewLibrary } =
+    await import('../../testSupport/googleStreetViewFakes.mjs');
+  const fake = fakeStreetViewLibrary({
+    panoramas: {
+      'pano-a': { lat: 38.5816, lng: -121.4944, imageDate: '2024-05' },
+    },
+    nearest: nearest ?? (() => 'pano-a'),
+  });
+  const mapillaryLookups = [];
+  const mapillary = fakeProvider({
+    nearestImage: async (point) => {
+      mapillaryLookups.push(point);
+      return null;
+    },
+  });
+  mapillary.requiresKeyId = 'mapillary';
+  if (mapillaryKeyless) {
+    mapillary.stats.keyRequired = true;
+    const create = mapillary.create;
+    mapillary.create = (context) => ({
+      ...create(context),
+      status: async () => ({ configured: false }),
+    });
+  }
+  const loader = fakeMapsLoader(fake.library);
+  const google = createGoogleProvider({
+    getApiKey: () => 'browser-key',
+    loader,
+  });
+  const { layer, viewer } = await enabledLayer(t, [mapillary, google]);
+  const stack = fakeMapStack(mapStack);
+  layer.attachMapStackController(stack);
+  layer.attachViewerHost(fakeHost());
+  return { layer, viewer, stack, fake, loader, mapillaryLookups };
+}
+
+test('Street View starts off, and the layer row names the key of the providers that are on', async (t) => {
+  const { layer } = await withStreetView(t);
+  const google = () =>
+    layer.getUIState().providers.find((p) => p.id === 'google');
+  assert.equal(google().on, false);
+  assert.equal(layer.requiresKeyId, 'mapillary');
+  layer.setProviderEnabled('google', true);
+  assert.equal(layer.requiresKeyId, 'google-maps', 'Street View alone');
+});
+
+test('the layer starts with one source lit: the first that defaults on', async (t) => {
+  const { layer } = await enabledLayer(t, [
+    fakeProvider(),
+    fakeProvider({ id: 'panoramax', pickPrefix: 'pmx:' }),
+  ]);
+  assert.deepEqual(
+    layer
+      .getUIState()
+      .providers.filter((p) => p.on)
+      .map((p) => p.id),
+    ['mapillary'],
+  );
+});
+
+test('leaving Google 3D during a Street View lookup ends it without an error or a stuck spinner', async (t) => {
+  const { layer, stack, fake } = await withStreetView(t);
+  layer.setProviderEnabled('google', true);
+  let answer;
+  fake.library.StreetViewService.prototype.getPanorama = () =>
+    new Promise((resolve) => {
+      answer = resolve;
+    });
+  const opening = layer.openNearest({ lat: 38.5816, lon: -121.4944 });
+  await settle();
+  assert.equal(layer.getUIState().street.loading, true);
+  stack.switchTo('bing');
+  answer({ data: { location: { pano: 'pano-a' }, imageDate: '2024-05' } });
+  assert.equal(await opening, false);
+  const { street } = layer.getUIState();
+  assert.equal(street.loading, false, 'OPEN STREET VIEW is usable again');
+  assert.equal(street.error, null);
+  assert.equal(street.open, false);
+});
+
+test('a source swap during a lookup reports no false "no imagery"', async (t) => {
+  let answer;
+  const mapillary = fakeProvider({
+    nearestImage: () =>
+      new Promise((resolve) => {
+        answer = resolve;
+      }),
+  });
+  const other = fakeProvider({ id: 'panoramax', pickPrefix: 'pmx:' });
+  const { layer } = await enabledLayer(t, [mapillary, other]);
+  const opening = layer.openNearest({ lat: 1, lon: 2 });
+  layer.setProviderEnabled('panoramax', true);
+  answer('img-1');
+  assert.equal(await opening, false);
+  assert.equal(layer.getUIState().street.error, null);
+  assert.equal(layer.getUIState().street.loading, false);
+});
+
+test('Street View lit off Google 3D says why the panel is empty', async (t) => {
+  const { layer, stack } = await withStreetView(t);
+  layer.setProviderEnabled('google', true);
+  stack.switchTo('esri-imagery');
+  assert.match(
+    layer.getUIState().coverage.hint,
+    /Google Street View needs the Google 3D map/,
+  );
+  layer.setProviderEnabled('mapillary', true);
+  assert.doesNotMatch(layer.getUIState().coverage.hint, /Google 3D/);
+});
+
+test('one imagery source at a time: lighting one darkens the other, either way', async (t) => {
+  const { layer } = await withStreetView(t);
+  const lit = () =>
+    layer
+      .getUIState()
+      .providers.filter((p) => p.on)
+      .map((p) => p.id);
+  assert.deepEqual(lit(), ['mapillary'], 'Mapillary by default: it is free');
+  layer.setProviderEnabled('google', true);
+  assert.deepEqual(lit(), ['google']);
+  assert.equal(layer.getParams().mapillary, false);
+  layer.setProviderEnabled('mapillary', true);
+  assert.deepEqual(lit(), ['mapillary']);
+  assert.equal(layer.getParams().google, false);
+  // Params that light one switch to it; reapplying them changes nothing.
+  layer.setParams({ google: true });
+  assert.deepEqual(lit(), ['google']);
+  layer.setParams({ google: true });
+  assert.deepEqual(lit(), ['google']);
+  // Params lighting both keep the one already on, however often applied.
+  for (let i = 0; i < 2; i++) {
+    layer.setParams({ mapillary: true, providerSwitches: 'google-1' });
+    assert.deepEqual(lit(), ['google']);
+  }
+  layer.setParams({ mapillary: true, google: false });
+  assert.deepEqual(lit(), ['mapillary']);
+  // Filter-only params leave the source alone.
+  layer.setParams({ pano: 'pano' });
+  assert.deepEqual(lit(), ['mapillary']);
+  // Darkening the only lit one leaves none: the panel turns the layer off.
+  layer.setProviderEnabled('mapillary', false);
+  assert.deepEqual(lit(), []);
+});
+
+test('Street View appears only on the Google 3D map: chip, credit, source and images', async (t) => {
+  const { layer, viewer, stack } = await withStreetView(t, {
+    mapStack: 'esri-imagery',
+  });
+  layer.setProviderEnabled('google', true);
+  await settle();
+  const ui = () => layer.getUIState();
+  const listed = () => ui().providers.map((p) => p.id);
+  const credited = () =>
+    viewer.credits.some((credit) => /Street View imagery/.test(credit.html));
+  assert.deepEqual(listed(), ['mapillary'], 'no Street View chip');
+  assert.equal(credited(), false, 'no Google credit on another map');
+  assert.equal(layer.source, 'Mapillary');
+  assert.equal(layer.getStats().source, 'Mapillary');
+  assert.equal(await layer.openImage('google', 'pano-a'), false);
+  assert.match(ui().street.error, /needs the Google 3D map/);
+  assert.equal(layer.getParams().google, true, 'the choice is kept');
+
+  stack.switchTo('photoreal');
+  assert.deepEqual(listed(), ['mapillary', 'google']);
+  assert.equal(credited(), true);
+  assert.equal(layer.source, 'Mapillary · Google Street View');
+  assert.equal(await layer.openImage('google', 'pano-a'), true);
+  assert.equal(ui().street.providerId, 'google');
+
+  stack.switchTo('bing');
+  await settle();
+  assert.equal(ui().street.open, false, 'closed with the map');
+  assert.equal(credited(), false);
+  assert.deepEqual(listed(), ['mapillary']);
+});
+
+test('the UI state says when a click (or the button) can open Street View here', async (t) => {
+  const { layer } = await withStreetView(t);
+  assert.equal(typeof layer.getUIState().groundClickReady, 'boolean');
+});
+
+test('a lookup for the click-to-open providers asks only them and reports "that point"', async (t) => {
+  const { layer, mapillaryLookups } = await withStreetView(t, {
+    nearest: () => null,
+  });
+  layer.setProviderEnabled('google', true);
+  await settle();
+  const opened = await layer.openNearest(
+    { lat: 38.58, lon: -121.49 },
+    { providerIds: ['google'], frame: false },
+  );
+  assert.equal(opened, false);
+  assert.deepEqual(mapillaryLookups, [], 'Mapillary was not asked');
+  assert.equal(
+    layer.getUIState().street.error,
+    'No street-level imagery within 50 m of that point',
+  );
+});
+
+test('the nearest-image refusal is written in the language of the page', async (t) => {
+  const { layer } = await withStreetView(t, { nearest: () => null });
+  layer.setProviderEnabled('google', true);
+  await settle();
+  setLocale('es');
+  try {
+    await layer.openNearest(
+      { lat: 38.58, lon: -121.49 },
+      { providerIds: ['google'], frame: false },
+    );
+    const error = layer.getUIState().street.error;
+    assert.notEqual(error, 'No street-level imagery within 50 m of that point');
+    assert.match(error, /50/, 'keeps the radius');
+  } finally {
+    setLocale('en');
+  }
+});
+
+test('an image opened from a ground click leaves the camera where it is', async (t) => {
+  const { layer, viewer } = await withStreetView(t);
+  layer.setProviderEnabled('google', true);
+  await settle();
+  await layer.openNearest(
+    { lat: 38.58, lon: -121.49 },
+    { providerIds: ['google'], frame: false },
+  );
+  assert.equal(layer.getUIState().street.imageId, 'pano-a');
+  assert.equal(viewer.flights.started, 0, 'no framing flight');
+});
+
+test('off Google 3D not even Google\u2019s script is loaded for Street View', async (t) => {
+  const { layer, loader } = await withStreetView(t, {
+    mapStack: 'esri-imagery',
+  });
+  layer.setProviderEnabled('google', true);
+  layer.attachViewerHost({ ownerDocument: { createElement: () => ({}) } });
+  await new Promise((resolve) => setTimeout(resolve, 100));
+  assert.deepEqual(loader.imports, [], 'no prewarm, no lookup');
+});
+
+test('the button’s “centre of the view” is the ground under the middle of the screen', async (t) => {
+  const { createStreetLevelLayer: create } = await import('./index.js');
+  const scenePick = await import('../../data/scenePick.js');
+  const lookups = [];
+  const provider = fakeProvider({
+    nearestImage: async (point) => {
+      lookups.push(point);
+      return null;
+    },
+  });
+  const saved = globalThis.document;
+  const drawing = new Proxy({}, { get: () => () => ({ addColorStop() {} }) });
+  globalThis.document = Object.assign(new EventTarget(), {
+    createElement: () => ({ getContext: () => drawing }),
+  });
+  const viewer = fakeViewer();
+  const centre = Cesium.Cartesian3.fromDegrees(-121.4937, 38.5799, 0);
+  Object.assign(viewer.scene, {
+    pickPositionSupported: true,
+    pickPosition: (at) => (at.x === 500 && at.y === 300 ? centre : undefined),
+  });
+  viewer.scene.canvas.clientWidth = 1000;
+  viewer.scene.canvas.clientHeight = 600;
+  const layer = create({ providers: [provider], services: { scenePick } });
+  layer.init(viewer);
+  layer.enable(viewer);
+  t.after(() => {
+    layer.destroy();
+    globalThis.document = saved;
+  });
+  await layer.openNearest(undefined, { aim: 'screen-centre' });
+  assert.equal(lookups.length, 1);
+  assert.ok(Math.abs(lookups[0].lat - 38.5799) < 1e-9);
+  assert.ok(Math.abs(lookups[0].lon - -121.4937) < 1e-9);
+});
+
+test('the button aimed at the sky opens nothing, and says to aim at a street', async (t) => {
+  const { createStreetLevelLayer: create } = await import('./index.js');
+  const scenePick = await import('../../data/scenePick.js');
+  const lookups = [];
+  const provider = fakeProvider({
+    nearestImage: async (point) => {
+      lookups.push(point);
+      return null;
+    },
+  });
+  const saved = globalThis.document;
+  const drawing = new Proxy({}, { get: () => () => ({ addColorStop() {} }) });
+  globalThis.document = Object.assign(new EventTarget(), {
+    createElement: () => ({ getContext: () => drawing }),
+  });
+  const viewer = fakeViewer();
+  // Every ground pick misses: the middle of the screen is sky.
+  Object.assign(viewer.scene, {
+    pickPositionSupported: true,
+    pickPosition: () => undefined,
+  });
+  viewer.camera.pickEllipsoid = () => undefined;
+  viewer.scene.canvas.clientWidth = 1000;
+  viewer.scene.canvas.clientHeight = 600;
+  const layer = create({ providers: [provider], services: { scenePick } });
+  layer.init(viewer);
+  layer.enable(viewer);
+  t.after(() => {
+    layer.destroy();
+    globalThis.document = saved;
+  });
+  assert.equal(
+    await layer.openNearest(undefined, { aim: 'screen-centre' }),
+    false,
+  );
+  assert.deepEqual(lookups, [], 'no lookup at the view centre instead');
+  const { street } = layer.getUIState();
+  assert.match(street.error, /Aim the middle of the view at a street/);
+  assert.equal(street.loading, false);
+});
+
+test('with no Mapillary token, the layer points at Street View, on Google 3D only', async (t) => {
+  const { layer, stack } = await withStreetView(t, { mapillaryKeyless: true });
+  await settle();
+  const stats = layer.getStats();
+  assert.equal(stats.keyRequired, true);
+  assert.deepEqual(stats.keyAlternatives, [
+    { id: 'google', label: 'GOOGLE STREET VIEW', requiresKeyId: 'google-maps' },
+  ]);
+  assert.deepEqual(layer.getUIState().keyAlternatives, stats.keyAlternatives);
+  stack.switchTo('esri-imagery');
+  assert.deepEqual(layer.getStats().keyAlternatives, [], 'not off Google 3D');
+  // Lit, Street View draws: the layer is no longer key-gated.
+  stack.switchTo('photoreal');
+  layer.setProviderEnabled('google', true);
+  assert.equal(layer.getStats().keyRequired, false);
+});
+
+test('a failed lookup’s error goes when another source is lit; a provider can open an image without framing', async (t) => {
+  const failing = fakeProvider({
+    nearestImage: async () => {
+      throw new Error('KartaView did not answer in time — try again');
+    },
+  });
+  const other = fakeProvider({ id: 'other', pickPrefix: 'oth:' });
+  const { layer, viewer } = await enabledLayer(t, [failing, other]);
+  layer.attachViewerHost({});
+  await layer.openNearest({ lat: 1, lon: 1 });
+  assert.match(layer.getUIState().street.error, /did not answer/);
+  layer.setProviderEnabled('other', true);
+  await settle();
+  assert.equal(layer.getUIState().street.error, null);
+  // A provider's own open (KartaView's ‹ ›) can leave the camera alone.
+  await other.context().actions.openImage('img-1', { frame: false });
+  assert.deepEqual(other.calls.open, ['img-1']);
+  assert.equal(viewer.flights.started, 0);
+});
+
+test('a provider’s own open can leave the camera where it is; a default open frames', async (t) => {
+  const provider = posingProvider();
+  const { layer, viewer } = await enabledLayer(t, [provider]);
+  layer.attachViewerHost({});
+  await provider.context().actions.openImage('img-1', { frame: false });
+  assert.deepEqual(provider.calls.open, ['img-1']);
+  assert.equal(viewer.flights.started, 0, 'frame: false keeps the camera');
+  await provider.context().actions.openImage('img-2');
+  assert.equal(viewer.flights.started, 1, 'a default open frames the image');
+});
+
+test('a provider’s openNearest (a line click) asks only that provider and leaves the camera', async (t) => {
+  const lit = posingProvider({ nearestImage: async () => 'lit-near' });
+  const other = fakeProvider({
+    id: 'other',
+    pickPrefix: 'oth:',
+    nearestImage: async () => 'other-near',
+  });
+  const { layer, viewer } = await enabledLayer(t, [lit, other]);
+  layer.attachViewerHost({});
+  const point = { lat: 38.58, lon: -121.49 };
+  // The other source is off: its click asks nobody else.
+  await other.context().actions.openNearest(point);
+  await settle();
+  assert.deepEqual(lit.calls.open, [], 'the lit source was not asked');
+  assert.deepEqual(other.calls.open, []);
+  await lit.context().actions.openNearest(point);
+  assert.deepEqual(lit.calls.open, ['lit-near']);
+  assert.equal(viewer.flights.started, 0, 'the user picked the spot');
+});
+
+test('KartaView through the core: its lines counted as streets', async (t) => {
+  const kartaView = createKartaViewProvider({
+    source: {
+      getTile: async () => ({ lines: [] }),
+      nearestPhotos: async () => [],
+      getPhoto: async () => {
+        throw new Error('KartaView has no such photo');
+      },
+      getSequencePhotos: async () => ({ photos: [], hasMore: false }),
+      probeImage: async () => true,
+    },
+  });
+  const { layer } = await enabledLayer(t, [kartaView]);
+  layer.setProviderEnabled('kartaview', true);
+  await settle();
+  const ui = layer.getUIState();
+  assert.equal(ui.coverage.label?.noun, 'streets');
+});
+
+test('switching source by params (the chip path) stops a running lookup and clears its spinner and error', async (t) => {
+  const slow = slowLookups();
+  const looking = fakeProvider({ nearestImage: slow.nearestImage });
+  const other = fakeProvider({ id: 'other', pickPrefix: 'oth:' });
+  const { layer } = await enabledLayer(t, [looking, other]);
+  layer.attachViewerHost({});
+  const opening = layer.openNearest({ lat: 1, lon: 1 });
+  await settle();
+  assert.equal(layer.getUIState().street.loading, true);
+  layer.setParams({ mapillary: false, other: true });
+  assert.equal(slow.lookups[0].signal.aborted, true, 'the lookup is stopped');
+  assert.equal(
+    layer.getUIState().street.loading,
+    false,
+    'no spinner left behind',
+  );
+  // The stopped lookup answers late: nothing opens, nothing is reported.
+  slow.lookups[0].answer.resolve('img1');
+  assert.equal(await opening, false);
+  assert.deepEqual(looking.calls.open, []);
+  assert.equal(layer.getUIState().street.error, null);
+});
+
+test('switching source by params clears a failed lookup’s error; reapplying the same switches does not', async (t) => {
+  const failing = fakeProvider({
+    nearestImage: async () => {
+      throw new Error('KartaView did not answer in time — try again');
+    },
+  });
+  const { layer: second } = await enabledLayer(t, [
+    failing,
+    fakeProvider({ id: 'other', pickPrefix: 'oth:' }),
+  ]);
+  second.attachViewerHost({});
+  await second.openNearest({ lat: 1, lon: 1 });
+  assert.match(second.getUIState().street.error, /did not answer/);
+  second.setParams({ mapillary: false, other: true });
+  assert.equal(second.getUIState().street.error, null);
+  // Reapplying the same switches (a restore) leaves state alone.
+  await second.openNearest({ lat: 1, lon: 1 });
+  const kept = second.getUIState().street.error;
+  assert.match(kept, /No street-level imagery/);
+  second.setParams({ mapillary: false, other: true });
+  assert.equal(second.getUIState().street.error, kept);
+});

src/layers/streetLevel/limiter.js

@@ -0,0 +1,49 @@
+/**
+ * A gate letting at most `limit` tasks run at once, first in first out, or
+ * newest first with `lifo` (the last request is the one the user waits on).
+ */
+export function createLimiter(limit, { lifo = false } = {}) {
+  let running = 0;
+  const queue = [];
+  function next() {
+    while (running < limit && queue.length) {
+      const { task, resolve, reject, signal } = lifo
+        ? queue.pop()
+        : queue.shift();
+      if (signal?.aborted) {
+        reject(signal.reason);
+        continue;
+      }
+      running++;
+      Promise.resolve()
+        .then(task)
+        .then(resolve, reject)
+        .finally(() => {
+          running--;
+          next();
+        });
+    }
+  }
+  return {
+    run(task, { signal } = {}) {
+      return new Promise((resolve, reject) => {
+        const item = { task, resolve, reject, signal };
+        queue.push(item);
+        signal?.addEventListener(
+          'abort',
+          () => {
+            const at = queue.indexOf(item);
+            if (at === -1) return;
+            queue.splice(at, 1);
+            reject(signal.reason);
+          },
+          { once: true },
+        );
+        next();
+      });
+    },
+    get pending() {
+      return running + queue.length;
+    },
+  };
+}

src/layers/streetLevel/limiter.test.mjs

@@ -0,0 +1,84 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import { createLimiter } from './limiter.js';
+
+const tick = () => new Promise((resolve) => setTimeout(resolve, 0));
+
+/** A task that runs until `finish()`. */
+function held(log, name) {
+  let finish;
+  const done = new Promise((resolve) => (finish = resolve));
+  return {
+    task: () => {
+      log.push(name);
+      return done.then(() => name);
+    },
+    finish: () => finish(),
+  };
+}
+
+test('at most `limit` tasks run; queued ones start first in, first out', async () => {
+  const log = [];
+  const gate = createLimiter(2);
+  const tasks = ['a', 'b', 'c', 'd'].map((name) => held(log, name));
+  const results = tasks.map(({ task }) => gate.run(task));
+  await tick();
+  assert.deepEqual(log, ['a', 'b']);
+  assert.equal(gate.pending, 4);
+  tasks[0].finish();
+  await tick();
+  assert.deepEqual(log, ['a', 'b', 'c']);
+  for (const { finish } of tasks) finish();
+  assert.deepEqual(await Promise.all(results), ['a', 'b', 'c', 'd']);
+  assert.equal(gate.pending, 0);
+});
+
+test('lifo starts the newest queued task next', async () => {
+  const log = [];
+  const gate = createLimiter(1, { lifo: true });
+  const tasks = ['a', 'b', 'c'].map((name) => held(log, name));
+  const results = tasks.map(({ task }) => gate.run(task));
+  await tick();
+  tasks[0].finish();
+  await tick();
+  assert.deepEqual(log, ['a', 'c']);
+  tasks[2].finish();
+  tasks[1].finish();
+  await Promise.all(results);
+});
+
+test('a queued task whose signal aborts never runs, leaves the queue and rejects with the reason', async () => {
+  const log = [];
+  const gate = createLimiter(1);
+  const first = held(log, 'a');
+  const running = gate.run(first.task);
+  const controller = new AbortController();
+  const queued = gate.run(held(log, 'b').task, { signal: controller.signal });
+  await tick();
+  assert.equal(gate.pending, 2);
+  controller.abort(new Error('overtaken'));
+  await assert.rejects(queued, /overtaken/);
+  assert.equal(gate.pending, 1, 'out of the queue');
+  first.finish();
+  await running;
+  await tick();
+  assert.deepEqual(log, ['a'], 'b never ran');
+});
+
+test('a task already aborted when its turn comes is skipped', async () => {
+  const log = [];
+  const gate = createLimiter(1);
+  const first = held(log, 'a');
+  const running = gate.run(first.task);
+  const signal = {
+    aborted: false,
+    reason: new Error('gone'),
+    addEventListener() {},
+  };
+  const queued = gate.run(held(log, 'b').task, { signal });
+  signal.aborted = true;
+  first.finish();
+  await running;
+  await assert.rejects(queued, /gone/);
+  assert.deepEqual(log, ['a']);
+});

src/layers/streetLevel/lineCoverage.js

@@ -1,37 +1,57 @@
 import * as Cesium from 'cesium';
-import { decodeCoverageTile } from './decode.js';
 import { passesImageryFilter } from './filter.js';
 import { groundUnderCamera, viewFocus, visibleBbox } from './view.js';
-import { coverageZoomForHeight, tilesForBbox } from './tileMath.js';
-import {
-  COLORS,
-  COVERAGE_LINE_WIDTH_PX,
-  COVERAGE_MAX_SEQUENCES,
-  COVERAGE_MAX_TILES,
-  COVERAGE_MOVE_DEBOUNCE_MS,
-  KEY_REJECTED_MESSAGE,
-  PICK_PREFIX,
-  RATE_LIMITED_MESSAGE,
-  SEQUENCE_VIEW_RANGE_MIN_M,
-  SEQUENCE_VIEW_RANGE_PER_HEIGHT,
-} from './policy.js';
+import { tilesForBbox } from './tileMath.js';
+import { msg } from '../../i18n/index.js';
 
 /** Sequences per primitive: smaller batches build, and show, sooner. */
 const SEQUENCE_PRIMITIVE_BATCH = 120;
 
-const PER_TILE_SEQUENCE_CAP = Math.floor(
-  COVERAGE_MAX_SEQUENCES / COVERAGE_MAX_TILES,
+/** Hint above the street-zoom ceiling, where no coverage is drawn. */
+export const ZOOM_IN_HINT = msg('Zoom in to see street-level coverage');
+/** Hint when no ground is in view within range (looking at the sky). */
+const NO_GROUND_HINT = msg(
+  'Point the camera at the ground for street-level coverage',
 );
 
-/** Sequence id for a line's pick id (`mly:seq:<id>`), else null. */
-export function sequenceIdFromPick(pickId) {
-  if (typeof pickId !== 'string' || !pickId.startsWith(PICK_PREFIX.sequence))
+/** Sequence id for a line's pick id (`<prefix><id>`), else null. */
+export function sequenceIdFromPick(pickId, prefix) {
+  if (typeof pickId !== 'string' || !prefix || !pickId.startsWith(prefix))
     return null;
-  return pickId.slice(PICK_PREFIX.sequence.length);
+  return pickId.slice(prefix.length) || null;
+}
+
+/**
+ * A provider's coverage bookkeeping, before the first refresh. A provider
+ * with a key waits for its status (`blocked: 'status'`); a keyless one
+ * draws at once.
+ */
+export function freshCoverage({ keyless = false } = {}) {
+  return {
+    zoom: null,
+    /** Current zoom's tiles by `z/x/y` key. */
+    tiles: new Map(),
+    /** The selected sequence drawn over the coverage, or null. */
+    highlight: null,
+    /** Tile key → its request's controller; any entry means LOADING. */
+    pending: new Map(),
+    lastError: null,
+    /**
+     * Why tile requests are paused, or null: 'status' until the key status
+     * answers, 'no-key', 'rejected' (until the provider goes off) or
+     * 'rate-limited' (until `blockTimer` fires).
+     */
+    blocked: keyless ? null : 'status',
+    blockTimer: null,
+    debounceTimer: null,
+    removeCameraListener: null,
+    terrainReady: null,
+    hint: '',
+  };
 }
 
 /** Line instances for sequences' parts, every part picking its sequence. */
-function lineInstances(sequences, color, width) {
+function lineInstances(sequences, color, width, prefix) {
   const attributes = {
     color: Cesium.ColorGeometryInstanceAttribute.fromColor(color),
   };
@@ -48,7 +68,7 @@ function lineInstances(sequences, color, width) {
       instances.push(
         new Cesium.GeometryInstance({
           geometry: new Cesium.GroundPolylineGeometry({ positions, width }),
-          id: `${PICK_PREFIX.sequence}${sequence.id}`,
+          id: `${prefix}${sequence.id}`,
           attributes,
         }),
       );
@@ -67,21 +87,62 @@ function linePrimitive(geometryInstances, asynchronous) {
   });
 }
 
-/** Hint above the street-zoom ceiling, where no coverage is drawn. */
-export const ZOOM_IN_HINT = 'Zoom in to see street-level coverage';
-/** Hint when no ground is in view within range (looking at the sky). */
-const NO_GROUND_HINT =
-  'Point the camera at the ground for street-level coverage';
+function pointsOf(sequence) {
+  let count = 0;
+  for (const part of sequence.parts) count += part.length;
+  return count;
+}
 
 /**
- * Camera-driven coverage: Mapillary sequence lines (z11–14) near the ground,
- * draped on terrain and 3D tiles alike. Nothing is drawn from orbit.
+ * @typedef {object} LineCoverageTuning
+ * @property {number} maxTiles            Tiles drawn at once.
+ * @property {number} maxSequences        Lines drawn at once, over every tile.
+ * @property {number} [maxPoints]         Line points drawn at once, over every tile (default: no limit).
+ * @property {number} lineWidthPx
+ * @property {number} moveDebounceMs      Camera rest before the tile set is recomputed.
+ * @property {number} viewRangeMinM       Coverage reaches at least this far…
+ * @property {number} viewRangePerHeight  …or camera height times this.
+ * @property {boolean} [keepOrder]        Cap a tile's lines in the order decoded (default: newest first).
  */
-export function createCoverage({ state, source }) {
+
+/**
+ * Camera-driven sequence lines from any XYZ line-tile source, near the
+ * ground only, draped on terrain and 3D tiles alike. Nothing is drawn from
+ * orbit.
+ *
+ * @param {object} options
+ * @param {object} options.state  Provider state: `context`, `services`, `viewer`, `coverage` (freshCoverage), `sequence`.
+ * @param {(tile: {x: number, y: number, z: number}, init: {signal: AbortSignal}) => Promise<{sequences: Array<object>}>} options.fetchTile
+ *   A decoded tile; sequences are `{id, parts, capturedAt, isPano}`. A
+ *   rejection may carry `keyRequired`, `keyRejected` or `retryAfterSec`.
+ * @param {(heightM: number|null) => number|null} options.zoomFor
+ *   Tile zoom for a camera height above ground; null draws nothing.
+ * @param {{coverage: string, selected: string}} options.colors
+ * @param {string} options.pickPrefix   Pick-id prefix of the lines.
+ * @param {string} options.renderKey    Render-governor reason.
+ * @param {LineCoverageTuning} options.tuning
+ * @param {{keyRejected?: string, rateLimited: string, tooHigh?: string}} options.messages
+ * @param {(sequence: object, filter: object) => boolean} [options.passes]  Whether the imagery filter keeps a line.
+ */
+export function createLineCoverage({
+  state,
+  fetchTile,
+  zoomFor,
+  colors,
+  pickPrefix,
+  renderKey,
+  tuning,
+  messages,
+  passes = passesImageryFilter,
+}) {
   const { render } = state.services;
+  const perTileSequenceCap = Math.floor(tuning.maxSequences / tuning.maxTiles);
+  const perTilePointCap = tuning.maxPoints
+    ? Math.floor(tuning.maxPoints / tuning.maxTiles)
+    : Infinity;
 
   function requestRender() {
-    render?.governorRequestRender?.('mapillary-coverage');
+    render?.governorRequestRender?.(renderKey);
   }
 
   function ensureTerrainReady() {
@@ -95,19 +156,25 @@ export function createCoverage({ state, source }) {
 
   /** The imagery filter, resolved now: "since N days" moves with the clock. */
   function filter() {
-    return state.getFilter();
+    return state.context.getFilter();
   }
 
   /**
    * A tile's sequences, filtered then capped: capping first could leave a
-   * dense tile of newer flat captures with no 360° lines at all.
+   * dense tile of newer flat captures with no 360° lines at all. A line past
+   * the point budget is skipped; a shorter one may still fit.
    */
   function drawnSequences(entry) {
     const drawn = [];
     const current = filter();
+    let points = 0;
     for (const sequence of entry.sequenceList) {
-      if (drawn.length >= PER_TILE_SEQUENCE_CAP) break;
-      if (passesImageryFilter(sequence, current)) drawn.push(sequence);
+      if (drawn.length >= perTileSequenceCap) break;
+      if (!passes(sequence, current)) continue;
+      const size = pointsOf(sequence);
+      if (points + size > perTilePointCap) continue;
+      points += size;
+      drawn.push(sequence);
     }
     return drawn;
   }
@@ -116,8 +183,9 @@ export function createCoverage({ state, source }) {
   function buildSequencePrimitives(sequences) {
     const instances = lineInstances(
       sequences,
-      Cesium.Color.fromCssColorString(COLORS.coverage).withAlpha(0.92),
-      COVERAGE_LINE_WIDTH_PX,
+      Cesium.Color.fromCssColorString(colors.coverage).withAlpha(0.92),
+      tuning.lineWidthPx,
+      pickPrefix,
     );
     const primitives = [];
     for (let i = 0; i < instances.length; i += SEQUENCE_PRIMITIVE_BATCH)
@@ -144,8 +212,9 @@ export function createCoverage({ state, source }) {
       parts.push(...(entry.sequences.get(sequenceId)?.parts || []));
     const instances = lineInstances(
       [{ id: sequenceId, parts }],
-      Cesium.Color.fromCssColorString(COLORS.selected),
-      COVERAGE_LINE_WIDTH_PX + 1,
+      Cesium.Color.fromCssColorString(colors.selected),
+      tuning.lineWidthPx + 1,
+      pickPrefix,
     );
     if (!instances.length) return;
     state.coverage.highlight = scene.groundPrimitives.add(
@@ -194,14 +263,12 @@ export function createCoverage({ state, source }) {
     try {
       // Fetch and the one-time terrain-height table load run side by side,
       // both handled from the start so an early tile failure is not unhandled.
-      const [bytes] = await Promise.all([
-        source.getTile('coverage', tile.z, tile.x, tile.y, {
-          signal: controller.signal,
-        }),
+      const [decoded] = await Promise.all([
+        fetchTile(tile, { signal: controller.signal }),
         ensureTerrainReady(),
       ]);
       // Only an abort, a zoom change, a clear or a newer request for this tile
-      // discards the bytes; a refresh that still wants the tile keeps them.
+      // discards it; a refresh that still wants the tile keeps it.
       if (
         controller.signal.aborted ||
         state.coverage.pending.get(key) !== controller ||
@@ -209,12 +276,14 @@ export function createCoverage({ state, source }) {
         tile.z !== state.coverage.zoom
       )
         return;
-      const decoded = decodeCoverageTile(bytes, tile);
+      const sequences = decoded?.sequences || [];
       const entry = { primitives: [], sequences: new Map() };
-      // Newest first; the per-tile cap applies to what passes the filter.
-      entry.sequenceList = decoded.sequences.sort(
-        (a, b) => (b.capturedAt || 0) - (a.capturedAt || 0),
-      );
+      // Newest first, unless the provider ordered them itself; the per-tile
+      // cap applies to what passes the filter.
+      entry.sequenceList = tuning.keepOrder
+        ? sequences
+        : sequences.sort((a, b) => (b.capturedAt || 0) - (a.capturedAt || 0));
+      entry.total = sequences.length;
       attachPrimitive(entry);
       state.coverage.tiles.set(key, entry);
       state.coverage.lastError = null;
@@ -231,7 +300,9 @@ export function createCoverage({ state, source }) {
       if (error?.keyRejected) block('rejected');
       else if (error?.keyRequired) block('no-key');
       else if (error?.retryAfterSec) block('rate-limited', error.retryAfterSec);
-      else state.coverage.lastError = error?.message || 'Coverage tile failed';
+      else
+        state.coverage.lastError =
+          error?.message || msg('Coverage tile failed');
     } finally {
       // Only the request that still owns the key settles it: a superseded one
       // must not drop a newer request's entry (which is what counts as loading).
@@ -242,9 +313,10 @@ export function createCoverage({ state, source }) {
   }
 
   /**
-   * Pause tile requests (see `blocked` in state.js). A rate limit keeps what
-   * is drawn and refreshes once its wait is over; a key problem outranks it,
-   * and a rejected key holds until `unblock` (the layer goes off).
+   * Pause tile requests (see `blocked` in freshCoverage). A rate limit keeps
+   * what is drawn and refreshes once its wait is over; a key problem
+   * outranks it, and a rejected key holds until `unblock` (the provider goes
+   * off).
    */
   function block(reason, retryAfterSec = 0) {
     const current = state.coverage.blocked;
@@ -261,7 +333,7 @@ export function createCoverage({ state, source }) {
       }, retryAfterSec * 1000);
   }
 
-  /** The layer went off: forget refusals and errors, so the next run asks again. */
+  /** The provider went off: forget refusals and errors, so the next run asks again. */
   function unblock() {
     clearTimeout(state.coverage.blockTimer);
     state.coverage.blockTimer = null;
@@ -281,7 +353,7 @@ export function createCoverage({ state, source }) {
   }
 
   function notify() {
-    state.notify?.();
+    state.context.notify();
   }
 
   /**
@@ -294,15 +366,15 @@ export function createCoverage({ state, source }) {
     const height = Number.isFinite(cameraHeight)
       ? cameraHeight - (ground ?? 0)
       : null;
-    const zoom = coverageZoomForHeight(height);
-    if (zoom == null) return { hint: ZOOM_IN_HINT };
+    const zoom = zoomFor(height);
+    if (zoom == null) return { hint: messages.tooHigh || ZOOM_IN_HINT };
     // Rays meet the ground where it really is (1,600 m up in Denver) and stop
     // short of the horizon, which would stretch the box to the world.
     const ranged = {
       groundHeight: ground,
       maxRange: Math.max(
-        SEQUENCE_VIEW_RANGE_MIN_M,
-        height * SEQUENCE_VIEW_RANGE_PER_HEIGHT,
+        tuning.viewRangeMinM,
+        height * tuning.viewRangePerHeight,
       ),
     };
     const bbox = visibleBbox(viewer, ranged);
@@ -310,7 +382,7 @@ export function createCoverage({ state, source }) {
     // Ranked from between the camera's ground point and the screen centre's:
     // a tilted view's box centre can sit kilometres past both.
     const tiles = tilesForBbox(bbox, zoom, {
-      limit: COVERAGE_MAX_TILES,
+      limit: tuning.maxTiles,
       from: viewFocus(viewer, ranged),
     });
     return { zoom, tiles };
@@ -319,7 +391,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 || !state.isActive() || state.coverage.blocked) return;
+    if (!viewer || !state.context.isActive() || state.coverage.blocked) return;
     const { zoom, tiles, hint } = wantedTiles(viewer);
     if (hint) {
       state.coverage.hint = hint;
@@ -345,10 +417,7 @@ export function createCoverage({ state, source }) {
 
   function scheduleRefresh() {
     clearTimeout(state.coverage.debounceTimer);
-    state.coverage.debounceTimer = setTimeout(
-      refresh,
-      COVERAGE_MOVE_DEBOUNCE_MS,
-    );
+    state.coverage.debounceTimer = setTimeout(refresh, tuning.moveDebounceMs);
   }
 
   function attach(viewer) {
@@ -379,7 +448,7 @@ export function createCoverage({ state, source }) {
     requestRender();
   }
 
-  /** Rebuild every loaded tile from its decoded cache (after a filter change). */
+  /** Rebuild every loaded tile from its decoded lines (after a filter change). */
   function rebuild() {
     for (const entry of state.coverage.tiles.values()) {
       detachPrimitive(entry);
@@ -390,6 +459,12 @@ export function createCoverage({ state, source }) {
     notify();
   }
 
+  /** Load every tile again (a source that filters on its server had its filter changed). */
+  function reload() {
+    clear();
+    refresh();
+  }
+
   /**
    * Sequences drawn. A sequence that crosses a tile edge is in both tiles'
    * lists, so sequences count once by id.
@@ -409,15 +484,15 @@ 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' && state.isActive()),
+        (blocked === 'status' && state.context.isActive()),
       hint: state.coverage.hint,
       keyRequired: blocked === 'no-key' || blocked === 'rejected',
       keyRejected: blocked === 'rejected',
       error:
         blocked === 'rejected'
-          ? KEY_REJECTED_MESSAGE
+          ? messages.keyRejected || null
           : blocked === 'rate-limited'
-            ? RATE_LIMITED_MESSAGE
+            ? messages.rateLimited
             : state.coverage.lastError,
     };
   }
@@ -430,7 +505,9 @@ export function createCoverage({ state, source }) {
     unblock,
     setKeyStatus,
     rebuild,
+    reload,
     highlight,
+    sequenceCount,
     stats,
   };
 }

src/layers/streetLevel/lineCoverage.test.mjs

@@ -1,13 +1,52 @@
 import assert from 'node:assert/strict';
 import test from 'node:test';
 import * as Cesium from 'cesium';
-import { createCoverage, ZOOM_IN_HINT } from './coverage.js';
-import { freshCoverage } from './state.js';
+import {
+  createLineCoverage,
+  freshCoverage,
+  ZOOM_IN_HINT,
+} from './lineCoverage.js';
 import { resolveFilter } from './filter.js';
-import { encodeCoverageTile } from './coverageFixture.mjs';
+import { encodeCoverageTile } from './providers/mapillary/coverageFixture.mjs';
+import { decodeCoverageTile } from './providers/mapillary/decode.js';
 import { rayCamera } from '../../testSupport/streetLevelFakes.mjs';
-import { COVERAGE_MAX_SEQUENCES, COVERAGE_MAX_TILES } from './policy.js';
-import { lonToTileX, latToTileY, tileBounds } from './tileMath.js';
+import {
+  COLORS,
+  COVERAGE_TUNING,
+  KEY_REJECTED_MESSAGE,
+  PICK_PREFIX,
+  RATE_LIMITED_MESSAGE,
+} from './providers/mapillary/policy.js';
+import {
+  coverageZoomForHeight,
+  lonToTileX,
+  latToTileY,
+  tileBounds,
+} from './tileMath.js';
+
+const { maxSequences: COVERAGE_MAX_SEQUENCES, maxTiles: COVERAGE_MAX_TILES } =
+  COVERAGE_TUNING;
+
+/** Line coverage as the Mapillary provider builds it, over `source`. */
+function createCoverage({ state, source }) {
+  return createLineCoverage({
+    state,
+    fetchTile: async (tile, { signal }) =>
+      decodeCoverageTile(
+        await source.getTile('coverage', tile.z, tile.x, tile.y, { signal }),
+        tile,
+      ),
+    zoomFor: coverageZoomForHeight,
+    colors: COLORS,
+    pickPrefix: PICK_PREFIX.sequence,
+    renderKey: 'mapillary-coverage',
+    tuning: COVERAGE_TUNING,
+    messages: {
+      keyRejected: KEY_REJECTED_MESSAGE,
+      rateLimited: RATE_LIMITED_MESSAGE,
+    },
+  });
+}
 
 const RAD = Math.PI / 180;
 // Node has no WebGL context to report line-width limits; a browser's
@@ -94,9 +133,11 @@ function setup() {
     enabled: true,
     providerOn: true,
     filter: { pano: 'all', sinceDays: 0 },
-    getFilter: () => resolveFilter(state.filter),
-    isActive: () => state.enabled && state.providerOn,
-    notify() {},
+    context: {
+      getFilter: () => resolveFilter(state.filter),
+      isActive: () => state.enabled && state.providerOn,
+      notify() {},
+    },
     coverage: {
       ...freshCoverage(),
       // The key status is in; skip Cesium's one-time terrain table download.

src/layers/streetLevel/marker.js

@@ -1,10 +1,26 @@
 import * as Cesium from 'cesium';
-import { positionMarkerGlyph } from './glyphs.js';
+import { positionMarkerGlyph, viewConeMarkerGlyph } from './glyphs.js';
 import { COLORS, POSITION_PICK_ID } from './policy.js';
 import { createHorizonCull } from './view.js';
 
 const SPRITE_ID = 'street-level:marker';
 
+function markerLook(style) {
+  if (style?.kind === 'view-cone') {
+    const color = style.color || COLORS.position;
+    return {
+      key: `view-cone:${color}`,
+      image: viewConeMarkerGlyph({ color }),
+      size: 48,
+    };
+  }
+  return {
+    key: 'pin',
+    image: positionMarkerGlyph({ color: COLORS.position }),
+    size: 40,
+  };
+}
+
 /** On-globe marker for the open image, clamped to the ground. */
 export function createMarker({ state }) {
   const { render, sprites } = state.services;
@@ -29,8 +45,8 @@ export function createMarker({ state }) {
     sprites?.registerSpriteCollection?.(SPRITE_ID, state.marker.collection);
   }
 
-  /** Move (or create) the marker; a null position removes it. */
-  function set(position, bearing) {
+  /** Move (or create) the marker; null removes it. `style`: the provider's `marker`. */
+  function set(position, bearing, style = null) {
     const collection = state.marker.collection;
     if (!collection) return;
     if (!position) {
@@ -41,14 +57,20 @@ export function createMarker({ state }) {
       return;
     }
     const cartesian = Cesium.Cartesian3.fromDegrees(position.lon, position.lat);
+    const look = markerLook(style);
+    if (state.marker.billboard && state.marker.look !== look.key) {
+      collection.remove?.(state.marker.billboard);
+      state.marker.billboard = null;
+    }
     if (!state.marker.billboard) {
+      state.marker.look = look.key;
       state.marker.billboard = collection.add({
         id: POSITION_PICK_ID,
         position: cartesian,
-        image: positionMarkerGlyph({ color: COLORS.position }),
-        imageId: 'sl-position',
-        width: 40,
-        height: 40,
+        image: look.image,
+        imageId: `sl-position:${look.key}`,
+        width: look.size,
+        height: look.size,
         alignedAxis: Cesium.Cartesian3.UNIT_Z,
         heightReference: Cesium.HeightReference.CLAMP_TO_GROUND,
         disableDepthTestDistance: Number.POSITIVE_INFINITY,

src/layers/streetLevel/marker.test.mjs

@@ -31,6 +31,7 @@ function setup() {
       collection: {
         show: true,
         add: (options) => ({ ...options }),
+        remove() {},
         removeAll() {},
       },
       billboard: null,
@@ -87,3 +88,25 @@ test('the marker is clamped to the ground and turned to the bearing', () => {
   assert.ok(Math.abs(Cesium.Math.toDegrees(placed.longitude) + 121.5) < 1e-9);
   assert.equal(billboard.rotation, -Cesium.Math.toRadians(90));
 });
+
+test('a Street View photo gets a blue view cone; a Mapillary photo GEV\u2019s pin', () => {
+  const { state, marker } = setup();
+  const removed = [];
+  state.marker.collection.remove = (billboard) => removed.push(billboard);
+  const streetView = { kind: 'view-cone', color: '#4285f4' };
+  marker.set({ lon: -121.49, lat: 38.58 }, 45, streetView);
+  const cone = state.marker.billboard;
+  assert.equal(cone.imageId, 'sl-position:view-cone:#4285f4');
+  assert.equal(
+    cone.rotation,
+    -Cesium.Math.toRadians(45),
+    'it turns with the view',
+  );
+  // Dragging the panorama keeps the look and the billboard.
+  marker.set({ lon: -121.49, lat: 38.58 }, 90, streetView);
+  assert.equal(state.marker.billboard, cone);
+  // A Mapillary photo next (its provider has no marker): the pin.
+  marker.set({ lon: -121.49, lat: 38.58 }, 90, undefined);
+  assert.equal(state.marker.billboard.imageId, 'sl-position:pin');
+  assert.deepEqual(removed, [cone]);
+});

src/layers/streetLevel/panorama.js

@@ -0,0 +1,245 @@
+/**
+ * A minimal equirectangular panorama renderer on WebGL: one full-screen
+ * triangle whose fragment shader turns each pixel's view ray into texture
+ * coordinates. The image centre is the camera's forward direction; yaw turns
+ * right from it, pitch looks up.
+ */
+
+export const PANO_FOV_DEFAULT_DEG = 80;
+export const PANO_FOV_MIN_DEG = 30;
+export const PANO_FOV_MAX_DEG = 100;
+export const PANO_PITCH_LIMIT_DEG = 85;
+
+const VERTEX = `
+attribute vec2 a_position;
+varying vec2 v_ndc;
+void main() {
+  v_ndc = a_position;
+  gl_Position = vec4(a_position, 0.0, 1.0);
+}`;
+
+const FRAGMENT = `
+precision highp float;
+uniform sampler2D u_image;
+uniform float u_yaw;
+uniform float u_pitch;
+uniform float u_tanHalfFov;
+uniform float u_aspect;
+varying vec2 v_ndc;
+const float PI = 3.141592653589793;
+void main() {
+  vec3 ray = normalize(vec3(v_ndc.x * u_tanHalfFov * u_aspect, v_ndc.y * u_tanHalfFov, -1.0));
+  float cp = cos(u_pitch), sp = sin(u_pitch);
+  ray = vec3(ray.x, ray.y * cp - ray.z * sp, ray.y * sp + ray.z * cp);
+  float cy = cos(u_yaw), sy = sin(u_yaw);
+  ray = vec3(ray.x * cy - ray.z * sy, ray.y, ray.x * sy + ray.z * cy);
+  float lon = atan(ray.x, -ray.z);
+  float lat = asin(clamp(ray.y, -1.0, 1.0));
+  gl_FragColor = texture2D(u_image, vec2(0.5 + lon / (2.0 * PI), 0.5 - lat / PI));
+}`;
+
+/** Wrap degrees into [0, 360). */
+export function wrapDegrees(value) {
+  return ((value % 360) + 360) % 360;
+}
+
+export function clampPitch(degrees) {
+  return Math.max(
+    -PANO_PITCH_LIMIT_DEG,
+    Math.min(PANO_PITCH_LIMIT_DEG, degrees),
+  );
+}
+
+export function clampFov(degrees) {
+  return Math.max(PANO_FOV_MIN_DEG, Math.min(PANO_FOV_MAX_DEG, degrees));
+}
+
+/**
+ * Texture coordinates the shader samples for a view ray, for tests and
+ * picking: `yaw`/`pitch` in degrees, the ray in camera space (x right, y up,
+ * z backward).
+ */
+export function rayToUv(ray, { yaw = 0, pitch = 0 } = {}) {
+  const p = (pitch * Math.PI) / 180;
+  const w = (yaw * Math.PI) / 180;
+  const length = Math.hypot(ray[0], ray[1], ray[2]) || 1;
+  let [x, y, z] = ray.map((v) => v / length);
+  [y, z] = [
+    y * Math.cos(p) - z * Math.sin(p),
+    y * Math.sin(p) + z * Math.cos(p),
+  ];
+  [x, z] = [
+    x * Math.cos(w) - z * Math.sin(w),
+    x * Math.sin(w) + z * Math.cos(w),
+  ];
+  const lon = Math.atan2(x, -z);
+  const lat = Math.asin(Math.max(-1, Math.min(1, y)));
+  return [0.5 + lon / (2 * Math.PI), 0.5 - lat / Math.PI];
+}
+
+function compile(gl, type, source) {
+  const shader = gl.createShader(type);
+  gl.shaderSource(shader, source);
+  gl.compileShader(shader);
+  if (!gl.getShaderParameter(shader, gl.COMPILE_STATUS)) {
+    const log = gl.getShaderInfoLog(shader);
+    gl.deleteShader(shader);
+    throw new Error(`Panorama shader failed: ${log}`);
+  }
+  return shader;
+}
+
+const isPowerOfTwo = (n) => n > 0 && (n & (n - 1)) === 0;
+
+/**
+ * A panorama view on `canvas`. Throws when WebGL is unavailable, so the
+ * caller can fall back to a flat picture.
+ * @param {HTMLCanvasElement} canvas
+ * @returns {{setImage: (image: TexImageSource) => void, setView: (view: {yaw?: number, pitch?: number, fov?: number}) => void, getView: () => {yaw: number, pitch: number, fov: number}, resize: () => void, render: () => void, hasImage: () => boolean, destroy: () => void}}
+ */
+export function createPanoramaRenderer(canvas) {
+  const gl =
+    canvas.getContext('webgl', {
+      antialias: false,
+      depth: false,
+      preserveDrawingBuffer: false,
+    }) || canvas.getContext('experimental-webgl');
+  if (!gl) throw new Error('WebGL is unavailable');
+
+  const program = gl.createProgram();
+  gl.attachShader(program, compile(gl, gl.VERTEX_SHADER, VERTEX));
+  gl.attachShader(program, compile(gl, gl.FRAGMENT_SHADER, FRAGMENT));
+  gl.linkProgram(program);
+  if (!gl.getProgramParameter(program, gl.LINK_STATUS))
+    throw new Error('Panorama program failed to link');
+  gl.useProgram(program);
+
+  const buffer = gl.createBuffer();
+  gl.bindBuffer(gl.ARRAY_BUFFER, buffer);
+  // One triangle covering the screen.
+  gl.bufferData(
+    gl.ARRAY_BUFFER,
+    new Float32Array([-1, -1, 3, -1, -1, 3]),
+    gl.STATIC_DRAW,
+  );
+  const position = gl.getAttribLocation(program, 'a_position');
+  gl.enableVertexAttribArray(position);
+  gl.vertexAttribPointer(position, 2, gl.FLOAT, false, 0, 0);
+  const uniforms = Object.fromEntries(
+    ['u_image', 'u_yaw', 'u_pitch', 'u_tanHalfFov', 'u_aspect'].map((name) => [
+      name,
+      gl.getUniformLocation(program, name),
+    ]),
+  );
+  const texture = gl.createTexture();
+  let loaded = false;
+  let frame = 0;
+  const view = { yaw: 0, pitch: 0, fov: PANO_FOV_DEFAULT_DEG };
+
+  /** Match the drawing buffer to the canvas's laid-out size. */
+  function syncSize() {
+    const ratio = Math.min(globalThis.devicePixelRatio || 1, 2);
+    const width = Math.max(1, Math.round(canvas.clientWidth * ratio));
+    const height = Math.max(1, Math.round(canvas.clientHeight * ratio));
+    if (canvas.width !== width || canvas.height !== height) {
+      canvas.width = width;
+      canvas.height = height;
+    }
+  }
+
+  function resize() {
+    syncSize();
+    scheduleRender();
+  }
+
+  function draw() {
+    frame = 0;
+    if (gl.isContextLost()) return;
+    // Every frame: the canvas may have been laid out since the last one.
+    syncSize();
+    gl.viewport(0, 0, canvas.width, canvas.height);
+    gl.clearColor(0, 0, 0, 1);
+    gl.clear(gl.COLOR_BUFFER_BIT);
+    if (!loaded) return;
+    gl.uniform1i(uniforms.u_image, 0);
+    gl.uniform1f(uniforms.u_yaw, (view.yaw * Math.PI) / 180);
+    gl.uniform1f(uniforms.u_pitch, (view.pitch * Math.PI) / 180);
+    gl.uniform1f(uniforms.u_tanHalfFov, Math.tan((view.fov * Math.PI) / 360));
+    gl.uniform1f(uniforms.u_aspect, canvas.width / Math.max(1, canvas.height));
+    gl.drawArrays(gl.TRIANGLES, 0, 3);
+  }
+
+  function scheduleRender() {
+    if (frame) return;
+    frame = requestAnimationFrame(draw);
+  }
+
+  return {
+    setImage(image) {
+      gl.activeTexture(gl.TEXTURE0);
+      gl.bindTexture(gl.TEXTURE_2D, texture);
+      gl.pixelStorei(gl.UNPACK_FLIP_Y_WEBGL, false);
+      // RGBA: the format a decoded ImageBitmap uploads without conversion.
+      gl.texImage2D(
+        gl.TEXTURE_2D,
+        0,
+        gl.RGBA,
+        gl.RGBA,
+        gl.UNSIGNED_BYTE,
+        image,
+      );
+      // Read before the close: a closed bitmap measures 0×0.
+      const { width, height } = image;
+      // The pixels are on the GPU now; a bitmap's copy can go.
+      image.close?.();
+      // Linear only: a mipmapped lookup draws a seam where longitude wraps.
+      gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MIN_FILTER, gl.LINEAR);
+      gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MAG_FILTER, gl.LINEAR);
+      const repeat =
+        isPowerOfTwo(width) && isPowerOfTwo(height)
+          ? gl.REPEAT
+          : gl.CLAMP_TO_EDGE;
+      gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_S, repeat);
+      gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_T, gl.CLAMP_TO_EDGE);
+      loaded = true;
+      resize();
+      scheduleRender();
+    },
+    setView(next = {}) {
+      if (Number.isFinite(next.yaw)) view.yaw = wrapDegrees(next.yaw);
+      if (Number.isFinite(next.pitch)) view.pitch = clampPitch(next.pitch);
+      if (Number.isFinite(next.fov)) view.fov = clampFov(next.fov);
+      scheduleRender();
+    },
+    getView: () => ({ ...view }),
+    resize,
+    render: scheduleRender,
+    hasImage: () => loaded,
+    clear() {
+      loaded = false;
+      // Hand the 32 MB texture back: a closed viewer keeps only 1×1.
+      gl.bindTexture(gl.TEXTURE_2D, texture);
+      gl.texImage2D(
+        gl.TEXTURE_2D,
+        0,
+        gl.RGBA,
+        1,
+        1,
+        0,
+        gl.RGBA,
+        gl.UNSIGNED_BYTE,
+        new Uint8Array(4),
+      );
+      scheduleRender();
+    },
+    destroy() {
+      if (frame) cancelAnimationFrame(frame);
+      frame = 0;
+      loaded = false;
+      gl.deleteTexture(texture);
+      gl.deleteBuffer(buffer);
+      gl.deleteProgram(program);
+      gl.getExtension('WEBGL_lose_context')?.loseContext();
+    },
+  };
+}

src/layers/streetLevel/panorama.test.mjs

@@ -0,0 +1,199 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import {
+  PANO_FOV_MAX_DEG,
+  PANO_FOV_MIN_DEG,
+  PANO_PITCH_LIMIT_DEG,
+  clampFov,
+  clampPitch,
+  createPanoramaRenderer,
+  rayToUv,
+  wrapDegrees,
+} from './panorama.js';
+
+const close = (actual, expected) =>
+  actual.forEach((value, i) =>
+    assert.ok(Math.abs(value - expected[i]) < 1e-9, `${actual} ≉ ${expected}`),
+  );
+
+test('straight ahead samples the image centre; yaw turns right, pitch looks up', () => {
+  close(rayToUv([0, 0, -1]), [0.5, 0.5]);
+  close(rayToUv([0, 0, -1], { yaw: 90 }), [0.75, 0.5]);
+  close(rayToUv([0, 0, -1], { yaw: -90 }), [0.25, 0.5]);
+  close(rayToUv([0, 0, -1], { pitch: 45 }), [0.5, 0.25]);
+  close(rayToUv([0, 0, -1], { pitch: -90 }), [0.5, 1]);
+  // Pitch first, then yaw: looking up-right stays up.
+  close(rayToUv([0, 0, -1], { yaw: 90, pitch: 45 }), [0.75, 0.25]);
+  // A ray to the right of the screen is the same as turning right.
+  close(rayToUv([1, 0, 0]), [0.75, 0.5]);
+});
+
+test('view limits: pitch stops short of the poles, field of view stays usable', () => {
+  assert.equal(clampPitch(120), PANO_PITCH_LIMIT_DEG);
+  assert.equal(clampPitch(-120), -PANO_PITCH_LIMIT_DEG);
+  assert.equal(clampFov(5), PANO_FOV_MIN_DEG);
+  assert.equal(clampFov(170), PANO_FOV_MAX_DEG);
+  assert.equal(wrapDegrees(-30), 330);
+  assert.equal(wrapDegrees(725), 5);
+});
+
+/**
+ * A WebGL stand-in that records draw calls and uniform values; `lost` makes
+ * it report a lost context.
+ */
+function stubGl() {
+  const gl = {
+    lost: false,
+    calls: [],
+    uniforms: {},
+    isContextLost: () => gl.lost,
+    getShaderParameter: () => true,
+    getProgramParameter: () => true,
+    getUniformLocation: (program, name) => name,
+    getExtension: () => null,
+    uniform1f: (name, value) => (gl.uniforms[name] = value),
+  };
+  return new Proxy(gl, {
+    get(target, key) {
+      if (key in target) return target[key];
+      if (typeof key === 'string' && /^[A-Z_0-9]+$/.test(key)) return key;
+      return (...args) => {
+        target.calls.push(key);
+        return { key, args };
+      };
+    },
+  });
+}
+
+/** A panorama on a stub canvas, with frames run when the test says. */
+function stubPanorama(t, { width = 400, height = 250 } = {}) {
+  const gl = stubGl();
+  const canvas = {
+    clientWidth: width,
+    clientHeight: height,
+    width: 300,
+    height: 150,
+    getContext: () => gl,
+  };
+  const frames = [];
+  const saved = {
+    request: globalThis.requestAnimationFrame,
+    cancel: globalThis.cancelAnimationFrame,
+  };
+  globalThis.requestAnimationFrame = (callback) => frames.push(callback);
+  globalThis.cancelAnimationFrame = () => {};
+  t.after(() => {
+    globalThis.requestAnimationFrame = saved.request;
+    globalThis.cancelAnimationFrame = saved.cancel;
+  });
+  const renderer = createPanoramaRenderer(canvas);
+  const runFrames = () => {
+    while (frames.length) frames.shift()();
+  };
+  return { gl, canvas, renderer, runFrames };
+}
+
+const IMAGE = { width: 1024, height: 512 };
+
+test('a panorama draws once it has an image; looking up and right are positive angles', (t) => {
+  const { gl, renderer, runFrames } = stubPanorama(t);
+  renderer.render();
+  runFrames();
+  assert.equal(gl.calls.includes('drawArrays'), false, 'nothing to draw yet');
+  renderer.setImage(IMAGE);
+  renderer.setView({ yaw: 30, pitch: 30 });
+  runFrames();
+  assert.ok(gl.calls.includes('drawArrays'));
+  assert.ok(gl.uniforms.u_pitch > 0, `u_pitch ${gl.uniforms.u_pitch}`);
+  assert.ok(Math.abs(gl.uniforms.u_pitch - Math.PI / 6) < 1e-9);
+  assert.ok(Math.abs(gl.uniforms.u_yaw - Math.PI / 6) < 1e-9);
+  renderer.setView({ pitch: -20 });
+  runFrames();
+  assert.ok(gl.uniforms.u_pitch < 0, 'looking down is negative');
+});
+
+test('a lost WebGL context draws nothing', (t) => {
+  const { gl, renderer, runFrames } = stubPanorama(t);
+  renderer.setImage(IMAGE);
+  gl.lost = true;
+  gl.calls.length = 0;
+  runFrames();
+  assert.deepEqual(
+    gl.calls.filter((call) =>
+      ['viewport', 'clear', 'drawArrays'].includes(call),
+    ),
+    [],
+  );
+});
+
+test('the canvas is measured again when it draws, not only when its image arrived', (t) => {
+  // The image arrives while the canvas is still hidden (0×0)…
+  const { canvas, renderer, runFrames } = stubPanorama(t, {
+    width: 0,
+    height: 0,
+  });
+  renderer.setImage(IMAGE);
+  assert.deepEqual([canvas.width, canvas.height], [1, 1]);
+  // …and is laid out before the frame draws.
+  canvas.clientWidth = 400;
+  canvas.clientHeight = 250;
+  runFrames();
+  assert.deepEqual([canvas.width, canvas.height], [400, 250]);
+});
+
+test('an image uploads as RGBA and its bitmap is released; closing hands the texture back as 1×1', (t) => {
+  const { gl, renderer } = stubPanorama(t);
+  const uploads = [];
+  gl.texImage2D = (...args) => uploads.push(args);
+  let closed = false;
+  renderer.setImage({
+    width: 2048,
+    height: 1024,
+    close: () => (closed = true),
+  });
+  assert.equal(uploads.length, 1);
+  assert.equal(
+    uploads[0][2],
+    'RGBA',
+    'the format a decoded bitmap uploads without conversion',
+  );
+  assert.equal(closed, true, 'the decoded copy is freed once on the GPU');
+  renderer.clear();
+  const last = uploads.at(-1);
+  assert.deepEqual(
+    [last[3], last[4]],
+    [1, 1],
+    'a closed viewer keeps a 1×1 texture',
+  );
+  assert.equal(renderer.hasImage(), false);
+});
+
+test('a power-of-two bitmap wraps in longitude even though it is closed once uploaded', (t) => {
+  const { gl, renderer } = stubPanorama(t);
+  const wraps = [];
+  gl.texParameteri = (target, name, value) => wraps.push([name, value]);
+  gl.TEXTURE_WRAP_S = 'WRAP_S';
+  gl.REPEAT = 'REPEAT';
+  gl.CLAMP_TO_EDGE = 'CLAMP';
+  const bitmap = {
+    width: 2048,
+    height: 1024,
+    // A closed ImageBitmap measures 0×0.
+    close() {
+      this.width = 0;
+      this.height = 0;
+    },
+  };
+  renderer.setImage(bitmap);
+  assert.deepEqual(
+    wraps.find(([name]) => name === 'WRAP_S'),
+    ['WRAP_S', 'REPEAT'],
+  );
+  wraps.length = 0;
+  renderer.setImage({ width: 2000, height: 1000 });
+  assert.deepEqual(
+    wraps.find(([name]) => name === 'WRAP_S'),
+    ['WRAP_S', 'CLAMP'],
+    'other sizes clamp (WebGL 1 repeats powers of two only)',
+  );
+});

src/layers/streetLevel/photoViewer.js

@@ -0,0 +1,935 @@
+import {
+  createPanoramaRenderer,
+  PANO_FOV_DEFAULT_DEG,
+  wrapDegrees,
+} from './panorama.js';
+import { imageSize } from './imageSize.js';
+import { msg, t } from '../../i18n/index.js';
+
+/** A photo download (tens of kilobytes to a few megabytes). */
+/** EXPAND puts the viewer's wrap full screen, or (iPhone) opens it as a popover. */
+const EXPANDED_SELECTOR =
+  '.sl-viewer-wrap:fullscreen, .sl-viewer-wrap:popover-open';
+
+export const IMAGE_TIMEOUT_MS = 15_000;
+
+/** A picture file or decoded side past these is refused (a photo is a few MB). */
+export const MAX_IMAGE_BYTES = 48 * 1024 * 1024;
+export const MAX_IMAGE_SIDE = 16_384;
+/** 64 MP: 256 MB once decoded to RGBA. A 16,384 px square is four times that. */
+export const MAX_IMAGE_PIXELS = 8_192 * 8_192;
+/** Where in a file to look for its dimensions (a JPEG's EXIF comes first). */
+const HEADER_BYTES = 256 * 1024;
+
+/** Whether a picture this size is past what the viewer decodes. */
+export function tooManyPixels(width, height) {
+  return (
+    width > MAX_IMAGE_SIDE ||
+    height > MAX_IMAGE_SIDE ||
+    width * height > MAX_IMAGE_PIXELS
+  );
+}
+
+/** Panorama texture widths: enough for a docked viewer, and for an expanded one. */
+export const PANO_MID_SIZE = Object.freeze([2048, 1024]);
+export const PANO_FULL_SIZE = Object.freeze([4096, 2048]);
+
+/**
+ * Load an image within the timeout. A CORS-clean one (for WebGL) is decoded
+ * off the main thread into an ImageBitmap where the browser can: uploading
+ * a decoded bitmap costs a fraction of uploading an <img> (90 ms → 15 ms for
+ * 4096×2048 on a phone-class CPU). `resize` shrinks a bitmap while decoding
+ * it (a panorama larger than any texture the viewer uploads).
+ * @param {string} url
+ * @param {{crossOrigin?: boolean, timeoutMs?: number, resize?: [number, number]|null, failure?: string}} [options]
+ */
+export function loadImage(
+  url,
+  {
+    crossOrigin = true,
+    timeoutMs = IMAGE_TIMEOUT_MS,
+    resize = null,
+    failure = msg('The photo could not be loaded'),
+    signal = null,
+  } = {},
+) {
+  if (
+    crossOrigin &&
+    url &&
+    typeof globalThis.createImageBitmap === 'function' &&
+    typeof globalThis.fetch === 'function'
+  )
+    return loadBitmap(url, timeoutMs, resize, failure, signal);
+  return new Promise((resolve, reject) => {
+    if (!url) return reject(new Error(failure));
+    if (signal?.aborted) return reject(new Error(failure));
+    const image = new Image();
+    if (crossOrigin) image.crossOrigin = 'anonymous';
+    image.decoding = 'async';
+    // Stop the download: another photo opened, or the time ran out.
+    const stop = () => {
+      clearTimeout(timer);
+      signal?.removeEventListener?.('abort', stop);
+      image.onload = image.onerror = null;
+      image.src = '';
+      reject(new Error(failure));
+    };
+    const timer = setTimeout(stop, timeoutMs);
+    signal?.addEventListener?.('abort', stop, { once: true });
+    const settle = () => {
+      clearTimeout(timer);
+      signal?.removeEventListener?.('abort', stop);
+    };
+    image.onload = () => {
+      settle();
+      // An <img> reads no header first: refuse what it decoded too large.
+      if (tooManyPixels(image.naturalWidth || 0, image.naturalHeight || 0)) {
+        image.src = '';
+        reject(oversized(failure));
+        return;
+      }
+      resolve(image);
+    };
+    image.onerror = () => {
+      settle();
+      reject(new Error(failure));
+    };
+    image.src = url;
+  });
+}
+
+async function loadBitmap(url, timeoutMs, resize, failure, signal) {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+  // The caller's abort (the photo changed) stops a multi-megabyte download.
+  const onAbort = () => controller.abort();
+  if (signal?.aborted) controller.abort();
+  signal?.addEventListener?.('abort', onAbort, { once: true });
+  try {
+    const response = await fetch(url, {
+      mode: 'cors',
+      signal: controller.signal,
+    });
+    if (!response.ok) throw new Error(failure);
+    // Picture hosts are not ours: refuse a file or an image past any real
+    // photo's size before it is decoded.
+    const length = Number(response.headers?.get?.('content-length'));
+    if (length > MAX_IMAGE_BYTES) throw oversized(failure);
+    const blob = await boundedBlob(response, failure);
+    // Its declared size, before anything decodes it.
+    const size = imageSize(
+      new Uint8Array(await blob.slice(0, HEADER_BYTES).arrayBuffer()),
+    );
+    if (size && tooManyPixels(size.width, size.height))
+      throw oversized(failure);
+    const bitmap = await (resize
+      ? createImageBitmap(blob, {
+          resizeWidth: resize[0],
+          resizeHeight: resize[1],
+          resizeQuality: 'high',
+        })
+      : createImageBitmap(blob));
+    // (A resized decode reports its new size: this guards unresized ones.)
+    if (tooManyPixels(bitmap.width, bitmap.height)) {
+      bitmap.close?.();
+      throw oversized(failure);
+    }
+    return bitmap;
+  } catch (error) {
+    // A size refusal stays one: the viewer must not fetch it another way.
+    if (error?.tooLarge) throw error;
+    throw new Error(failure);
+  } finally {
+    clearTimeout(timer);
+    signal?.removeEventListener?.('abort', onAbort);
+  }
+}
+
+/**
+ * A picture refused for its size (`tooLarge`): the viewer will not load
+ * that file another way, an <img> having no size limit at all.
+ */
+export function oversized(failure) {
+  return Object.assign(new Error(failure), { tooLarge: true });
+}
+
+/**
+ * The body as a Blob, read with a running count so a host that sends no
+ * length (or a false one) cannot fill memory before the cap is checked.
+ */
+async function boundedBlob(response, failure) {
+  const reader = response.body?.getReader?.();
+  if (!reader) {
+    const blob = await response.blob();
+    if (blob.size > MAX_IMAGE_BYTES) throw oversized(failure);
+    return blob;
+  }
+  const chunks = [];
+  let total = 0;
+  for (;;) {
+    const { done, value } = await reader.read();
+    if (done) break;
+    total += value.byteLength;
+    if (total > MAX_IMAGE_BYTES) {
+      reader.cancel().catch(() => {});
+      throw oversized(failure);
+    }
+    chunks.push(value);
+  }
+  return new Blob(chunks, {
+    type: response.headers?.get?.('content-type') || 'image/jpeg',
+  });
+}
+
+/** The panorama size a canvas this wide can show sharply at this field of view. */
+export function panoSizeFor(canvasPixels, fovDeg) {
+  const needed = (Math.max(1, canvasPixels) * 360) / Math.max(1, fovDeg);
+  return needed > PANO_MID_SIZE[0] ? PANO_FULL_SIZE : PANO_MID_SIZE;
+}
+
+/**
+ * @typedef {object} PhotoSources   Where a provider's photo comes from.
+ * @property {(photo: object) => boolean} hasPano   A 360° photo with an equirectangular image.
+ * @property {(photo: object) => {url: string, width: number, resize?: [number, number]|null}|null} panoFirst
+ *   The panorama shown first, its texture width (0 when it is only a preview), and a size to shrink it to.
+ * @property {(photo: object, size: [number, number], view: {expanded: boolean}) => {url: string, resize?: [number, number]|null, timeoutMs?: number}|null} panoSharp
+ *   A sharper panorama for a canvas that needs `size`, or null; `expanded` while the viewer is.
+ * @property {(photo: object, view: {expanded: boolean}) => Array<string>} flatFirst   Flat versions to try in turn (`expanded` while the viewer is).
+ * @property {(photo: object, pixels: number) => string|null} flatSharp
+ *   A sharper flat version for a picture this many device pixels wide, or null.
+ * @property {(photo: object) => {title?: string|null, creator?: string|null, license?: string|null, externalUrl: string, capturedAtPrecision?: 'day'|'month'}} describe
+ * @property {(photo: object) => number|null} [bearingOf]   Where the camera looked (default `photo.heading`).
+ */
+
+/**
+ * Viewer adapter for providers whose photos are plain image files: a flat
+ * photo in an <img>, a 360° photo on a WebGL panorama (drag to look, wheel
+ * or pinch to zoom), and ‹ › to step along the sequence (also ← →). Poses
+ * follow the view direction.
+ *
+ * Photos are normalized by the provider: `{id, sequenceId, lon, lat,
+ * heading, isPano, capturedAt}` plus whatever its `sources` read.
+ *
+ * @param {object} options
+ * @param {string} options.providerId
+ * @param {string} options.name   Provider name for labels and messages, e.g. 'KartaView'.
+ * @param {PhotoSources} options.sources
+ * @param {(photoId: string) => Promise<object>} options.getPhoto   A normalized photo.
+ * @param {(photo: object, delta: -1|1) => Promise<string|null>} options.step   The photo `delta` along the sequence, or null at its end.
+ * @param {(imageId: string) => void} options.onStep   Open the photo ‹ › chose (through the core, so loading and errors show).
+ * @param {(photo: object) => void} [options.onShown]   A photo is on screen.
+ * @param {(photo: object) => void} [options.onShowing]   The photo this open shows, just before its pose.
+ * @param {(imageId: string) => void} [options.onReopen]   Draw the same photo again after a GPU reset (default: `onStep`).
+ * @param {() => boolean} [options.onEscape]   Esc in the docked viewer: true when it was used (e.g. a selection cleared).
+ * @param {object} [options.render]   Render governor.
+ * @param {(url: string, options?: object) => Promise<HTMLImageElement|ImageBitmap>} [options.load]
+ * @param {(canvas: HTMLCanvasElement) => object} [options.createRenderer]
+ * @returns {import('./registry.js').ViewerAdapter}
+ */
+export function createPhotoViewer({
+  providerId,
+  name,
+  sources,
+  getPhoto,
+  step,
+  onStep,
+  onShown = () => {},
+  onShowing = () => {},
+  onReopen = onStep,
+  onEscape = () => false,
+  render,
+  load = loadImage,
+  createRenderer = createPanoramaRenderer,
+}) {
+  const LOAD_FAILED = `The ${name} photo could not be loaded`;
+  const listeners = new Set();
+  let root = null;
+  let picture = null;
+  let canvas = null;
+  let prevButton = null;
+  let nextButton = null;
+  let renderer = null;
+  /** WebGL failed once: 360° photos show their front view instead. */
+  let rendererFailed = false;
+  let photo = null;
+  /** What shows: 'flat', 'pano' or null. */
+  let showing = null;
+  let openSeq = 0;
+  let renderMode = 'letterbox';
+  let drag = null;
+  let poseFrame = 0;
+  let removeListeners = [];
+  /** The document the viewer was built in (new canvases come from it). */
+  let documentOf = null;
+  /** A context loss's look direction, for the reopen of that photo. */
+  let restoreView = null;
+  /** The panel's viewer box, where Esc is listened for (null: the root). */
+  let escapeTarget = null;
+  /** Width of the panorama texture on screen (0: the preview). */
+  let panoWidth = 0;
+  /** The sharper panorama on its way, for which open (resizes come in bursts). */
+  let panoComing = null;
+  /** A resize came while it loaded: look again once it lands. */
+  let lookAgain = false;
+  /** The sharper flat version on screen, and the one on its way. */
+  let flatSharp = { shown: null, loading: null };
+  /** The open in progress: another open, a close or an unmount stops its downloads. */
+  let openAbort = null;
+  /** The photo an open is fetching: ‹ › step on from it, not the old one. */
+  let openingId = null;
+  /** ‹ › chose this photo: keep the panorama's look direction for it. */
+  let keepViewFor = null;
+  /** ‹ › presses run one after another, each from where the last one went. */
+  let steps = Promise.resolve();
+
+  /** Files refused for their size: never loaded again, by any path. */
+  const refused = new Set();
+  async function loadAs(url, options) {
+    if (refused.has(url)) throw oversized(LOAD_FAILED);
+    try {
+      return await load(url, { failure: LOAD_FAILED, ...options });
+    } catch (error) {
+      if (error?.tooLarge) refused.add(url);
+      throw error;
+    }
+  }
+
+  function requestRender() {
+    render?.governorRequestRender?.(`${providerId}-viewer`);
+  }
+
+  function emit() {
+    if (!photo || !showing) return;
+    // A lost GPU context, still being recovered: the open that redraws the
+    // panorama poses once it is on screen.
+    if (showing === 'pano' && !renderer) return;
+    const view = showing === 'pano' ? renderer.getView() : null;
+    const heading = sources.bearingOf
+      ? sources.bearingOf(photo)
+      : photo.heading;
+    const described = sources.describe(photo);
+    const pose = {
+      providerId,
+      imageId: photo.id,
+      position: { lon: photo.lon, lat: photo.lat },
+      bearing:
+        heading === null || heading === undefined
+          ? null
+          : view
+            ? wrapDegrees(heading + view.yaw)
+            : heading,
+      tilt: view ? view.pitch : 0,
+      altitude: null,
+      isPano: showing === 'pano',
+      capturedAt: photo.capturedAt,
+      capturedAtPrecision: described.capturedAtPrecision || 'day',
+      title: described.title ?? null,
+      creator: described.creator ?? null,
+      license: described.license ?? null,
+      sequenceId: photo.sequenceId,
+      externalUrl: described.externalUrl,
+    };
+    for (const listener of [...listeners]) {
+      try {
+        listener(pose);
+      } catch {
+        /* listener errors are the core's to log */
+      }
+    }
+    requestRender();
+  }
+
+  /** Re-emit on the next frame: a drag moves the view many times a frame. */
+  function emitSoon() {
+    if (poseFrame) return;
+    poseFrame = requestAnimationFrame(() => {
+      poseFrame = 0;
+      emit();
+    });
+  }
+
+  function syncButtons() {
+    const enabled = Boolean(photo?.sequenceId) && showing !== null;
+    if (prevButton) prevButton.disabled = !enabled;
+    if (nextButton) nextButton.disabled = !enabled;
+    if (enabled) checkEnds(photo);
+  }
+
+  /** Disable ‹ or › at once where the sequence ends (it also warms the neighbours). */
+  function checkEnds(target) {
+    for (const [delta, button] of [
+      [-1, prevButton],
+      [1, nextButton],
+    ])
+      step(target, delta).then(
+        (id) => {
+          if (photo === target && button && !id) disable(button);
+        },
+        () => {},
+      );
+  }
+
+  /** Disable a step button, keeping keyboard focus in the viewer. */
+  function disable(button) {
+    if (button.ownerDocument?.activeElement === button) root?.focus?.();
+    button.disabled = true;
+  }
+
+  function show(kind) {
+    showing = kind;
+    if (picture) picture.hidden = kind !== 'flat';
+    if (canvas) canvas.hidden = kind !== 'pano';
+    if (root) root.dataset.kind = kind || '';
+    syncButtons();
+  }
+
+  function applyRenderMode() {
+    if (picture)
+      picture.style.objectFit = renderMode === 'fill' ? 'cover' : 'contain';
+  }
+
+  function ensureRenderer() {
+    if (renderer || rendererFailed || !canvas) return renderer;
+    try {
+      renderer = createRenderer(canvas);
+    } catch {
+      rendererFailed = true;
+      renderer = null;
+    }
+    return renderer;
+  }
+
+  /**
+   * A lost WebGL context (GPU reset, memory pressure) takes the panorama
+   * with it: drop the renderer, and show the photo again on a new one.
+   */
+  function onContextLost(event) {
+    event.preventDefault?.();
+    const lost = renderer;
+    renderer = null;
+    // The new renderer starts facing the photo's heading: keep the user's look.
+    if (showing === 'pano' && photo && lost)
+      restoreView = { id: photo.id, view: lost.getView() };
+    try {
+      lost?.destroy();
+    } catch {
+      /* already gone */
+    }
+    // A lost canvas hands back its lost context: draw on a new element.
+    const fresh = makeCanvas(documentOf);
+    fresh.hidden = canvas.hidden;
+    canvas.replaceWith?.(fresh);
+    canvas = fresh;
+    // Show the photo again through the core, unless a newer one is opening.
+    if (showing === 'pano' && photo && openingId === null) {
+      const again = photo.id;
+      show(null);
+      openingId = again;
+      onReopen(again);
+    }
+  }
+
+  /** The panorama canvas, wired for drag, pinch, wheel and context loss. */
+  function makeCanvas(doc) {
+    const element = doc.createElement('canvas');
+    element.className = 'sl-photo-pano';
+    element.hidden = true;
+    listen(element, 'pointerdown', onPointerDown);
+    listen(element, 'pointermove', onPointerMove);
+    listen(element, 'pointerup', onPointerUp);
+    listen(element, 'pointercancel', onPointerUp);
+    listen(element, 'wheel', onWheel, { passive: false });
+    listen(element, 'webglcontextlost', onContextLost);
+    return element;
+  }
+
+  /**
+   * Step along the sequence from the photo showing, or from the one on its
+   * way after an earlier press, and open it through the core.
+   */
+  function stepBy(delta) {
+    steps = steps.then(async () => {
+      const fromId = openingId ?? photo?.id;
+      if (!fromId || !root) return;
+      let from;
+      let nextId = null;
+      try {
+        from = await getPhoto(fromId);
+        if (from.sequenceId) nextId = await step(from, delta);
+      } catch {
+        // Not the end of the sequence, just no answer: the press is lost.
+        return;
+      }
+      // Closed, or another photo was opened meanwhile.
+      if ((openingId ?? photo?.id) !== fromId) return;
+      if (!nextId) {
+        const button = delta < 0 ? prevButton : nextButton;
+        if (button && photo?.id === fromId) disable(button);
+        return;
+      }
+      openingId = nextId;
+      keepViewFor = nextId;
+      onStep(nextId);
+    });
+  }
+
+  /** Pointers on the panorama: one drags the view, two pinch the zoom. */
+  const pointers = new Map();
+  let pinch = null;
+
+  function pinchSpan() {
+    const [a, b] = [...pointers.values()];
+    return Math.max(1, Math.hypot(a.x - b.x, a.y - b.y));
+  }
+
+  function onPointerDown(event) {
+    if (showing !== 'pano' || !renderer) return;
+    if (event.pointerType === 'mouse' && event.button !== 0) return;
+    pointers.set(event.pointerId, { x: event.clientX, y: event.clientY });
+    canvas.setPointerCapture?.(event.pointerId);
+    if (pointers.size === 2) {
+      drag = null;
+      pinch = { span: pinchSpan(), fov: renderer.getView().fov };
+      return;
+    }
+    drag = {
+      id: event.pointerId,
+      x: event.clientX,
+      y: event.clientY,
+      view: renderer.getView(),
+    };
+    canvas.classList.add('sl-photo-dragging');
+  }
+
+  function onPointerMove(event) {
+    if (pointers.has(event.pointerId))
+      pointers.set(event.pointerId, { x: event.clientX, y: event.clientY });
+    if (pinch && pointers.size === 2 && renderer) {
+      renderer.setView({ fov: pinch.fov * (pinch.span / pinchSpan()) });
+      return;
+    }
+    if (!drag || event.pointerId !== drag.id || !renderer) return;
+    const { fov } = drag.view;
+    const width = Math.max(1, canvas.clientWidth);
+    const height = Math.max(1, canvas.clientHeight);
+    const vertical = fov;
+    const horizontal = fov * (width / height);
+    renderer.setView({
+      yaw: drag.view.yaw - ((event.clientX - drag.x) / width) * horizontal,
+      pitch: drag.view.pitch + ((event.clientY - drag.y) / height) * vertical,
+    });
+    emitSoon();
+  }
+
+  function onPointerUp(event) {
+    pointers.delete(event.pointerId);
+    if (pointers.size < 2) pinch = null;
+    if (!drag || event.pointerId !== drag.id) return;
+    drag = null;
+    canvas.classList.remove('sl-photo-dragging');
+  }
+
+  function onWheel(event) {
+    if (showing !== 'pano' || !renderer) return;
+    event.preventDefault();
+    const { fov } = renderer.getView();
+    renderer.setView({ fov: fov * Math.exp(event.deltaY * 0.001) });
+  }
+
+  /**
+   * Docked, Esc anywhere in the viewer's box (the photo, its toolbar, its
+   * caption) is the provider's before the panel's, which would collapse;
+   * expanded, the panel's own Esc shrinks it.
+   */
+  function onEscapeKey(event) {
+    if (
+      event.key !== 'Escape' ||
+      event.shiftKey ||
+      event.defaultPrevented ||
+      isExpanded() ||
+      !onEscape()
+    )
+      return;
+    event.preventDefault();
+    event.stopPropagation();
+  }
+
+  function onKeyDown(event) {
+    if (!escapeTarget) onEscapeKey(event);
+    if (
+      event.defaultPrevented ||
+      event.altKey ||
+      event.ctrlKey ||
+      event.metaKey
+    )
+      return;
+    const pano = showing === 'pano' && renderer;
+    const turn = { ArrowLeft: -1, ArrowRight: 1 }[event.key];
+    // Shift+← → look around a panorama; ← → step along the sequence.
+    if (turn && event.shiftKey && pano) {
+      event.preventDefault();
+      const { yaw, fov } = renderer.getView();
+      renderer.setView({ yaw: yaw + (turn * fov) / 4 });
+      emitSoon();
+    } else if (turn) {
+      event.preventDefault();
+      stepBy(turn);
+    } else if ((event.key === 'ArrowUp' || event.key === 'ArrowDown') && pano) {
+      event.preventDefault();
+      const { pitch, fov } = renderer.getView();
+      renderer.setView({
+        pitch: pitch + ((event.key === 'ArrowUp' ? 1 : -1) * fov) / 6,
+      });
+      emitSoon();
+    } else if (['+', '=', '-', '_'].includes(event.key) && pano) {
+      event.preventDefault();
+      const { fov } = renderer.getView();
+      renderer.setView({
+        fov: fov * (event.key === '+' || event.key === '=' ? 0.85 : 1 / 0.85),
+      });
+    }
+  }
+
+  function listen(target, type, handler, options) {
+    target.addEventListener(type, handler, options);
+    removeListeners.push(() =>
+      target.removeEventListener(type, handler, options),
+    );
+  }
+
+  function build(host) {
+    const doc = host.ownerDocument;
+    documentOf = doc;
+    root = doc.createElement('div');
+    root.className = 'sl-photo-viewer';
+    root.dataset.provider = providerId;
+    root.tabIndex = 0;
+    root.setAttribute('role', 'group');
+    root.setAttribute(
+      'aria-label',
+      t(
+        '{name} photo. ← and → step along the sequence. On a 360° photo, drag or use Shift+← →, ↑ ↓ to look around, and + − to zoom',
+        { name },
+      ),
+    );
+    picture = doc.createElement('img');
+    picture.className = 'sl-photo-flat';
+    picture.alt = t('{name} street-level photo', { name });
+    picture.draggable = false;
+    picture.hidden = true;
+    canvas = makeCanvas(doc);
+    const nav = (label, glyph, delta) => {
+      const button = doc.createElement('button');
+      button.type = 'button';
+      button.className = `sl-photo-step sl-photo-step-${delta < 0 ? 'prev' : 'next'}`;
+      button.textContent = glyph;
+      button.title = label;
+      button.setAttribute('aria-label', label);
+      button.disabled = true;
+      listen(button, 'click', (event) => {
+        event.stopPropagation();
+        stepBy(delta);
+      });
+      return button;
+    };
+    prevButton = nav(t('Previous photo in this sequence (←)'), '‹', -1);
+    nextButton = nav(t('Next photo in this sequence (→)'), '›', 1);
+    root.append(picture, canvas, prevButton, nextButton);
+    host.append(root);
+    listen(root, 'keydown', onKeyDown);
+    // The viewer's box in the panel; without one, the root's own handler
+    // takes Esc (one listener per element and type).
+    escapeTarget = host.closest?.('.sl-viewer-wrap') ?? null;
+    if (escapeTarget) listen(escapeTarget, 'keydown', onEscapeKey);
+    applyRenderMode();
+  }
+
+  function teardown() {
+    pointers.clear();
+    pinch = null;
+    for (const remove of removeListeners) remove();
+    removeListeners = [];
+    if (poseFrame) cancelAnimationFrame(poseFrame);
+    poseFrame = 0;
+    drag = null;
+    renderer?.destroy();
+    renderer = null;
+    root?.remove();
+    root = picture = canvas = prevButton = nextButton = null;
+    showing = null;
+    photo = null;
+  }
+
+  /** Device pixels across the flat photo's frame (its longer side). */
+  function viewerPixels() {
+    const ratio = globalThis.devicePixelRatio || 1;
+    const element = showing === 'pano' ? canvas : picture;
+    const side = Math.max(
+      element?.clientWidth || 0,
+      element?.clientHeight || 0,
+    );
+    return (side || root?.clientWidth || 0) * ratio;
+  }
+
+  /** A sharper version once the first is on screen, if nothing replaced it. */
+  async function upgrade(target, seq, kind) {
+    // A 360° photo shown flat (no WebGL) keeps its front view.
+    if (kind === 'flat' && target.isPano) return;
+    // Another photo is opening: the one still shown is not worth more bytes.
+    if (openingId !== null && openingId !== target.id) return;
+    const signal = openAbort?.signal;
+    if (kind === 'pano') {
+      const size = panoSizeNow();
+      if (size[0] <= panoWidth) return;
+      // Resizes come in bursts while the panel animates: one load at a time
+      // for this photo, and one more look once it lands.
+      if (panoComing?.seq === seq) {
+        lookAgain = true;
+        return;
+      }
+      const sharp = sources.panoSharp(target, size, {
+        expanded: isExpanded(),
+      });
+      if (!sharp?.url) return;
+      const coming = { seq, width: size[0], controller: new AbortController() };
+      panoComing = coming;
+      lookAgain = false;
+      try {
+        const image = await loadAs(sharp.url, {
+          crossOrigin: true,
+          signal: coming.controller.signal,
+          resize: sharp.resize ?? null,
+          ...(sharp.timeoutMs ? { timeoutMs: sharp.timeoutMs } : {}),
+        });
+        if (seq !== openSeq || photo !== target || showing !== 'pano') {
+          image.close?.();
+          return;
+        }
+        if (!renderer || size[0] <= panoWidth) {
+          image.close?.();
+          return;
+        }
+        renderer.setImage(image);
+        panoWidth = size[0];
+        requestRender();
+      } catch {
+        /* the first version stays */
+      } finally {
+        if (panoComing === coming) {
+          panoComing = null;
+          if (lookAgain && seq === openSeq && photo === target) {
+            lookAgain = false;
+            upgrade(target, seq, 'pano');
+          }
+        }
+      }
+      return;
+    }
+    const url = sources.flatSharp(target, viewerPixels());
+    if (!url || url === flatSharp.shown || url === flatSharp.loading) return;
+    const sharp = flatSharp;
+    sharp.loading = url;
+    try {
+      const image = await loadAs(url, { crossOrigin: false, signal });
+      if (seq !== openSeq || photo !== target || showing !== 'flat') return;
+      picture.src = image.src;
+      sharp.shown = url;
+      requestRender();
+    } catch {
+      /* the first version stays; a later resize may try again */
+    } finally {
+      // Discarded or failed: nothing is on its way, so it may be asked again.
+      if (sharp.loading === url) sharp.loading = null;
+    }
+  }
+
+  /** The viewer is expanded (full screen, or the iPhone popover), not docked in the panel. */
+  function isExpanded() {
+    try {
+      return Boolean(root?.closest?.(EXPANDED_SELECTOR));
+    } catch {
+      // A browser without :popover-open has no popover EXPAND either.
+      return Boolean(root?.closest?.('.sl-viewer-wrap:fullscreen'));
+    }
+  }
+
+  /** Another photo, or none: a sharper panorama still on its way is not needed. */
+  function dropSharpPanorama() {
+    panoComing?.controller?.abort();
+    panoComing = null;
+    lookAgain = false;
+  }
+
+  /** The sharp panorama this viewer needs now: 2,048 docked, 4,096 expanded. */
+  function panoSizeNow() {
+    const ratio = Math.min(globalThis.devicePixelRatio || 1, 2);
+    const width = (canvas?.clientWidth || 0) * ratio;
+    return panoSizeFor(width, renderer?.getView().fov ?? PANO_FOV_DEFAULT_DEG);
+  }
+
+  async function showPano(target, seq, keepView, signal) {
+    // If the panorama fails, the caller shows the front view rather than
+    // waiting on it twice.
+    const first = sources.panoFirst(target);
+    if (!first?.url) throw new Error(LOAD_FAILED);
+    const image = await loadAs(first.url, {
+      crossOrigin: true,
+      signal,
+      // Never decoded at more than the texture it becomes.
+      resize: first.resize ?? PANO_MID_SIZE,
+    });
+    if (seq !== openSeq) {
+      image.close?.();
+      return false;
+    }
+    // The context may have been lost while this loaded: build on the new
+    // canvas, or let the caller show the front view.
+    if (!ensureRenderer()) {
+      image.close?.();
+      throw new Error(LOAD_FAILED);
+    }
+    const restore = restoreView?.id === target.id ? restoreView.view : null;
+    restoreView = null;
+    if (restore) renderer.setView(restore);
+    else if (!keepView || showing !== 'pano')
+      renderer.setView({ yaw: 0, pitch: 0, fov: PANO_FOV_DEFAULT_DEG });
+    photo = target;
+    // Shown first: a hidden canvas measures 0 and would be sized 1×1.
+    show('pano');
+    renderer.setImage(image);
+    panoWidth = first.width || 0;
+    // A sharper version of the photo before was dropped by `open`; one of
+    // this photo, asked by a resize meanwhile, is still worth having.
+    return true;
+  }
+
+  async function showFlat(target, seq, signal) {
+    const urls = sources
+      .flatFirst(target, { expanded: isExpanded() })
+      .filter(Boolean);
+    let image;
+    let failure = null;
+    for (const url of urls) {
+      try {
+        image = await loadAs(url, { crossOrigin: false, signal });
+        break;
+      } catch (error) {
+        failure = error;
+        if (seq !== openSeq) return false;
+      }
+    }
+    if (!image) throw failure || new Error(LOAD_FAILED);
+    if (seq !== openSeq) return false;
+    picture.src = image.src;
+    flatSharp = { shown: null, loading: null };
+    photo = target;
+    show('flat');
+    return true;
+  }
+
+  async function openPhoto(id, seq, keepView, signal) {
+    const target = await getPhoto(id, { signal });
+    if (seq !== openSeq) return;
+    let shown = false;
+    if (sources.hasPano(target) && ensureRenderer()) {
+      try {
+        shown = await showPano(target, seq, keepView, signal);
+      } catch {
+        // The panorama failed: its front view is better than nothing.
+        if (seq !== openSeq) return;
+        shown = await showFlat(target, seq, signal);
+      }
+    } else shown = await showFlat(target, seq, signal);
+    if (!shown) return;
+    onShowing(target);
+    emit();
+    onShown(target);
+    upgrade(target, seq, showing);
+  }
+
+  const adapter = {
+    async mount(host) {
+      if (!host) throw new Error('Street Level viewer has no host element');
+      if (root && root.parentNode === host) return;
+      teardown();
+      rendererFailed = false;
+      build(host);
+    },
+
+    /** Resolves once the photo is on screen and its pose was emitted. */
+    async open(imageId) {
+      if (!root) throw new Error(`${name} viewer is not mounted`);
+      const id = String(imageId);
+      const seq = ++openSeq;
+      dropSharpPanorama();
+      // The previous open's downloads stop: only this photo is wanted now.
+      openAbort?.abort();
+      const opening = (openAbort = new AbortController());
+      const keepView = keepViewFor === id;
+      keepViewFor = null;
+      openingId = id;
+      try {
+        await openPhoto(id, seq, keepView, opening.signal);
+      } catch (error) {
+        // A later open, or a close, stopped this one: that is not a failure.
+        if (seq !== openSeq) return;
+        throw error;
+      } finally {
+        if (openingId === id && seq === openSeq) openingId = null;
+      }
+    },
+
+    close() {
+      openSeq++;
+      dropSharpPanorama();
+      openAbort?.abort();
+      openAbort = null;
+      openingId = null;
+      keepViewFor = null;
+      photo = null;
+      flatSharp = { shown: null, loading: null };
+      show(null);
+      if (picture) picture.removeAttribute('src');
+      renderer?.clear?.();
+    },
+
+    unmount() {
+      openSeq++;
+      dropSharpPanorama();
+      openAbort?.abort();
+      openAbort = null;
+      refused.clear();
+      openingId = null;
+      keepViewFor = null;
+      flatSharp = { shown: null, loading: null };
+      teardown();
+    },
+
+    resize() {
+      renderer?.resize();
+      // Expanded: a docked viewer's panorama or flat version is now too soft.
+      if (showing === 'pano' && photo && panoSizeNow()[0] > panoWidth)
+        upgrade(photo, openSeq, 'pano');
+      else if (showing === 'flat' && photo) upgrade(photo, openSeq, 'flat');
+    },
+
+    /** FIT / FILL frame a flat photo; a panorama has no frame to fit. */
+    supportsRenderModes: () => showing !== 'pano',
+
+    setRenderMode(mode) {
+      renderMode = mode === 'fill' ? 'fill' : 'letterbox';
+      applyRenderMode();
+    },
+
+    /** The photo's direction became known (its drive loaded): pose again. */
+    refreshPose() {
+      emit();
+    },
+
+    onPose(listener) {
+      listeners.add(listener);
+      return () => listeners.delete(listener);
+    },
+  };
+  return adapter;
+}

src/layers/streetLevel/photoViewer.test.mjs

@@ -0,0 +1,538 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import { createPhotoViewer } from './photoViewer.js';
+import { fakeHost, until } from '../../testSupport/kartaViewFakes.mjs';
+
+const PHOTOS = {
+  a: { id: 'a', sequenceId: 's', lon: 1, lat: 2, heading: 0, isPano: true },
+  b: { id: 'b', sequenceId: 's', lon: 1, lat: 2, heading: 0, isPano: true },
+  f: { id: 'f', sequenceId: 's', lon: 1, lat: 2, heading: 0, isPano: false },
+  g: { id: 'g', sequenceId: 's', lon: 1, lat: 2, heading: 0, isPano: false },
+};
+
+/** Sources whose panoramas and sharper flat versions are named after the photo. */
+const SOURCES = {
+  hasPano: (photo) => photo.isPano,
+  panoFirst: (photo) => ({ url: `${photo.id}-first`, width: 2048 }),
+  panoSharp: (photo) => ({ url: `${photo.id}-sharp` }),
+  flatFirst: (photo) => [`${photo.id}-first`],
+  flatSharp: (photo, pixels) => (pixels > 1000 ? `${photo.id}-sharp` : null),
+  describe: () => ({ externalUrl: 'https://example.org' }),
+};
+
+/** A viewer whose loads wait until `release(url)` (or fail with `fail(url)`). */
+function setup() {
+  const pending = new Map();
+  const loads = [];
+  const images = [];
+  const viewer = createPhotoViewer({
+    providerId: 'test',
+    name: 'Test',
+    sources: SOURCES,
+    getPhoto: async (id) => PHOTOS[id],
+    step: async () => null,
+    onStep() {},
+    load: (url) =>
+      new Promise((resolve, reject) => {
+        loads.push(url);
+        pending.set(url, { resolve, reject });
+      }),
+    createRenderer: () => ({
+      setImage: (image) => images.push(image.src),
+      setView() {},
+      getView: () => ({ yaw: 0, pitch: 0, fov: 80 }),
+      resize() {},
+      clear() {},
+      destroy() {},
+    }),
+  });
+  const release = (url) => {
+    const closed = { value: false };
+    pending.get(url).resolve({ src: url, close: () => (closed.value = true) });
+    pending.delete(url);
+    return closed;
+  };
+  const fail = (url) => {
+    pending.get(url).reject(new Error('gone'));
+    pending.delete(url);
+  };
+  return { viewer, loads, images, release, fail, host: fakeHost() };
+}
+
+const tick = () => new Promise((resolve) => setTimeout(resolve, 0));
+const parts = (host) => {
+  const [picture, canvas] = host.children[0].children;
+  return { picture, canvas };
+};
+
+test('a panorama that arrives after another photo opened is released, not shown', async () => {
+  const env = setup();
+  await env.viewer.mount(env.host);
+  const first = env.viewer.open('a');
+  await tick();
+  const second = env.viewer.open('b');
+  await tick();
+  const stale = env.release('a-first');
+  await first;
+  assert.equal(stale.value, true, 'its bitmap is closed');
+  env.release('b-first');
+  await second;
+  assert.deepEqual(env.images, ['b-first']);
+});
+
+test('one sharp panorama download per open, even across a quick switch and a burst of resizes', async (t) => {
+  const env = setup();
+  t.after(() => delete globalThis.devicePixelRatio);
+  globalThis.devicePixelRatio = 1;
+  await env.viewer.mount(env.host);
+  const { canvas } = parts(env.host);
+  canvas.clientWidth = 1800;
+  const opening = env.viewer.open('a');
+  await tick();
+  env.release('a-first');
+  await opening;
+  await tick();
+  assert.ok(env.loads.includes('a-sharp'), 'expanded: the sharp one is asked');
+  // Photo b opens while a's sharp version is still on its way.
+  const next = env.viewer.open('b');
+  await tick();
+  env.release('b-first');
+  await next;
+  await tick();
+  assert.ok(env.loads.includes('b-sharp'));
+  // a's download finishes late; resizes must not ask for b's again.
+  env.release('a-sharp');
+  await tick();
+  env.viewer.resize();
+  env.viewer.resize();
+  await tick();
+  assert.equal(env.loads.filter((url) => url === 'b-sharp').length, 1);
+  env.release('b-sharp');
+  await tick();
+  assert.deepEqual(env.images, ['a-first', 'b-first', 'b-sharp']);
+});
+
+test('a sharper flat version that failed is tried again on the next resize', async (t) => {
+  const env = setup();
+  t.after(() => delete globalThis.devicePixelRatio);
+  globalThis.devicePixelRatio = 1;
+  await env.viewer.mount(env.host);
+  const { picture } = parts(env.host);
+  picture.clientWidth = 1200;
+  const opening = env.viewer.open('f');
+  await tick();
+  env.release('f-first');
+  await opening;
+  await tick();
+  env.fail('f-sharp');
+  await tick();
+  assert.equal(picture.src, 'f-first');
+  env.viewer.resize();
+  await tick();
+  assert.equal(env.loads.filter((url) => url === 'f-sharp').length, 2);
+  env.release('f-sharp');
+  assert.ok(await until(() => picture.src === 'f-sharp'));
+});
+
+test('Esc: the docked viewer offers it to the provider first; expanded, it is the dialog’s', async () => {
+  let asked = 0;
+  const viewer = createPhotoViewer({
+    providerId: 'test',
+    name: 'Test',
+    sources: SOURCES,
+    getPhoto: async (id) => PHOTOS[id],
+    step: async () => null,
+    onStep() {},
+    onEscape: () => ++asked > 0,
+    load: async (url) => ({ src: url }),
+  });
+  const host = fakeHost();
+  await viewer.mount(host);
+  const root = host.children[0];
+  const press = () => {
+    const event = { key: 'Escape', prevented: false, stopped: false };
+    event.preventDefault = () => (event.prevented = true);
+    event.stopPropagation = () => (event.stopped = true);
+    root.fire('keydown', event);
+    return event;
+  };
+  const docked = press();
+  assert.equal(asked, 1);
+  assert.equal(docked.prevented && docked.stopped, true);
+  root.closest = (selector) =>
+    selector.includes('sl-viewer-wrap:fullscreen') ? {} : null;
+  const expanded = press();
+  assert.equal(asked, 1, 'not asked while expanded');
+  assert.equal(expanded.prevented, false);
+});
+
+test('a sharp panorama still downloading when another photo opens is aborted', async (t) => {
+  const signals = [];
+  const viewer = createPhotoViewer({
+    providerId: 'test',
+    name: 'Test',
+    sources: SOURCES,
+    getPhoto: async (id) => PHOTOS[id],
+    step: async () => null,
+    onStep() {},
+    load: (url, options) =>
+      url.endsWith('-sharp')
+        ? new Promise((_, reject) => {
+            signals.push(options.signal);
+            options.signal?.addEventListener('abort', () =>
+              reject(new Error('aborted')),
+            );
+          })
+        : Promise.resolve({ src: url }),
+    createRenderer: () => ({
+      setImage() {},
+      setView() {},
+      getView: () => ({ yaw: 0, pitch: 0, fov: 80 }),
+      resize() {},
+      clear() {},
+      destroy() {},
+    }),
+  });
+  t.after(() => delete globalThis.devicePixelRatio);
+  globalThis.devicePixelRatio = 1;
+  const host = fakeHost();
+  await viewer.mount(host);
+  parts(host).canvas.clientWidth = 1800;
+  await viewer.open('a');
+  await tick();
+  assert.equal(signals.length, 1);
+  assert.equal(signals[0].aborted, false);
+  await viewer.open('f');
+  assert.equal(signals[0].aborted, true, 'not needed any more');
+});
+
+test('a lost WebGL context while the first panorama loads releases its bitmap', async () => {
+  let closed = false;
+  let built = 0;
+  let land = null;
+  const viewer = createPhotoViewer({
+    providerId: 'test',
+    name: 'Test',
+    sources: SOURCES,
+    getPhoto: async (id) => PHOTOS[id],
+    step: async () => null,
+    onStep() {},
+    load: (url) =>
+      new Promise((resolve) => {
+        land = () => resolve({ src: url, close: () => (closed = true) });
+      }),
+    // The first renderer is lost mid-load; a new one cannot be built.
+    createRenderer: () => {
+      built++;
+      if (built > 1) throw new Error('context lost');
+      return {
+        setImage() {},
+        setView() {},
+        getView: () => ({ yaw: 0, pitch: 0, fov: 80 }),
+        resize() {},
+        clear() {},
+        destroy() {},
+      };
+    },
+  });
+  const host = fakeHost();
+  await viewer.mount(host);
+  const opening = viewer.open('a');
+  assert.ok(await until(() => land !== null), 'the panorama is loading');
+  parts(host).canvas.fire('webglcontextlost', {});
+  const first = land;
+  first();
+  // The panorama failed: the front view is loaded flat instead.
+  assert.ok(await until(() => land !== first), 'the flat fallback loads');
+  land();
+  await opening;
+  assert.equal(built, 2, 'a new renderer was tried');
+  assert.equal(closed, true, 'the bitmap no renderer took is closed');
+});
+
+test('docked, Esc anywhere in the viewer’s box (toolbar, caption) is offered to the provider', async () => {
+  let asked = 0;
+  const viewer = createPhotoViewer({
+    providerId: 'test',
+    name: 'Test',
+    sources: SOURCES,
+    getPhoto: async (id) => PHOTOS[id],
+    step: async () => null,
+    onStep() {},
+    onEscape: () => ++asked > 0,
+    load: async (url) => ({ src: url }),
+  });
+  const host = fakeHost();
+  const wrap = fakeHost();
+  host.closest = (selector) => (selector === '.sl-viewer-wrap' ? wrap : null);
+  await viewer.mount(host);
+  const flags = { stopped: false, prevented: false };
+  // Focus back on EXPAND after a shrink: the key reaches the wrap, not the photo.
+  wrap.fire('keydown', {
+    key: 'Escape',
+    stopPropagation: () => (flags.stopped = true),
+    preventDefault: () => (flags.prevented = true),
+  });
+  assert.equal(asked, 1);
+  assert.deepEqual(flags, { stopped: true, prevented: true });
+  viewer.unmount();
+  wrap.fire('keydown', { key: 'Escape' });
+  assert.equal(asked, 1, 'unmounted: the listener is gone');
+});
+
+test('a picture file or bitmap past any real photo’s size is refused', async (t) => {
+  const { loadImage, MAX_IMAGE_BYTES, MAX_IMAGE_SIDE } =
+    await import('./photoViewer.js');
+  const saved = {
+    fetch: globalThis.fetch,
+    createImageBitmap: globalThis.createImageBitmap,
+  };
+  t.after(() => Object.assign(globalThis, saved));
+  let closed = 0;
+  const bitmap = (width, height) => ({ width, height, close: () => closed++ });
+  globalThis.createImageBitmap = async (blob) => blob.bitmap;
+  const respond = ({ length, size, width = 100, height = 50 }) =>
+    (globalThis.fetch = async () => ({
+      ok: true,
+      headers: new Map([['content-length', String(length ?? '')]]),
+      blob: async () => ({
+        size: size ?? 10,
+        bitmap: bitmap(width, height),
+        slice: () => ({ arrayBuffer: async () => new ArrayBuffer(0) }),
+      }),
+    }));
+  const refusedForSize = (error) => {
+    assert.match(error.message, /could not be loaded/);
+    assert.equal(error.tooLarge, true, 'marked as a size refusal');
+    return true;
+  };
+  respond({ length: MAX_IMAGE_BYTES + 1 });
+  await assert.rejects(loadImage('https://x/a.jpg'), refusedForSize);
+  respond({ size: MAX_IMAGE_BYTES + 1 });
+  await assert.rejects(loadImage('https://x/a.jpg'), refusedForSize);
+  respond({ width: MAX_IMAGE_SIDE + 1 });
+  await assert.rejects(loadImage('https://x/a.jpg'), refusedForSize);
+  assert.equal(closed, 1, 'the oversize bitmap is released');
+  // No length given, a body that keeps coming: cut off while it streams.
+  let pulled = 0;
+  globalThis.fetch = async () => ({
+    ok: true,
+    headers: new Map(),
+    body: new ReadableStream({
+      pull(controller) {
+        pulled++;
+        controller.enqueue(new Uint8Array(8 * 1024 * 1024));
+      },
+    }),
+  });
+  await assert.rejects(loadImage('https://x/a.jpg'), refusedForSize);
+  assert.ok(pulled * 8 * 1024 * 1024 <= MAX_IMAGE_BYTES + 16 * 1024 * 1024);
+  // Other failures are not size refusals.
+  globalThis.fetch = async () => ({ ok: false, headers: new Map() });
+  await assert.rejects(
+    loadImage('https://x/a.jpg'),
+    (error) => !error.tooLarge,
+  );
+  respond({});
+  assert.equal((await loadImage('https://x/a.jpg')).width, 100);
+});
+
+/** A viewer whose loads are held, recording each load's signal by url. */
+function heldViewer() {
+  const pending = new Map();
+  const signals = new Map();
+  const loads = [];
+  const viewer = createPhotoViewer({
+    providerId: 'test',
+    name: 'Test',
+    sources: SOURCES,
+    getPhoto: async (id) => PHOTOS[id],
+    step: async () => null,
+    onStep() {},
+    load: (url, options = {}) =>
+      new Promise((resolve, reject) => {
+        loads.push(url);
+        signals.set(url, options.signal);
+        options.signal?.addEventListener('abort', () =>
+          reject(new Error('aborted')),
+        );
+        pending.set(url, { resolve, reject });
+      }),
+  });
+  const release = (url) => {
+    pending.get(url).resolve({ src: url });
+    pending.delete(url);
+  };
+  return { viewer, pending, signals, loads, release, host: fakeHost() };
+}
+
+test('a new open, a close or an unmount stops the downloads of the open before it', async () => {
+  const env = heldViewer();
+  await env.viewer.mount(env.host);
+  const first = env.viewer.open('f');
+  assert.ok(await until(() => env.signals.has('f-first')));
+  const second = env.viewer.open('g');
+  assert.equal(env.signals.get('f-first').aborted, true, 'f is not wanted now');
+  await first.catch(() => {});
+  assert.ok(await until(() => env.signals.has('g-first')));
+  env.viewer.close();
+  assert.equal(env.signals.get('g-first').aborted, true, 'closed');
+  await second.catch(() => {});
+  const third = env.viewer.open('f');
+  assert.ok(await until(() => env.pending.has('f-first')));
+  env.viewer.unmount();
+  assert.equal(env.signals.get('f-first').aborted, true, 'unmounted');
+  await third.catch(() => {});
+});
+
+test('a sharper flat version on its way stops when another photo opens, and is asked again later', async (t) => {
+  t.after(() => delete globalThis.devicePixelRatio);
+  globalThis.devicePixelRatio = 1;
+  const env = heldViewer();
+  await env.viewer.mount(env.host);
+  parts(env.host).picture.clientWidth = 1200;
+  const opening = env.viewer.open('f');
+  assert.ok(await until(() => env.pending.has('f-first')));
+  env.release('f-first');
+  await opening;
+  assert.ok(
+    await until(() => env.pending.has('f-sharp')),
+    'the 1,200 px viewer asks for more',
+  );
+  // Resizes while it loads (the panel animating) do not ask again.
+  env.viewer.resize();
+  env.viewer.resize();
+  await new Promise((resolve) => setTimeout(resolve, 0));
+  assert.equal(env.loads.filter((url) => url === 'f-sharp').length, 1);
+  // g opens (and fails): f's sharp download stops, f stays on screen.
+  const failing = env.viewer.open('g');
+  assert.equal(env.signals.get('f-sharp').aborted, true);
+  assert.ok(await until(() => env.pending.has('g-first')));
+  env.pending.get('g-first').reject(new Error('gone'));
+  env.pending.delete('g-first');
+  await failing.catch(() => {});
+  // The discarded response does not block f's sharp version for good.
+  env.signals.delete('f-sharp');
+  env.viewer.resize();
+  assert.ok(await until(() => env.signals.has('f-sharp')), 'asked again');
+});
+
+test('a resize while another photo opens does not upgrade the photo still shown', async (t) => {
+  t.after(() => delete globalThis.devicePixelRatio);
+  globalThis.devicePixelRatio = 1;
+  const env = heldViewer();
+  await env.viewer.mount(env.host);
+  const opening = env.viewer.open('f');
+  assert.ok(await until(() => env.pending.has('f-first')));
+  env.release('f-first');
+  await opening;
+  // g is opening; EXPAND resizes the viewer meanwhile.
+  const next = env.viewer.open('g');
+  assert.ok(await until(() => env.pending.has('g-first')));
+  parts(env.host).picture.clientWidth = 1200;
+  env.viewer.resize();
+  await new Promise((resolve) => setTimeout(resolve, 0));
+  assert.equal(env.pending.has('f-sharp'), false, 'f is on its way out');
+  env.release('g-first');
+  await next;
+  assert.ok(await until(() => env.pending.has('g-sharp')), 'g gets it');
+});
+
+test('a panorama is always decoded at a bounded size', async () => {
+  const env = heldViewer();
+  const options = [];
+  const viewer = createPhotoViewer({
+    providerId: 'test',
+    name: 'Test',
+    sources: SOURCES,
+    getPhoto: async (id) => PHOTOS[id],
+    step: async () => null,
+    onStep() {},
+    load: async (url, opts) => {
+      options.push(opts);
+      return { src: url };
+    },
+    createRenderer: () => ({
+      setImage() {},
+      setView() {},
+      getView: () => ({ yaw: 0, pitch: 0, fov: 80 }),
+      resize() {},
+      clear() {},
+      destroy() {},
+    }),
+  });
+  await viewer.mount(env.host);
+  await viewer.open('a');
+  // SOURCES' panoFirst names no size: the viewer still bounds it.
+  assert.deepEqual(options[0].resize, [2048, 1024]);
+});
+
+test('a header that declares a huge image is refused before anything decodes it', async (t) => {
+  const { loadImage } = await import('./photoViewer.js');
+  const saved = {
+    fetch: globalThis.fetch,
+    createImageBitmap: globalThis.createImageBitmap,
+  };
+  t.after(() => Object.assign(globalThis, saved));
+  let decoded = 0;
+  globalThis.createImageBitmap = async () => {
+    decoded++;
+    return { width: 10, height: 10 };
+  };
+  // A 1 kB PNG that says it is 16,384 × 16,384.
+  const png = new Uint8Array(1024);
+  png.set([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a, 0, 0, 0, 13]);
+  png.set(
+    [...'IHDR'].map((c) => c.charCodeAt(0)),
+    12,
+  );
+  png.set([0, 0, 0x40, 0, 0, 0, 0x40, 0], 16);
+  globalThis.fetch = async () => new Response(png);
+  await assert.rejects(
+    loadImage('https://x/bomb.png'),
+    (error) => error.tooLarge === true,
+  );
+  assert.equal(decoded, 0, 'never decoded');
+});
+
+test('an <img> that turns out too large is refused and let go', async (t) => {
+  const { loadImage, MAX_IMAGE_SIDE } = await import('./photoViewer.js');
+  const saved = globalThis.Image;
+  t.after(() => (globalThis.Image = saved));
+  let size = [MAX_IMAGE_SIDE + 1, 100];
+  const images = [];
+  globalThis.Image = class {
+    constructor() {
+      images.push(this);
+    }
+    set src(value) {
+      this._src = value;
+      if (value)
+        queueMicrotask(() => {
+          [this.naturalWidth, this.naturalHeight] = size;
+          this.onload?.();
+        });
+    }
+    get src() {
+      return this._src;
+    }
+  };
+  await assert.rejects(
+    loadImage('https://x/a.jpg', { crossOrigin: false }),
+    (error) => error.tooLarge === true,
+  );
+  assert.equal(images.at(-1).src, '', 'its pixels let go');
+  size = [4000, 3000];
+  const ok = await loadImage('https://x/b.jpg', { crossOrigin: false });
+  assert.equal(ok.naturalWidth, 4000);
+  // An aborted <img> load stops and rejects.
+  size = [10, 10];
+  const controller = new AbortController();
+  const aborted = loadImage('https://x/c.jpg', {
+    crossOrigin: false,
+    signal: controller.signal,
+  });
+  controller.abort();
+  await assert.rejects(aborted);
+  assert.equal(images.at(-1).src, '', 'its download stops');
+});

src/layers/streetLevel/policy.js

@@ -1,17 +1,9 @@
-/** 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';
+// Reached by the providers' source modules (no browser globals, see
+// check:boundaries), so no i18n import: the text stays English data here.
+const msg = (text) => text;
 
-/** What the provider needs from its source (source.js or a stand-in). */
-export const MAPILLARY_SOURCE_METHODS = Object.freeze([
-  'getStatus',
-  'getTile',
-  'getSequenceImages',
-]);
+/** Identity and shared tuning for the provider-neutral Street Level layer. */
+export const STREET_LEVEL_LAYER_ID = 'street-level';
 
 /**
  * The pixel window a click picks in: coverage lines are 2.5 px wide and there
@@ -19,19 +11,19 @@ export const MAPILLARY_SOURCE_METHODS = Object.freeze([
  */
 export const CLICK_PICK_WINDOW_PX = 9;
 
-/** Pick id of the viewer position marker. */
+/** Pick id of the viewer position marker; the core owns it, not a provider. */
 export const POSITION_PICK_ID = 'sl:pos';
 
-/** Stable id prefixes for picked primitives; every one starts with `mly:`. */
-export const PICK_PREFIX = Object.freeze({
-  root: 'mly:',
-  sequence: 'mly:seq:',
-  image: 'mly:img:',
+/** One colour per imagery source: chip, coverage lines and cones. */
+export const PROVIDER_COLORS = Object.freeze({
+  mapillary: '#05cb63',
+  google: '#4285f4',
+  kartaview: '#635bff',
+  panoramax: '#ff6f00',
 });
 
-/** Mapillary green for lines and cones, GEV cyan for the selection, amber for the marker. */
+/** Colours every provider shares: the selection highlight and the marker. */
 export const COLORS = Object.freeze({
-  coverage: '#05cb63',
   selected: '#00d4ff',
   position: '#ffb300',
 });
@@ -42,49 +34,25 @@ export const PANO_MODES = Object.freeze(['all', 'pano', 'flat']);
 /** Longest "captured since" window the filter accepts, in days (~100 years). */
 export const MAX_SINCE_DAYS = 36_500;
 
-/** Filter the layer starts with: all imagery, any date. */
+/** Filter every provider starts with: all imagery, any date. */
 export const FILTER_DEFAULT = Object.freeze({ pano: 'all', sinceDays: 0 });
 
-/** Camera-driven coverage refresh. */
-export const COVERAGE_MOVE_DEBOUNCE_MS = 320;
-export const COVERAGE_MAX_TILES = 9;
-/** Shown when Mapillary refuses the server's token (401/403). */
-export const KEY_REJECTED_MESSAGE =
-  'Mapillary rejected MAPILLARY_CLIENT_TOKEN — replace it in Provider Settings';
-/** Shown while Mapillary rate-limits tile requests (429). */
-export const RATE_LIMITED_MESSAGE =
-  'Coverage requests are being rate-limited — they resume on their own';
-/**
- * Street-zoom coverage reaches this far from the camera: camera height times
- * the factor, never below the floor, even when a tilted view sees further.
- */
-export const SEQUENCE_VIEW_RANGE_MIN_M = 2_500;
-export const SEQUENCE_VIEW_RANGE_PER_HEIGHT = 10;
-export const COVERAGE_MAX_SEQUENCES = 6000;
-export const COVERAGE_LINE_WIDTH_PX = 2.5;
+/** Nearest-image search radius in metres. */
+export const NEAREST_RADIUS_M = 50;
 
-/** Per-sequence image cones after a sequence is selected. */
-export const SEQUENCE_IMAGES_LIMIT = 2000;
-export const IMAGE_CONE_SIZE_PX = 26;
-export const IMAGE_CONE_MIN_SPACING_M = 3;
+/** The Google 3D map stack: Street View may be shown only on it. */
+export const GOOGLE_3D_MAP_STACK_ID = 'photoreal';
 
-/** On-globe credit: Mapillary imagery is CC BY-SA 4.0 and needs attribution. */
-export const MAPILLARY_CREDIT_HTML =
-  'Street Level: imagery © <a href="https://www.mapillary.com" target="_blank" rel="noopener">Mapillary</a> contributors, CC BY-SA 4.0';
+/** Above this, a ground click is a misclick, not a street. */
+export const GROUND_CLICK_MAX_HEIGHT_M = 3_000;
 
-/** Deep link to an image on mapillary.com, as the web app shares them. */
-export function mapillaryImageUrl(imageId) {
-  const id = String(imageId || '').trim();
-  if (!id) return 'https://www.mapillary.com/app/';
-  return `https://www.mapillary.com/app/?pKey=${encodeURIComponent(id)}&focus=photo`;
-}
-
-/** Fields requested for a sequence's images. */
-export const SEQUENCE_IMAGE_FIELDS =
-  'id,captured_at,compass_angle,geometry,is_pano';
+/** English data: the Street Level panel translates it (translateKnown). */
+export const AIM_AT_GROUND_MESSAGE = msg(
+  'Aim the middle of the view at a street to look for imagery there',
+);
 
 /** The key gate's label for the pill and the layer list, or null when the key is fine. */
 export function keyStatusLabel({ keyRequired, keyRejected }) {
-  if (keyRejected) return 'KEY REJECTED';
-  return keyRequired ? 'KEY REQUIRED' : null;
+  if (keyRejected) return msg('KEY REJECTED');
+  return keyRequired ? msg('KEY REQUIRED') : null;
 }

src/layers/streetLevel/providers/google/index.js

@@ -0,0 +1,181 @@
+import { GOOGLE_3D_MAP_STACK_ID } from '../../policy.js';
+import { createMapsLoader } from './mapsLoader.js';
+import { getLocale } from '../../../../i18n/index.js';
+import { createGoogleViewer } from './viewer.js';
+import {
+  COLORS,
+  GOOGLE_CREDIT_HTML,
+  GOOGLE_KEY_ID,
+  GOOGLE_LABEL,
+  GOOGLE_NAME,
+  GOOGLE_PROVIDER_ID,
+  GROUND_CLICK_HINT,
+  KEY_REJECTED_MESSAGE,
+  NEAREST_RADIUS_M,
+  NEAREST_TIMEOUT_MS,
+  NO_ANSWER_MESSAGE,
+  PICK_PREFIX,
+} from './policy.js';
+
+/** `promise`, unless it times out, `signal` aborts or Google refuses the key. */
+function settleWithin(promise, { ms, signal, loader }) {
+  return new Promise((resolve, reject) => {
+    const timer = setTimeout(
+      () => finish(reject, new Error(NO_ANSWER_MESSAGE)),
+      ms,
+    );
+    const onAbort = () => finish(reject, signal.reason);
+    signal?.addEventListener('abort', onAbort, { once: true });
+    const stopAuthWatch = loader.onAuthFailure(() =>
+      finish(reject, new Error(KEY_REJECTED_MESSAGE)),
+    );
+    promise.then(
+      (value) => finish(resolve, value),
+      (error) => finish(reject, error),
+    );
+    function finish(settle, value) {
+      clearTimeout(timer);
+      signal?.removeEventListener('abort', onAbort);
+      stopAuthWatch();
+      settle(value);
+    }
+  });
+}
+
+/**
+ * Google Street View provider: Google's panorama viewer and nearest-panorama
+ * lookups. It draws no coverage; a click on a street opens the panorama.
+ * @returns {import('../../registry.js').StreetLevelProvider}
+ */
+export function createGoogleProvider({
+  getApiKey,
+  loader = createMapsLoader({ getApiKey, getLanguage: getLocale }),
+}) {
+  if (typeof getApiKey !== 'function')
+    throw new TypeError('Google Street View needs getApiKey');
+
+  return Object.freeze({
+    id: GOOGLE_PROVIDER_ID,
+    name: GOOGLE_NAME,
+    label: GOOGLE_LABEL,
+    requiresKeyId: GOOGLE_KEY_ID,
+    pickPrefix: PICK_PREFIX.root,
+    colors: COLORS,
+    credit: Object.freeze({ html: GOOGLE_CREDIT_HTML }),
+    groundClick: true,
+    // Google's terms forbid Street View beside non-Google maps.
+    requiresMapStack: GOOGLE_3D_MAP_STACK_ID,
+    // Every panorama is billed to the Maps key.
+    defaultOn: false,
+    // All 360°, and no coverage for a date filter to thin.
+    filters: [],
+    marker: Object.freeze({ kind: 'view-cone', color: COLORS.coverage }),
+
+    create(context) {
+      let keyRequired = !getApiKey();
+      let active = false;
+      let service = null;
+      async function getService() {
+        const lib = await loader.importLibrary('streetView');
+        service ||= new lib.StreetViewService();
+        return service;
+      }
+      const viewer = createGoogleViewer({
+        loader,
+        getService,
+        render: context.services?.render,
+      });
+      const stopAuthWatch = loader.onAuthFailure(() => {
+        // Switched off: its chip says so.
+        if (context.isActive?.())
+          context.actions.reportError(KEY_REJECTED_MESSAGE);
+        context.notify();
+      });
+
+      return {
+        async status() {
+          keyRequired = !getApiKey();
+          context.notify();
+          return { configured: !keyRequired };
+        },
+
+        init() {},
+
+        activate() {
+          active = true;
+        },
+
+        deactivate() {
+          active = false;
+        },
+
+        destroy() {
+          active = false;
+          stopAuthWatch();
+        },
+
+        /** No filter applies to Street View (see `filters`). */
+        setFilter() {},
+
+        coverageStats() {
+          const keyRejected = loader.authFailed();
+          return {
+            count: 0,
+            loading: false,
+            hint:
+              !active || keyRequired || keyRejected ? '' : GROUND_CLICK_HINT,
+            error: keyRejected ? KEY_REJECTED_MESSAGE : null,
+            keyRequired,
+            keyRejected,
+          };
+        },
+
+        handlePick: () => false,
+
+        /**
+         * Nearest Google-collected outdoor panorama, or null. The imagery
+         * filters do not apply (see `filters`).
+         */
+        async nearestImage({ lat, lon }, { signal } = {}) {
+          if (loader.authFailed()) throw new Error(KEY_REJECTED_MESSAGE);
+          signal?.throwIfAborted();
+          // Set once the caller has its answer (aborted, timed out, refused):
+          // a lookup still waiting on Google's script then asks nothing.
+          let settled = false;
+          const lookup = (async () => {
+            const lib = await loader.importLibrary('streetView');
+            await getService();
+            if (settled) return null;
+            const { GOOGLE, OUTDOOR } = lib.StreetViewSource;
+            try {
+              const { data } = await service.getPanorama({
+                location: { lat, lng: lon },
+                radius: NEAREST_RADIUS_M,
+                // Both: Google's own imagery, outdoors (sources intersect).
+                sources: [GOOGLE, OUTDOOR],
+                preference: lib.StreetViewPreference.NEAREST,
+              });
+              return data;
+            } catch (error) {
+              if (error?.code === 'ZERO_RESULTS') return null;
+              throw error;
+            }
+          })();
+          const data = await settleWithin(lookup, {
+            ms: NEAREST_TIMEOUT_MS,
+            signal,
+            loader,
+          }).finally(() => {
+            settled = true;
+          });
+          const panoId = data?.location?.pano;
+          if (!panoId) return null;
+          viewer.remember(panoId, data);
+          return panoId;
+        },
+
+        viewer,
+      };
+    },
+  });
+}

src/layers/streetLevel/providers/google/mapsLoader.js

@@ -0,0 +1,93 @@
+/**
+ * Loads the Google Maps JavaScript API once per page, on first use. Google's
+ * `gm_authFailure` (key refused) reaches every `onAuthFailure` listener.
+ */
+
+import { msg } from '../../../../i18n/index.js';
+
+const SCRIPT_ORIGIN = 'https://maps.googleapis.com';
+const READY_CALLBACK = '__gevGoogleMapsReady';
+/** The page's one script load, shared by every loader on it. */
+const PAGE_LOAD = Symbol.for('gev.googleMapsLoad');
+
+/**
+ * @param {{getApiKey: () => string|null|undefined, getLanguage?: () => string|null|undefined, document?: Document, global?: object}} options
+ *   `getLanguage` names the UI language; Google's own controls (Terms,
+ *   Report a problem) follow it. English adds nothing, as before.
+ */
+export function createMapsLoader({
+  getApiKey,
+  getLanguage,
+  document = globalThis.document,
+  global = globalThis,
+}) {
+  let authFailed = false;
+  let authHandlerInstalled = false;
+  const authListeners = new Set();
+
+  /** Once per loader: a retry must not wrap its own handler. */
+  function installAuthHandler() {
+    if (authHandlerInstalled) return;
+    authHandlerInstalled = true;
+    const previous = global.gm_authFailure;
+    global.gm_authFailure = () => {
+      authFailed = true;
+      for (const listener of [...authListeners]) {
+        try {
+          listener();
+        } catch {
+          /* a listener's error is its own */
+        }
+      }
+      if (typeof previous === 'function') previous();
+    };
+  }
+
+  function load() {
+    const key = getApiKey?.();
+    if (!key)
+      return Promise.reject(new Error(msg('GOOGLE_MAPS_API_KEY is not set')));
+    installAuthHandler();
+    if (global[PAGE_LOAD]) return global[PAGE_LOAD];
+    if (global.google?.maps?.importLibrary)
+      return Promise.resolve(global.google.maps);
+    const loading = new Promise((resolve, reject) => {
+      global[READY_CALLBACK] = () => {
+        delete global[READY_CALLBACK];
+        resolve(global.google.maps);
+      };
+      const script = document.createElement('script');
+      script.async = true;
+      const params = new URLSearchParams({
+        key,
+        v: 'weekly',
+        loading: 'async',
+        callback: READY_CALLBACK,
+      });
+      const language = getLanguage?.();
+      if (language && language !== 'en') params.set('language', language);
+      script.src = `${SCRIPT_ORIGIN}/maps/api/js?${params}`;
+      script.onerror = () => {
+        if (global[PAGE_LOAD] === loading) delete global[PAGE_LOAD];
+        script.remove();
+        delete global[READY_CALLBACK];
+        reject(new Error(msg('The Google Maps JavaScript API could not load')));
+      };
+      document.head.append(script);
+    });
+    global[PAGE_LOAD] = loading;
+    return loading;
+  }
+
+  return {
+    async importLibrary(name) {
+      const maps = await load();
+      return maps.importLibrary(name);
+    },
+    authFailed: () => authFailed,
+    onAuthFailure(listener) {
+      authListeners.add(listener);
+      return () => authListeners.delete(listener);
+    },
+  };
+}

src/layers/streetLevel/providers/google/mapsLoader.test.mjs

@@ -0,0 +1,160 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import { createMapsLoader } from './mapsLoader.js';
+
+/** A document whose appended scripts the test loads or fails. */
+function fakePage() {
+  const scripts = [];
+  const document = {
+    createElement: () => {
+      const script = {
+        remove() {
+          scripts.splice(scripts.indexOf(script), 1);
+        },
+      };
+      return script;
+    },
+    head: { append: (script) => scripts.push(script) },
+  };
+  const global = {};
+  const library = { name: 'streetView' };
+  /** Google's script arrived: it defines google.maps and calls back. */
+  const loadScript = () => {
+    global.google = {
+      maps: { importLibrary: async (name) => ({ ...library, name }) },
+    };
+    const callback = new URL(scripts.at(-1).src).searchParams.get('callback');
+    global[callback]();
+  };
+  return { document, global, scripts, loadScript };
+}
+
+const settle = () => new Promise((resolve) => setTimeout(resolve, 0));
+
+test('the API loads once, with the key, asynchronously, and hands out libraries', async () => {
+  const page = fakePage();
+  const loader = createMapsLoader({ getApiKey: () => 'k-1', ...page });
+  const first = loader.importLibrary('streetView');
+  const second = loader.importLibrary('streetView');
+  await settle();
+  assert.equal(page.scripts.length, 1, 'one script for concurrent imports');
+  const url = new URL(page.scripts[0].src);
+  assert.equal(
+    url.origin + url.pathname,
+    'https://maps.googleapis.com/maps/api/js',
+  );
+  assert.equal(url.searchParams.get('key'), 'k-1');
+  assert.equal(url.searchParams.get('loading'), 'async');
+  assert.equal(page.scripts[0].async, true);
+  page.loadScript();
+  assert.equal((await first).name, 'streetView');
+  assert.equal((await second).name, 'streetView');
+  const callback = url.searchParams.get('callback');
+  assert.equal(page.global[callback], undefined, 'the callback is cleaned up');
+});
+
+test('two loaders on one page share one script and both get the API', async () => {
+  const page = fakePage();
+  const first = createMapsLoader({ getApiKey: () => 'k', ...page });
+  const second = createMapsLoader({ getApiKey: () => 'k', ...page });
+  const one = first.importLibrary('streetView');
+  const two = second.importLibrary('streetView');
+  await settle();
+  assert.equal(page.scripts.length, 1, 'one script for the page');
+  page.loadScript();
+  assert.equal((await one).name, 'streetView');
+  assert.equal((await two).name, 'streetView');
+  assert.equal((await first.importLibrary('streetView')).name, 'streetView');
+});
+
+test('after a failed script, either loader on the page can retry it', async () => {
+  const page = fakePage();
+  const first = createMapsLoader({ getApiKey: () => 'k', ...page });
+  const second = createMapsLoader({ getApiKey: () => 'k', ...page });
+  const failed = first.importLibrary('streetView');
+  await settle();
+  page.scripts[0].onerror();
+  await assert.rejects(failed, /could not load/);
+  const retry = second.importLibrary('streetView');
+  const again = first.importLibrary('streetView');
+  await settle();
+  assert.equal(page.scripts.length, 1);
+  page.loadScript();
+  assert.equal((await retry).name, 'streetView');
+  assert.equal((await again).name, 'streetView');
+});
+
+test('without a key nothing loads', async () => {
+  const page = fakePage();
+  const loader = createMapsLoader({ getApiKey: () => null, ...page });
+  await assert.rejects(loader.importLibrary('streetView'), /not set/);
+  assert.equal(page.scripts.length, 0);
+});
+
+test('a script that fails to load can be retried', async () => {
+  const page = fakePage();
+  const loader = createMapsLoader({ getApiKey: () => 'k', ...page });
+  const failed = loader.importLibrary('streetView');
+  await settle();
+  page.scripts[0].onerror();
+  await assert.rejects(failed, /could not load/);
+  assert.equal(page.scripts.length, 0, 'the failed script is removed');
+  const retry = loader.importLibrary('streetView');
+  await settle();
+  assert.equal(page.scripts.length, 1);
+  page.loadScript();
+  assert.equal((await retry).name, 'streetView');
+});
+
+test("Google's refusal of the key reaches every listener and the page's own handler", async () => {
+  const page = fakePage();
+  let before = 0;
+  page.global.gm_authFailure = () => before++;
+  const loader = createMapsLoader({ getApiKey: () => 'k', ...page });
+  const heard = [];
+  const stop = loader.onAuthFailure(() => heard.push('a'));
+  loader.importLibrary('streetView');
+  await settle();
+  assert.equal(loader.authFailed(), false);
+  page.global.gm_authFailure();
+  assert.equal(loader.authFailed(), true);
+  assert.deepEqual(heard, ['a']);
+  assert.equal(before, 1, 'a handler installed earlier still runs');
+  stop();
+  page.global.gm_authFailure();
+  assert.deepEqual(heard, ['a']);
+});
+
+test('a retried load still reports a refusal once, and the page handler once', async () => {
+  const page = fakePage();
+  let before = 0;
+  page.global.gm_authFailure = () => before++;
+  const loader = createMapsLoader({ getApiKey: () => 'k', ...page });
+  const heard = [];
+  loader.onAuthFailure(() => heard.push('a'));
+  const failed = loader.importLibrary('streetView');
+  await settle();
+  page.scripts[0].onerror();
+  await assert.rejects(failed);
+  loader.importLibrary('streetView');
+  await settle();
+  page.global.gm_authFailure();
+  assert.deepEqual(heard, ['a']);
+  assert.equal(before, 1);
+});
+
+test('Google controls follow the UI language; English adds no parameter', async () => {
+  const language = (locale) => {
+    const page = fakePage();
+    const loader = createMapsLoader({
+      getApiKey: () => 'k-1',
+      getLanguage: () => locale,
+      ...page,
+    });
+    void loader.importLibrary('streetView').catch(() => {});
+    return new URL(page.scripts[0].src).searchParams.get('language');
+  };
+  assert.equal(language('es'), 'es');
+  assert.equal(language('ru'), 'ru');
+  assert.equal(language('en'), null);
+});

src/layers/streetLevel/providers/google/policy.js

@@ -0,0 +1,68 @@
+import { COLORS as SHARED_COLORS, PROVIDER_COLORS } from '../../policy.js';
+import { msg } from '../../../../i18n/index.js';
+
+export { NEAREST_RADIUS_M } from '../../policy.js';
+
+export const GOOGLE_PROVIDER_ID = 'google';
+export const GOOGLE_NAME = msg('Google Street View');
+export const GOOGLE_LABEL = msg('GOOGLE STREET VIEW');
+/** The browser Maps key; Street View also needs the Maps JavaScript API on it. */
+export const GOOGLE_KEY_ID = 'google-maps';
+
+export const PICK_PREFIX = Object.freeze({ root: 'gsv:' });
+
+export const COLORS = Object.freeze({
+  coverage: PROVIDER_COLORS.google,
+  selected: SHARED_COLORS.selected,
+});
+
+export const GOOGLE_CREDIT_HTML =
+  'Street View imagery © <a href="https://www.google.com/streetview/" target="_blank" rel="noopener">Google</a>';
+
+/** Shown when Google refuses the key (gm_authFailure). */
+export const KEY_REJECTED_MESSAGE = msg(
+  'Google refused GOOGLE_MAPS_API_KEY for Street View — check that the Maps JavaScript API is enabled for it and this site is an allowed referrer',
+);
+
+/** Past these, a nearest lookup, an open or a details lookup has failed. */
+export const NEAREST_TIMEOUT_MS = 10_000;
+export const OPEN_TIMEOUT_MS = 20_000;
+export const DETAILS_TIMEOUT_MS = 10_000;
+/** Pause after a failed details lookup before a view event can retry. */
+export const DETAILS_RETRY_COOLDOWN_MS = 5_000;
+
+export const NO_ANSWER_MESSAGE = msg(
+  'Street View did not answer — check the network, and that the Maps JavaScript API is enabled for GOOGLE_MAPS_API_KEY',
+);
+
+export const GROUND_CLICK_HINT = msg('click a street to open Street View');
+
+/** Deep link to a panorama on Google Maps (Maps URLs). */
+export function streetViewUrl(panoId, { heading = 0, pitch = 0 } = {}) {
+  const params = new URLSearchParams({
+    api: '1',
+    map_action: 'pano',
+    pano: String(panoId),
+    heading: String(Math.round(heading)),
+    pitch: String(Math.round(pitch)),
+  });
+  return `https://www.google.com/maps/@?${params}`;
+}
+
+/** Epoch ms for a Street View image date ('YYYY-MM'), or null. */
+export function imageDateMs(imageDate) {
+  const match = /^(\d{4})-(\d{2})/.exec(String(imageDate ?? ''));
+  if (!match) return null;
+  const month = Number(match[2]);
+  if (month < 1 || month > 12) return null;
+  return Date.UTC(Number(match[1]), month - 1, 1);
+}
+
+/** The photographer from a copyright line ('© 2024 Google' → 'Google'). */
+export function creatorFrom(copyright) {
+  const text = String(copyright ?? '')
+    .replace(/^©\s*(\d{4}\s+)?/, '')
+    .replace(/^From the Owner,\s*Photo by:\s*/i, '')
+    .trim();
+  return text || null;
+}

src/layers/streetLevel/providers/google/provider.test.mjs

@@ -0,0 +1,293 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import { createGoogleProvider } from './index.js';
+import {
+  GROUND_CLICK_HINT,
+  KEY_REJECTED_MESSAGE,
+  creatorFrom,
+  imageDateMs,
+  streetViewUrl,
+} from './policy.js';
+import { PROVIDER_COLORS } from '../../policy.js';
+import { requiresKeyIdFor, validateProviders } from '../../registry.js';
+import { createMapillaryProvider } from '../mapillary/index.js';
+import {
+  fakeHost,
+  fakeMapsLoader,
+  fakeStreetViewLibrary,
+} from '../../../../testSupport/googleStreetViewFakes.mjs';
+
+const PANORAMAS = {
+  fresh: { lat: 38.5816, lng: -121.4944, imageDate: '2025-06' },
+  old: { lat: 38.6, lng: -121.5, imageDate: '2009-03' },
+};
+
+function setup({ key = 'browser-key', nearest = () => 'fresh' } = {}) {
+  const fake = fakeStreetViewLibrary({ panoramas: PANORAMAS, nearest });
+  const loader = fakeMapsLoader(fake.library);
+  let apiKey = key;
+  const def = createGoogleProvider({ getApiKey: () => apiKey, loader });
+  const reported = [];
+  let filter = { pano: 'all', sinceMs: null };
+  let active = false;
+  const context = {
+    services: {},
+    getFilter: () => filter,
+    isActive: () => active,
+    notify() {},
+    actions: { reportError: (message) => reported.push(message) },
+  };
+  const created = def.create(context);
+  // The core switches it on and off; mirror that for isActive().
+  const instance = {
+    ...created,
+    activate() {
+      active = true;
+      created.activate();
+    },
+    deactivate() {
+      active = false;
+      created.deactivate();
+    },
+  };
+  return {
+    def,
+    instance,
+    fake,
+    loader,
+    reported,
+    setFilter: (next) => (filter = next),
+    setKey: (next) => (apiKey = next),
+  };
+}
+
+test('the provider registers beside Mapillary, off by default, gated on the browser Maps key', () => {
+  const { def } = setup();
+  assert.equal(def.id, 'google');
+  assert.equal(def.label, 'GOOGLE STREET VIEW');
+  assert.deepEqual(def.filters, [], 'no imagery filter applies');
+  assert.deepEqual(def.marker, { kind: 'view-cone', color: '#4285f4' });
+  assert.equal(def.requiresKeyId, 'google-maps');
+  assert.equal(def.defaultOn, false, 'every panorama is billed');
+  assert.equal(def.groundClick, true);
+  assert.equal(def.colors.coverage, PROVIDER_COLORS.google);
+  assert.match(def.credit.html, /Street View imagery © .*Google/);
+  const mapillary = createMapillaryProvider({
+    source: {
+      getStatus() {},
+      getTile() {},
+      getSequenceImages() {},
+      nearestImages() {},
+    },
+  });
+  const both = validateProviders([mapillary, def]);
+  assert.equal(requiresKeyIdFor(both), null, 'each chip gates on its own key');
+  assert.throws(() => createGoogleProvider({}), /getApiKey/);
+});
+
+test('status follows the browser Maps key', async () => {
+  const { instance, setKey } = setup({ key: '' });
+  assert.deepEqual(await instance.status(), { configured: false });
+  assert.equal(instance.coverageStats().keyRequired, true);
+  setKey('browser-key');
+  assert.deepEqual(await instance.status(), { configured: true });
+  assert.equal(instance.coverageStats().keyRequired, false);
+});
+
+test('the nearest lookup asks Google for its own outdoor imagery within 50 m', async () => {
+  const { instance, fake } = setup();
+  assert.equal(
+    await instance.nearestImage({ lat: 38.58, lon: -121.49 }),
+    'fresh',
+  );
+  const [request] = fake.lookups;
+  assert.deepEqual(request.location, { lat: 38.58, lng: -121.49 });
+  assert.equal(request.radius, 50);
+  assert.deepEqual(request.sources, ['google', 'outdoor']);
+  assert.equal(request.preference, 'nearest');
+});
+
+test('no panorama nearby is null; the imagery filters (Mapillary\u2019s) do not apply', async () => {
+  const none = setup({ nearest: () => null });
+  assert.equal(await none.instance.nearestImage({ lat: 0, lon: 0 }), null);
+
+  const { instance, setFilter } = setup({ nearest: () => 'old' }); // 2009
+  for (const filter of [
+    { pano: 'all', sinceMs: Date.UTC(2020, 0, 1) },
+    { pano: 'flat', sinceMs: null },
+    { pano: 'pano', sinceMs: Date.UTC(2025, 0, 1) },
+  ]) {
+    setFilter(filter);
+    assert.equal(await instance.nearestImage({ lat: 0, lon: 0 }), 'old');
+  }
+  assert.equal(instance.coverageStats().hint, '', 'off: no hint');
+  instance.activate();
+  setFilter({ pano: 'flat', sinceMs: null });
+  assert.equal(instance.coverageStats().hint, GROUND_CLICK_HINT);
+});
+
+test('an aborted lookup gives up before asking Google', async () => {
+  const { instance } = setup();
+  const controller = new AbortController();
+  controller.abort();
+  await assert.rejects(
+    instance.nearestImage({ lat: 0, lon: 0 }, { signal: controller.signal }),
+    { name: 'AbortError' },
+  );
+});
+
+test('a key Google refuses reads KEY REJECTED, shows why, and stops lookups', async () => {
+  const { instance, loader, reported } = setup();
+  instance.activate();
+  assert.equal(instance.coverageStats().hint, GROUND_CLICK_HINT);
+  loader.refuseKey();
+  const stats = instance.coverageStats();
+  assert.equal(stats.keyRejected, true);
+  assert.equal(stats.error, KEY_REJECTED_MESSAGE);
+  assert.equal(stats.hint, '', 'no "click a street" hint over a dead key');
+  assert.deepEqual(reported, [KEY_REJECTED_MESSAGE]);
+  await assert.rejects(instance.nearestImage({ lat: 0, lon: 0 }), {
+    message: KEY_REJECTED_MESSAGE,
+  });
+  instance.destroy();
+  assert.equal(loader.listenerCount(), 0, 'destroy stops listening');
+});
+
+test('the hint shows only while the provider is on', () => {
+  const { instance } = setup();
+  assert.equal(instance.coverageStats().hint, '');
+  instance.activate();
+  assert.equal(instance.coverageStats().hint, GROUND_CLICK_HINT);
+  instance.deactivate();
+  assert.equal(instance.coverageStats().hint, '');
+});
+
+test('image dates, photographers and deep links read the way Google writes them', () => {
+  assert.equal(imageDateMs('2024-05'), Date.UTC(2024, 4, 1));
+  assert.equal(imageDateMs('2024-13'), null);
+  assert.equal(imageDateMs(undefined), null);
+  assert.equal(creatorFrom('© 2024 Google'), 'Google');
+  assert.equal(creatorFrom('From the Owner, Photo by: Ada'), 'Ada');
+  assert.equal(creatorFrom(''), null);
+  assert.equal(
+    streetViewUrl('a b', { heading: 90.4, pitch: -9.6 }),
+    'https://www.google.com/maps/@?api=1&map_action=pano&pano=a+b&heading=90&pitch=-10',
+  );
+});
+
+test('a lookup Google never answers fails after the timeout, and a refused key fails it at once', async (t) => {
+  t.mock.timers.enable({ apis: ['setTimeout'] });
+  const { NEAREST_TIMEOUT_MS, NO_ANSWER_MESSAGE } = await import('./policy.js');
+  const { instance, fake, loader } = setup();
+  fake.library.StreetViewService.prototype.getPanorama = () =>
+    new Promise(() => {});
+  const hung = instance.nearestImage({ lat: 0, lon: 0 });
+  await Promise.resolve();
+  await Promise.resolve();
+  t.mock.timers.tick(NEAREST_TIMEOUT_MS);
+  await assert.rejects(hung, { message: NO_ANSWER_MESSAGE });
+
+  const refused = instance.nearestImage({ lat: 0, lon: 0 });
+  await Promise.resolve();
+  loader.refuseKey();
+  await assert.rejects(refused, { message: KEY_REJECTED_MESSAGE });
+  assert.equal(
+    loader.listenerCount(),
+    1,
+    'only the provider’s own watch is left',
+  );
+});
+
+test('aborting a lookup in flight gives up at once', async () => {
+  const { instance, fake } = setup();
+  fake.library.StreetViewService.prototype.getPanorama = () =>
+    new Promise(() => {});
+  const controller = new AbortController();
+  const lookup = instance.nearestImage(
+    { lat: 0, lon: 0 },
+    { signal: controller.signal },
+  );
+  controller.abort();
+  await assert.rejects(lookup, { name: 'AbortError' });
+});
+
+test('a lookup cancelled while Google\u2019s script loads asks Google nothing', async (t) => {
+  t.mock.timers.enable({ apis: ['setTimeout'] });
+  const { NEAREST_TIMEOUT_MS } = await import('./policy.js');
+  const fake = fakeStreetViewLibrary({
+    panoramas: PANORAMAS,
+    nearest: () => 'fresh',
+  });
+  const loader = fakeMapsLoader(fake.library, { deferred: true });
+  const instance = createGoogleProvider({
+    getApiKey: () => 'browser-key',
+    loader,
+  }).create({
+    services: {},
+    getFilter: () => ({ pano: 'all', sinceMs: null }),
+    isActive: () => true,
+    notify() {},
+    actions: { reportError() {} },
+  });
+  const flush = async () => {
+    for (let i = 0; i < 10; i++) await Promise.resolve();
+  };
+  // Aborted, then timed out, while the script still loads.
+  const controller = new AbortController();
+  const aborted = instance.nearestImage(
+    { lat: 0, lon: 0 },
+    { signal: controller.signal },
+  );
+  controller.abort();
+  await assert.rejects(aborted, { name: 'AbortError' });
+  const expired = instance.nearestImage({ lat: 0, lon: 0 });
+  t.mock.timers.tick(NEAREST_TIMEOUT_MS);
+  await assert.rejects(expired, /did not answer/);
+  // The script arrives: a current lookup still gets its answer.
+  const current = instance.nearestImage({ lat: 0, lon: 0 });
+  loader.release();
+  await flush();
+  assert.equal(await current, 'fresh');
+  assert.equal(fake.lookups.length, 1, 'only the current lookup asked Google');
+});
+
+test('a Google outage is an error, not "no imagery here"', async () => {
+  const { instance, fake } = setup();
+  fake.library.StreetViewService.prototype.getPanorama = () =>
+    Promise.reject(
+      Object.assign(new Error('UNKNOWN_ERROR'), {
+        code: 'UNKNOWN_ERROR',
+        endpoint: 'STREETVIEW_GET_PANORAMA',
+      }),
+    );
+  await assert.rejects(instance.nearestImage({ lat: 0, lon: 0 }), {
+    code: 'UNKNOWN_ERROR',
+  });
+});
+
+test('a refusal while the provider is off reports no error over another photo', () => {
+  const { instance, loader, reported } = setup();
+  loader.refuseKey();
+  assert.deepEqual(reported, []);
+  assert.equal(
+    instance.coverageStats().keyRejected,
+    true,
+    'its chip still says so',
+  );
+});
+
+test('the panorama a lookup found is dated without a second lookup', async () => {
+  const { instance, fake } = setup();
+  await instance.nearestImage({ lat: 38.58, lon: -121.49 });
+  const host = fakeHost();
+  const poses = [];
+  instance.viewer.onPose((pose) => poses.push(pose));
+  await instance.viewer.mount(host);
+  await instance.viewer.open('fresh');
+  assert.equal(poses.at(-1).capturedAt, Date.UTC(2025, 5, 1));
+  assert.deepEqual(
+    fake.lookups.filter((request) => request.pano),
+    [],
+    'no getPanorama({pano}) for a panorama the lookup already described',
+  );
+});

src/layers/streetLevel/providers/google/viewer.js

@@ -0,0 +1,290 @@
+import {
+  DETAILS_RETRY_COOLDOWN_MS,
+  DETAILS_TIMEOUT_MS,
+  GOOGLE_PROVIDER_ID,
+  KEY_REJECTED_MESSAGE,
+  NO_ANSWER_MESSAGE,
+  OPEN_TIMEOUT_MS,
+  creatorFrom,
+  imageDateMs,
+  streetViewUrl,
+} from './policy.js';
+import { msg } from '../../../../i18n/index.js';
+
+const PANORAMA_OPTIONS = Object.freeze({
+  visible: false,
+  // The caption has the address; Google's card covers a docked panorama.
+  addressControl: false,
+  linksControl: true,
+  panControl: true,
+  zoomControl: true,
+  clickToGo: true,
+  showRoadLabels: true,
+  // The panel has EXPAND and ×.
+  fullscreenControl: false,
+  enableCloseButton: false,
+  motionTracking: false,
+  motionTrackingControl: false,
+});
+
+/**
+ * Viewer adapter over Google's StreetViewPanorama: emits a pose for every
+ * panorama and view change, including steps along Google's arrows.
+ * @param {{loader: ReturnType<import('./mapsLoader.js').createMapsLoader>, getService?: () => Promise<object>, render?: object}} options
+ * @returns {import('../../registry.js').ViewerAdapter & {remember: Function}}
+ */
+export function createGoogleViewer({ loader, getService, render } = {}) {
+  let library = null;
+  let panorama = null;
+  let element = null;
+  let host = null;
+  let service = null;
+  let pendingOpen = null;
+  let cancelShown = null;
+  /** Bumped by `unmount`: a construction it overtook builds nothing. */
+  let generation = 0;
+  let subscriptions = [];
+  const described = new Map();
+  /** Panorama id → its lookup in flight; a late answer to a dropped one is ignored. */
+  const lookingUp = new Map();
+  const retryAfter = new Map();
+  const listeners = new Set();
+
+  function requestRender() {
+    render?.governorRequestRender?.('google-street-view');
+  }
+
+  async function ensureLibrary() {
+    library ||= await loader.importLibrary('streetView');
+    return library;
+  }
+
+  function emit(pose) {
+    for (const listener of [...listeners]) {
+      try {
+        listener(pose);
+      } catch {
+        /* listener errors are the core's to log */
+      }
+    }
+  }
+
+  function metaFrom(data) {
+    return {
+      capturedAt: imageDateMs(data?.imageDate),
+      creator: creatorFrom(data?.copyright),
+      title: data?.location?.description || null,
+    };
+  }
+
+  /**
+   * Look up a panorama's date, photographer and address once, then re-emit
+   * the pose. A failed or timed-out lookup can retry after the cooldown.
+   */
+  async function describe(panoId) {
+    if (described.has(panoId) || lookingUp.has(panoId)) return;
+    if (Date.now() < (retryAfter.get(panoId) ?? 0)) return;
+    const lookup = { timer: null };
+    lookingUp.set(panoId, lookup);
+    const current = () => lookingUp.get(panoId) === lookup;
+    try {
+      const { data } = await new Promise((resolve, reject) => {
+        lookup.timer = setTimeout(
+          () => reject(new Error(NO_ANSWER_MESSAGE)),
+          DETAILS_TIMEOUT_MS,
+        );
+        (async () => {
+          service ||= getService
+            ? await getService()
+            : new (await ensureLibrary()).StreetViewService();
+          if (!current())
+            throw new Error('Street View details lookup was released');
+          return service.getPanorama({ pano: panoId });
+        })().then(resolve, reject);
+      });
+      if (!current()) return;
+      described.set(panoId, metaFrom(data));
+      retryAfter.delete(panoId);
+    } catch {
+      if (current())
+        retryAfter.set(panoId, Date.now() + DETAILS_RETRY_COOLDOWN_MS);
+      return;
+    } finally {
+      clearTimeout(lookup.timer);
+      if (current()) lookingUp.delete(panoId);
+    }
+    publishPose();
+  }
+
+  function releaseLookups() {
+    for (const lookup of lookingUp.values()) clearTimeout(lookup.timer);
+    lookingUp.clear();
+  }
+
+  function publishPose() {
+    const panoId = panorama?.getPano?.();
+    const latLng = panorama?.getPosition?.();
+    if (!panoId || !latLng || pendingOpen === null) return;
+    const meta = described.get(panoId);
+    if (!meta) describe(panoId);
+    const pov = panorama.getPov() || {};
+    emit({
+      providerId: GOOGLE_PROVIDER_ID,
+      imageId: panoId,
+      position: { lon: latLng.lng(), lat: latLng.lat() },
+      bearing: Number.isFinite(pov.heading) ? pov.heading : null,
+      tilt: Number.isFinite(pov.pitch) ? pov.pitch : 0,
+      altitude: null,
+      isPano: true,
+      capturedAt: meta?.capturedAt ?? null,
+      capturedAtPrecision: 'month',
+      creator: meta?.creator ?? null,
+      title: meta?.title ?? null,
+      sequenceId: null,
+      externalUrl: streetViewUrl(panoId, {
+        heading: pov.heading || 0,
+        pitch: pov.pitch || 0,
+      }),
+    });
+    requestRender();
+  }
+
+  async function ensurePanorama(target) {
+    if (panorama && host === target) return panorama;
+    const built = generation;
+    const { StreetViewPanorama } = await ensureLibrary();
+    if (built !== generation) throw new Error('Street View was unmounted');
+    if (panorama && host === target) return panorama;
+    destroyPanorama();
+    element = target.ownerDocument.createElement('div');
+    element.className = 'sl-google-panorama';
+    element.style.cssText = 'position:absolute;inset:0;';
+    target.append(element);
+    host = target;
+    panorama = new StreetViewPanorama(element, PANORAMA_OPTIONS);
+    // Not pano_changed: it can fire with the old panorama's position.
+    subscriptions = ['position_changed', 'pov_changed'].map((name) =>
+      panorama.addListener(name, () => publishPose()),
+    );
+    return panorama;
+  }
+
+  function destroyPanorama() {
+    for (const subscription of subscriptions) subscription.remove();
+    subscriptions = [];
+    try {
+      panorama?.setVisible(false);
+    } catch {
+      /* already gone */
+    }
+    element?.remove();
+    panorama = null;
+    element = null;
+    host = null;
+  }
+
+  /**
+   * Resolves once `panoId` shows (OK status, or a new position when the
+   * status stays OK); rejects on no imagery, a refused key or no answer.
+   */
+  function shown(instance, panoId) {
+    if (instance.getPano() === panoId && instance.getStatus() === 'OK')
+      return Promise.resolve();
+    return new Promise((resolve, reject) => {
+      const timer = setTimeout(
+        () => finish(reject, new Error(NO_ANSWER_MESSAGE)),
+        OPEN_TIMEOUT_MS,
+      );
+      const stopAuthWatch = loader.onAuthFailure(() =>
+        finish(reject, new Error(KEY_REJECTED_MESSAGE)),
+      );
+      cancelShown = () => finish(resolve);
+      // At a position event the status may still be the last panorama's failure.
+      const onStatus = () => {
+        if (pendingOpen !== panoId) return finish(resolve);
+        const status = instance.getStatus();
+        if (status === 'OK') finish(resolve);
+        else if (status)
+          finish(
+            reject,
+            new Error(msg('Street View has no imagery for this place')),
+          );
+      };
+      const onPosition = () => {
+        if (pendingOpen !== panoId || instance.getStatus() === 'OK')
+          finish(resolve);
+      };
+      const subscriptions = [
+        instance.addListener('status_changed', onStatus),
+        instance.addListener('position_changed', onPosition),
+      ];
+      function finish(settle, value) {
+        cancelShown = null;
+        clearTimeout(timer);
+        for (const subscription of subscriptions) subscription.remove();
+        stopAuthWatch();
+        settle(value);
+      }
+    });
+  }
+
+  return {
+    async mount(target) {
+      if (!target) throw new Error('Street Level viewer has no host element');
+      await ensurePanorama(target);
+    },
+
+    async open(imageId) {
+      const panoId = String(imageId);
+      if (!host) throw new Error('Street View is not mounted');
+      if (loader.authFailed()) throw new Error(KEY_REJECTED_MESSAGE);
+      cancelShown?.();
+      pendingOpen = panoId;
+      const instance = await ensurePanorama(host);
+      if (pendingOpen !== panoId) return;
+      const ready = shown(instance, panoId);
+      instance.setPano(panoId);
+      instance.setVisible(true);
+      await ready;
+      if (pendingOpen !== panoId) return;
+      publishPose();
+    },
+
+    close() {
+      pendingOpen = null;
+      cancelShown?.();
+      try {
+        panorama?.setVisible(false);
+      } catch {
+        /* torn down */
+      }
+    },
+
+    unmount() {
+      pendingOpen = null;
+      cancelShown?.();
+      releaseLookups();
+      generation++;
+      destroyPanorama();
+    },
+
+    resize() {
+      if (!panorama) return;
+      try {
+        globalThis.google?.maps?.event?.trigger(panorama, 'resize');
+      } catch {
+        /* no-op */
+      }
+    },
+
+    onPose(listener) {
+      listeners.add(listener);
+      return () => listeners.delete(listener);
+    },
+
+    /** Seed the details cache from a nearest lookup's answer. */
+    remember(panoId, data) {
+      if (panoId && data) described.set(String(panoId), metaFrom(data));
+    },
+  };
+}

src/layers/streetLevel/providers/google/viewer.test.mjs

@@ -0,0 +1,471 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import { createGoogleViewer } from './viewer.js';
+import { DETAILS_RETRY_COOLDOWN_MS, DETAILS_TIMEOUT_MS } from './policy.js';
+import {
+  fakeHost,
+  fakeMapsLoader,
+  fakeStreetViewLibrary,
+} from '../../../../testSupport/googleStreetViewFakes.mjs';
+
+const PANORAMAS = {
+  'pano-a': {
+    lat: 38.5816,
+    lng: -121.4944,
+    imageDate: '2024-05',
+    copyright: '© 2024 Google',
+    description: '10th St',
+  },
+  'pano-b': {
+    lat: 38.5817,
+    lng: -121.4944,
+    imageDate: '2019-08',
+    copyright: 'From the Owner, Photo by: Ada',
+  },
+};
+
+function setup() {
+  const fake = fakeStreetViewLibrary({ panoramas: PANORAMAS });
+  const loader = fakeMapsLoader(fake.library);
+  const viewer = createGoogleViewer({ loader });
+  const poses = [];
+  viewer.onPose((pose) => poses.push(pose));
+  const host = fakeHost();
+  return { fake, loader, viewer, poses, host };
+}
+
+const settle = () => new Promise((resolve) => setTimeout(resolve, 0));
+
+test('opening a panorama shows it and emits a provider-neutral pose', async () => {
+  const { fake, viewer, poses, host } = setup();
+  await viewer.mount(host);
+  assert.equal(host.children.length, 1, 'renders in its own element');
+  const [panorama] = fake.built;
+  assert.equal(panorama.options.fullscreenControl, false);
+  assert.equal(panorama.options.addressControl, false, 'the caption has it');
+  assert.equal(panorama.options.enableCloseButton, false);
+  assert.equal(panorama.visible, false, 'nothing shows before an open');
+
+  await viewer.open('pano-a');
+  assert.equal(panorama.visible, true);
+  await settle(); // the pose is dated once its lookup answers
+  const pose = poses.at(-1);
+  assert.deepEqual(
+    {
+      providerId: pose.providerId,
+      imageId: pose.imageId,
+      position: pose.position,
+      isPano: pose.isPano,
+      capturedAt: pose.capturedAt,
+      capturedAtPrecision: pose.capturedAtPrecision,
+      creator: pose.creator,
+      title: pose.title,
+    },
+    {
+      providerId: 'google',
+      imageId: 'pano-a',
+      position: { lon: -121.4944, lat: 38.5816 },
+      isPano: true,
+      capturedAt: Date.UTC(2024, 4, 1),
+      capturedAtPrecision: 'month',
+      creator: 'Google',
+      title: '10th St',
+    },
+  );
+  assert.match(pose.externalUrl, /map_action=pano&pano=pano-a/);
+});
+
+test('dragging the view and stepping along an arrow both emit poses; the date is looked up once per panorama', async () => {
+  const { fake, viewer, poses, host } = setup();
+  await viewer.mount(host);
+  await viewer.open('pano-a');
+  const [panorama] = fake.built;
+  panorama.setPov({ heading: 90, pitch: -10 });
+  await settle();
+  assert.deepEqual(
+    [poses.at(-1).bearing, poses.at(-1).tilt],
+    [90, -10],
+    'the view follows the drag',
+  );
+  // Google's own arrow: the panorama changes without an open.
+  panorama.setPano('pano-b');
+  await settle();
+  await settle();
+  assert.equal(poses.at(-1).imageId, 'pano-b');
+  assert.equal(poses.at(-1).creator, 'Ada');
+  const dateLookups = fake.lookups.filter((request) => request.pano);
+  assert.deepEqual(
+    dateLookups.map((request) => request.pano),
+    ['pano-a', 'pano-b'],
+  );
+});
+
+test('a panorama Google has no imagery for fails the open', async () => {
+  const { viewer, host } = setup();
+  await viewer.mount(host);
+  await assert.rejects(viewer.open('gone'), /no imagery/);
+});
+
+test('a closed panorama is hidden and its late view changes emit nothing', async () => {
+  const { fake, viewer, poses, host } = setup();
+  await viewer.mount(host);
+  await viewer.open('pano-a');
+  const [panorama] = fake.built;
+  viewer.close();
+  assert.equal(panorama.visible, false);
+  const count = poses.length;
+  panorama.setPov({ heading: 180, pitch: 0 });
+  await settle();
+  assert.equal(poses.length, count);
+});
+
+test('an open overtaken by a newer one only shows the newer panorama', async () => {
+  const { viewer, poses, host } = setup();
+  await viewer.mount(host);
+  const first = viewer.open('pano-a');
+  const second = viewer.open('pano-b');
+  await Promise.all([first, second]);
+  assert.deepEqual(
+    [...new Set(poses.map((pose) => pose.imageId))].at(-1),
+    'pano-b',
+  );
+  assert.ok(!poses.some((pose) => pose.imageId === 'pano-a'));
+});
+
+test('unmounting removes the element and every listener', async () => {
+  const { fake, viewer, host } = setup();
+  await viewer.mount(host);
+  const [panorama] = fake.built;
+  assert.ok(panorama.listenerCount() > 0);
+  viewer.unmount();
+  assert.equal(host.children.length, 0);
+  assert.equal(panorama.listenerCount(), 0);
+  await assert.rejects(viewer.open('pano-a'), /not mounted/);
+});
+
+test('there is no prewarm: Google\u2019s script loads on first use only, never on another map', () => {
+  const { viewer, loader } = setup();
+  assert.equal(viewer.prewarm, undefined);
+  assert.deepEqual(loader.imports, []);
+});
+
+test('a key Google refuses fails the open at once, not after the timeout', async () => {
+  const { fake, loader, viewer, host } = setup();
+  await viewer.mount(host);
+  const [panorama] = fake.built;
+  // Google refuses the key while the panorama loads; it never reports OK.
+  panorama.setPano = (id) => {
+    panorama.pano = id;
+    queueMicrotask(() => loader.refuseKey());
+  };
+  await assert.rejects(viewer.open('pano-a'), /Maps JavaScript API is enabled/);
+  await assert.rejects(viewer.open('pano-b'), /Maps JavaScript API is enabled/);
+  assert.equal(loader.listenerCount(), 0, 'no auth listener is left behind');
+});
+
+test('a viewer unmounted while the library loads builds no panorama (none is billed)', async () => {
+  const fake = fakeStreetViewLibrary({ panoramas: PANORAMAS });
+  const loader = fakeMapsLoader(fake.library, { deferred: true });
+  const viewer = createGoogleViewer({ loader });
+  const host = fakeHost();
+  const mounting = viewer.mount(host);
+  viewer.unmount();
+  loader.release();
+  await assert.rejects(mounting, /unmounted/);
+  assert.equal(fake.built.length, 0);
+  assert.equal(host.children.length, 0);
+});
+
+test('a date that arrives after the photo was closed emits nothing', async () => {
+  const { fake, viewer, poses, host } = setup();
+  await viewer.mount(host);
+  await viewer.open('pano-a');
+  const [panorama] = fake.built;
+  let answer;
+  fake.library.StreetViewService.prototype.getPanorama = () =>
+    new Promise((resolve) => {
+      answer = resolve;
+    });
+  panorama.setPano('pano-b'); // Google's arrow; its date is still unknown
+  await settle();
+  assert.equal(poses.at(-1).imageId, 'pano-b', 'the step shows at once');
+  assert.equal(
+    poses.at(-1).capturedAt,
+    null,
+    'undated until the lookup answers',
+  );
+  viewer.close();
+  const count = poses.length;
+  answer({ data: { imageDate: '2019-08' } });
+  await settle();
+  assert.equal(poses.length, count);
+});
+
+test('an open never waits on the date lookup', async () => {
+  const { fake, viewer, poses, host } = setup();
+  await viewer.mount(host);
+  fake.library.StreetViewService.prototype.getPanorama = () =>
+    new Promise(() => {}); // the metadata never answers
+  await viewer.open('pano-a');
+  assert.equal(poses.at(-1).imageId, 'pano-a');
+  viewer.unmount();
+});
+
+test('closing while a panorama loads settles the open and drops its listeners', async () => {
+  const { fake, loader, viewer, host } = setup();
+  await viewer.mount(host);
+  const [panorama] = fake.built;
+  const before = panorama.listenerCount();
+  panorama.setPano = (id) => {
+    panorama.pano = id; // still loading
+  };
+  const opening = viewer.open('pano-a');
+  await settle();
+  viewer.close();
+  await opening;
+  assert.equal(panorama.listenerCount(), before);
+  assert.equal(loader.listenerCount(), 0);
+});
+
+test('a second open whose status stays OK still resolves, on the new position', async () => {
+  const { fake, viewer, poses, host } = setup();
+  await viewer.mount(host);
+  await viewer.open('pano-a');
+  assert.equal(fake.built[0].getStatus(), 'OK');
+  await viewer.open('pano-b'); // OK → OK: no status_changed
+  assert.equal(poses.at(-1).imageId, 'pano-b');
+});
+
+test('Google answering with a newer id for the place shows that id', async () => {
+  const fake = fakeStreetViewLibrary({
+    panoramas: PANORAMAS,
+    substitutes: { 'old-id': 'pano-a' },
+  });
+  const viewer = createGoogleViewer({ loader: fakeMapsLoader(fake.library) });
+  const poses = [];
+  viewer.onPose((pose) => poses.push(pose));
+  await viewer.mount(fakeHost());
+  await viewer.open('old-id');
+  assert.equal(poses.at(-1).imageId, 'pano-a');
+});
+
+test('a panorama that never shows fails after the timeout and leaves no listener', async (t) => {
+  t.mock.timers.enable({ apis: ['setTimeout'] });
+  const { OPEN_TIMEOUT_MS, NO_ANSWER_MESSAGE } = await import('./policy.js');
+  const { fake, loader, viewer, host } = setup();
+  await viewer.mount(host);
+  const [panorama] = fake.built;
+  const before = panorama.listenerCount();
+  panorama.setPano = (id) => {
+    panorama.pano = id; // Google never answers
+  };
+  const opening = viewer.open('pano-a');
+  await Promise.resolve();
+  await Promise.resolve();
+  t.mock.timers.tick(OPEN_TIMEOUT_MS);
+  await assert.rejects(opening, { message: NO_ANSWER_MESSAGE });
+  assert.equal(panorama.listenerCount(), before);
+  assert.equal(loader.listenerCount(), 0);
+});
+
+test('failed details lookups cool down through repeated drags and retry after the pause', async (t) => {
+  let now = 1_000;
+  t.mock.method(Date, 'now', () => now);
+  const { fake, viewer, poses, host } = setup();
+  await viewer.mount(host);
+  const getPanorama = fake.library.StreetViewService.prototype.getPanorama;
+  let failures = 2;
+  let calls = 0;
+  fake.library.StreetViewService.prototype.getPanorama = function (request) {
+    calls++;
+    if (failures-- > 0) return Promise.reject(new Error('offline'));
+    return getPanorama.call(this, request);
+  };
+  await viewer.open('pano-a');
+  assert.equal(poses.at(-1).capturedAt, null, 'undated while it failed');
+  assert.equal(calls, 1);
+  for (let attempt = 0; attempt < 2; attempt++) {
+    for (let heading = 0; heading < 20; heading++) {
+      fake.built[0].setPov({ heading, pitch: 0 });
+      await settle();
+    }
+    assert.equal(calls, attempt + 1, 'drags do not retry during the pause');
+    assert.equal(poses.at(-1).bearing, 19, 'pose updates still follow drags');
+    now += DETAILS_RETRY_COOLDOWN_MS - 1;
+    fake.built[0].setPov({ heading: 20, pitch: 0 });
+    await settle();
+    assert.equal(calls, attempt + 1, 'still paused just before the deadline');
+    now++;
+    fake.built[0].setPov({ heading: 21, pitch: 0 });
+    await settle();
+    assert.equal(calls, attempt + 2, 'one retry at the deadline');
+  }
+  assert.equal(poses.at(-1).capturedAt, Date.UTC(2024, 4, 1));
+  now += DETAILS_RETRY_COOLDOWN_MS;
+  fake.built[0].setPov({ heading: 10, pitch: 0 });
+  await settle();
+  assert.equal(calls, 3, 'successful details stay cached');
+});
+
+test('a failed panorama does not delay details for another panorama', async (t) => {
+  t.mock.method(Date, 'now', () => 1_000);
+  const { fake, viewer, poses, host } = setup();
+  await viewer.mount(host);
+  const getPanorama = fake.library.StreetViewService.prototype.getPanorama;
+  const requests = [];
+  fake.library.StreetViewService.prototype.getPanorama = function (request) {
+    requests.push(request.pano);
+    if (request.pano === 'pano-a') return Promise.reject(new Error('offline'));
+    return getPanorama.call(this, request);
+  };
+  await viewer.open('pano-a');
+  fake.built[0].setPano('pano-b');
+  await settle();
+  assert.deepEqual(requests, ['pano-a', 'pano-b']);
+  assert.equal(poses.at(-1).creator, 'Ada');
+  fake.built[0].setPano('pano-a');
+  await settle();
+  assert.deepEqual(
+    requests,
+    ['pano-a', 'pano-b'],
+    'returning respects the pause',
+  );
+});
+
+test('a retry after a failed open is not failed by the old panorama\u2019s status', async () => {
+  const { viewer, poses, host } = setup();
+  await viewer.mount(host);
+  await assert.rejects(viewer.open('gone'), /no imagery/);
+  // The new panorama moves first; its OK status follows.
+  await viewer.open('pano-a');
+  assert.equal(poses.at(-1).imageId, 'pano-a');
+});
+
+test('a details lookup that never answers times out, cools down and retries', async (t) => {
+  t.mock.timers.enable({ apis: ['setTimeout', 'Date'], now: 1_000 });
+  const flush = async () => {
+    for (let i = 0; i < 10; i++) await Promise.resolve();
+  };
+  const { fake, viewer, poses, host } = setup();
+  await viewer.mount(host);
+  const getPanorama = fake.library.StreetViewService.prototype.getPanorama;
+  const requests = [];
+  let hang = true;
+  fake.library.StreetViewService.prototype.getPanorama = function (request) {
+    requests.push(request.pano);
+    return hang ? new Promise(() => {}) : getPanorama.call(this, request);
+  };
+  const opening = viewer.open('pano-a');
+  await flush();
+  await opening;
+  assert.deepEqual(requests, ['pano-a']);
+  fake.built[0].setPov({ heading: 5, pitch: 0 });
+  await flush();
+  assert.deepEqual(requests, ['pano-a'], 'one lookup in flight at a time');
+  t.mock.timers.tick(DETAILS_TIMEOUT_MS);
+  await flush();
+  hang = false;
+  fake.built[0].setPov({ heading: 6, pitch: 0 });
+  await flush();
+  assert.deepEqual(requests, ['pano-a'], 'the cooldown follows a timeout');
+  t.mock.timers.tick(DETAILS_RETRY_COOLDOWN_MS);
+  fake.built[0].setPov({ heading: 7, pitch: 0 });
+  await flush();
+  assert.deepEqual(requests, ['pano-a', 'pano-a']);
+  assert.equal(poses.at(-1).capturedAt, Date.UTC(2024, 4, 1));
+  assert.equal(poses.at(-1).bearing, 7);
+});
+
+test('a remount looks up again a panorama whose lookup hung', async () => {
+  const { fake, viewer, poses, host } = setup();
+  await viewer.mount(host);
+  const getPanorama = fake.library.StreetViewService.prototype.getPanorama;
+  const requests = [];
+  let answerHung;
+  fake.library.StreetViewService.prototype.getPanorama = function (request) {
+    requests.push(request.pano);
+    if (requests.length === 1)
+      return new Promise((resolve) => {
+        answerHung = () => resolve(getPanorama.call(this, request));
+      });
+    return getPanorama.call(this, request);
+  };
+  await viewer.open('pano-b');
+  viewer.unmount();
+  await viewer.mount(host);
+  await viewer.open('pano-b');
+  await settle();
+  assert.deepEqual(requests, ['pano-b', 'pano-b']);
+  assert.equal(poses.at(-1).creator, 'Ada');
+  // The hung answer arriving now is for a viewer that is gone: dropped.
+  const count = poses.length;
+  answerHung();
+  await settle();
+  assert.equal(poses.length, count);
+});
+
+test('superseded panorama waits cannot steal the current close cleanup', async (t) => {
+  t.mock.timers.enable({ apis: ['setTimeout'] });
+  const { OPEN_TIMEOUT_MS } = await import('./policy.js');
+  const flush = async () => {
+    for (let i = 0; i < 10; i++) await Promise.resolve();
+  };
+  const { fake, loader, viewer, host } = setup();
+  await viewer.mount(host);
+  const [panorama] = fake.built;
+  panorama.setPano = (id) => {
+    panorama.pano = id;
+  };
+  const first = viewer.open('pano-a');
+  await flush();
+  const second = viewer.open('pano-b');
+  await flush();
+  panorama.fire('position_changed'); // new panorama has not reached OK
+  await flush();
+  viewer.close();
+  const remaining = loader.listenerCount();
+  t.mock.timers.tick(OPEN_TIMEOUT_MS);
+  await Promise.allSettled([first, second]);
+  assert.equal(
+    remaining,
+    0,
+    'close disposes every pending open without waiting 20 seconds',
+  );
+  assert.equal(panorama.visible, false);
+});
+
+test('unmount during details-service acquisition makes no later billed lookup', async () => {
+  const fake = fakeStreetViewLibrary({ panoramas: PANORAMAS });
+  const loader = fakeMapsLoader(fake.library);
+  const { createGoogleProvider } = await import('./index.js');
+  let release;
+  const acquiring = new Promise((resolve) => {
+    release = resolve;
+  });
+  const importLibrary = loader.importLibrary.bind(loader);
+  let imports = 0;
+  loader.importLibrary = async (name) => {
+    if (++imports > 1) await acquiring;
+    return importLibrary(name);
+  };
+  const provider = createGoogleProvider({
+    getApiKey: () => 'fixture-key',
+    loader,
+  });
+  const instance = provider.create({
+    notify() {},
+    actions: { reportError() {} },
+  });
+  const viewer = instance.viewer;
+  await viewer.mount(fakeHost());
+  await viewer.open('pano-a');
+  viewer.unmount();
+  release();
+  for (let i = 0; i < 10; i++) await Promise.resolve();
+  assert.equal(
+    fake.lookups.length,
+    0,
+    'teardown invalidates the request before calling getPanorama',
+  );
+  instance.destroy();
+});

src/layers/streetLevel/providers/kartaview/decode.js

@@ -0,0 +1,176 @@
+import { MASK_KEEP_SHARE, MASK_SAMPLE_PX } from './policy.js';
+
+/** More than any real tile holds (a dense z13 tile has ~4,700 segments). */
+export const MAX_TILE_SEGMENTS = 20_000;
+/** A chained line stops growing here and the next one starts. */
+export const MAX_LINE_POINTS = 5_000;
+
+/**
+ * The way segments of a KartaView coverage tile
+ * (`{lines: [{track: [{lat, lng}]}]}`), as [lon, lat] point lists. Lines
+ * carry no sequence, date or projection: a filter thins them through a mask
+ * (see `maskedSegments`).
+ * @param {object} payload
+ * @returns {Array<Array<[number, number]>>}
+ */
+export function tileSegments(payload) {
+  // Not cached as empty: an unreadable tile is asked for again.
+  if (!Array.isArray(payload?.lines))
+    throw new Error('KartaView sent an unreadable coverage tile');
+  const segments = [];
+  for (const line of payload.lines) {
+    if (segments.length >= MAX_TILE_SEGMENTS) break;
+    const points = [];
+    for (const point of Array.isArray(line?.track) ? line.track : []) {
+      const lon = Number(point?.lng);
+      const lat = Number(point?.lat);
+      if (!Number.isFinite(lon) || !Number.isFinite(lat)) continue;
+      const last = points[points.length - 1];
+      if (last && last[0] === lon && last[1] === lat) continue;
+      points.push([lon, lat]);
+    }
+    if (points.length >= 2) segments.push(points);
+  }
+  return segments;
+}
+
+/**
+ * Segments chained into line records for the shared coverage: segments
+ * that meet end to start are joined, which cuts the line count about
+ * fourfold.
+ * @param {Array<Array<[number, number]>>} segments
+ * @param {{x: number, y: number, z: number}} address
+ * @returns {{sequences: Array<{id: string, parts: Array<Array<[number, number]>>, capturedAt: number, isPano: boolean}>}}
+ */
+export function chainSegments(segments, { x, y, z }) {
+  const key = ([lon, lat]) => `${lon},${lat}`;
+  const startingAt = new Map();
+  segments.forEach((segment, index) => {
+    const at = key(segment[0]);
+    const list = startingAt.get(at);
+    if (list) list.push(index);
+    else startingAt.set(at, [index]);
+  });
+  const used = new Uint8Array(segments.length);
+  // Per start point, how far its list has been used: each segment is looked
+  // at once, so a tile of segments sharing one point stays linear.
+  const cursor = new Map();
+  const nextFrom = (point) => {
+    const at = key(point);
+    const list = startingAt.get(at);
+    if (!list) return undefined;
+    let i = cursor.get(at) ?? 0;
+    while (i < list.length && used[list[i]]) i++;
+    cursor.set(at, i);
+    return list[i];
+  };
+  const sequences = [];
+  segments.forEach((segment, index) => {
+    if (used[index]) return;
+    used[index] = 1;
+    const chain = [...segment];
+    for (;;) {
+      const next = nextFrom(chain[chain.length - 1]);
+      if (next === undefined) break;
+      // Full: the segment starts the next line instead.
+      if (chain.length + segments[next].length - 1 > MAX_LINE_POINTS) break;
+      used[next] = 1;
+      chain.push(...segments[next].slice(1));
+    }
+    sequences.push({
+      id: `${z}/${x}/${y}/${sequences.length}`,
+      parts: [chain],
+      capturedAt: 0,
+      isPano: false,
+    });
+  });
+  return { sequences };
+}
+
+/** Decode a KartaView coverage tile into the shared coverage's line records. */
+export function decodeCoverageTile(payload, address) {
+  return chainSegments(tileSegments(payload), address);
+}
+
+/**
+ * The segments a filtered PNG tile of the same address draws over. The PNG
+ * draws the same ways a few pixels wide (on a transparent ground): a
+ * segment is kept when at least half the points sampled along it have a
+ * drawn pixel within one pixel. Segments either lie on it or miss it
+ * almost entirely (Jakarta, 360° only: 332 of 1,041 kept, 676 missed, 33
+ * between). A segment with no point on the tile is not this tile's to keep.
+ * @param {Array<Array<[number, number]>>} segments
+ * @param {{width: number, height: number, alpha: ArrayLike<number>}} mask  one alpha byte per pixel
+ * @param {{x: number, y: number, z: number}} address
+ */
+export function maskedSegments(segments, mask, { x, y, z }) {
+  const { width, height, alpha } = mask;
+  const n = 2 ** z;
+  const toPixel = ([lon, lat]) => {
+    const sin = Math.sin((lat * Math.PI) / 180);
+    const my = 0.5 - Math.log((1 + sin) / (1 - sin)) / (4 * Math.PI);
+    return [(((lon + 180) / 360) * n - x) * width, (my * n - y) * height];
+  };
+  const drawnNear = (px, py) => {
+    const cx = Math.floor(px);
+    const cy = Math.floor(py);
+    for (let dy = -1; dy <= 1; dy++)
+      for (let dx = -1; dx <= 1; dx++) {
+        const X = cx + dx;
+        const Y = cy + dy;
+        if (X < 0 || Y < 0 || X >= width || Y >= height) continue;
+        if (alpha[Y * width + X] > 0) return true;
+      }
+    return false;
+  };
+  return segments.filter((segment) => {
+    let on = 0;
+    let tested = 0;
+    let [ax, ay] = toPixel(segment[0]);
+    for (let i = 1; i < segment.length; i++) {
+      const [bx, by] = toPixel(segment[i]);
+      const steps = Math.max(
+        1,
+        Math.ceil(Math.hypot(bx - ax, by - ay) / MASK_SAMPLE_PX),
+      );
+      // Each point once: a segment's next stretch starts where this one ends.
+      for (let j = i === 1 ? 0 : 1; j <= steps; j++) {
+        const px = ax + ((bx - ax) * j) / steps;
+        const py = ay + ((by - ay) * j) / steps;
+        if (px < 0 || py < 0 || px >= width || py >= height) continue;
+        tested++;
+        if (drawnNear(px, py)) on++;
+      }
+      ax = bx;
+      ay = by;
+    }
+    return tested > 0 && on / tested >= MASK_KEEP_SHARE;
+  });
+}
+
+/**
+ * A PNG mask's alpha, one byte per pixel, decoded off the main thread
+ * where the browser can.
+ * @param {Uint8Array} bytes  the PNG
+ * @returns {Promise<{width: number, height: number, alpha: Uint8Array}>}
+ */
+export async function readMaskImage(bytes) {
+  const bitmap = await createImageBitmap(
+    new Blob([bytes], { type: 'image/png' }),
+  );
+  try {
+    const { width, height } = bitmap;
+    const canvas =
+      typeof OffscreenCanvas === 'function'
+        ? new OffscreenCanvas(width, height)
+        : Object.assign(document.createElement('canvas'), { width, height });
+    const context = canvas.getContext('2d', { willReadFrequently: true });
+    context.drawImage(bitmap, 0, 0);
+    const rgba = context.getImageData(0, 0, width, height).data;
+    const alpha = new Uint8Array(width * height);
+    for (let i = 0; i < alpha.length; i++) alpha[i] = rgba[i * 4 + 3];
+    return { width, height, alpha };
+  } finally {
+    bitmap.close?.();
+  }
+}

src/layers/streetLevel/providers/kartaview/decode.test.mjs

@@ -0,0 +1,186 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import {
+  MAX_LINE_POINTS,
+  MAX_TILE_SEGMENTS,
+  chainSegments,
+  decodeCoverageTile,
+  maskedSegments,
+  tileSegments,
+} from './decode.js';
+
+const at = (lng, lat) => ({ lat: String(lat), lng: String(lng) });
+const TILE = { x: 4412, y: 6061, z: 14 };
+
+test('segments that meet end to start chain into one line', () => {
+  const { sequences } = decodeCoverageTile(
+    {
+      lines: [
+        { track: [at(1, 1), at(2, 1)], matched: '1' },
+        { track: [at(5, 5), at(6, 6)], matched: '1' },
+        { track: [at(2, 1), at(3, 1), at(4, 2)], matched: '1' },
+      ],
+    },
+    TILE,
+  );
+  assert.equal(sequences.length, 2);
+  assert.deepEqual(sequences[0].parts, [
+    [
+      [1, 1],
+      [2, 1],
+      [3, 1],
+      [4, 2],
+    ],
+  ]);
+  assert.equal(sequences[0].id, '14/4412/6061/0');
+  assert.equal(sequences[1].id, '14/4412/6061/1');
+  // Nothing to date or project: every line passes as flat and undated.
+  assert.equal(sequences[0].capturedAt, 0);
+  assert.equal(sequences[0].isPano, false);
+});
+
+test('a junction continues one way only, and every segment is drawn exactly once', () => {
+  const { sequences } = decodeCoverageTile(
+    {
+      lines: [
+        { track: [at(0, 0), at(1, 0)] },
+        { track: [at(1, 0), at(2, 0)] },
+        { track: [at(1, 0), at(1, 1)] },
+        // A loop back to its own start must end, not spin.
+        { track: [at(9, 9), at(9, 8)] },
+        { track: [at(9, 8), at(9, 9)] },
+      ],
+    },
+    TILE,
+  );
+  const points = sequences.reduce((sum, s) => sum + s.parts[0].length, 0);
+  assert.equal(sequences.length, 3);
+  // 5 segments of 2 points, 2 joins in chains: 10 - 2 = 8 points.
+  assert.equal(points, 8);
+});
+
+test('bad points, repeats and one-point tracks are skipped; an empty tile has no lines', () => {
+  const { sequences } = decodeCoverageTile(
+    {
+      lines: [
+        { track: [at(1, 1), at(1, 1), { lat: 'x', lng: '2' }, at(2, 2)] },
+        { track: [at(3, 3)] },
+        { track: null },
+        null,
+      ],
+    },
+    TILE,
+  );
+  assert.equal(sequences.length, 1);
+  assert.deepEqual(sequences[0].parts[0], [
+    [1, 1],
+    [2, 2],
+  ]);
+  assert.deepEqual(decodeCoverageTile({ lines: [] }, TILE).sequences, []);
+});
+
+test('a tile that is not a line list fails, so it is asked for again rather than kept empty', () => {
+  for (const payload of [
+    null,
+    {},
+    { lines: 'nope' },
+    { status: { apiCode: 690 } },
+  ])
+    assert.throws(
+      () => decodeCoverageTile(payload, TILE),
+      /unreadable coverage tile/,
+    );
+});
+
+test('a tile whose segments all share one point decodes in linear time', () => {
+  // [P, Q_i, P]: every chain step looks at the same start point's list.
+  // 60k: the old quadratic chaining took over a second; capped and linear
+  // decoding takes tens of milliseconds.
+  const lines = Array.from({ length: 60_000 }, (_, i) => ({
+    track: [at(0, 0), at(1 + i * 1e-6, 1), at(0, 0)],
+  }));
+  const started = performance.now();
+  const { sequences } = decodeCoverageTile({ lines }, TILE);
+  const ms = performance.now() - started;
+  assert.ok(
+    ms < 1_000,
+    `${Math.round(ms)} ms (quadratic chaining took ~200 ms per 20k and grows fourfold per doubling)`,
+  );
+  const points = sequences.reduce((sum, s) => sum + s.parts[0].length, 0);
+  assert.ok(sequences.every((s) => s.parts[0].length <= MAX_LINE_POINTS));
+  assert.equal(
+    points,
+    MAX_TILE_SEGMENTS * 2 + sequences.length,
+    'every segment drawn once',
+  );
+});
+
+test('a tile is capped in segments and in points per line', () => {
+  const lines = Array.from({ length: MAX_TILE_SEGMENTS + 500 }, (_, i) => ({
+    track: [at(i, 0), at(i + 1, 0)],
+  }));
+  const { sequences } = decodeCoverageTile({ lines }, TILE);
+  const points = sequences.reduce((sum, s) => sum + s.parts[0].length, 0);
+  // One long chain, cut into lines of at most MAX_LINE_POINTS.
+  assert.ok(sequences.every((s) => s.parts[0].length <= MAX_LINE_POINTS));
+  assert.ok(points <= MAX_TILE_SEGMENTS + sequences.length);
+  assert.ok(
+    sequences.length >= Math.floor(MAX_TILE_SEGMENTS / MAX_LINE_POINTS),
+  );
+});
+
+/** [lon, lat] at pixel (px, py) of a 512 px mask of `tile` (Web Mercator). */
+function lonLatAt(px, py, { x, y, z } = TILE, size = 512) {
+  const n = 2 ** z;
+  const lon = ((x + px / size) / n) * 360 - 180;
+  const my = Math.PI * (1 - (2 * (y + py / size)) / n);
+  const lat = (Math.atan(Math.sinh(my)) * 180) / Math.PI;
+  return [lon, lat];
+}
+
+/** A 512 px mask drawn on the given rows. */
+function rowsMask(rows) {
+  const alpha = new Uint8Array(512 * 512);
+  for (const [from, to] of rows) alpha.fill(255, from * 512, (to + 1) * 512);
+  return { width: 512, height: 512, alpha };
+}
+
+test('a mask keeps the segments it draws over, chained as before', () => {
+  const along = (row, from = 40, to = 470) => [
+    lonLatAt(from, row),
+    lonLatAt(to, row),
+  ];
+  const segments = [
+    along(100), // drawn at row 100
+    along(101.6), // a pixel off: still drawn within one pixel
+    along(300), // not drawn
+    // Two thirds along the drawn row, then off it: kept (at least half).
+    [lonLatAt(40, 100), lonLatAt(400, 100), lonLatAt(400, 280)],
+    // A third along it, then off: dropped.
+    [lonLatAt(300, 100), lonLatAt(400, 100), lonLatAt(400, 300)],
+    // Off the tile entirely: not this tile's to keep.
+    [lonLatAt(-200, 100), lonLatAt(-20, 100)],
+  ];
+  const kept = maskedSegments(segments, rowsMask([[99, 100]]), TILE);
+  assert.deepEqual(kept, [segments[0], segments[1], segments[3]]);
+  assert.deepEqual(maskedSegments(segments, rowsMask([]), TILE), []);
+  // A full mask keeps every segment that is on the tile.
+  assert.equal(maskedSegments(segments, rowsMask([[0, 511]]), TILE).length, 5);
+});
+
+test('decoding is segments then chaining: the same lines either way', () => {
+  const payload = {
+    lines: [
+      { track: [at(1, 1), at(2, 1)] },
+      { track: [at(2, 1), at(3, 1)] },
+      { track: [at(5, 5), at(6, 6)] },
+    ],
+  };
+  const segments = tileSegments(payload);
+  assert.equal(segments.length, 3);
+  assert.deepEqual(
+    chainSegments(segments, TILE),
+    decodeCoverageTile(payload, TILE),
+  );
+  assert.throws(() => tileSegments({}), /unreadable coverage tile/);
+});

src/layers/streetLevel/providers/kartaview/index.js

@@ -0,0 +1,578 @@
+import { createLineCoverage, freshCoverage } from '../../lineCoverage.js';
+import { createLru, createTileCache } from '../../tileCache.js';
+
+export { createTileCache } from '../../tileCache.js';
+import { createSequenceCones, thinImages } from '../../sequenceCones.js';
+import { metresBetween } from '../../view.js';
+import {
+  chainSegments,
+  maskedSegments,
+  readMaskImage,
+  tileSegments,
+} from './decode.js';
+import { createKartaViewSource } from './source.js';
+import { createKartaViewViewer } from './viewer.js';
+import { msg } from '../../../../i18n/index.js';
+import {
+  ARCHIVED_MESSAGE,
+  COLORS,
+  COVERAGE_MAX_HEIGHT_M,
+  COVERAGE_NOUN,
+  COVERAGE_STREET_ZOOM_BELOW_M,
+  COVERAGE_TUNING,
+  FILTERED_OUT_MESSAGE,
+  KARTAVIEW_CREDIT_HTML,
+  KARTAVIEW_LABEL,
+  KARTAVIEW_NAME,
+  KARTAVIEW_PROVIDER_ID,
+  LINE_CLICK_HINT,
+  NEAREST_PROBES,
+  NEAREST_RADIUS_M,
+  NO_COVERAGE_HINT,
+  PICK_PREFIX,
+  RATE_LIMITED_MESSAGE,
+  SEQUENCE_PAGE_EDGE,
+  SEQUENCE_PAGE_SIZE,
+  TOO_HIGH_HINT,
+  assignCourses,
+  cameraBearing,
+  normalizePhoto,
+  passesKartaViewFilter,
+  tileFilterQuery,
+} from './policy.js';
+
+/** Photos kept in memory by id (sequence pages fill it). */
+const PHOTO_CACHE_SIZE = 4000;
+/** Sequence pages kept in memory. */
+const PAGE_CACHE_SIZE = 12;
+
+/** z14 near the street, z13 a little higher, nothing above. */
+export function kartaViewZoomFor(heightM) {
+  if (!Number.isFinite(heightM) || heightM > COVERAGE_MAX_HEIGHT_M) return null;
+  return heightM > COVERAGE_STREET_ZOOM_BELOW_M ? 13 : 14;
+}
+
+/** The 1-based page of a sequence that holds `index`, if no photo is missing. */
+function pageOf(index) {
+  return Math.floor(Math.max(0, index) / SEQUENCE_PAGE_SIZE) + 1;
+}
+
+/**
+ * KartaView Street Level provider: keyless coverage lines from KartaView's
+ * tile API, the photos nearest a clicked line, cones along the photo's
+ * sequence, and a flat or 360° viewer with ‹ › along the sequence.
+ * @param {{source?: ReturnType<typeof createKartaViewSource>, viewerOptions?: object, readMask?: typeof readMaskImage}} [options]
+ * @returns {import('../../registry.js').StreetLevelProvider}
+ */
+export function createKartaViewProvider({
+  source = createKartaViewSource(),
+  viewerOptions = {},
+  readMask = readMaskImage,
+} = {}) {
+  return Object.freeze({
+    id: KARTAVIEW_PROVIDER_ID,
+    name: KARTAVIEW_NAME,
+    label: KARTAVIEW_LABEL,
+    requiresKeyId: null,
+    pickPrefix: PICK_PREFIX.root,
+    colors: COLORS,
+    // Its own marker, as Street View has: a purple cone that turns with the view.
+    marker: Object.freeze({ kind: 'view-cone', color: COLORS.coverage }),
+    credit: Object.freeze({ html: KARTAVIEW_CREDIT_HTML }),
+    defaultOn: false,
+    // 360° / flat and SINCE, as Mapillary: KartaView filters the lines on
+    // its server (see tileFilterQuery), the photos by their own record.
+    filters: Object.freeze(['pano', 'since']),
+    // SINCE is the upload date for KartaView: the panel notes it.
+    sinceBasis: 'upload',
+    coverageLabel: Object.freeze({
+      noun: COVERAGE_NOUN,
+      action: LINE_CLICK_HINT,
+    }),
+
+    create(context) {
+      const state = {
+        context,
+        services: context.services,
+        viewer: null,
+        coverage: freshCoverage({ keyless: true }),
+        sequence: {
+          selectedId: null,
+          images: [],
+          collection: null,
+          loading: false,
+          error: null,
+          abort: null,
+        },
+      };
+      const photos = createLru(PHOTO_CACHE_SIZE);
+      const pages = createLru(PAGE_CACHE_SIZE);
+      /** The photo last opened in each sequence: its cones centre on it. */
+      const anchors = new Map();
+      /** The sequence page the cones were drawn from. */
+      let drawnPage = null;
+
+      /** A record as a photo; the one already known keeps its identity (and course). */
+      function remember(record) {
+        const fresh = normalizePhoto(record);
+        if (!fresh) return null;
+        const known = photos.get(fresh.id);
+        const photo = known ? Object.assign(known, fresh) : fresh;
+        photos.set(photo.id, photo);
+        return photo;
+      }
+
+      async function getPhoto(photoId, { signal } = {}) {
+        const cached = photos.get(photoId);
+        if (cached) return cached;
+        const photo = remember(await source.getPhoto(photoId, { signal }));
+        if (!photo)
+          throw new Error(msg('KartaView has no position for this photo'));
+        return photo;
+      }
+
+      /** A page of a sequence's photos, in index order (shared while in flight). */
+      function loadPage(sequenceId, page) {
+        const key = `${sequenceId}:${page}`;
+        let entry = pages.get(key);
+        if (!entry) {
+          entry = source
+            .getSequencePhotos(sequenceId, {
+              page,
+              itemsPerPage: SEQUENCE_PAGE_SIZE,
+            })
+            .then(({ photos: records, hasMore }) => {
+              const list = assignCourses(
+                records
+                  .map(remember)
+                  .filter(Boolean)
+                  .sort(
+                    (a, b) => (a.sequenceIndex ?? 0) - (b.sequenceIndex ?? 0),
+                  ),
+                metresBetween,
+              );
+              // The open photo may have just learnt which way it looked. The
+              // page is good whatever the viewer is doing.
+              try {
+                viewer.refreshPose?.();
+              } catch {
+                /* the next pose carries the direction */
+              }
+              return { page, hasMore, photos: list };
+            });
+          pages.set(key, entry);
+          entry.catch(() => pages.delete(key));
+        }
+        return entry;
+      }
+
+      /**
+       * The page holding `photo`. Pages follow photo ids, which only roughly
+       * follow the index, and photos go missing, so the page the index
+       * suggests is a first guess: step towards the photo until a page holds
+       * it, or the pages straddle where it would be.
+       */
+      async function homePage(photo) {
+        let number = pageOf(photo.sequenceIndex ?? 0);
+        const index = photo.sequenceIndex ?? 0;
+        let page = await loadPage(photo.sequenceId, number);
+        if (!page.photos.length && number > 1) {
+          // Past the end (many photos deleted): find the last page by halving.
+          let low = 1;
+          let high = number - 1;
+          while (low < high) {
+            const middle = Math.ceil((low + high) / 2);
+            if ((await loadPage(photo.sequenceId, middle)).photos.length)
+              low = middle;
+            else high = middle - 1;
+          }
+          number = low;
+        }
+        const seen = new Set();
+        while (!seen.has(number) && seen.size < 8) {
+          seen.add(number);
+          page = await loadPage(photo.sequenceId, number);
+          if (page.photos.some((p) => p.id === photo.id)) return page;
+          const first = page.photos[0]?.sequenceIndex;
+          const last = page.photos.at(-1)?.sequenceIndex;
+          // Past the last page, or before this page's photos: go back.
+          if ((first === undefined || index < first) && number > 1) number--;
+          else if (last !== undefined && index > last && page.hasMore) number++;
+          else break;
+        }
+        return page;
+      }
+
+      /**
+       * The photos around `photo` in index order: its page, plus a
+       * neighbour page when it sits near an edge (pages overlap in index).
+       * @returns {Promise<{home: number, photos: Array<object>}>}
+       */
+      async function windowOf(photo) {
+        const home = await homePage(photo);
+        const list = home.photos;
+        const found = list.findIndex((p) => p.id === photo.id);
+        // A photo no page lists sits where its index would.
+        const at =
+          found !== -1
+            ? found
+            : list.filter(
+                (p) => (p.sequenceIndex ?? 0) < (photo.sequenceIndex ?? 0),
+              ).length;
+        const parts = [list];
+        if (at < SEQUENCE_PAGE_EDGE && home.page > 1)
+          parts.push((await loadPage(photo.sequenceId, home.page - 1)).photos);
+        if (at >= list.length - SEQUENCE_PAGE_EDGE && home.hasMore)
+          parts.push((await loadPage(photo.sequenceId, home.page + 1)).photos);
+        if (parts.length === 1) return { home: home.page, photos: list };
+        const byId = new Map(parts.flat().map((p) => [p.id, p]));
+        return {
+          home: home.page,
+          photos: [...byId.values()].sort(
+            (a, b) => (a.sequenceIndex ?? 0) - (b.sequenceIndex ?? 0),
+          ),
+        };
+      }
+
+      /**
+       * Photo id → whether its file is there (archived ones are not). Only
+       * a definite answer is kept: a storage hiccup is asked again next
+       * time, and meanwhile the photo is tried. A probe is shared, so it
+       * runs to its own timeout rather than any one caller's abort.
+       */
+      const probes = createLru(PHOTO_CACHE_SIZE);
+      function showable(photo) {
+        if (!photo?.urls?.view) return Promise.resolve(false);
+        let probe = probes.get(photo.id);
+        if (!probe) {
+          probe = source.probeImage(photo.urls.view).then(
+            (answer) => {
+              if (answer === null) probes.delete(photo.id);
+              return answer !== false;
+            },
+            () => {
+              probes.delete(photo.id);
+              return true;
+            },
+          );
+          probes.set(photo.id, probe);
+        }
+        return probe;
+      }
+
+      // A tile's way segments, kept a while: panning back, or a filter
+      // change, asks KartaView nothing more for them.
+      const tiles = createTileCache({
+        load: async (tile, { signal }) =>
+          tileSegments(await source.getTile(tile, { signal })),
+      });
+      // A filtered tile's mask, by filter and tile.
+      const masks = createTileCache({
+        load: async ({ query, ...tile }, { signal }) =>
+          readMask(await source.getTileMask(tile, query, { signal })),
+        keyOf: ({ query, z, x, y }) => `${query}|${z}/${x}/${y}`,
+      });
+      /** The tile's lines under the filter now: all, or the masked ones. */
+      async function fetchTile(tile, options) {
+        const query = tileFilterQuery(context.getFilter());
+        if (!query) return chainSegments(await tiles.get(tile, options), tile);
+        const [segments, mask] = await Promise.all([
+          tiles.get(tile, options),
+          masks.get({ ...tile, query }, options),
+        ]);
+        return chainSegments(maskedSegments(segments, mask, tile), tile);
+      }
+      /** The query the drawn lines were loaded under. */
+      let drawnQuery = tileFilterQuery(context.getFilter());
+
+      /**
+       * The next showable photo `delta` along the sequence, or null at its
+       * end. Archived photos are skipped, a few at most.
+       */
+      async function step(photo, delta) {
+        if (!photo?.sequenceId) return null;
+        let from = photo;
+        for (let skipped = 0; skipped <= NEAREST_PROBES; skipped++) {
+          const { photos: list } = await windowOf(from);
+          let at = list.findIndex((p) => p.id === from.id);
+          if (at === -1) {
+            // Not found anywhere: the nearest index on the right side.
+            const index = from.sequenceIndex ?? 0;
+            const later = list.findIndex((p) => (p.sequenceIndex ?? 0) > index);
+            if (delta > 0 && later === -1) return null;
+            at =
+              delta > 0
+                ? later - 1
+                : later === -1
+                  ? list.length
+                  : list.findIndex((p) => (p.sequenceIndex ?? 0) >= index);
+          }
+          const next = list[at + delta];
+          if (!next) return null;
+          if (await showable(next)) return next.id;
+          from = next;
+        }
+        return null;
+      }
+
+      const coverage = createLineCoverage({
+        state,
+        fetchTile,
+        zoomFor: kartaViewZoomFor,
+        colors: COLORS,
+        pickPrefix: PICK_PREFIX.line,
+        renderKey: 'kartaview-coverage',
+        tuning: COVERAGE_TUNING,
+        messages: { rateLimited: RATE_LIMITED_MESSAGE, tooHigh: TOO_HIGH_HINT },
+        // Filtered on the way in (fetchTile): a line has no date to test.
+        passes: () => true,
+      });
+      // Its lines are streets, not drives: a selected drive shows as cones
+      // only, so the coverage is never highlighted.
+
+      const cones = createSequenceCones({
+        state,
+        async loadImages(sequenceId, { signal }) {
+          let anchor = anchors.get(sequenceId);
+          if (!anchor) return [];
+          let window = await windowOf(anchor);
+          signal?.throwIfAborted();
+          // Another photo of the drive opened while that page loaded (its
+          // re-centre found nothing drawn yet): centre on the newest one.
+          while (anchors.get(sequenceId) !== anchor) {
+            anchor = anchors.get(sequenceId);
+            window = await windowOf(anchor);
+            signal?.throwIfAborted();
+          }
+          drawnPage = { sequenceId, page: window.home };
+          countPhotos(sequenceId);
+          return thinImages(
+            window.photos.map((photo) => ({
+              id: photo.id,
+              lon: photo.lon,
+              lat: photo.lat,
+              compassAngle: cameraBearing(photo) ?? 0,
+              capturedAt: photo.capturedAt ?? 0,
+              uploadedAt: photo.uploadedAt,
+              isPano: photo.isPano,
+            })),
+          );
+        },
+        colors: COLORS,
+        pickPrefix: PICK_PREFIX.image,
+        spriteId: 'street-level:kartaview-cones',
+        renderKey: 'kartaview-sequence',
+        // By projection and upload date, as the lines.
+        passes: passesKartaViewFilter,
+      });
+
+      /** Sequence id → its photo count from KartaView (asked once). */
+      const counts = new Map();
+      function countPhotos(sequenceId) {
+        if (counts.has(sequenceId) || !source.getSequenceCount) return;
+        counts.set(sequenceId, undefined);
+        source.getSequenceCount(sequenceId).then(
+          (count) => {
+            if (count === null) counts.delete(sequenceId);
+            else {
+              counts.set(sequenceId, count);
+              context.notify();
+            }
+          },
+          () => counts.delete(sequenceId),
+        );
+      }
+
+      /** ‹ › open through the core (loading, errors, cones), camera still. */
+      function openStepped(photoId) {
+        context.actions.openImage(photoId, { frame: false });
+      }
+
+      /**
+       * The cones show one page of a sequence: once a photo of the selected
+       * sequence opens on another page (‹ ›, a cone, a line), re-centre them.
+       */
+      async function recentreCones(photo) {
+        if (!photo?.sequenceId) return;
+        if (state.sequence.selectedId !== photo.sequenceId) return;
+        const drawn = drawnPage;
+        if (drawn?.sequenceId !== photo.sequenceId) return;
+        const window = await windowOf(photo).catch(() => null);
+        // Still the drawn page and the latest photo once the page is in.
+        if (
+          window &&
+          drawnPage === drawn &&
+          window.home !== drawn.page &&
+          anchors.get(photo.sequenceId) === photo
+        )
+          cones.select(photo.sequenceId, { force: true });
+      }
+
+      const viewer = createKartaViewViewer({
+        getPhoto: async (photoId) => {
+          const photo = await getPhoto(photoId);
+          if (photo.sequenceId) anchors.set(photo.sequenceId, photo);
+          return photo;
+        },
+        step,
+        onStep: openStepped,
+        onShown: recentreCones,
+        // After a GPU reset the same photo is drawn again by the viewer
+        // itself: going through the core would cancel a lookup the user
+        // started. A failure still shows.
+        onReopen: (photoId) =>
+          viewer
+            .open(photoId)
+            .catch((error) =>
+              context.actions.reportError(
+                error?.message ||
+                  msg('The KartaView photo could not be loaded'),
+              ),
+            ),
+        // Esc in the viewer clears the selected drive, as the panel says.
+        onEscape: () => {
+          if (!state.sequence.selectedId) return false;
+          cones.clearSelection();
+          drawnPage = null;
+          return true;
+        },
+        render: context.services?.render,
+        ...viewerOptions,
+      });
+
+      return {
+        async status() {
+          return { configured: true };
+        },
+
+        init(cesiumViewer) {
+          state.viewer = cesiumViewer;
+          cones.ensureCollections(cesiumViewer);
+          cones.setVisible(false);
+        },
+
+        activate(cesiumViewer) {
+          state.viewer = cesiumViewer;
+          cones.setVisible(true);
+          coverage.attach(cesiumViewer);
+        },
+
+        deactivate() {
+          coverage.detach();
+          coverage.clear();
+          coverage.unblock();
+          cones.clearSelection();
+          cones.setVisible(false);
+          drawnPage = null;
+          // Tens of MB of decoded lines are not kept for a source left off.
+          tiles.clear();
+          masks.clear();
+        },
+
+        destroy(cesiumViewer) {
+          coverage.detach();
+          coverage.clear();
+          coverage.unblock();
+          cones.destroy(cesiumViewer);
+          tiles.clear();
+          masks.clear();
+        },
+
+        /**
+         * The filter changed: the lines come from KartaView again under it
+         * (cleared until they come), the cones are drawn again.
+         */
+        setFilter() {
+          const query = tileFilterQuery(context.getFilter());
+          if (query !== drawnQuery) {
+            drawnQuery = query;
+            coverage.reload();
+          }
+          cones.rerender();
+        },
+
+        /** Keyless; an empty view that has loaded says there is nothing here. */
+        coverageStats() {
+          const stats = coverage.stats();
+          const empty =
+            state.coverage.zoom !== null &&
+            !stats.loading &&
+            stats.count === 0 &&
+            !stats.error;
+          return {
+            ...stats,
+            hint: stats.hint || (empty ? NO_COVERAGE_HINT : ''),
+          };
+        },
+
+        /** A line opens the photo nearest the click; a cone opens its photo. */
+        handlePick(pickId, { groundPoint } = {}) {
+          if (pickId.startsWith(PICK_PREFIX.image)) {
+            context.actions.openImage(pickId.slice(PICK_PREFIX.image.length));
+            return true;
+          }
+          if (pickId.startsWith(PICK_PREFIX.line)) {
+            const point = groundPoint?.();
+            if (point) context.actions.openNearest(point);
+            return true;
+          }
+          return false;
+        },
+
+        // Always loaded afresh: the cones show the page of the photo open now.
+        selectSequence: (sequenceId) =>
+          cones.select(sequenceId, { force: true }),
+        clearSequence: () => {
+          cones.clearSelection();
+          drawnPage = null;
+        },
+        // The drive's own count, not the thinned page of it the cones show.
+        sequenceStats: () => ({
+          selectedId: state.sequence.selectedId,
+          images:
+            counts.get(state.sequence.selectedId) ??
+            state.sequence.images.length,
+          loading: state.sequence.loading,
+          error: state.sequence.error,
+        }),
+
+        /**
+         * The nearest photo within the search radius that can be shown, or
+         * null. Many photos are archived (their files answer 409) or have no
+         * file at all, so the nearest few are tried in turn.
+         */
+        async nearestImage({ lat, lon }, { signal } = {}) {
+          const filter = context.getFilter();
+          const records = await source.nearestPhotos(
+            { lat, lon, filter },
+            { signal },
+          );
+          const near = [];
+          let filteredOut = 0;
+          for (const record of records) {
+            const photo = remember(record);
+            if (!photo?.urls.view) continue;
+            const metres = metresBetween({ lat, lon }, photo);
+            if (metres > NEAREST_RADIUS_M) continue;
+            if (!passesKartaViewFilter(photo, filter)) filteredOut++;
+            else near.push({ photo, metres });
+          }
+          near.sort((a, b) => a.metres - b.metres);
+          // Probed side by side (photo storage is not the API host): the
+          // nearest one that answers wins.
+          const candidates = near.slice(0, NEAREST_PROBES);
+          const answers = await Promise.all(
+            candidates.map(({ photo }) => showable(photo, { signal })),
+          );
+          const hit = candidates.find((_, i) => answers[i]);
+          if (hit) return hit.photo.id;
+          if (near.length) throw new Error(ARCHIVED_MESSAGE);
+          if (filteredOut) throw new Error(FILTERED_OUT_MESSAGE);
+          return null;
+        },
+
+        viewer,
+      };
+    },
+  });
+}

src/layers/streetLevel/providers/kartaview/policy.js

@@ -0,0 +1,398 @@
+import { COLORS as SHARED_COLORS, PROVIDER_COLORS } from '../../policy.js';
+import { msg } from '../../../../i18n/index.js';
+
+export { NEAREST_RADIUS_M } from '../../policy.js';
+
+/** Identity and tuning for the KartaView street-level provider (keyless). */
+export const KARTAVIEW_PROVIDER_ID = 'kartaview';
+export const KARTAVIEW_NAME = 'KartaView';
+export const KARTAVIEW_LABEL = 'KARTAVIEW';
+
+/**
+ * The public API. Its documented twin, api.openstreetcam.org, still answers
+ * but serves empty coverage tiles.
+ */
+export const KARTAVIEW_API_HOST = 'https://api.kartaview.org';
+/** KartaView's image proxy: resizes a photo given its base64url address. */
+export const KARTAVIEW_CDN_HOST = 'https://cdn.kartaview.org';
+
+/** Stable id prefixes for picked primitives; every one starts with `kv:`. */
+export const PICK_PREFIX = Object.freeze({
+  root: 'kv:',
+  line: 'kv:line:',
+  image: 'kv:img:',
+});
+
+export const COLORS = Object.freeze({
+  coverage: PROVIDER_COLORS.kartaview,
+  selected: SHARED_COLORS.selected,
+});
+
+/**
+ * Coverage lines are OSM ways with photos, from z13–14 JSON tiles. Lower
+ * zooms take seconds per tile (z10 does not answer), so higher up the panel
+ * asks the user to zoom in.
+ */
+export const COVERAGE_STREET_ZOOM_BELOW_M = 2_500;
+export const COVERAGE_MAX_HEIGHT_M = 6_000;
+export const COVERAGE_TUNING = Object.freeze({
+  maxTiles: 9,
+  // Chained ways are short: a dense downtown z13 tile holds ~1,500, so each
+  // tile may draw 1,600 (a frame stays at 16.7 ms with 4,400 drawn).
+  maxSequences: 14_400,
+  lineWidthPx: 2.5,
+  moveDebounceMs: 320,
+  viewRangeMinM: 2_500,
+  viewRangePerHeight: 10,
+  // Lines carry no date to sort by: keep KartaView's order.
+  keepOrder: true,
+});
+export const TOO_HIGH_HINT = msg('zoom in to see KartaView coverage');
+export const NO_COVERAGE_HINT = msg('no KartaView photos in view');
+export const RATE_LIMITED_MESSAGE = msg(
+  'KartaView is rate-limiting requests — they resume on their own',
+);
+
+/**
+ * The photo API answers 429 to more than about three requests at once, so
+ * at most two are in flight; a 429 is retried after a short wait.
+ */
+export const PHOTO_API_CONCURRENCY = 2;
+export const PHOTO_API_RETRIES = 3;
+export const PHOTO_API_RETRY_BASE_MS = 800;
+/** A Retry-After longer than this is not waited out. */
+export const PHOTO_API_RETRY_MAX_MS = 10_000;
+/** The API is HTTP/1.1 (six connections): tiles 3, lookups 2, pages 1. */
+export const TILE_CONCURRENCY = 3;
+export const PAGE_CONCURRENCY = 1;
+export const TILE_TIMEOUT_MS = 20_000;
+export const PHOTO_API_TIMEOUT_MS = 15_000;
+/**
+ * The first try of a lookup: KartaView sometimes sits on a lookup for 11 s
+ * and more, then answers the same one again in 3 s.
+ */
+export const PHOTO_API_FIRST_TIMEOUT_MS = 8_000;
+/** A sequence page is about 650 kB of JSON. */
+export const PAGE_TIMEOUT_MS = 30_000;
+/** Real tiles are under 1 MB; refuse anything absurd before parsing it. */
+export const MAX_RESPONSE_BYTES = 16 * 1024 * 1024;
+/** A photo download (tens of kilobytes to a few megabytes). */
+export const IMAGE_TIMEOUT_MS = 15_000;
+/** Whether a photo file is there (not archived): headers only. */
+export const IMAGE_PROBE_TIMEOUT_MS = 8_000;
+/** Nearest photos probed (at once) before giving up on archived ones; ‹ › skip this many. */
+export const NEAREST_PROBES = 6;
+export const ARCHIVED_MESSAGE = msg(
+  'KartaView’s photos here are archived and cannot be shown',
+);
+
+/** Photos asked for around a point; the API returns them nearest first. */
+export const NEAREST_LIMIT = 10;
+/** The photo API's search zoom: 18 searches the few tens of metres around the point. */
+export const NEAREST_SEARCH_ZOOM = 18;
+
+/**
+ * Photos of a sequence fetched at once, around the open one. Records are
+ * ~2.6 kB each, so a page is ~650 kB; the cones and ‹ › use it. Pages are in
+ * photo-id order, which only roughly follows the sequence index.
+ */
+export const SEQUENCE_PAGE_SIZE = 250;
+/** Within this many photos of a page's edge, its neighbour page joins it. */
+export const SEQUENCE_PAGE_EDGE = 12;
+
+/** Equirectangular panorama sizes: a quick preview, then the sharp one. */
+export const PANO_PREVIEW_SIZE = Object.freeze([1024, 512]);
+/** A flat photo's first version, then its sharp one. */
+export const FLAT_VIEW_SIZE = Object.freeze([1280, 1280]);
+export const FLAT_FULL_SIZE = Object.freeze([2560, 2560]);
+
+/** On-globe credit: KartaView imagery is CC BY-SA 4.0 and needs attribution. */
+export const KARTAVIEW_CREDIT_HTML =
+  'Street Level: imagery © <a href="https://kartaview.org" target="_blank" rel="noopener">KartaView</a> contributors, CC BY-SA 4.0';
+
+/**
+ * The imagery filter (360° or flat, SINCE). KartaView filters coverage on
+ * its server only in its PNG tiles: its JSON tiles come back empty once a
+ * filter is asked for. So a filtered PNG tile is a mask, and a JSON line is
+ * kept where it lies on the mask's drawn pixels.
+ *
+ * KartaView's date filter is the upload date, and SINCE goes by it
+ * throughout (lines, the photo a click opens, the cones), as KartaView's own
+ * map does; the panel says so under the slider.
+ */
+export const MASK_TIMEOUT_MS = 20_000;
+/**
+ * A filtered PNG tile is drawn on demand and a dense one can outlast
+ * KartaView's own 60 s (504); it keeps drawing, and has the tile a few
+ * seconds later. A timeout or a 5xx is asked again this many times in all.
+ */
+export const MASK_ATTEMPTS = 4;
+export const MASK_RETRY_WAIT_MS = 4_000;
+/** Real masks are tens of kilobytes. */
+export const MASK_MAX_BYTES = 2 * 1024 * 1024;
+/** A segment is kept when this share of the points along it lies on the mask. */
+export const MASK_KEEP_SHARE = 0.5;
+/** Points along a segment are tested this many mask pixels apart. */
+export const MASK_SAMPLE_PX = 2;
+export const MASK_SLOW_MESSAGE = msg(
+  'KartaView did not filter this area in time — move the map to ask again',
+);
+export const FILTERED_OUT_MESSAGE = msg(
+  'None of KartaView’s photos here pass the imagery filter',
+);
+/** Under the SINCE slider while KartaView is lit. */
+export const SINCE_NOTE = 'KartaView: by upload date';
+
+/** The UTC calendar day of `ms`, as KartaView's startDate reads it. */
+function utcDay(ms) {
+  return new Date(ms).toISOString().slice(0, 10);
+}
+
+const filtersSince = (filter) =>
+  Number.isFinite(filter?.sinceMs) && filter.sinceMs > 0;
+
+const DAY_MS = 86_400_000;
+
+/**
+ * Whether a photo passes the resolved imagery filter by its projection and
+ * upload date, the cut-off taken as its UTC day, as KartaView's startDate.
+ * @param {{isPano: boolean, uploadedAt: number|null}} photo
+ * @param {{pano: string, sinceMs: number|null}|null} filter
+ */
+export function passesKartaViewFilter(photo, filter) {
+  if (!filter) return true;
+  if (filter.pano === 'pano' && !photo.isPano) return false;
+  if (filter.pano === 'flat' && photo.isPano) return false;
+  if (!filtersSince(filter)) return true;
+  const day = Math.floor(filter.sinceMs / DAY_MS) * DAY_MS;
+  return (photo.uploadedAt ?? 0) >= day;
+}
+
+/**
+ * The query of a filtered PNG coverage tile, or '' when nothing is
+ * filtered. The day, not the instant, so it is stable for a day (and keys
+ * the mask cache).
+ * @param {{pano: string, sinceMs: number|null}|null} filter  resolved
+ */
+export function tileFilterQuery(filter) {
+  const params = new URLSearchParams();
+  if (filter?.pano === 'pano') params.set('fieldOfView', '360');
+  else if (filter?.pano === 'flat') params.set('fieldOfView', 'plane');
+  if (filtersSince(filter)) params.set('startDate', utcDay(filter.sinceMs));
+  return params.toString();
+}
+
+/**
+ * The photo search's own filter: projection and upload date (its
+ * `fieldOfView` is ignored).
+ * @param {{pano: string, sinceMs: number|null}|null} filter  resolved
+ * @returns {Record<string, string>}
+ */
+export function photoFilterParams(filter) {
+  const params = {};
+  if (filter?.pano === 'pano') params.projection = 'SPHERE';
+  else if (filter?.pano === 'flat') params.projection = 'PLANE';
+  if (filtersSince(filter)) params.startDate = utcDay(filter.sinceMs);
+  return params;
+}
+
+/** The cone and coverage noun: a line is a street with photos, not a sequence. */
+export const COVERAGE_NOUN = 'streets';
+export const LINE_CLICK_HINT = 'click a line for its nearest photo';
+
+/** Base64url of a string, as the image proxy reads addresses. */
+function base64Url(text) {
+  const bytes = new TextEncoder().encode(text);
+  let binary = '';
+  for (const byte of bytes) binary += String.fromCharCode(byte);
+  return btoa(binary)
+    .replace(/\+/g, '-')
+    .replace(/\//g, '_')
+    .replace(/=+$/, '');
+}
+
+/** A photo resized by KartaView's image proxy to fit `width`×`height`. */
+export function resizedImageUrl(url, [width, height]) {
+  if (!url) return null;
+  return `${KARTAVIEW_CDN_HOST}/pr:sharp/rs:fit:${width}:${height}/${base64Url(url)}`;
+}
+
+/** Epoch ms for a KartaView timestamp ('2016-02-19 15:28:18.000', UTC), or null. */
+export function kartaViewTimeMs(value) {
+  const match =
+    /^(\d{4})-(\d{2})-(\d{2})(?:[ T](\d{2}):(\d{2})(?::(\d{2}))?)?/.exec(
+      String(value ?? ''),
+    );
+  if (!match) return null;
+  const [, y, mo, d, h = '0', mi = '0', s = '0'] = match;
+  if (Number(y) < 1990) return null;
+  const ms = Date.UTC(+y, +mo - 1, +d, +h, +mi, +s);
+  return Number.isFinite(ms) ? ms : null;
+}
+
+/** Initial great-circle bearing from `a` to `b`, degrees clockwise from north. */
+export function bearingBetween(a, b) {
+  const rad = Math.PI / 180;
+  const dLon = (b.lon - a.lon) * rad;
+  const y = Math.sin(dLon) * Math.cos(b.lat * rad);
+  const x =
+    Math.cos(a.lat * rad) * Math.sin(b.lat * rad) -
+    Math.sin(a.lat * rad) * Math.cos(b.lat * rad) * Math.cos(dLon);
+  return (Math.atan2(y, x) / rad + 360) % 360;
+}
+
+/** Photos closer than this say nothing about the direction of travel. */
+const COURSE_MIN_STEP_M = 2;
+/** How many photos along to look for one far enough away. */
+const COURSE_SEARCH = 5;
+
+/**
+ * Give each photo of a drive (in index order) its `course`: the direction
+ * of travel from it to the next photo a few metres on (from the previous one
+ * at the end). KartaView is dashcam imagery, so this is where the camera
+ * looks; its `heading` is the device compass, which reads 0 without one and
+ * can sit 110° off inside a car.
+ * @param {Array<{lon: number, lat: number, course?: number|null}>} photos
+ * @param {(a: object, b: object) => number} metres
+ */
+export function assignCourses(photos, metres) {
+  photos.forEach((photo, i) => {
+    let course = null;
+    for (let j = i + 1; j <= i + COURSE_SEARCH && j < photos.length; j++)
+      if (metres(photo, photos[j]) >= COURSE_MIN_STEP_M) {
+        course = bearingBetween(photo, photos[j]);
+        break;
+      }
+    for (
+      let k = i - 1;
+      course === null && k >= i - COURSE_SEARCH && k >= 0;
+      k--
+    )
+      if (metres(photos[k], photo) >= COURSE_MIN_STEP_M)
+        course = bearingBetween(photos[k], photo);
+    photo.course = course;
+  });
+  return photos;
+}
+
+/** Where the camera looked: the direction of travel, else the compass, else unknown. */
+export function cameraBearing(photo) {
+  return photo?.course ?? photo?.heading ?? null;
+}
+
+/** A coordinate pair as numbers; the road-matched one when KartaView has it. */
+function positionOf(record) {
+  const matchLat = Number(record.matchLat);
+  const matchLon = Number(record.matchLng);
+  if (
+    Number.isFinite(matchLat) &&
+    Number.isFinite(matchLon) &&
+    (matchLat !== 0 || matchLon !== 0)
+  )
+    return { lat: matchLat, lon: matchLon };
+  return { lat: Number(record.lat), lon: Number(record.lng) };
+}
+
+const STORAGE_HOST = /^storage\d+$/;
+
+/** A KartaView photo-storage address, or null for anything else. */
+function storageUrl(value) {
+  try {
+    const url = new URL(String(value));
+    return url.protocol === 'https:' &&
+      /^storage\d+\.openstreetcam\.org$/.test(url.hostname)
+      ? url.href
+      : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * A photo file's address. The API's `fileurl*` fields always name storage1,
+ * but a photo whose `storage` is another host (storage2…) is only there, so
+ * the address is built from `storage` and the relative `filepath*`. A
+ * `fileurl*` fallback must itself be on KartaView's storage.
+ */
+function fileUrl(record, pathKey, urlKey) {
+  const path = record[pathKey];
+  if (STORAGE_HOST.test(record.storage || '') && path)
+    return storageUrl(
+      `https://${record.storage}.openstreetcam.org/files/photo/${path}`,
+    );
+  return storageUrl(record[urlKey]);
+}
+
+/** A storage URL with its `{{sizeprefix}}` placeholder filled. */
+function sized(record, prefix) {
+  const fill = (value) =>
+    typeof value === 'string' && value.includes('{{sizeprefix}}')
+      ? value.replace('{{sizeprefix}}', prefix)
+      : null;
+  const path = fill(record.filepath);
+  return fileUrl(
+    { ...record, filepath: path, fileurl: fill(record.fileurl) },
+    'filepath',
+    'fileurl',
+  );
+}
+
+/**
+ * A photo API record in the shape the provider uses, or null without an id
+ * or a position.
+ * @returns {{id: string, sequenceId: string|null, sequenceIndex: number|null, lon: number, lat: number, heading: number|null, isPano: boolean, capturedAt: number|null, urls: {view: string|null, full: string|null, pano: string|null}}|null}
+ */
+export function normalizePhoto(record) {
+  if (!record || record.id == null) return null;
+  const { lat, lon } = positionOf(record);
+  if (!Number.isFinite(lat) || !Number.isFinite(lon)) return null;
+  // 0,0 is a missing fix, not a photo in the Gulf of Guinea.
+  if (lat === 0 && lon === 0) return null;
+  if (Math.abs(lat) > 90 || Math.abs(lon) > 180) return null;
+  // An exact 0 is a device without a compass (whole drives read 0), not north.
+  const heading =
+    record.heading === '' || record.heading == null
+      ? NaN
+      : Number(record.heading) || NaN;
+  const isPano =
+    record.projection === 'SPHERE' || Number(record.fieldOfView) >= 360;
+  const full =
+    fileUrl(record, 'filepathProc', 'fileurlProc') || sized(record, 'proc');
+  const index = Number(record.sequenceIndex);
+  return {
+    id: String(record.id),
+    sequenceId: record.sequenceId != null ? String(record.sequenceId) : null,
+    sequenceIndex: Number.isFinite(index) ? index : null,
+    lon,
+    lat,
+    heading: Number.isFinite(heading) ? heading : null,
+    isPano,
+    capturedAt:
+      kartaViewTimeMs(record.shotDate) ?? kartaViewTimeMs(record.dateAdded),
+    // KartaView's SINCE goes by this (its server filters by upload date).
+    uploadedAt: kartaViewTimeMs(record.dateAdded),
+    urls: {
+      // A 1280 px rendition; for a 360° photo it is the front view only.
+      view:
+        fileUrl(record, 'filepathLTh', 'fileurlLTh') ||
+        sized(record, 'lth') ||
+        full,
+      full,
+      // A 360° photo's equirectangular image ('wrapped_proc').
+      pano: isPano && /wrapped/.test(full || '') ? full : null,
+    },
+  };
+}
+
+/**
+ * Where the image link goes. KartaView's photo pages fail for signed-out
+ * visitors ("Sequence cannot be loaded"), so it is the full-size photo
+ * through KartaView's image proxy, which also serves photos whose storage
+ * host answers 502 directly.
+ */
+export function kartaViewPhotoUrl(photo) {
+  const url = photo?.urls?.full || photo?.urls?.view;
+  return url
+    ? `${KARTAVIEW_CDN_HOST}/pr:sharp/${base64Url(url)}`
+    : 'https://kartaview.org';
+}

src/layers/streetLevel/providers/kartaview/policy.test.mjs

@@ -0,0 +1,348 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import {
+  assignCourses,
+  bearingBetween,
+  cameraBearing,
+  kartaViewPhotoUrl,
+  kartaViewTimeMs,
+  normalizePhoto,
+  passesKartaViewFilter,
+  photoFilterParams,
+  resizedImageUrl,
+  tileFilterQuery,
+} from './policy.js';
+
+/** A photo record as /2.0/photo returns it (trimmed to what is read). */
+function record(overrides = {}) {
+  return {
+    id: '7102491',
+    sequenceId: '14010',
+    sequenceIndex: '950',
+    lat: '42.335712',
+    lng: '-83.048301',
+    matchLat: '42.335731506347656',
+    matchLng: '-83.04828643798828',
+    heading: '299.58',
+    fieldOfView: '0',
+    projection: 'PLANE',
+    shotDate: '2016-08-23 20:17:47.000',
+    dateAdded: '2016-08-24 04:01:07',
+    storage: 'storage1',
+    filepath: '2016/8/24/{{sizeprefix}}/14010_ba53c_57bd1d23d50b7.jpg',
+    filepathLTh: '2016/8/24/lth/14010_ba53c_57bd1d23d50b7.jpg',
+    filepathProc: '2016/8/24/proc/14010_ba53c_57bd1d23d50b7.jpg',
+    fileurl:
+      'https://storage1.openstreetcam.org/files/photo/2016/8/24/{{sizeprefix}}/14010_ba53c_57bd1d23d50b7.jpg',
+    fileurlLTh:
+      'https://storage1.openstreetcam.org/files/photo/2016/8/24/lth/14010_ba53c_57bd1d23d50b7.jpg',
+    fileurlProc:
+      'https://storage1.openstreetcam.org/files/photo/2016/8/24/proc/14010_ba53c_57bd1d23d50b7.jpg',
+    ...overrides,
+  };
+}
+
+test('a photo record normalizes to numbers, the road-matched position and UTC capture time', () => {
+  const photo = normalizePhoto(record());
+  assert.equal(photo.id, '7102491');
+  assert.equal(photo.sequenceId, '14010');
+  assert.equal(photo.sequenceIndex, 950);
+  assert.equal(photo.lat, 42.335731506347656);
+  assert.equal(photo.lon, -83.04828643798828);
+  assert.equal(photo.heading, 299.58);
+  assert.equal(photo.isPano, false);
+  assert.equal(photo.capturedAt, Date.UTC(2016, 7, 23, 20, 17, 47));
+  assert.equal(photo.urls.pano, null);
+});
+
+test('photo files come from the storage host the record names, not the one its URLs say', () => {
+  // The API writes storage1 into every URL; this photo lives on storage2.
+  const photo = normalizePhoto(record({ storage: 'storage2' }));
+  assert.equal(
+    photo.urls.view,
+    'https://storage2.openstreetcam.org/files/photo/2016/8/24/lth/14010_ba53c_57bd1d23d50b7.jpg',
+  );
+  assert.equal(
+    photo.urls.full,
+    'https://storage2.openstreetcam.org/files/photo/2016/8/24/proc/14010_ba53c_57bd1d23d50b7.jpg',
+  );
+  // The link goes through the image proxy, which serves photos whose
+  // storage host answers 502 directly.
+  const link = kartaViewPhotoUrl(photo);
+  assert.match(link, /^https:\/\/cdn\.kartaview\.org\/pr:sharp\/[\w-]+$/);
+  assert.equal(
+    Buffer.from(link.split('/').at(-1), 'base64url').toString(),
+    photo.urls.full,
+  );
+  // A fallback address must be on KartaView's storage, over https.
+  for (const fileurlLTh of [
+    'https://tracker.example/x.jpg',
+    'http://storage1.openstreetcam.org/a.jpg',
+    'https://storage1.openstreetcam.org.evil.example/a.jpg',
+    'javascript:alert(1)',
+  ]) {
+    const hostile = normalizePhoto(
+      record({ storage: '', filepathLTh: '', fileurlLTh, fileurl: fileurlLTh }),
+    );
+    assert.notEqual(hostile.urls.view, fileurlLTh);
+    assert.doesNotMatch(
+      String(hostile.urls.view),
+      /tracker|javascript|evil|^http:/,
+    );
+  }
+  // An unexpected storage value falls back to the URLs as given.
+  const odd = normalizePhoto(record({ storage: 'https://evil.example' }));
+  assert.match(odd.urls.view, /^https:\/\/storage1\.openstreetcam\.org\//);
+  // No large thumbnail path: the size prefix fills in.
+  const bare = normalizePhoto(
+    record({ filepathLTh: '', fileurlLTh: '', storage: 'storage3' }),
+  );
+  assert.equal(
+    bare.urls.view,
+    'https://storage3.openstreetcam.org/files/photo/2016/8/24/lth/14010_ba53c_57bd1d23d50b7.jpg',
+  );
+});
+
+test('a 360° photo keeps its equirectangular image; the unmatched position is the fallback', () => {
+  const photo = normalizePhoto(
+    record({
+      projection: 'SPHERE',
+      fieldOfView: '360',
+      matchLat: '0',
+      matchLng: '0',
+      storage: 'storage13',
+      filepathProc: '2022/10/6/wrapped_proc/6187609_626b8.jpg',
+    }),
+  );
+  assert.equal(photo.isPano, true);
+  assert.equal(photo.lat, 42.335712);
+  assert.equal(
+    photo.urls.pano,
+    'https://storage13.openstreetcam.org/files/photo/2022/10/6/wrapped_proc/6187609_626b8.jpg',
+  );
+  // A sphere without a wrapped image has nothing to project.
+  assert.equal(
+    normalizePhoto(record({ projection: 'SPHERE', fieldOfView: '360' })).urls
+      .pano,
+    null,
+  );
+});
+
+test('records without an id or a position are dropped; a missing heading is null', () => {
+  assert.equal(normalizePhoto(null), null);
+  // 0,0 is a missing fix.
+  assert.equal(
+    normalizePhoto(
+      record({ lat: '0', lng: '0', matchLat: '0', matchLng: '0' }),
+    ),
+    null,
+  );
+  assert.equal(normalizePhoto(record({ lat: '95', matchLat: '95' })), null);
+  assert.equal(normalizePhoto(record({ id: undefined })), null);
+  assert.equal(
+    normalizePhoto(
+      record({ lat: 'x', lng: 'y', matchLat: undefined, matchLng: undefined }),
+    ),
+    null,
+  );
+  assert.equal(normalizePhoto(record({ heading: '' })).heading, null);
+  // A device without a compass reads 0 for a whole drive: unknown, not north.
+  assert.equal(normalizePhoto(record({ heading: '0' })).heading, null);
+  assert.equal(normalizePhoto(record({ heading: '0.5' })).heading, 0.5);
+  assert.equal(normalizePhoto(record({ heading: 'n/a' })).heading, null);
+});
+
+test('timestamps parse as UTC; years before 1990 and garbage are unknown', () => {
+  assert.equal(kartaViewTimeMs('2022-03-21'), Date.UTC(2022, 2, 21));
+  assert.equal(
+    kartaViewTimeMs('2022-03-21T06:42:59'),
+    Date.UTC(2022, 2, 21, 6, 42, 59),
+  );
+  assert.equal(kartaViewTimeMs('0000-00-00 00:00:00'), null);
+  assert.equal(kartaViewTimeMs(''), null);
+  assert.equal(kartaViewTimeMs(null), null);
+  const fallback = normalizePhoto(record({ shotDate: null }));
+  assert.equal(fallback.capturedAt, Date.UTC(2016, 7, 24, 4, 1, 7));
+});
+
+test('resized images go through the proxy with a base64url address', () => {
+  const url = resizedImageUrl(
+    'https://storage13.openstreetcam.org/files/photo/a?b=c+d',
+    [1024, 512],
+  );
+  const [, encoded] = /\/rs:fit:1024:512\/(.+)$/.exec(url);
+  assert.match(url, /^https:\/\/cdn\.kartaview\.org\/pr:sharp\/rs:fit:/);
+  assert.doesNotMatch(encoded, /[+/=]/);
+  const decoded = Buffer.from(
+    encoded.replace(/-/g, '+').replace(/_/g, '/'),
+    'base64',
+  ).toString();
+  assert.equal(
+    decoded,
+    'https://storage13.openstreetcam.org/files/photo/a?b=c+d',
+  );
+  assert.equal(resizedImageUrl(null, [1, 1]), null);
+});
+
+test('a storage value that only contains a storage host name builds no address from it', () => {
+  for (const storage of ['evil.example/#storage1', 'storage1.evil.example']) {
+    const photo = normalizePhoto(record({ storage }));
+    // Not a storage host: the API's own storage URLs serve.
+    assert.equal(
+      photo.urls.view,
+      'https://storage1.openstreetcam.org/files/photo/2016/8/24/lth/14010_ba53c_57bd1d23d50b7.jpg',
+      storage,
+    );
+    assert.equal(
+      photo.urls.full,
+      'https://storage1.openstreetcam.org/files/photo/2016/8/24/proc/14010_ba53c_57bd1d23d50b7.jpg',
+      storage,
+    );
+  }
+});
+
+test('a 360° field of view makes a panorama whatever the projection says', () => {
+  assert.equal(
+    normalizePhoto(record({ projection: 'PLANE', fieldOfView: '360' })).isPano,
+    true,
+  );
+  assert.equal(
+    normalizePhoto(record({ projection: 'PLANE', fieldOfView: '359' })).isPano,
+    false,
+  );
+});
+
+test('a longitude past ±180 is not a position', () => {
+  assert.equal(normalizePhoto(record({ lng: '181', matchLng: '181' })), null);
+  assert.equal(normalizePhoto(record({ lng: '-181', matchLng: '-181' })), null);
+  assert.equal(
+    normalizePhoto(record({ lng: '180', matchLng: '180' })).lon,
+    180,
+  );
+});
+
+test('with no processed-photo path the size prefix gives the full photo', () => {
+  const photo = normalizePhoto(
+    record({ filepathProc: '', fileurlProc: '', storage: 'storage3' }),
+  );
+  assert.equal(
+    photo.urls.full,
+    'https://storage3.openstreetcam.org/files/photo/2016/8/24/proc/14010_ba53c_57bd1d23d50b7.jpg',
+  );
+  // Only the large thumbnail, no path at all: the thumbnail still shows.
+  const thumbOnly = normalizePhoto(
+    record({
+      filepathProc: '',
+      fileurlProc: '',
+      filepath: '',
+      fileurl: '',
+      storage: 'storage3',
+    }),
+  );
+  assert.equal(thumbOnly.urls.full, null);
+  assert.match(
+    thumbOnly.urls.view,
+    /^https:\/\/storage3\.openstreetcam\.org\/.*\/lth\//,
+  );
+});
+
+test('the camera looks along the drive: each photo’s course points to the next one a few metres on', () => {
+  // North along a meridian, 5 m apart, then a repeat of the last position.
+  const step = 5 / 110_540;
+  const photos = [0, 1, 2, 3].map((i) => ({ lon: 10, lat: 50 + i * step }));
+  photos.push({ lon: 10, lat: 50 + 3 * step }); // a stop: same place
+  const metres = (a, b) =>
+    Math.hypot(
+      (b.lon - a.lon) * 111_320 * Math.cos((a.lat * Math.PI) / 180),
+      (b.lat - a.lat) * 110_540,
+    );
+  assignCourses(photos, metres);
+  for (const photo of photos)
+    assert.ok(
+      Math.abs(photo.course) < 0.5 || Math.abs(photo.course - 360) < 0.5,
+      `${photo.course}`,
+    );
+  // Eastward: 90°.
+  const east = [0, 1].map((i) => ({ lon: 10 + (i * 5) / 71_600, lat: 50 }));
+  assignCourses(east, metres);
+  assert.ok(
+    Math.abs(east[0].course - 90) < 0.5 && Math.abs(east[1].course - 90) < 0.5,
+  );
+  // A lone photo has no course; the compass is the fallback, then unknown.
+  const [lone] = assignCourses([{ lon: 1, lat: 1 }], metres);
+  assert.equal(lone.course, null);
+  assert.equal(cameraBearing({ ...lone, heading: 42 }), 42);
+  assert.equal(cameraBearing({ ...lone, heading: null }), null);
+  assert.equal(
+    cameraBearing({ course: 90, heading: 200 }),
+    90,
+    'the drive beats the compass',
+  );
+  assert.ok(
+    Math.abs(bearingBetween({ lon: 0, lat: 0 }, { lon: 0, lat: -1 }) - 180) <
+      1e-9,
+  );
+});
+
+test('the imagery filter becomes KartaView’s tile query and photo-search params', () => {
+  // 2026-03-05 23:30 UTC: the cut-off day is the UTC one.
+  const sinceMs = Date.UTC(2026, 2, 5, 23, 30);
+  assert.equal(tileFilterQuery(null), '');
+  assert.equal(tileFilterQuery({ pano: 'all', sinceMs: null }), '');
+  assert.equal(
+    tileFilterQuery({ pano: 'pano', sinceMs: null }),
+    'fieldOfView=360',
+  );
+  assert.equal(
+    tileFilterQuery({ pano: 'flat', sinceMs }),
+    'fieldOfView=plane&startDate=2026-03-05',
+  );
+  assert.equal(tileFilterQuery({ pano: 'all', sinceMs: 0 }), '');
+  // The search ignores fieldOfView; its projection filters instead.
+  assert.deepEqual(photoFilterParams({ pano: 'all', sinceMs: null }), {});
+  assert.deepEqual(photoFilterParams({ pano: 'pano', sinceMs }), {
+    projection: 'SPHERE',
+    startDate: '2026-03-05',
+  });
+  assert.deepEqual(photoFilterParams({ pano: 'flat', sinceMs: null }), {
+    projection: 'PLANE',
+  });
+});
+
+test('KartaView’s SINCE is the upload date, from the start of the cut-off’s UTC day', () => {
+  const photo = normalizePhoto(
+    record({
+      shotDate: '2016-08-23 20:17:47.000',
+      dateAdded: '2026-03-05 00:10:00',
+    }),
+  );
+  assert.equal(photo.uploadedAt, Date.UTC(2026, 2, 5, 0, 10));
+  const since = (iso) => ({ pano: 'all', sinceMs: Date.parse(iso) });
+  // Taken in 2016, uploaded on the cut-off day: it passes, as KartaView's
+  // startDate=2026-03-05 keeps it.
+  assert.equal(
+    passesKartaViewFilter(photo, since('2026-03-05T23:00:00Z')),
+    true,
+  );
+  assert.equal(
+    passesKartaViewFilter(photo, since('2026-03-06T00:00:00Z')),
+    false,
+  );
+  assert.equal(
+    passesKartaViewFilter(photo, { pano: 'pano', sinceMs: null }),
+    false,
+  );
+  assert.equal(
+    passesKartaViewFilter(photo, { pano: 'flat', sinceMs: null }),
+    true,
+  );
+  assert.equal(passesKartaViewFilter(photo, null), true);
+  assert.equal(
+    passesKartaViewFilter(
+      { ...photo, uploadedAt: null },
+      since('2020-01-01T00:00:00Z'),
+    ),
+    false,
+    'no upload date passes no SINCE',
+  );
+});

src/layers/streetLevel/providers/kartaview/source.js

@@ -0,0 +1,422 @@
+import {
+  IMAGE_PROBE_TIMEOUT_MS,
+  MAX_RESPONSE_BYTES,
+  KARTAVIEW_API_HOST,
+  MASK_ATTEMPTS,
+  MASK_MAX_BYTES,
+  MASK_RETRY_WAIT_MS,
+  MASK_SLOW_MESSAGE,
+  MASK_TIMEOUT_MS,
+  NEAREST_LIMIT,
+  NEAREST_SEARCH_ZOOM,
+  PAGE_CONCURRENCY,
+  PAGE_TIMEOUT_MS,
+  PHOTO_API_CONCURRENCY,
+  PHOTO_API_RETRIES,
+  PHOTO_API_RETRY_BASE_MS,
+  PHOTO_API_RETRY_MAX_MS,
+  PHOTO_API_FIRST_TIMEOUT_MS,
+  PHOTO_API_TIMEOUT_MS,
+  TILE_CONCURRENCY,
+  TILE_TIMEOUT_MS,
+  photoFilterParams,
+} from './policy.js';
+import { msg } from '../../../../i18n/index.js';
+import { createLimiter } from '../../limiter.js';
+
+export { createLimiter } from '../../limiter.js';
+
+/**
+ * An HTTP or API failure; `retryAfterSec` is set while KartaView rate-limits,
+ * `timedOut` when it did not answer in time (the one failure worth asking
+ * again at once).
+ */
+export class KartaViewSourceError extends Error {
+  constructor(
+    message,
+    { status = 0, retryAfterSec = null, timedOut = false } = {},
+  ) {
+    super(message);
+    this.name = 'KartaViewSourceError';
+    this.status = status;
+    this.retryAfterSec = retryAfterSec;
+    this.timedOut = timedOut;
+  }
+}
+
+// Failure texts are English data: the Street Level panel translates them.
+const NO_ANSWER = msg('KartaView did not answer in time — try again');
+const UNREACHABLE = msg('KartaView could not be reached — check the network');
+const UNREADABLE = msg('KartaView sent an answer that could not be read');
+/** Statuses that mean a photo file is gone, not that storage hiccupped. */
+const GONE_STATUSES = Object.freeze([403, 404, 409, 410]);
+
+/** Resolves after `ms`, or rejects when `signal` aborts first. */
+function wait(ms, signal) {
+  return new Promise((resolve, reject) => {
+    if (signal?.aborted) return reject(signal.reason);
+    const timer = setTimeout(done, ms);
+    const onAbort = () => {
+      clearTimeout(timer);
+      reject(signal.reason);
+    };
+    signal?.addEventListener('abort', onAbort, { once: true });
+    function done() {
+      signal?.removeEventListener('abort', onAbort);
+      resolve();
+    }
+  });
+}
+
+/** Seconds from a Retry-After header, or null. */
+function retryAfterSeconds(response) {
+  const header = response.headers?.get?.('retry-after');
+  const value = header == null || header === '' ? NaN : Number(header);
+  return Number.isFinite(value) && value >= 0 ? value : null;
+}
+
+/**
+ * KartaView's public API, browser-side and keyless (it allows any origin).
+ * It speaks HTTP/1.1, so the browser opens six connections to it: tiles take
+ * at most three, photo lookups two and sequence pages one, so a lookup never
+ * waits behind slow tiles or pages. The photo API answers 429 to more than
+ * about three requests at once; a 429 (and a lookup that timed out) is
+ * retried.
+ * @param {{fetchImpl?: typeof fetch, apiHost?: string, retryBaseMs?: number, maskRetryMs?: number}} [options]
+ */
+export function createKartaViewSource({
+  fetchImpl = (...args) => globalThis.fetch(...args),
+  apiHost = KARTAVIEW_API_HOST,
+  retryBaseMs = PHOTO_API_RETRY_BASE_MS,
+  maskRetryMs = MASK_RETRY_WAIT_MS,
+} = {}) {
+  const limiter = createLimiter(PHOTO_API_CONCURRENCY);
+  const tileLimiter = createLimiter(TILE_CONCURRENCY);
+  const pageLimiter = createLimiter(PAGE_CONCURRENCY, { lifo: true });
+
+  /** GET JSON within `timeoutMs`; the caller's abort wins over the timeout. */
+  function getJson(url, { signal, timeoutMs }) {
+    return fetchBody(url, { signal, timeoutMs, as: 'json' });
+  }
+
+  /**
+   * GET a body within `timeoutMs`, at most `maxBytes` of it, as parsed JSON
+   * or (`as: 'bytes'`) a Uint8Array; the caller's abort wins over the
+   * timeout.
+   */
+  async function fetchBody(
+    url,
+    { signal, timeoutMs, as = 'json', maxBytes = MAX_RESPONSE_BYTES },
+  ) {
+    const controller = new AbortController();
+    const onAbort = () => controller.abort(signal.reason);
+    if (signal?.aborted) throw signal.reason;
+    signal?.addEventListener('abort', onAbort, { once: true });
+    const timer = setTimeout(
+      () =>
+        controller.abort(
+          new KartaViewSourceError(NO_ANSWER, { timedOut: true }),
+        ),
+      timeoutMs,
+    );
+    let response = null;
+    let read = false;
+    try {
+      response = await fetchImpl(url, { signal: controller.signal });
+      if (response.status === 429)
+        throw new KartaViewSourceError(
+          msg('KartaView is rate-limiting requests'),
+          {
+            status: 429,
+            retryAfterSec: retryAfterSeconds(response) ?? 2,
+          },
+        );
+      // English data with a number: the Street Level panel and the layer
+      // panel show it through the 'KartaView answered HTTP {status}' entry.
+      if (!response.ok)
+        throw new KartaViewSourceError(
+          `KartaView answered HTTP ${response.status}`,
+          { status: response.status },
+        );
+      const length = Number(response.headers?.get?.('content-length'));
+      const tooMuch = () =>
+        new KartaViewSourceError(msg('KartaView sent too much data'), {
+          status: response.status,
+        });
+      if (length > maxBytes) throw tooMuch();
+      // KartaView answers chunked, without a length: count while reading.
+      const reader = response.body?.getReader?.();
+      if (!reader) {
+        read = true;
+        try {
+          if (as === 'bytes')
+            return new Uint8Array(await response.arrayBuffer());
+          return await response.json();
+        } catch (error) {
+          if (controller.signal.aborted) throw error;
+          throw new KartaViewSourceError(UNREADABLE, {
+            status: response.status,
+          });
+        }
+      }
+      read = true;
+      const chunks = [];
+      let bytes = 0;
+      for (;;) {
+        const { done, value } = await reader.read();
+        if (done) break;
+        bytes += value.byteLength;
+        if (bytes > maxBytes) {
+          reader.cancel().catch(() => {});
+          throw tooMuch();
+        }
+        chunks.push(value);
+      }
+      const body = new Uint8Array(bytes);
+      let offset = 0;
+      for (const chunk of chunks) {
+        body.set(chunk, offset);
+        offset += chunk.byteLength;
+      }
+      if (as === 'bytes') return body;
+      try {
+        return JSON.parse(new TextDecoder().decode(body));
+      } catch {
+        throw new KartaViewSourceError(UNREADABLE, {
+          status: response.status,
+        });
+      }
+    } catch (error) {
+      if (signal?.aborted) throw signal.reason;
+      if (controller.signal.aborted) throw controller.signal.reason;
+      if (error instanceof KartaViewSourceError) throw error;
+      // fetch rejects on no network, a blocked request or a refused CORS check.
+      throw new KartaViewSourceError(UNREACHABLE);
+    } finally {
+      clearTimeout(timer);
+      signal?.removeEventListener('abort', onAbort);
+      // An answer turned away unread (429, an error, too long) still holds
+      // its connection, one of the six the browser has: let it go.
+      if (response && !read) {
+        controller.abort();
+        if (response.body && !response.body.locked)
+          response.body.cancel?.().catch?.(() => {});
+      }
+    }
+  }
+
+  /**
+   * A photo-API call through `gate`, retrying 429s with backoff and, once, a
+   * call that timed out.
+   */
+  async function photoApi(
+    path,
+    params,
+    { signal } = {},
+    {
+      gate = limiter,
+      timeoutMs = PHOTO_API_TIMEOUT_MS,
+      firstTimeoutMs = PHOTO_API_FIRST_TIMEOUT_MS,
+    } = {},
+  ) {
+    const query = params ? `?${new URLSearchParams(params)}` : '';
+    const url = `${apiHost}${path}${query}`;
+    let timeouts = 0;
+    for (let attempt = 0; ; attempt++) {
+      try {
+        const payload = await gate.run(
+          // A slow first answer is usually quick when asked again.
+          () =>
+            getJson(url, {
+              signal,
+              timeoutMs: timeouts === 0 ? firstTimeoutMs : timeoutMs,
+            }),
+          { signal },
+        );
+        const code = Number(payload?.status?.apiCode);
+        // 600 ok, 601 empty, 602 partial: anything else is a refusal.
+        // Shown through 'KartaView refused the request (code {code})'.
+        if (Number.isFinite(code) && (code < 600 || code > 603))
+          throw new KartaViewSourceError(
+            `KartaView refused the request (code ${code})`,
+            { status: Number(payload?.status?.httpCode) || 0 },
+          );
+        return payload?.result ?? {};
+      } catch (error) {
+        if (signal?.aborted) throw error;
+        const timedOut = error?.timedOut === true;
+        if (timedOut && timeouts++ < 1) continue;
+        if (error?.status !== 429 || attempt >= PHOTO_API_RETRIES) {
+          if (error?.status === 429)
+            throw new KartaViewSourceError(
+              msg(
+                'KartaView is rate-limiting requests — try again in a moment',
+              ),
+              { status: 429, retryAfterSec: error.retryAfterSec },
+            );
+          throw error;
+        }
+        await wait(
+          Math.min(
+            PHOTO_API_RETRY_MAX_MS,
+            Math.max(
+              retryBaseMs * 2 ** attempt,
+              (error.retryAfterSec ?? 0) * 1000,
+            ),
+          ),
+          signal,
+        );
+      }
+    }
+  }
+
+  return {
+    /** A coverage tile: `{lines: [{track: [{lat, lng}]}]}`. */
+    async getTile({ x, y, z }, { signal } = {}) {
+      const url = `${apiHost}/2.0/sequence/tiles/${x}/${y}/${z}.json`;
+      const once = () =>
+        tileLimiter.run(
+          () => getJson(url, { signal, timeoutMs: TILE_TIMEOUT_MS }),
+          { signal },
+        );
+      try {
+        return await once();
+      } catch (error) {
+        // A cold dense tile can outlast the timeout; KartaView has it ready
+        // by the second ask.
+        if (signal?.aborted || error?.timedOut !== true) throw error;
+        return once();
+      }
+    },
+
+    /**
+     * A filtered coverage tile as PNG bytes, `query` from tileFilterQuery
+     * (KartaView filters only its PNG tiles). It draws a filtered tile on
+     * demand; a dense one can outlast its own 60 s (504) and still be drawn,
+     * so a timeout or a 5xx is asked again a few seconds later.
+     */
+    async getTileMask({ x, y, z }, query, { signal } = {}) {
+      const url = `${apiHost}/2.0/sequence/tiles/${x}/${y}/${z}.png?${query}`;
+      for (let attempt = 1; ; attempt++) {
+        try {
+          // Outside the gate between tries: a wait holds no connection.
+          return await tileLimiter.run(
+            () =>
+              fetchBody(url, {
+                signal,
+                timeoutMs: MASK_TIMEOUT_MS,
+                as: 'bytes',
+                maxBytes: MASK_MAX_BYTES,
+              }),
+            { signal },
+          );
+        } catch (error) {
+          if (signal?.aborted) throw error;
+          const drawing =
+            error?.timedOut === true || [502, 503, 504].includes(error?.status);
+          if (!drawing) throw error;
+          if (attempt >= MASK_ATTEMPTS)
+            throw new KartaViewSourceError(MASK_SLOW_MESSAGE, {
+              timedOut: true,
+            });
+          await wait(maskRetryMs, signal);
+        }
+      }
+    },
+
+    /**
+     * Whether a photo file is there: true, false when it is gone (archived
+     * photos answer 409, and a HEAD says 200 regardless), or null when the
+     * storage did not say (timeout, network, 5xx). It GETs and stops at the
+     * headers.
+     */
+    async probeImage(url, { signal } = {}) {
+      if (!url) return false;
+      const controller = new AbortController();
+      const onAbort = () => controller.abort(signal.reason);
+      if (signal?.aborted) throw signal.reason;
+      signal?.addEventListener('abort', onAbort, { once: true });
+      const timer = setTimeout(
+        () => controller.abort(),
+        IMAGE_PROBE_TIMEOUT_MS,
+      );
+      try {
+        const response = await fetchImpl(url, { signal: controller.signal });
+        if (response.ok) return true;
+        return GONE_STATUSES.includes(response.status) ? false : null;
+      } catch {
+        if (signal?.aborted) throw signal.reason;
+        return null;
+      } finally {
+        clearTimeout(timer);
+        signal?.removeEventListener('abort', onAbort);
+        // The body is not needed: drop it.
+        controller.abort();
+      }
+    },
+
+    /**
+     * Photo records around a point, nearest first; with a resolved imagery
+     * `filter`, only those of its projection uploaded since its cut-off.
+     */
+    async nearestPhotos({ lat, lon, filter = null }, { signal } = {}) {
+      const result = await photoApi(
+        '/2.0/photo/',
+        {
+          lat: lat.toFixed(7),
+          lng: lon.toFixed(7),
+          zoomLevel: String(NEAREST_SEARCH_ZOOM),
+          itemsPerPage: String(NEAREST_LIMIT),
+          ...photoFilterParams(filter),
+        },
+        { signal },
+      );
+      return Array.isArray(result.data) ? result.data : [];
+    },
+
+    /** One photo record. */
+    async getPhoto(photoId, { signal } = {}) {
+      const result = await photoApi(
+        `/2.0/photo/${encodeURIComponent(photoId)}`,
+        null,
+        { signal },
+      );
+      if (!result.data || typeof result.data !== 'object')
+        throw new KartaViewSourceError(msg('KartaView has no such photo'));
+      return result.data;
+    },
+
+    /** How many photos a sequence has, or null if KartaView does not say. */
+    async getSequenceCount(sequenceId, { signal } = {}) {
+      const result = await photoApi(
+        `/2.0/sequence/${encodeURIComponent(sequenceId)}`,
+        null,
+        { signal },
+      );
+      const count = Number(result.data?.countActivePhotos);
+      return Number.isFinite(count) && count > 0 ? count : null;
+    },
+
+    /** A page of a sequence's photos in capture order (1-based `page`). */
+    async getSequencePhotos(
+      sequenceId,
+      { page, itemsPerPage },
+      { signal } = {},
+    ) {
+      const result = await photoApi(
+        `/2.0/sequence/${encodeURIComponent(sequenceId)}/photos`,
+        { page: String(page), itemsPerPage: String(itemsPerPage) },
+        { signal },
+        {
+          gate: pageLimiter,
+          timeoutMs: PAGE_TIMEOUT_MS,
+          firstTimeoutMs: PAGE_TIMEOUT_MS,
+        },
+      );
+      return {
+        photos: Array.isArray(result.data) ? result.data : [],
+        hasMore: result.hasMoreData === true,
+      };
+    },
+  };
+}

src/layers/streetLevel/providers/kartaview/source.test.mjs

@@ -0,0 +1,728 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import {
+  KartaViewSourceError,
+  createKartaViewSource,
+  createLimiter,
+} from './source.js';
+import {
+  MASK_ATTEMPTS,
+  MASK_SLOW_MESSAGE,
+  NEAREST_LIMIT,
+  NEAREST_SEARCH_ZOOM,
+  PHOTO_API_CONCURRENCY,
+  PHOTO_API_RETRIES,
+  PHOTO_API_FIRST_TIMEOUT_MS,
+  PHOTO_API_TIMEOUT_MS,
+  PAGE_TIMEOUT_MS,
+  TILE_CONCURRENCY,
+} from './policy.js';
+
+/** A body streamed as browsers do, in `size`-byte chunks. */
+function streamed(text, size = 16_384) {
+  const bytes = new TextEncoder().encode(text);
+  let at = 0;
+  return {
+    getReader: () => ({
+      read: async () => {
+        if (at >= bytes.length) return { done: true };
+        const value = bytes.slice(at, at + size);
+        at += size;
+        return { done: false, value };
+      },
+      cancel: async () => {},
+    }),
+  };
+}
+
+// A 200 as browsers deliver it: streamed, so the code under test reads it
+// the way it does in production (`json` is there only to fail loudly).
+const ok = (body) => ({
+  ok: true,
+  status: 200,
+  headers: new Map(),
+  body: streamed(JSON.stringify(body)),
+  json: async () => {
+    throw new Error('a browser answer is read from its stream');
+  },
+});
+const status = (code, headers = new Map()) => ({
+  ok: false,
+  status: code,
+  headers,
+  json: async () => ({}),
+});
+const photoPayload = (data) => ({
+  status: { apiCode: 600, httpCode: 200 },
+  result: { data, hasMoreData: false },
+});
+
+test('coverage tiles come from api.kartaview.org as JSON', async () => {
+  const urls = [];
+  const source = createKartaViewSource({
+    fetchImpl: async (url) => {
+      urls.push(url);
+      return ok({ lines: [] });
+    },
+  });
+  assert.deepEqual(await source.getTile({ x: 4412, y: 6061, z: 14 }), {
+    lines: [],
+  });
+  assert.deepEqual(urls, [
+    'https://api.kartaview.org/2.0/sequence/tiles/4412/6061/14.json',
+  ]);
+});
+
+test('photo lookups run at most two at a time', async () => {
+  let running = 0;
+  let peak = 0;
+  const source = createKartaViewSource({
+    fetchImpl: async () => {
+      running++;
+      peak = Math.max(peak, running);
+      await new Promise((resolve) => setTimeout(resolve, 5));
+      running--;
+      return ok(photoPayload({ id: '1' }));
+    },
+  });
+  await Promise.all(
+    Array.from({ length: 7 }, (_, i) => source.getPhoto(String(i))),
+  );
+  assert.equal(peak, PHOTO_API_CONCURRENCY);
+});
+
+test('a 429 is retried after a wait, then answered', async () => {
+  let calls = 0;
+  const source = createKartaViewSource({
+    retryBaseMs: 1,
+    fetchImpl: async () => {
+      calls++;
+      return calls < 3
+        ? status(429, new Map([['retry-after', '0']]))
+        : ok(photoPayload([{ id: '9' }]));
+    },
+  });
+  const records = await source.nearestPhotos({ lat: 42.3, lon: -83.04 });
+  assert.deepEqual(records, [{ id: '9' }]);
+  assert.equal(calls, 3);
+});
+
+test('rate-limiting that outlasts the retries is reported with a wait', async () => {
+  let calls = 0;
+  const source = createKartaViewSource({
+    retryBaseMs: 1,
+    fetchImpl: async () => {
+      calls++;
+      return status(429, new Map([['retry-after', '0.001']]));
+    },
+  });
+  await assert.rejects(source.getPhoto('1'), (error) => {
+    assert.ok(error instanceof KartaViewSourceError);
+    assert.equal(error.status, 429);
+    assert.ok(error.retryAfterSec > 0);
+    assert.match(error.message, /try again in a moment/);
+    return true;
+  });
+  assert.equal(calls, PHOTO_API_RETRIES + 1);
+});
+
+test('an API refusal inside a 200 is a readable error with its code; 601 is just empty', async () => {
+  const refusing = createKartaViewSource({
+    fetchImpl: async () =>
+      ok({
+        status: { apiCode: 612, apiMessage: ' out of range ', httpCode: 400 },
+        result: {},
+      }),
+  });
+  await assert.rejects(
+    refusing.getPhoto('1'),
+    /KartaView refused the request \(code 612\)/,
+  );
+  const empty = createKartaViewSource({
+    fetchImpl: async () =>
+      ok({ status: { apiCode: 601 }, result: { data: [] } }),
+  });
+  assert.deepEqual(await empty.nearestPhotos({ lat: 0, lon: 0 }), []);
+  const page = await empty.getSequencePhotos('2008', {
+    page: 2,
+    itemsPerPage: 1000,
+  });
+  assert.deepEqual(page, { photos: [], hasMore: false });
+});
+
+test('HTTP errors, network failures and non-JSON become readable errors', async () => {
+  const http = createKartaViewSource({ fetchImpl: async () => status(500) });
+  await assert.rejects(http.getTile({ x: 0, y: 0, z: 14 }), /HTTP 500/);
+  let asked = 0;
+  const offline = createKartaViewSource({
+    fetchImpl: async () => {
+      asked++;
+      throw new TypeError('Failed to fetch');
+    },
+  });
+  // Not a timeout: no network is said as much, and not asked again at once.
+  await assert.rejects(
+    offline.getPhoto('1'),
+    /could not be reached — check the network/,
+  );
+  assert.equal(asked, 1);
+  const garbled = createKartaViewSource({
+    fetchImpl: async () => ({
+      ok: true,
+      status: 200,
+      headers: new Map(),
+      json: async () => {
+        throw new SyntaxError('Unexpected token <');
+      },
+    }),
+  });
+  await assert.rejects(
+    garbled.getTile({ x: 0, y: 0, z: 14 }),
+    /could not be read/,
+  );
+  const torn = createKartaViewSource({
+    fetchImpl: async () => ({
+      ok: true,
+      status: 200,
+      headers: new Map(),
+      body: streamed('{"lines": [', 4),
+    }),
+  });
+  await assert.rejects(
+    torn.getTile({ x: 0, y: 0, z: 14 }),
+    /could not be read/,
+  );
+});
+
+test('an abort stops a queued lookup without fetching, and wins over a retry wait', async () => {
+  let calls = 0;
+  let release;
+  const gate = new Promise((resolve) => (release = resolve));
+  const source = createKartaViewSource({
+    retryBaseMs: 10_000,
+    fetchImpl: async (url) => {
+      calls++;
+      if (url.includes('/slow')) await gate;
+      return status(429);
+    },
+  });
+  // Two slow lookups fill the queue; the third waits for a slot.
+  const first = new AbortController();
+  const slow = [
+    source.getPhoto('slow', { signal: first.signal }),
+    source.getPhoto('slow', { signal: first.signal }),
+  ];
+  const controller = new AbortController();
+  const queued = source.getPhoto('queued', { signal: controller.signal });
+  controller.abort(new Error('overtaken'));
+  await assert.rejects(queued, /overtaken/);
+  assert.equal(calls, 2, 'the queued lookup never fetched');
+  release();
+  // Each slow one is now waiting 10 s to retry; nothing else is asked.
+  const retrying = new AbortController();
+  const waiting = source.getPhoto('slow', { signal: retrying.signal });
+  await new Promise((resolve) => setTimeout(resolve, 20));
+  retrying.abort(new Error('closed'));
+  await assert.rejects(waiting, /closed/);
+  // The two first lookups are still waiting out their backoff: drop them.
+  first.abort(new Error('done'));
+  for (const promise of slow) await assert.rejects(promise, /done/);
+});
+
+test('the limiter runs tasks in order and keeps going after a failure', async () => {
+  const limiter = createLimiter(1);
+  const order = [];
+  const failing = limiter.run(async () => {
+    order.push('a');
+    throw new Error('a failed');
+  });
+  const second = limiter.run(async () => {
+    order.push('b');
+    return 'b';
+  });
+  await assert.rejects(failing, /a failed/);
+  assert.equal(await second, 'b');
+  assert.deepEqual(order, ['a', 'b']);
+  await new Promise((resolve) => setTimeout(resolve, 0));
+  assert.equal(limiter.pending, 0);
+});
+
+test('tiles, lookups and sequence pages queue separately, so a lookup never waits behind them', async () => {
+  const running = { tile: 0, photo: 0, page: 0 };
+  const peak = { tile: 0, photo: 0, page: 0 };
+  const release = [];
+  const kind = (url) =>
+    url.includes('/tiles/')
+      ? 'tile'
+      : url.includes('/photos')
+        ? 'page'
+        : 'photo';
+  const source = createKartaViewSource({
+    fetchImpl: async (url) => {
+      const k = kind(url);
+      running[k]++;
+      peak[k] = Math.max(peak[k], running[k]);
+      if (k !== 'photo') await new Promise((resolve) => release.push(resolve));
+      running[k]--;
+      return k === 'tile' ? ok({ lines: [] }) : ok(photoPayload([]));
+    },
+  });
+  const tiles = Array.from({ length: 9 }, (_, i) =>
+    source.getTile({ x: i, y: 0, z: 14 }),
+  );
+  const pages = [1, 2].map((page) =>
+    source.getSequencePhotos('1', { page, itemsPerPage: 500 }),
+  );
+  // Every slow tile and page is in flight or queued; a lookup still answers.
+  assert.deepEqual(await source.nearestPhotos({ lat: 1, lon: 1 }), []);
+  assert.equal(peak.tile, TILE_CONCURRENCY);
+  assert.equal(peak.page, 1);
+  while (release.length) {
+    release.shift()();
+    await new Promise((resolve) => setTimeout(resolve, 0));
+  }
+  await Promise.all([...tiles, ...pages]);
+  assert.equal(peak.tile, TILE_CONCURRENCY);
+  assert.equal(peak.page, 1);
+});
+
+test('a lookup that times out is asked once more, then reported as no answer in time', async (t) => {
+  t.mock.timers.enable({ apis: ['setTimeout'] });
+  let calls = 0;
+  const outcome = await onMockClock(t, () =>
+    createKartaViewSource({
+      fetchImpl: (url, { signal }) => {
+        calls++;
+        return new Promise((resolve, reject) =>
+          signal.addEventListener('abort', () => reject(signal.reason)),
+        );
+      },
+    }).getPhoto('1'),
+  );
+  assert.match(
+    String(outcome?.error?.message),
+    /did not answer in time — try again/,
+  );
+  assert.equal(outcome.error.timedOut, true);
+  assert.equal(calls, 2);
+});
+
+test('an image probe reads only the status: an archived photo (409) is not showable', async () => {
+  const seen = [];
+  const source = createKartaViewSource({
+    fetchImpl: async (url, { signal }) => {
+      seen.push(signal);
+      return {
+        ok: !url.includes('archived'),
+        status: url.includes('archived') ? 409 : 200,
+      };
+    },
+  });
+  assert.equal(
+    await source.probeImage('https://storage13.openstreetcam.org/ok.jpg'),
+    true,
+  );
+  assert.equal(
+    await source.probeImage('https://storage13.openstreetcam.org/archived.jpg'),
+    false,
+  );
+  assert.equal(await source.probeImage(null), false);
+  assert.ok(
+    seen.every((signal) => signal.aborted),
+    'the body is dropped',
+  );
+  const offline = createKartaViewSource({
+    fetchImpl: async () => {
+      throw new TypeError('Failed to fetch');
+    },
+  });
+  // No answer is not an answer: the caller may try again later.
+  assert.equal(
+    await offline.probeImage('https://x.openstreetcam.org/a.jpg'),
+    null,
+  );
+  const busy = createKartaViewSource({
+    fetchImpl: async () => ({ ok: false, status: 502 }),
+  });
+  assert.equal(
+    await busy.probeImage('https://x.openstreetcam.org/a.jpg'),
+    null,
+  );
+});
+
+test('a cold tile that times out is asked once more; an unreachable one is not', async (t) => {
+  t.mock.timers.enable({ apis: ['setTimeout'] });
+  let calls = 0;
+  const outcome = await onMockClock(t, () =>
+    createKartaViewSource({
+      fetchImpl: (url, { signal }) => {
+        calls++;
+        if (calls === 1)
+          return new Promise((resolve, reject) =>
+            signal.addEventListener('abort', () => reject(signal.reason)),
+          );
+        return Promise.resolve(ok({ lines: [] }));
+      },
+    }).getTile({ x: 1, y: 2, z: 13 }),
+  );
+  assert.deepEqual(outcome.value, { lines: [] });
+  assert.equal(calls, 2);
+  let asked = 0;
+  const offline = createKartaViewSource({
+    fetchImpl: async () => {
+      asked++;
+      throw new TypeError('Failed to fetch');
+    },
+  });
+  await assert.rejects(
+    offline.getTile({ x: 1, y: 2, z: 13 }),
+    /could not be reached/,
+  );
+  assert.equal(asked, 1);
+});
+
+test('an absurdly large answer is refused before it is parsed', async () => {
+  let parsed = false;
+  const source = createKartaViewSource({
+    fetchImpl: async () => ({
+      ok: true,
+      status: 200,
+      headers: new Map([['content-length', String(64 * 1024 * 1024)]]),
+      json: async () => {
+        parsed = true;
+        return { lines: [] };
+      },
+    }),
+  });
+  await assert.rejects(source.getTile({ x: 1, y: 2, z: 13 }), /too much data/);
+  assert.equal(parsed, false);
+});
+
+test('sequence pages run one at a time, the newest first', async () => {
+  const order = [];
+  let release;
+  const gate = new Promise((resolve) => (release = resolve));
+  const source = createKartaViewSource({
+    fetchImpl: async (url) => {
+      const page = new URL(url).searchParams.get('page');
+      order.push(page);
+      if (page === '1') await gate;
+      return ok(photoPayload([]));
+    },
+  });
+  const pages = ['1', '2', '3'].map((page) =>
+    source.getSequencePhotos('9', { page, itemsPerPage: 250 }),
+  );
+  await new Promise((resolve) => setTimeout(resolve, 0));
+  release();
+  await Promise.all(pages);
+  assert.deepEqual(order, ['1', '3', '2']);
+});
+
+/** Every pending promise callback, without moving the mocked clock. */
+const flush = () => new Promise((resolve) => setImmediate(resolve));
+
+/**
+ * Run `call` on the mocked clock in 100 ms steps until it settles (60 s at
+ * most). `stamp()` reads the clock, for a fetch to record when it was asked.
+ */
+async function onMockClock(t, call, { until = 60_000 } = {}) {
+  let now = 0;
+  const stamp = () => now;
+  let outcome = null;
+  const promise = call(stamp);
+  promise.then(
+    (value) => (outcome = { value, at: now }),
+    (error) => (outcome = { error, at: now }),
+  );
+  while (!outcome && now < until) {
+    await flush();
+    if (outcome) break;
+    t.mock.timers.tick(100);
+    now += 100;
+  }
+  await flush();
+  return outcome;
+}
+
+test('429 waits double from 0.8 s, wait out a longer Retry-After up to 10 s, and 2 s without one', async (t) => {
+  t.mock.timers.enable({ apis: ['setTimeout'] });
+  async function waits(retryAfter) {
+    const asked = [];
+    const headers = new Map(
+      retryAfter === undefined ? [] : [['retry-after', retryAfter]],
+    );
+    const outcome = await onMockClock(t, (stamp) =>
+      createKartaViewSource({
+        fetchImpl: async () => {
+          asked.push(stamp());
+          return asked.length <= PHOTO_API_RETRIES
+            ? status(429, headers)
+            : ok(photoPayload({ id: '1' }));
+        },
+      }).getPhoto('1'),
+    );
+    assert.deepEqual(outcome?.value, { id: '1' }, `answered (${retryAfter})`);
+    return asked.slice(1).map((at, i) => at - asked[i]);
+  }
+  assert.deepEqual(await waits('0'), [800, 1600, 3200], 'doubling backoff');
+  assert.deepEqual(await waits('5'), [5000, 5000, 5000], 'Retry-After wins');
+  assert.deepEqual(await waits('30'), [10_000, 10_000, 10_000], 'capped');
+  assert.deepEqual(await waits(undefined), [2000, 2000, 3200], 'assumed 2 s');
+});
+
+test('a lookup that hangs is given up after a short first try, then the full timeout, then reported', async (t) => {
+  t.mock.timers.enable({ apis: ['setTimeout'] });
+  const asked = [];
+  const outcome = await onMockClock(t, (stamp) =>
+    createKartaViewSource({
+      fetchImpl: (url, { signal }) => {
+        asked.push(stamp());
+        return new Promise((resolve, reject) =>
+          signal.addEventListener('abort', () => reject(signal.reason)),
+        );
+      },
+    }).getPhoto('1'),
+  );
+  assert.deepEqual(asked, [0, PHOTO_API_FIRST_TIMEOUT_MS]);
+  assert.match(String(outcome?.error?.message), /did not answer in time/);
+  assert.equal(outcome.at, PHOTO_API_FIRST_TIMEOUT_MS + PHOTO_API_TIMEOUT_MS);
+});
+
+test('the nearest lookup asks for the few photos around the point at the search zoom', async () => {
+  const urls = [];
+  const source = createKartaViewSource({
+    fetchImpl: async (url) => {
+      urls.push(new URL(url));
+      return ok(photoPayload([]));
+    },
+  });
+  await source.nearestPhotos({ lat: 42.33, lon: -83.04 });
+  assert.equal(urls[0].pathname, '/2.0/photo/');
+  assert.deepEqual(Object.fromEntries(urls[0].searchParams), {
+    lat: '42.3300000',
+    lng: '-83.0400000',
+    zoomLevel: String(NEAREST_SEARCH_ZOOM),
+    itemsPerPage: String(NEAREST_LIMIT),
+  });
+  assert.equal(NEAREST_SEARCH_ZOOM, 18);
+  assert.equal(NEAREST_LIMIT, 10);
+});
+
+test('a chunked answer with no length is cut off once it grows past the cap', async () => {
+  let reads = 0;
+  let cancelled = false;
+  const chunk = new Uint8Array(6 * 1024 * 1024);
+  const source = createKartaViewSource({
+    fetchImpl: async () => ({
+      ok: true,
+      status: 200,
+      headers: new Map(),
+      body: {
+        getReader: () => ({
+          read: async () =>
+            ++reads > 10 ? { done: true } : { done: false, value: chunk },
+          cancel: async () => {
+            cancelled = true;
+          },
+        }),
+      },
+    }),
+  });
+  await assert.rejects(source.getTile({ x: 1, y: 2, z: 13 }), /too much data/);
+  assert.equal(reads, 3, 'stopped at the third 6 MB chunk');
+  assert.equal(cancelled, true);
+  const small = createKartaViewSource({
+    fetchImpl: async () => {
+      const bytes = new TextEncoder().encode('{"lines":[]}');
+      let given = false;
+      return {
+        ok: true,
+        status: 200,
+        headers: new Map(),
+        body: {
+          getReader: () => ({
+            read: async () =>
+              given
+                ? { done: true }
+                : ((given = true), { done: false, value: bytes }),
+            cancel: async () => {},
+          }),
+        },
+      };
+    },
+  });
+  assert.deepEqual(await small.getTile({ x: 1, y: 2, z: 13 }), { lines: [] });
+});
+
+test('a chunked answer split mid-character is reassembled in order', async () => {
+  const payload = {
+    lines: [
+      {
+        track: [{ lat: '1', lng: '2' }],
+        name: 'Strada Memorandumului — Cluj-Napoca 😀',
+      },
+    ],
+    note: 'ăîşţ'.repeat(200),
+  };
+  const source = createKartaViewSource({
+    fetchImpl: async () => ({
+      ok: true,
+      status: 200,
+      headers: new Map(),
+      // 3-byte chunks cut multi-byte characters in two.
+      body: streamed(JSON.stringify(payload), 3),
+    }),
+  });
+  assert.deepEqual(await source.getTile({ x: 1, y: 2, z: 13 }), payload);
+});
+
+test('a sequence page gets the full 30 s on its first try, then 30 s once more', async (t) => {
+  t.mock.timers.enable({ apis: ['setTimeout'] });
+  const asked = [];
+  const outcome = await onMockClock(
+    t,
+    (stamp) =>
+      createKartaViewSource({
+        fetchImpl: (url, { signal }) => {
+          asked.push(stamp());
+          return new Promise((resolve, reject) =>
+            signal.addEventListener('abort', () => reject(signal.reason)),
+          );
+        },
+      }).getSequencePhotos('9', { page: 1, itemsPerPage: 250 }),
+    { until: 120_000 },
+  );
+  assert.deepEqual(asked, [0, PAGE_TIMEOUT_MS]);
+  assert.match(String(outcome?.error?.message), /did not answer in time/);
+  assert.equal(outcome.at, 2 * PAGE_TIMEOUT_MS);
+});
+
+test('an answer turned away unread (an error, a 429, a length past the cap) lets its connection go', async () => {
+  /** A response whose body is never read: records its cancel and the abort. */
+  const unread = (answer) => {
+    const seen = { cancelled: false, signal: null };
+    const fetchImpl = async (url, { signal }) => {
+      seen.signal = signal;
+      return {
+        ...answer,
+        body: {
+          locked: false,
+          getReader: () => {
+            throw new Error('not read');
+          },
+          cancel: async () => {
+            seen.cancelled = true;
+          },
+        },
+      };
+    };
+    return { seen, fetchImpl };
+  };
+  const cases = [
+    [{ ok: false, status: 503, headers: new Map() }, /HTTP 503/],
+    [
+      {
+        ok: true,
+        status: 200,
+        headers: new Map([['content-length', String(64 * 1024 * 1024)]]),
+      },
+      /too much data/,
+    ],
+  ];
+  for (const [answer, message] of cases) {
+    const { seen, fetchImpl } = unread(answer);
+    const source = createKartaViewSource({ fetchImpl });
+    await assert.rejects(source.getTile({ x: 1, y: 2, z: 13 }), message);
+    assert.equal(seen.signal.aborted, true, `${message}: request aborted`);
+    assert.equal(seen.cancelled, true, `${message}: body cancelled`);
+  }
+  // A 429 is let go before its retry is asked.
+  const { seen, fetchImpl } = unread({
+    ok: false,
+    status: 429,
+    headers: new Map([['retry-after', '0']]),
+  });
+  const signals = [];
+  const source = createKartaViewSource({
+    fetchImpl: async (url, init) => {
+      signals.push(init.signal);
+      if (signals.length === 1) return fetchImpl(url, init);
+      return ok(photoPayload([]));
+    },
+  });
+  await source.getPhoto('1');
+  assert.equal(signals[0].aborted, true);
+  assert.equal(seen.cancelled, true);
+  assert.equal(signals[1].aborted, false, 'a read answer is left alone');
+});
+
+test('a filtered tile comes as PNG bytes; KartaView still drawing it (504) is asked again, then given up', async () => {
+  const png = new Uint8Array([137, 80, 78, 71, 1, 2, 3]);
+  const bytesOf = () => ({
+    ok: true,
+    status: 200,
+    headers: new Map(),
+    body: {
+      getReader: () => {
+        let given = false;
+        return {
+          read: async () =>
+            given
+              ? { done: true }
+              : ((given = true), { done: false, value: png }),
+          cancel: async () => {},
+        };
+      },
+    },
+  });
+  const urls = [];
+  let answers = [status(504), status(503), bytesOf()];
+  const source = createKartaViewSource({
+    maskRetryMs: 0,
+    fetchImpl: async (url) => {
+      urls.push(url);
+      return answers.shift();
+    },
+  });
+  const tile = { x: 13054, y: 8474, z: 14 };
+  assert.deepEqual(await source.getTileMask(tile, 'fieldOfView=360'), png);
+  assert.deepEqual(urls, [
+    'https://api.kartaview.org/2.0/sequence/tiles/13054/8474/14.png?fieldOfView=360',
+    'https://api.kartaview.org/2.0/sequence/tiles/13054/8474/14.png?fieldOfView=360',
+    'https://api.kartaview.org/2.0/sequence/tiles/13054/8474/14.png?fieldOfView=360',
+  ]);
+  // Still drawing after every try: given up, saying so.
+  urls.length = 0;
+  answers = Array.from({ length: 10 }, () => status(504));
+  await assert.rejects(source.getTileMask(tile, 'fieldOfView=360'), {
+    message: MASK_SLOW_MESSAGE,
+    timedOut: true,
+  });
+  assert.equal(urls.length, MASK_ATTEMPTS);
+  // A refusal is not asked again.
+  urls.length = 0;
+  answers = [status(400)];
+  await assert.rejects(source.getTileMask(tile, 'fieldOfView=360'), /HTTP 400/);
+  assert.equal(urls.length, 1);
+});
+
+test('a filtered nearest search asks KartaView for the projection and upload date', async () => {
+  const urls = [];
+  const source = createKartaViewSource({
+    fetchImpl: async (url) => {
+      urls.push(new URL(url));
+      return ok(photoPayload([]));
+    },
+  });
+  await source.nearestPhotos({
+    lat: 42.3314,
+    lon: -83.0458,
+    filter: { pano: 'pano', sinceMs: Date.UTC(2026, 0, 2, 12) },
+  });
+  await source.nearestPhotos({ lat: 42.3314, lon: -83.0458 });
+  assert.equal(urls[0].searchParams.get('projection'), 'SPHERE');
+  assert.equal(urls[0].searchParams.get('startDate'), '2026-01-02');
+  assert.equal(urls[1].searchParams.has('projection'), false);
+  assert.equal(urls[1].searchParams.has('startDate'), false);
+});

src/layers/streetLevel/providers/kartaview/viewer.js

@@ -0,0 +1,93 @@
+import {
+  createPhotoViewer,
+  loadImage as loadAnyImage,
+} from '../../photoViewer.js';
+import {
+  FLAT_FULL_SIZE,
+  FLAT_VIEW_SIZE,
+  IMAGE_TIMEOUT_MS,
+  KARTAVIEW_NAME,
+  KARTAVIEW_PROVIDER_ID,
+  PANO_PREVIEW_SIZE,
+  cameraBearing,
+  kartaViewPhotoUrl,
+  resizedImageUrl,
+} from './policy.js';
+
+import { msg } from '../../../../i18n/index.js';
+
+export { panoSizeFor } from '../../photoViewer.js';
+
+/** English data: the Street Level panel translates it (translateKnown). */
+const LOAD_FAILED = msg('The KartaView photo could not be loaded');
+
+/** Load a KartaView photo (see photoViewer.js `loadImage`). */
+export function loadImage(url, options = {}) {
+  return loadAnyImage(url, {
+    timeoutMs: IMAGE_TIMEOUT_MS,
+    failure: LOAD_FAILED,
+    ...options,
+  });
+}
+
+/**
+ * Where KartaView photos come from. Only KartaView's image proxy can shrink
+ * a 13,000 px panorama, so panoramas and flat upgrades go through it.
+ * @type {import('../../photoViewer.js').PhotoSources}
+ */
+const KARTAVIEW_SOURCES = Object.freeze({
+  hasPano: (photo) => Boolean(photo.isPano && photo.urls.pano),
+  panoFirst: (photo) => ({
+    url: resizedImageUrl(photo.urls.pano, PANO_PREVIEW_SIZE),
+    width: 0,
+    resize: PANO_PREVIEW_SIZE,
+  }),
+  panoSharp: (photo, size) => ({
+    url: resizedImageUrl(photo.urls.pano, size),
+  }),
+  // The proxy's 1,280 px version is a few hundred kB; KartaView's own
+  // "large thumbnail" can be 1.7 MB. Either serves when the other fails.
+  // A 360° photo's front view is only on storage.
+  flatFirst: (photo) => [
+    photo.isPano ? null : resizedImageUrl(photo.urls.full, FLAT_VIEW_SIZE),
+    photo.urls.view,
+  ],
+  // A docked viewer shows the 1,280 px version in full: the 2,560 px one
+  // (~0.6 MB a photo) waits until the viewer is bigger than that.
+  flatSharp: (photo, pixels) =>
+    pixels > FLAT_VIEW_SIZE[0]
+      ? resizedImageUrl(photo.urls.full, FLAT_FULL_SIZE)
+      : null,
+  // The camera's direction, which the drive's track may refine.
+  bearingOf: (photo) => cameraBearing(photo),
+  describe: (photo) => ({
+    // KartaView's only place name is the sequence's, where the drive began.
+    title: null,
+    creator: null,
+    externalUrl: kartaViewPhotoUrl(photo),
+  }),
+});
+
+/**
+ * Viewer adapter for KartaView photos: a flat photo in an <img>, a 360°
+ * photo on a WebGL panorama, and ‹ › along the sequence (photoViewer.js).
+ *
+ * @param {object} options
+ * @param {(photoId: string) => Promise<object>} options.getPhoto   A normalized photo (policy.js normalizePhoto).
+ * @param {(photo: object, delta: -1|1) => Promise<string|null>} options.step
+ * @param {(imageId: string) => void} options.onStep
+ * @param {(photo: object) => void} [options.onShown]
+ * @param {object} [options.render]
+ * @param {(url: string, options?: object) => Promise<HTMLImageElement>} [options.load]
+ * @param {(canvas: HTMLCanvasElement) => object} [options.createRenderer]
+ * @returns {import('../../registry.js').ViewerAdapter}
+ */
+export function createKartaViewViewer({ load = loadImage, ...options }) {
+  return createPhotoViewer({
+    providerId: KARTAVIEW_PROVIDER_ID,
+    name: KARTAVIEW_NAME,
+    sources: KARTAVIEW_SOURCES,
+    load,
+    ...options,
+  });
+}

src/layers/streetLevel/providers/kartaview/viewer.test.mjs

@@ -0,0 +1,989 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import { createKartaViewViewer, loadImage, panoSizeFor } from './viewer.js';
+import { fakeHost, until } from '../../../../testSupport/kartaViewFakes.mjs';
+
+const PHOTOS = {
+  flat1: {
+    id: 'flat1',
+    sequenceId: 's1',
+    sequenceIndex: 1,
+    lon: -83.04,
+    lat: 42.33,
+    heading: 90,
+    isPano: false,
+    capturedAt: Date.UTC(2016, 7, 23),
+    urls: {
+      view: 'https://storage2.openstreetcam.org/lth/a.jpg',
+      full: 'https://storage2.openstreetcam.org/proc/a.jpg',
+      pano: null,
+    },
+  },
+  flat2: {
+    id: 'flat2',
+    sequenceId: 's1',
+    sequenceIndex: 2,
+    lon: -83.0401,
+    lat: 42.33,
+    heading: 92,
+    isPano: false,
+    capturedAt: Date.UTC(2016, 7, 23),
+    urls: {
+      view: 'https://storage2.openstreetcam.org/lth/b.jpg',
+      full: 'https://storage2.openstreetcam.org/proc/b.jpg',
+      pano: null,
+    },
+  },
+  pano1: {
+    id: 'pano1',
+    sequenceId: 's2',
+    sequenceIndex: 7,
+    lon: 106.84,
+    lat: -6.19,
+    heading: 150,
+    isPano: true,
+    capturedAt: Date.UTC(2022, 2, 21),
+    urls: {
+      view: 'https://storage13.openstreetcam.org/lth/p.jpg',
+      full: 'https://storage13.openstreetcam.org/wrapped_proc/p.jpg',
+      pano: 'https://storage13.openstreetcam.org/wrapped_proc/p.jpg',
+    },
+  },
+  pano2: {
+    id: 'pano2',
+    sequenceId: 's2',
+    sequenceIndex: 8,
+    lon: 106.8401,
+    lat: -6.19,
+    heading: 152,
+    isPano: true,
+    capturedAt: Date.UTC(2022, 2, 21),
+    urls: {
+      view: 'https://storage13.openstreetcam.org/lth/q.jpg',
+      full: 'https://storage13.openstreetcam.org/wrapped_proc/q.jpg',
+      pano: 'https://storage13.openstreetcam.org/wrapped_proc/q.jpg',
+    },
+  },
+};
+
+function fakeRenderer(canvas) {
+  const view = { yaw: 0, pitch: 0, fov: 80 };
+  return {
+    canvas,
+    images: [],
+    hiddenAtSetImage: [],
+    setImage(image) {
+      this.images.push(image.src);
+      // A hidden canvas measures 0×0: sizing it then gives a 1×1 buffer.
+      this.hiddenAtSetImage.push(canvas?.hidden);
+    },
+    setView(next) {
+      Object.assign(view, next);
+    },
+    getView: () => ({ ...view }),
+    resize() {},
+    clear() {},
+    destroy() {
+      this.destroyed = true;
+    },
+  };
+}
+
+PHOTOS.pano2 = {
+  ...PHOTOS.pano1,
+  id: 'pano2',
+  sequenceIndex: 8,
+  urls: {
+    view: 'https://storage13.openstreetcam.org/lth/p2.jpg',
+    full: 'https://storage13.openstreetcam.org/wrapped_proc/p2.jpg',
+    pano: 'https://storage13.openstreetcam.org/wrapped_proc/p2.jpg',
+  },
+};
+
+function setup({
+  failLoads = [],
+  rendererThrows = false,
+  steps = {},
+  failSteps = false,
+  hold = () => false,
+} = {}) {
+  const loads = [];
+  const held = [];
+  const closed = [];
+  const renderers = [];
+  const stepped = [];
+  const asked = [];
+  const attempts = { renderer: 0 };
+  const viewer = createKartaViewViewer({
+    getPhoto: async (id) => {
+      if (!PHOTOS[id]) throw new Error('no such photo');
+      return PHOTOS[id];
+    },
+    step: async (photo, delta) => {
+      asked.push(`${photo.id}:${delta}`);
+      if (failSteps) throw new Error('KartaView did not answer in time');
+      return steps[`${photo.id}:${delta}`] ?? null;
+    },
+    // The core opens what ‹ › chose; here the adapter is opened directly.
+    onStep: (id) => {
+      stepped.push(id);
+      viewer.open(id).catch(() => {});
+    },
+    load: async (url, options) => {
+      loads.push({ url, crossOrigin: options?.crossOrigin });
+      if (failLoads.some((part) => url.includes(part)))
+        throw new Error('The KartaView photo could not be loaded');
+      // A decoded bitmap: close() frees it.
+      const image = { src: url, close: () => closed.push(url) };
+      if (!hold(url)) return image;
+      return new Promise((resolve) => held.push(() => resolve(image)));
+    },
+    createRenderer: (canvas) => {
+      attempts.renderer++;
+      if (rendererThrows) throw new Error('WebGL is unavailable');
+      const renderer = fakeRenderer(canvas);
+      renderers.push(renderer);
+      return renderer;
+    },
+  });
+  const poses = [];
+  viewer.onPose((pose) => poses.push(pose));
+  const host = fakeHost();
+  return {
+    viewer,
+    poses,
+    host,
+    loads,
+    renderers,
+    stepped,
+    asked,
+    attempts,
+    held,
+    closed,
+  };
+}
+
+const parts = (host) => {
+  const root = host.children[0];
+  const [picture, canvas, prev, next] = root.children;
+  return { root, picture, canvas, prev, next };
+};
+const settle = () => new Promise((resolve) => setTimeout(resolve, 0));
+
+test('a flat photo shows its 1280 px version, then the sharp one, with a pose facing its heading', async () => {
+  const { viewer, poses, host, loads } = setup({
+    steps: { 'flat1:1': 'flat2', 'flat1:-1': 'flat0' },
+  });
+  await viewer.mount(host);
+  const { picture, canvas, prev, next } = parts(host);
+  picture.clientWidth = 1600; // expanded: the sharp version is wanted
+  assert.equal(prev.disabled, true, 'nothing to step through yet');
+  await viewer.open('flat1');
+  assert.equal(picture.hidden, false);
+  assert.equal(canvas.hidden, true);
+  assert.equal(prev.disabled, false);
+  assert.equal(next.disabled, false);
+  const pose = poses.at(-1);
+  assert.deepEqual(
+    {
+      providerId: pose.providerId,
+      imageId: pose.imageId,
+      position: pose.position,
+      bearing: pose.bearing,
+      tilt: pose.tilt,
+      isPano: pose.isPano,
+      sequenceId: pose.sequenceId,
+      capturedAt: pose.capturedAt,
+      title: pose.title,
+    },
+    {
+      providerId: 'kartaview',
+      imageId: 'flat1',
+      position: { lon: -83.04, lat: 42.33 },
+      bearing: 90,
+      tilt: 0,
+      isPano: false,
+      sequenceId: 's1',
+      capturedAt: Date.UTC(2016, 7, 23),
+      title: null,
+    },
+  );
+  assert.match(pose.externalUrl, /^https:\/\/cdn\.kartaview\.org\/pr:sharp\//);
+  // The proxy's 1,280 px version first: KartaView's own can be 1.7 MB.
+  assert.match(
+    loads[0].url,
+    /^https:\/\/cdn\.kartaview\.org\/.*rs:fit:1280:1280/,
+  );
+  assert.equal(loads[0].crossOrigin, false, 'an <img> needs no CORS');
+  await settle();
+  assert.match(
+    loads[1].url,
+    /^https:\/\/cdn\.kartaview\.org\/.*rs:fit:2560:2560/,
+  );
+  assert.equal(picture.src, loads[1].url, 'upgraded to the sharp version');
+  assert.equal(viewer.supportsRenderModes(), true);
+  viewer.setRenderMode('fill');
+  assert.equal(picture.style.objectFit, 'cover');
+});
+
+test('a failing image proxy falls back to the photo on KartaView storage', async () => {
+  const { viewer, host, loads } = setup({ failLoads: ['cdn.kartaview.org'] });
+  await viewer.mount(host);
+  await viewer.open('flat1');
+  assert.equal(loads[1].url, PHOTOS.flat1.urls.view);
+  assert.equal(parts(host).picture.hidden, false);
+  assert.equal(parts(host).picture.src, PHOTOS.flat1.urls.view);
+});
+
+test('a 360° photo shows on the panorama, preview first; dragging turns the bearing', async () => {
+  const { viewer, poses, host, loads, renderers } = setup();
+  await viewer.mount(host);
+  await viewer.open('pano1');
+  const { picture, canvas } = parts(host);
+  assert.equal(canvas.hidden, false);
+  assert.equal(picture.hidden, true);
+  assert.match(loads[0].url, /rs:fit:1024:512/);
+  assert.equal(loads[0].crossOrigin, true, 'WebGL textures need CORS');
+  assert.equal(poses.at(-1).isPano, true);
+  assert.equal(poses.at(-1).bearing, 150);
+  assert.equal(viewer.supportsRenderModes(), false, 'no frame to fit');
+  await settle();
+  // Docked (400 px at 80°), 2,048 px is all it can show.
+  assert.match(renderers[0].images.at(-1), /rs:fit:2048:1024/);
+  // Drag left by a quarter of the width: the view turns right.
+  const frames = [];
+  globalThis.requestAnimationFrame = (callback) => {
+    frames.push(callback);
+    return frames.length;
+  };
+  try {
+    canvas.fire('pointerdown', {
+      button: 0,
+      pointerId: 1,
+      clientX: 200,
+      clientY: 100,
+    });
+    canvas.fire('pointermove', { pointerId: 1, clientX: 100, clientY: 100 });
+    canvas.fire('pointerup', { pointerId: 1 });
+    frames.forEach((callback) => callback());
+  } finally {
+    delete globalThis.requestAnimationFrame;
+  }
+  const turned = poses.at(-1).bearing;
+  assert.ok(turned > 150 && turned < 360, `bearing ${turned} turned right`);
+});
+
+test('without WebGL, or when the panorama fails, a 360° photo shows its front view', async () => {
+  const noGl = setup({ rendererThrows: true });
+  await noGl.viewer.mount(noGl.host);
+  await noGl.viewer.open('pano1');
+  assert.equal(parts(noGl.host).picture.hidden, false);
+  assert.equal(noGl.loads[0].url, PHOTOS.pano1.urls.view);
+  assert.equal(noGl.poses.at(-1).isPano, false);
+  await settle();
+  assert.equal(
+    noGl.loads.length,
+    1,
+    'the equirectangular image never replaces it',
+  );
+
+  const broken = setup({ failLoads: ['cdn.kartaview.org'] });
+  await broken.viewer.mount(broken.host);
+  await broken.viewer.open('pano1');
+  assert.equal(parts(broken.host).picture.hidden, false);
+  assert.equal(broken.poses.at(-1).imageId, 'pano1');
+});
+
+test('‹ › and the arrow keys step along the sequence; ends disable at once', async () => {
+  const { viewer, poses, host, stepped, asked } = setup({
+    steps: { 'flat1:1': 'flat2', 'flat2:-1': 'flat1' },
+  });
+  await viewer.mount(host);
+  await viewer.open('flat1');
+  const { root, prev, next } = parts(host);
+  assert.ok(
+    await until(() => prev.disabled),
+    'flat1 is the first photo: known up front',
+  );
+  assert.equal(next.disabled, false);
+  next.fire('click');
+  assert.ok(await until(() => poses.at(-1).imageId === 'flat2'));
+  assert.deepEqual(stepped, ['flat2'], 'the core is asked to open it');
+  assert.ok(await until(() => next.disabled), 'flat2 is the last photo');
+  assert.equal(prev.disabled, false);
+  // A modified arrow, then a plain → (at the end: it only asks). Presses run
+  // in turn, so once → has asked, a stepping ⌘← would have asked first.
+  const before = asked.length;
+  root.fire('keydown', { key: 'ArrowLeft', metaKey: true });
+  root.fire('keydown', { key: 'ArrowRight' });
+  assert.ok(await until(() => asked.length > before));
+  await settle();
+  assert.deepEqual(
+    asked.slice(before),
+    ['flat2:1'],
+    'modified arrows are not ours',
+  );
+  assert.equal(poses.at(-1).imageId, 'flat2');
+  root.fire('keydown', { key: 'ArrowLeft' });
+  assert.ok(await until(() => poses.at(-1).imageId === 'flat1'));
+});
+
+test('quick presses each step on from the photo the last one chose', async () => {
+  const chain = { 'flat1:1': 'flat2', 'flat2:1': 'pano1' };
+  const { viewer, host, stepped } = setup({
+    steps: chain,
+    rendererThrows: true,
+  });
+  await viewer.mount(host);
+  await viewer.open('flat1');
+  const { next } = parts(host);
+  next.fire('click');
+  next.fire('click');
+  assert.ok(await until(() => stepped.length === 2), `stepped ${stepped}`);
+  assert.deepEqual(stepped, ['flat2', 'pano1']);
+});
+
+test('a newer open wins; close hides the photo; unmount tears down the panorama', async () => {
+  const { viewer, poses, host, renderers } = setup();
+  await viewer.mount(host);
+  const first = viewer.open('pano1');
+  const second = viewer.open('flat1');
+  await Promise.all([first, second]);
+  assert.deepEqual(
+    poses.map((pose) => pose.imageId),
+    ['flat1'],
+    'the overtaken panorama never posed',
+  );
+  assert.equal(renderers.length, 0, 'nor built a WebGL context');
+  await viewer.open('pano1');
+  viewer.close();
+  const { picture, canvas, root } = parts(host);
+  assert.equal(canvas.hidden, true);
+  assert.equal(picture.hidden, true);
+  assert.equal(root.dataset.kind, '');
+  await assert.rejects(viewer.open('nope'), /no such photo/);
+  viewer.unmount();
+  assert.equal(host.children.length, 0);
+  assert.equal(renderers[0].destroyed, true);
+  await assert.rejects(viewer.open('flat1'), /not mounted/);
+});
+
+test('a panorama is put on screen before its image is sized into the canvas', async () => {
+  const { viewer, host, renderers } = setup();
+  await viewer.mount(host);
+  await viewer.open('flat1');
+  await viewer.open('pano1');
+  await settle();
+  assert.deepEqual(renderers[0].hiddenAtSetImage, [false, false]);
+});
+
+test('a step that gets no answer is not the end of the sequence', async () => {
+  const { viewer, host, poses, asked } = setup({ failSteps: true });
+  await viewer.mount(host);
+  await viewer.open('flat1');
+  const { next } = parts(host);
+  next.disabled = false;
+  // The ends check asked once already; the press asks again and fails.
+  const asks = () => asked.filter((ask) => ask === 'flat1:1').length;
+  next.fire('click');
+  assert.ok(await until(() => asks() === 2), 'the press asked');
+  await settle();
+  assert.equal(next.disabled, false, 'still enabled: try again');
+  assert.equal(poses.at(-1).imageId, 'flat1');
+});
+
+test('the keyboard looks around a panorama: Shift+arrows turn, ↑ ↓ tilt, + − zoom', async (t) => {
+  globalThis.requestAnimationFrame = (callback) => setTimeout(callback, 0);
+  t.after(() => delete globalThis.requestAnimationFrame);
+  const { viewer, host, renderers, stepped, asked } = setup({
+    steps: { 'pano1:1': 'flat1' },
+  });
+  await viewer.mount(host);
+  await viewer.open('pano1');
+  const { root } = parts(host);
+  const view = () => renderers[0].getView();
+  const before = asked.length;
+  root.fire('keydown', { key: 'ArrowRight', shiftKey: true });
+  assert.ok(view().yaw > 0, 'turned right');
+  root.fire('keydown', { key: 'ArrowUp' });
+  assert.ok(view().pitch > 0, 'looked up');
+  const fov = view().fov;
+  root.fire('keydown', { key: '+' });
+  assert.ok(view().fov < fov, 'zoomed in');
+  root.fire('keydown', { key: '-' });
+  root.fire('keydown', { key: '-' });
+  assert.ok(view().fov > fov, 'zoomed out');
+  root.fire('keydown', { key: 'ArrowRight' });
+  assert.ok(await until(() => stepped.length === 1));
+  assert.deepEqual(stepped, ['flat1'], 'a plain arrow still steps');
+  // Only that press asked, then flat1's ends check: a Shift+→ that stepped
+  // would have sent the plain → on from flat1.
+  assert.ok(await until(() => asked.slice(before).length >= 3));
+  await settle();
+  assert.deepEqual(
+    asked.slice(before).sort(),
+    ['flat1:-1', 'flat1:1', 'pano1:1'],
+    'none of the others stepped',
+  );
+});
+
+test('two fingers pinch the panorama’s zoom', async () => {
+  const { viewer, host, renderers } = setup();
+  await viewer.mount(host);
+  await viewer.open('pano1');
+  const { canvas } = parts(host);
+  const before = renderers[0].getView().fov;
+  canvas.fire('pointerdown', {
+    pointerId: 1,
+    pointerType: 'touch',
+    clientX: 100,
+    clientY: 100,
+  });
+  canvas.fire('pointerdown', {
+    pointerId: 2,
+    pointerType: 'touch',
+    clientX: 140,
+    clientY: 100,
+  });
+  canvas.fire('pointermove', {
+    pointerId: 2,
+    pointerType: 'touch',
+    clientX: 180,
+    clientY: 100,
+  });
+  assert.ok(renderers[0].getView().fov < before, 'spread zooms in');
+  canvas.fire('pointerup', { pointerId: 1 });
+  canvas.fire('pointerup', { pointerId: 2 });
+});
+
+test('a lost WebGL context drops the panorama and shows the photo again on a new one', async () => {
+  const { viewer, host, renderers, poses, stepped } = setup();
+  await viewer.mount(host);
+  await viewer.open('pano1');
+  const lost = parts(host).canvas;
+  lost.fire('webglcontextlost');
+  assert.equal(renderers[0].destroyed, true);
+  // A lost canvas only ever gives back its lost context: a new element.
+  assert.notEqual(parts(host).canvas, lost);
+  assert.deepEqual(stepped, ['pano1'], 'reopened through the core');
+  assert.ok(await until(() => renderers.length === 2), 'a new renderer');
+  assert.equal(renderers[1].canvas, parts(host).canvas);
+  assert.equal(poses.at(-1).imageId, 'pano1');
+  assert.equal(parts(host).canvas.hidden, false);
+});
+
+test('a context lost while a newer photo opens leaves that open alone', async () => {
+  const { viewer, host, stepped } = setup();
+  await viewer.mount(host);
+  await viewer.open('pano1');
+  const opening = viewer.open('flat1');
+  parts(host).canvas.fire('webglcontextlost');
+  await opening;
+  assert.deepEqual(stepped, [], 'no reopen of the old panorama');
+  assert.equal(parts(host).picture.hidden, false);
+});
+
+test('a WebGL failure only lasts until the viewer is mounted again', async () => {
+  let fail = true;
+  const built = [];
+  const viewer = createKartaViewViewer({
+    getPhoto: async (id) => PHOTOS[id],
+    step: async () => null,
+    onStep() {},
+    load: async (url) => ({ src: url }),
+    createRenderer: (canvas) => {
+      if (fail) throw new Error('WebGL is unavailable');
+      const renderer = fakeRenderer(canvas);
+      built.push(renderer);
+      return renderer;
+    },
+  });
+  const host = fakeHost();
+  await viewer.mount(host);
+  await viewer.open('pano1');
+  assert.equal(parts(host).picture.hidden, false, 'front view');
+  viewer.unmount();
+  fail = false;
+  const again = fakeHost();
+  await viewer.mount(again);
+  await viewer.open('pano1');
+  assert.equal(built.length, 1);
+  assert.equal(parts(again).canvas.hidden, false);
+});
+
+/** Flat photos a → d of one drive, for the tests that hold loads back. */
+const DRIVE = Object.fromEntries(
+  ['a', 'b', 'c', 'd'].map((id, index) => [
+    id,
+    {
+      id,
+      sequenceId: 'drive',
+      sequenceIndex: index,
+      lon: 0.1 + index * 0.0001,
+      lat: 0.1,
+      heading: 0,
+      isPano: false,
+      capturedAt: 0,
+      urls: {
+        view: `https://storage2.openstreetcam.org/lth/${id}.jpg`,
+        full: `https://storage2.openstreetcam.org/proc/${id}.jpg`,
+        pano: null,
+      },
+    },
+  ]),
+);
+const DRIVE_ORDER = Object.keys(DRIVE);
+
+/** Which drive photo, at which size, an image address shows. */
+function shows(src) {
+  const proxied =
+    /^https:\/\/cdn\.kartaview\.org\/pr:sharp\/rs:fit:(\d+):\d+\/([\w-]+)$/.exec(
+      src || '',
+    );
+  const url = proxied ? Buffer.from(proxied[2], 'base64url').toString() : src;
+  const id = /\/(\w+)\.jpg$/.exec(url || '')?.[1] ?? null;
+  return proxied ? `${id}@${proxied[1]}` : id;
+}
+
+/**
+ * A viewer whose photo loads (and, with `slowSteps`, step answers) wait for
+ * the test. ‹ › open through a stand-in core that, like the real one, awaits
+ * a tick (the viewer mount) before it opens the photo.
+ */
+function heldSetup({ slowSteps = false } = {}) {
+  const loads = [];
+  const asks = [];
+  const stepped = [];
+  const shown = [];
+  const viewer = createKartaViewViewer({
+    getPhoto: async (id) => {
+      if (!DRIVE[id]) throw new Error('no such photo');
+      return DRIVE[id];
+    },
+    step: (photo, delta) => {
+      const answer = DRIVE_ORDER[DRIVE_ORDER.indexOf(photo.id) + delta] ?? null;
+      if (!slowSteps) return Promise.resolve(answer);
+      return new Promise((resolve) =>
+        asks.push({ key: `${photo.id}:${delta}`, resolve }),
+      );
+    },
+    onStep: async (id) => {
+      stepped.push(id);
+      await settle();
+      viewer.open(id).catch(() => {});
+    },
+    onShown: (photo) => shown.push(photo.id),
+    load: (url) =>
+      new Promise((resolve, reject) =>
+        loads.push({
+          url,
+          shows: shows(url),
+          resolve: () => resolve({ src: url }),
+          reject: () =>
+            reject(new Error('The KartaView photo could not be loaded')),
+        }),
+      ),
+    createRenderer: () => {
+      throw new Error('no WebGL in Node');
+    },
+  });
+  const poses = [];
+  viewer.onPose((pose) => poses.push(pose.imageId));
+  const host = fakeHost();
+  /** Let the load showing `what` (e.g. 'a@1280') finish. */
+  const release = async (what) => {
+    assert.ok(
+      await until(() => loads.some((load) => load.shows === what)),
+      `${what} is loading: ${loads.map((load) => load.shows)}`,
+    );
+    const at = loads.findIndex((load) => load.shows === what);
+    loads.splice(at, 1)[0].resolve();
+    await settle();
+  };
+  /** Answer the oldest pending step ask for `key` (e.g. 'a:1'). */
+  const answer = async (key, value) => {
+    assert.ok(await until(() => asks.some((ask) => ask.key === key)));
+    const at = asks.findIndex((ask) => ask.key === key);
+    asks.splice(at, 1)[0].resolve(value);
+    await settle();
+  };
+  return { viewer, host, loads, asks, stepped, shown, poses, release, answer };
+}
+
+test('quick presses while the next photo is still loading each step on from the last one chosen', async () => {
+  const { viewer, host, stepped, release } = heldSetup();
+  await viewer.mount(host);
+  const opening = viewer.open('a');
+  await release('a@1280');
+  await opening;
+  const { next } = parts(host);
+  assert.ok(await until(() => !next.disabled));
+  // b, c and d never load: each press steps on from the photo on its way.
+  next.fire('click');
+  next.fire('click');
+  next.fire('click');
+  assert.ok(await until(() => stepped.length >= 3), `stepped ${stepped}`);
+  await settle();
+  assert.deepEqual(stepped, ['b', 'c', 'd']);
+});
+
+test('a slow sharp version of an older photo never replaces the newer photo', async () => {
+  const { viewer, host, shown, poses, release } = heldSetup();
+  await viewer.mount(host);
+  // An expanded viewer, so the sharp version is wanted.
+  parts(host).picture.clientWidth = 1600;
+  const first = viewer.open('a');
+  await release('a@1280');
+  await first;
+  const second = viewer.open('b');
+  await release('b@1280');
+  await second;
+  const { picture } = parts(host);
+  assert.equal(shows(picture.src), 'b@1280');
+  await release('a@2560'); // a's upgrade, overtaken
+  assert.equal(shows(picture.src), 'b@1280', 'a never comes back');
+  await release('b@2560');
+  assert.equal(shows(picture.src), 'b@2560', 'b’s own upgrade lands');
+  assert.deepEqual(shown, ['a', 'b']);
+  assert.deepEqual(poses, ['a', 'b']);
+});
+
+test('an overtaken flat open never shows, nor tells the provider it did', async () => {
+  const { viewer, host, shown, poses, loads, release } = heldSetup();
+  await viewer.mount(host);
+  const first = viewer.open('a');
+  assert.ok(await until(() => loads.length === 1), 'a is loading');
+  const second = viewer.open('b');
+  await release('b@1280');
+  await second;
+  await release('a@1280');
+  await first;
+  const { picture } = parts(host);
+  assert.equal(shows(picture.src), 'b@1280');
+  assert.deepEqual(poses, ['b']);
+  assert.deepEqual(shown, ['b'], 'onShown only for the photo on screen');
+});
+
+test('a photo still loading when the viewer closes stays closed', async () => {
+  const { viewer, host, shown, poses, loads, release } = heldSetup();
+  await viewer.mount(host);
+  const opening = viewer.open('a');
+  assert.ok(await until(() => loads.length === 1), 'a is loading');
+  viewer.close();
+  await release('a@1280');
+  await opening;
+  const { picture, root } = parts(host);
+  assert.equal(picture.hidden, true);
+  assert.equal(root.dataset.kind, '');
+  assert.deepEqual(poses, []);
+  assert.deepEqual(shown, []);
+});
+
+test('an ends check for an earlier photo does not disable › on the photo now showing', async () => {
+  const { viewer, host, release, answer } = heldSetup({ slowSteps: true });
+  await viewer.mount(host);
+  const first = viewer.open('a');
+  await release('a@1280');
+  await first;
+  const second = viewer.open('c');
+  await release('c@1280');
+  await second;
+  const { prev, next } = parts(host);
+  await answer('c:-1', 'b');
+  await answer('c:1', 'd');
+  // a's check answers last, saying nothing lies before or after it.
+  await answer('a:-1', null);
+  await answer('a:1', null);
+  assert.equal(prev.disabled, false);
+  assert.equal(next.disabled, false, 'c still has a next photo');
+});
+
+test('a press whose answer comes after another photo was opened is dropped', async () => {
+  const { viewer, host, stepped, release, answer, asks } = heldSetup({
+    slowSteps: true,
+  });
+  await viewer.mount(host);
+  const first = viewer.open('a');
+  await release('a@1280');
+  await first;
+  await answer('a:-1', null);
+  await answer('a:1', 'b');
+  const { next } = parts(host);
+  next.disabled = false;
+  next.fire('click');
+  assert.ok(await until(() => asks.some((ask) => ask.key === 'a:1')));
+  // The user picks another photo meanwhile.
+  const other = viewer.open('d');
+  await release('d@1280');
+  await other;
+  await answer('a:1', 'b');
+  await settle();
+  assert.deepEqual(stepped, [], 'the old press does not open b over d');
+});
+
+test('a failed open does not become the photo ‹ › step from', async () => {
+  const { viewer, host, stepped } = setup({ steps: { 'flat1:1': 'flat2' } });
+  await viewer.mount(host);
+  await viewer.open('flat1');
+  await assert.rejects(viewer.open('nope'), /no such photo/);
+  parts(host).next.disabled = false;
+  parts(host).next.fire('click');
+  assert.ok(await until(() => stepped.length === 1));
+  assert.deepEqual(stepped, ['flat2'], 'from the photo still showing');
+});
+
+test('WebGL is tried once per mount, not again for every 360° photo', async () => {
+  const { viewer, host, attempts } = setup({ rendererThrows: true });
+  await viewer.mount(host);
+  await viewer.open('pano1');
+  await viewer.open('pano2');
+  assert.equal(attempts.renderer, 1);
+  assert.equal(parts(host).picture.hidden, false, 'front views instead');
+});
+
+test('a step button that disables under the keyboard hands focus to the viewer', async () => {
+  const { viewer, host } = setup();
+  await viewer.mount(host);
+  const { root, prev, next } = parts(host);
+  let focused = 0;
+  root.focus = () => focused++;
+  next.ownerDocument = { activeElement: next };
+  prev.ownerDocument = { activeElement: root };
+  await viewer.open('flat1');
+  assert.ok(await until(() => next.disabled && prev.disabled));
+  assert.equal(focused, 1, 'only for the focused button');
+});
+
+test('› to another 360° photo keeps the look direction; opening one afresh faces its heading', async (t) => {
+  globalThis.requestAnimationFrame = (callback) => setTimeout(callback, 0);
+  t.after(() => delete globalThis.requestAnimationFrame);
+  const { viewer, host, renderers, poses } = setup({
+    steps: { 'pano1:1': 'pano2' },
+  });
+  await viewer.mount(host);
+  await viewer.open('pano1');
+  const { root, next } = parts(host);
+  root.fire('keydown', { key: 'ArrowRight', shiftKey: true });
+  const yaw = renderers[0].getView().yaw;
+  assert.ok(yaw > 0);
+  next.fire('click');
+  assert.ok(await until(() => poses.at(-1).imageId === 'pano2'));
+  assert.equal(renderers[0].getView().yaw, yaw, 'still looking the same way');
+  await viewer.open('pano1');
+  assert.equal(renderers[0].getView().yaw, 0, 'a fresh open faces ahead');
+});
+
+/** A viewer whose loads for `held` URLs wait until `release()`. */
+function heldPanoSetup(held) {
+  const renderers = [];
+  const stepped = [];
+  let release;
+  const gate = new Promise((resolve) => (release = resolve));
+  const viewer = createKartaViewViewer({
+    getPhoto: async (id) => PHOTOS[id],
+    step: async () => null,
+    onStep: (id) => {
+      stepped.push(id);
+      viewer.open(id).catch(() => {});
+    },
+    load: async (url) => {
+      if (held.some((part) => url.includes(part))) await gate;
+      return { src: url };
+    },
+    createRenderer: (canvas) => {
+      const renderer = fakeRenderer(canvas);
+      renderers.push(renderer);
+      return renderer;
+    },
+  });
+  const poses = [];
+  viewer.onPose((pose) => poses.push(pose));
+  return { viewer, renderers, stepped, poses, host: fakeHost(), release };
+}
+
+const pano2Preview = Buffer.from(
+  'https://storage13.openstreetcam.org/wrapped_proc/p2.jpg',
+).toString('base64url');
+
+test('a context lost while a newer panorama loads shows that one on a new canvas, not a black viewer', async () => {
+  const { viewer, renderers, poses, host, release, stepped } = heldPanoSetup([
+    pano2Preview,
+  ]);
+  await viewer.mount(host);
+  await viewer.open('pano1');
+  const opening = viewer.open('pano2');
+  await new Promise((resolve) => setTimeout(resolve, 0));
+  parts(host).canvas.fire('webglcontextlost');
+  release();
+  await opening;
+  assert.equal(
+    poses.at(-1).imageId,
+    'pano2',
+    'the newer panorama is on screen',
+  );
+  assert.equal(poses.at(-1).isPano, true);
+  assert.deepEqual(stepped, [], 'its own open, not a reopen of the old one');
+  assert.equal(renderers.length, 2, 'drawn by a new renderer');
+  assert.equal(renderers[1].canvas, parts(host).canvas);
+  assert.equal(parts(host).canvas.hidden, false);
+});
+
+test('a second context loss, on the new canvas, reopens again; the new canvas still drags', async (t) => {
+  globalThis.requestAnimationFrame = (callback) => setTimeout(callback, 0);
+  t.after(() => delete globalThis.requestAnimationFrame);
+  const { viewer, host, renderers, stepped, poses } = setup();
+  await viewer.mount(host);
+  await viewer.open('pano1');
+  parts(host).canvas.fire('webglcontextlost');
+  assert.ok(await until(() => renderers.length === 2));
+  parts(host).canvas.fire('webglcontextlost');
+  assert.ok(await until(() => renderers.length === 3), 'reopened twice');
+  assert.deepEqual(stepped, ['pano1', 'pano1']);
+  assert.equal(renderers[2].canvas, parts(host).canvas);
+  const canvas = parts(host).canvas;
+  const before = poses.at(-1).bearing;
+  canvas.fire('pointerdown', {
+    button: 0,
+    pointerId: 7,
+    pointerType: 'mouse',
+    clientX: 200,
+    clientY: 100,
+  });
+  canvas.fire('pointermove', { pointerId: 7, clientX: 100, clientY: 100 });
+  canvas.fire('pointerup', { pointerId: 7 });
+  assert.ok(await until(() => poses.at(-1).bearing !== before), 'dragged');
+});
+
+test('a context loss keeps where the user was looking', async () => {
+  const { viewer, host, renderers } = setup();
+  await viewer.mount(host);
+  await viewer.open('pano1');
+  renderers[0].setView({ yaw: 70, pitch: 12, fov: 60 });
+  parts(host).canvas.fire('webglcontextlost');
+  assert.ok(await until(() => renderers.length === 2));
+  assert.deepEqual(renderers[1].getView(), { yaw: 70, pitch: 12, fov: 60 });
+});
+
+test('the panorama is as sharp as the viewer needs: 2,048 docked, 4,096 once expanded', async () => {
+  assert.deepEqual(panoSizeFor(400, 80), [2048, 1024]);
+  assert.deepEqual(panoSizeFor(1400, 80), [4096, 2048]);
+  const { viewer, host, renderers } = setup();
+  await viewer.mount(host);
+  await viewer.open('pano1');
+  assert.ok(await until(() => renderers[0].images.length === 2));
+  assert.match(renderers[0].images[1], /rs:fit:2048:1024/);
+  // Expanded: the panel tells the viewer it resized.
+  parts(host).canvas.clientWidth = 1400;
+  viewer.resize();
+  assert.ok(await until(() => renderers[0].images.length === 3));
+  assert.match(renderers[0].images[2], /rs:fit:4096:2048/);
+  viewer.resize();
+  for (let i = 0; i < 4; i++) await new Promise((r) => setTimeout(r, 0));
+  assert.equal(renderers[0].images.length, 3, 'not again once sharp');
+});
+
+test('a CORS image is decoded off the main thread into an ImageBitmap where the browser can', async (t) => {
+  // A blob whose header names no size (the viewer then reads none).
+  const fakeBlob = {
+    size: 4,
+    slice: () => ({ arrayBuffer: async () => new ArrayBuffer(0) }),
+  };
+  const saved = {
+    fetch: globalThis.fetch,
+    bitmap: globalThis.createImageBitmap,
+  };
+  t.after(() => {
+    globalThis.fetch = saved.fetch;
+    globalThis.createImageBitmap = saved.bitmap;
+  });
+  const fetched = [];
+  globalThis.fetch = async (url, init) => {
+    fetched.push({ url, mode: init.mode });
+    return url.includes('gone')
+      ? { ok: false, status: 409 }
+      : { ok: true, blob: async () => fakeBlob };
+  };
+  globalThis.createImageBitmap = async (blob) => ({
+    blob,
+    width: 4096,
+    height: 2048,
+  });
+  const bitmap = await loadImage('https://cdn.kartaview.org/a', {
+    crossOrigin: true,
+  });
+  assert.deepEqual(bitmap, { blob: fakeBlob, width: 4096, height: 2048 });
+  assert.deepEqual(fetched, [
+    { url: 'https://cdn.kartaview.org/a', mode: 'cors' },
+  ]);
+  await assert.rejects(
+    loadImage('https://cdn.kartaview.org/gone', { crossOrigin: true }),
+    /could not be loaded/,
+  );
+});
+
+test('a docked viewer keeps the 1,280 px photo; expanding it brings the 2,560 px one', async () => {
+  const { viewer, host, loads } = setup();
+  await viewer.mount(host);
+  await viewer.open('flat1');
+  for (let i = 0; i < 4; i++) await settle();
+  assert.equal(loads.length, 1, 'no 2,560 px download for a 400 px frame');
+  parts(host).picture.clientWidth = 1600;
+  viewer.resize();
+  assert.ok(await until(() => loads.length === 2));
+  assert.match(loads[1].url, /rs:fit:2560:2560/);
+  assert.equal(parts(host).picture.src, loads[1].url);
+  viewer.resize();
+  for (let i = 0; i < 4; i++) await settle();
+  assert.equal(loads.length, 2, 'once only');
+});
+
+test('resizes while a sharper panorama loads start no second load; the last size wins once it lands', async () => {
+  let first = true;
+  const { viewer, host, loads, renderers, held } = setup({
+    hold: (url) => {
+      const holdIt = first && url.includes('rs:fit:2048');
+      if (holdIt) first = false;
+      return holdIt;
+    },
+  });
+  await viewer.mount(host);
+  await viewer.open('pano1');
+  assert.ok(await until(() => held.length === 1));
+  // The panel animates open: a burst of resizes while 2,048 px loads.
+  parts(host).canvas.clientWidth = 1400;
+  for (let i = 0; i < 5; i++) viewer.resize();
+  for (let i = 0; i < 4; i++) await settle();
+  assert.equal(loads.length, 2, 'the preview and the one 2,048 px load');
+  held[0]();
+  assert.ok(await until(() => renderers[0].images.length === 3));
+  assert.match(renderers[0].images[1], /rs:fit:2048:1024/);
+  assert.match(renderers[0].images[2], /rs:fit:4096:2048/);
+  for (let i = 0; i < 4; i++) await settle();
+  assert.equal(loads.length, 3, 'one more load, for the size asked last');
+});
+
+test('a preview or sharper version nobody will draw is freed, not left decoded', async () => {
+  const { viewer, host, renderers, held, closed } = setup({
+    hold: (url) => /rs:fit:(1024|2048):/.test(url),
+  });
+  await viewer.mount(host);
+  // pano1's preview is still loading when flat1 opens over it.
+  const overtaken = viewer.open('pano1');
+  assert.ok(await until(() => held.length === 1));
+  await viewer.open('flat1');
+  held[0]();
+  await overtaken;
+  assert.deepEqual(closed.length, 1);
+  assert.match(closed[0], /rs:fit:1024/, 'the overtaken preview');
+  // pano1 shows; its sharp version lands after flat1 replaced it.
+  const shown = viewer.open('pano1');
+  assert.ok(await until(() => held.length === 2));
+  held[1]();
+  await shown;
+  assert.ok(await until(() => held.length === 3));
+  await viewer.open('flat1');
+  held[2]();
+  assert.ok(await until(() => closed.length === 2));
+  assert.match(closed[1], /rs:fit:2048/, 'the overtaken sharp version');
+  assert.equal(renderers[0].images.length, 1, 'only the preview was drawn');
+});

src/layers/streetLevel/providers/mapillary/coverageFixture.mjs

@@ -1,6 +1,6 @@
 import { PbfWriter } from 'pbf';
 
-const zigzag = (value) => (value << 1) ^ (value >> 31);
+export const zigzag = (value) => (value << 1) ^ (value >> 31);
 
 /** Tile-local [x, y] (0..extent) of a lon/lat inside tile (x, y, z). */
 function lonLatToTileLocal([lon, lat], { x, y, z }, extent = 4096) {
@@ -13,7 +13,7 @@ function lonLatToTileLocal([lon, lat], { x, y, z }, extent = 4096) {
 }
 
 /** One MVT layer writer with deduplicated keys and appended values. */
-function layerWriter(name, extent) {
+export function layerWriter(name, extent) {
   const keys = new Map();
   const values = [];
   const features = [];
@@ -62,7 +62,7 @@ function layerWriter(name, extent) {
 }
 
 /** MVT MoveTo/LineTo commands; the cursor carries over between parts. */
-function lineGeometry(parts) {
+export function lineGeometry(parts) {
   const out = [];
   let cx = 0;
   let cy = 0;

src/layers/streetLevel/providers/mapillary/decode.js

@@ -1,6 +1,6 @@
 import { PbfReader } from 'pbf';
 import { VectorTile } from '@mapbox/vector-tile';
-import { tileLocalToLonLat } from './tileMath.js';
+import { tileLocalToLonLat } from '../../tileMath.js';
 
 /**
  * Decode a `mly1_public` coverage tile (z11–14) into sequences. The z14

src/layers/streetLevel/providers/mapillary/index.js

@@ -1,9 +1,16 @@
-import { freshCoverage } from './state.js';
-import { createCoverage, sequenceIdFromPick } from './coverage.js';
-import { createSequences } from './sequences.js';
+import {
+  createLineCoverage,
+  freshCoverage,
+  sequenceIdFromPick,
+} from '../../lineCoverage.js';
+import { createSequenceCones, thinImages } from '../../sequenceCones.js';
+import { coverageZoomForHeight } from '../../tileMath.js';
+import { decodeCoverageTile } from './decode.js';
 import { createMapillaryViewer } from './viewer.js';
 import {
   COLORS,
+  COVERAGE_TUNING,
+  KEY_REJECTED_MESSAGE,
   MAPILLARY_CREDIT_HTML,
   MAPILLARY_KEY_ID,
   MAPILLARY_LABEL,
@@ -11,15 +18,28 @@ import {
   MAPILLARY_PROVIDER_ID,
   MAPILLARY_SOURCE_METHODS,
   PICK_PREFIX,
+  RATE_LIMITED_MESSAGE,
 } from './policy.js';
 
-/** Per-provider mutable state; coverage and sequences share it. */
+/** Normalize a graph image record into the shape the cones use. */
+function normalizeSequenceImage(record) {
+  const coordinates = record?.geometry?.coordinates;
+  if (!Array.isArray(coordinates) || coordinates.length < 2) return null;
+  return {
+    id: String(record.id),
+    lon: Number(coordinates[0]),
+    lat: Number(coordinates[1]),
+    compassAngle: Number(record.compass_angle) || 0,
+    capturedAt: Number(record.captured_at) || 0,
+    isPano: record.is_pano === true,
+  };
+}
+
+/** Per-provider mutable state; coverage and cones share it. */
 function createProviderState(context) {
   return {
+    context,
     services: context.services,
-    getFilter: context.getFilter,
-    isActive: context.isActive,
-    notify: context.notify,
     viewer: null,
     coverage: freshCoverage(),
     sequence: {
@@ -39,7 +59,7 @@ function createProviderState(context) {
  * 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}
+ * @returns {import('../../registry.js').StreetLevelProvider}
  */
 export function createMapillaryProvider({ source, photoViewer = null }) {
   if (
@@ -61,8 +81,44 @@ export function createMapillaryProvider({ source, photoViewer = null }) {
     create(context) {
       const state = createProviderState(context);
       const parts = {};
-      parts.coverage = createCoverage({ state, source });
-      parts.sequences = createSequences({ state, source, parts });
+      parts.coverage = createLineCoverage({
+        state,
+        fetchTile: async (tile, { signal }) =>
+          decodeCoverageTile(
+            await source.getTile('coverage', tile.z, tile.x, tile.y, {
+              signal,
+            }),
+            tile,
+          ),
+        zoomFor: coverageZoomForHeight,
+        colors: COLORS,
+        pickPrefix: PICK_PREFIX.sequence,
+        renderKey: 'mapillary-coverage',
+        tuning: COVERAGE_TUNING,
+        messages: {
+          keyRejected: KEY_REJECTED_MESSAGE,
+          rateLimited: RATE_LIMITED_MESSAGE,
+        },
+      });
+      parts.sequences = createSequenceCones({
+        state,
+        async loadImages(sequenceId, { signal }) {
+          const records = await source.getSequenceImages(sequenceId, {
+            signal,
+          });
+          return thinImages(
+            records
+              .map(normalizeSequenceImage)
+              .filter(Boolean)
+              .sort((a, b) => a.capturedAt - b.capturedAt),
+          );
+        },
+        colors: COLORS,
+        pickPrefix: PICK_PREFIX.image,
+        spriteId: 'street-level:mapillary-cones',
+        renderKey: 'mapillary-sequence',
+        onHighlight: (sequenceId) => parts.coverage.highlight(sequenceId),
+      });
 
       return {
         /** Coverage waits for the answer: no tile requests without a key. */
@@ -115,7 +171,7 @@ export function createMapillaryProvider({ source, photoViewer = null }) {
 
         /** A line selects its sequence; a cone opens its image. */
         handlePick(pickId) {
-          const sequenceId = sequenceIdFromPick(pickId);
+          const sequenceId = sequenceIdFromPick(pickId, PICK_PREFIX.sequence);
           if (sequenceId) {
             parts.sequences.select(sequenceId);
             return true;

src/layers/streetLevel/providers/mapillary/mapillary.test.mjs

@@ -1,8 +1,8 @@
 import assert from 'node:assert/strict';
 import test from 'node:test';
 import { mapillaryImageUrl } from './policy.js';
-import { sequenceIdFromPick } from './coverage.js';
-import { thinImages } from './sequences.js';
+import { sequenceIdFromPick } from '../../lineCoverage.js';
+import { thinImages } from '../../sequenceCones.js';
 
 test('image deep links match the mapillary.com share format', () => {
   assert.equal(
@@ -13,9 +13,9 @@ test('image deep links match the mapillary.com share format', () => {
 });
 
 test('a sequence line pick names its sequence; other picks do not', () => {
-  assert.equal(sequenceIdFromPick('mly:seq:abc'), 'abc');
-  assert.equal(sequenceIdFromPick('mly:img:abc'), null);
-  assert.equal(sequenceIdFromPick(null), null);
+  assert.equal(sequenceIdFromPick('mly:seq:abc', 'mly:seq:'), 'abc');
+  assert.equal(sequenceIdFromPick('mly:img:abc', 'mly:seq:'), null);
+  assert.equal(sequenceIdFromPick(null, 'mly:seq:'), null);
 });
 
 test('cone thinning across the date line drops images metres apart', () => {

src/layers/streetLevel/providers/mapillary/policy.js

@@ -0,0 +1,74 @@
+import { COLORS as SHARED_COLORS, PROVIDER_COLORS } from '../../policy.js';
+
+// Reached by source.js (no browser globals, see check:boundaries), so no
+// i18n import: the messages stay English data, translated where shown.
+const msg = (text) => text;
+
+/** Identity and tuning for the Mapillary street-level provider. */
+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',
+]);
+
+/** Stable id prefixes for picked primitives; every one starts with `mly:`. */
+export const PICK_PREFIX = Object.freeze({
+  root: 'mly:',
+  sequence: 'mly:seq:',
+  image: 'mly:img:',
+});
+
+/** Mapillary green for lines and cones; GEV cyan for the selection. */
+export const COLORS = Object.freeze({
+  coverage: PROVIDER_COLORS.mapillary,
+  selected: SHARED_COLORS.selected,
+});
+
+/** Shown when Mapillary refuses the server's token (401/403). */
+export const KEY_REJECTED_MESSAGE = msg(
+  'Mapillary rejected MAPILLARY_CLIENT_TOKEN — replace it in Provider Settings',
+);
+/** Shown while Mapillary rate-limits tile requests (429). */
+export const RATE_LIMITED_MESSAGE = msg(
+  'Coverage requests are being rate-limited — they resume on their own',
+);
+
+/** Coverage tuning (see LineCoverageTuning in lineCoverage.js). */
+export const COVERAGE_TUNING = Object.freeze({
+  maxTiles: 9,
+  maxSequences: 6000,
+  lineWidthPx: 2.5,
+  moveDebounceMs: 320,
+  /**
+   * Street-zoom coverage reaches this far from the camera: camera height
+   * times the factor, never below the floor, even when a tilted view sees
+   * further.
+   */
+  viewRangeMinM: 2_500,
+  viewRangePerHeight: 10,
+});
+
+/** Per-sequence image cones after a sequence is selected. */
+export const SEQUENCE_IMAGES_LIMIT = 2000;
+
+/** On-globe credit: Mapillary imagery is CC BY-SA 4.0 and needs attribution. */
+export const MAPILLARY_CREDIT_HTML =
+  'Street Level: imagery © <a href="https://www.mapillary.com" target="_blank" rel="noopener">Mapillary</a> contributors, CC BY-SA 4.0';
+
+/** Deep link to an image on mapillary.com, as the web app shares them. */
+export function mapillaryImageUrl(imageId) {
+  const id = String(imageId || '').trim();
+  if (!id) return 'https://www.mapillary.com/app/';
+  return `https://www.mapillary.com/app/?pKey=${encodeURIComponent(id)}&focus=photo`;
+}
+
+/** Fields requested for a sequence's images. */
+export const SEQUENCE_IMAGE_FIELDS =
+  'id,captured_at,compass_angle,geometry,is_pano';

src/layers/streetLevel/providers/mapillary/provider.test.mjs

@@ -1,15 +1,15 @@
 import assert from 'node:assert/strict';
 import test from 'node:test';
 import * as Cesium from 'cesium';
-import { createMapillaryProvider } from './mapillaryProvider.js';
+import { createMapillaryProvider } from './index.js';
 import { mapillaryImageUrl } from './policy.js';
-import { sequenceIdFromPick } from './coverage.js';
-import { thinImages } from './sequences.js';
-import { validateProviders } from './registry.js';
+import { sequenceIdFromPick } from '../../lineCoverage.js';
+import { thinImages } from '../../sequenceCones.js';
+import { validateProviders } from '../../registry.js';
 import {
   fakeMapillarySource,
   rayCamera,
-} from '../../testSupport/streetLevelFakes.mjs';
+} from '../../../../testSupport/streetLevelFakes.mjs';
 
 function fakeContext(filter = { pano: 'all', sinceMs: null }) {
   const opened = [];
@@ -61,9 +61,9 @@ test('picks route sequences to selection and images to the core opener', () => {
 });
 
 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);
+  assert.equal(sequenceIdFromPick('mly:seq:abc', 'mly:seq:'), 'abc');
+  assert.equal(sequenceIdFromPick('mly:img:abc', 'mly:seq:'), null);
+  assert.equal(sequenceIdFromPick(null, 'mly:seq:'), null);
 });
 
 test('cone thinning across the date line drops images metres apart', () => {

src/layers/streetLevel/providers/panoramax/decode.js

@@ -0,0 +1,238 @@
+import { PbfReader } from 'pbf';
+import { VectorTile } from '@mapbox/vector-tile';
+import { tileLocalToLonLat } from '../../tileMath.js';
+import {
+  DECODE_SLICE_MS,
+  SIMPLIFY_TOLERANCE_UNITS,
+  panoramaxTimeMs,
+} from './policy.js';
+
+/**
+ * Douglas–Peucker in tile units: the points of `line` ({x, y}) that keep
+ * it within `tolerance` of the original (measured to each segment, so
+ * dead ends and U-turns stay), first and last always kept.
+ * Iterative, so a long track cannot overflow the stack.
+ */
+export function simplifyLine(line, tolerance) {
+  if (line.length < 3 || !(tolerance > 0)) return line;
+  const keep = new Uint8Array(line.length);
+  keep[0] = 1;
+  keep[line.length - 1] = 1;
+  const spans = [[0, line.length - 1]];
+  while (spans.length) {
+    const [from, to] = spans.pop();
+    const a = line[from];
+    const b = line[to];
+    const dx = b.x - a.x;
+    const dy = b.y - a.y;
+    const span2 = dx * dx + dy * dy;
+    let far = -1;
+    let farthest = tolerance;
+    for (let i = from + 1; i < to; i++) {
+      const p = line[i];
+      // Distance to the segment, not the infinite line: a dead end or a
+      // U-turn (a point beyond the chord's ends) is kept.
+      const t = span2
+        ? Math.max(
+            0,
+            Math.min(1, ((p.x - a.x) * dx + (p.y - a.y) * dy) / span2),
+          )
+        : 0;
+      const d = Math.hypot(p.x - (a.x + t * dx), p.y - (a.y + t * dy));
+      if (d > farthest) {
+        farthest = d;
+        far = i;
+      }
+    }
+    if (far === -1) continue;
+    keep[far] = 1;
+    spans.push([from, far], [far, to]);
+  }
+  return line.filter((_, i) => keep[i]);
+}
+
+/** Epoch ms of a sequence's day ('2025-08-11'), or 0 when undated. */
+function dayMs(value) {
+  return panoramaxTimeMs(typeof value === 'string' ? value : '') ?? 0;
+}
+
+/**
+ * Decode a Panoramax coverage tile (`/api/map/{z}/{x}/{y}.mvt`).
+ *
+ * - `sequences` (z7–15): one line per sequence, its parts kept apart so no
+ *   segment is drawn across a gap, with its day and camera type; longest
+ *   first, so a cap on lines drawn drops the shortest.
+ * - `grid` (z0–6, density cells) is not read: nothing is drawn from orbit.
+ * - `pictures` (z15) is left for `decodePictures`.
+ *
+ * In one go; `decodeCoverageTileSliced` gives the page a turn between
+ * slices.
+ * @param {Uint8Array} bytes
+ * @param {{x: number, y: number, z: number}} address
+ * @returns {{sequences: Array<{id: string, parts: Array<Array<[number, number]>>, capturedAt: number, isPano: boolean}>}}
+ */
+export function decodeCoverageTile(bytes, address) {
+  const steps = coverageSteps(bytes, address);
+  let step = steps.next();
+  while (!step.done) step = steps.next();
+  return step.value;
+}
+
+/** Give the page a turn: input and rendering run before the next slice. */
+function nextTask() {
+  if (typeof globalThis.scheduler?.yield === 'function')
+    return globalThis.scheduler.yield();
+  return new Promise((resolve) => setTimeout(resolve, 0));
+}
+
+/**
+ * `decodeCoverageTile` in slices of about `sliceMs`, the page getting a
+ * turn between them: a 2 MB z10 tile over Paris is ~200 ms of decoding on
+ * a fast laptop, more on a phone, and would freeze the globe while the
+ * camera approaches. Stops at the next slice once `signal` aborts.
+ * @param {Uint8Array} bytes
+ * @param {{x: number, y: number, z: number}} address
+ * @param {{signal?: AbortSignal, sliceMs?: number, pause?: () => Promise<void>, now?: () => number}} [options]
+ */
+export async function decodeCoverageTileSliced(
+  bytes,
+  address,
+  {
+    signal,
+    sliceMs = DECODE_SLICE_MS,
+    pause = nextTask,
+    now = () => performance.now(),
+  } = {},
+) {
+  const steps = coverageSteps(bytes, address);
+  let started = now();
+  let step = steps.next();
+  while (!step.done) {
+    if (now() - started >= sliceMs) {
+      await pause();
+      signal?.throwIfAborted();
+      started = now();
+    }
+    step = steps.next();
+  }
+  return step.value;
+}
+
+/** The decode, a step a feature (see `decodeCoverageTile`). */
+function* coverageSteps(bytes, address) {
+  const result = { sequences: [] };
+  if (!bytes || !bytes.length) return result;
+  const tile = new VectorTile(new PbfReader(bytes));
+  const { x, y, z } = address;
+
+  const sequences = tile.layers.sequences;
+  if (sequences) {
+    const measured = [];
+    for (let i = 0; i < sequences.length; i++) {
+      const feature = sequences.feature(i);
+      const props = feature.properties || {};
+      const parts = [];
+      let length = 0;
+      const tolerance = (SIMPLIFY_TOLERANCE_UNITS * sequences.extent) / 4096;
+      for (const line of feature.loadGeometry()) {
+        if (line.length < 2) continue;
+        for (let k = 1; k < line.length; k++)
+          length += Math.hypot(
+            line[k].x - line[k - 1].x,
+            line[k].y - line[k - 1].y,
+          );
+        // Simplified before anything else: GPS tracks carry a point every
+        // few metres, and each becomes ~8 ground-line vertices on the GPU.
+        parts.push(
+          simplifyLine(line, tolerance).map((point) =>
+            tileLocalToLonLat(point.x, point.y, sequences.extent, x, y, z),
+          ),
+        );
+      }
+      if (!parts.length || props.id == null) continue;
+      const sequence = {
+        id: String(props.id),
+        parts,
+        capturedAt: dayMs(props.date),
+        // A sequence with no camera type is neither (the filters keep it).
+        isPano:
+          props.type === 'equirectangular'
+            ? true
+            : props.type === 'flat'
+              ? false
+              : null,
+      };
+      measured.push({ sequence, length });
+      yield;
+    }
+    // A turn before the sort: over a city it is thousands of lines.
+    yield;
+    measured.sort((a, b) => b.length - a.length);
+    result.sequences = measured.map(({ sequence }) => sequence);
+  }
+
+  return result;
+}
+
+/** A picture's sequence ids: the tile stores them as a JSON array in a string. */
+function sequenceIdsOf(props) {
+  const raw = props.sequences;
+  if (typeof raw === 'string' && raw.startsWith('[')) {
+    try {
+      const ids = JSON.parse(raw);
+      if (Array.isArray(ids)) return ids.map(String);
+    } catch {
+      /* fall through to the first sequence */
+    }
+  }
+  return props.first_sequence != null ? [String(props.first_sequence)] : [];
+}
+
+/**
+ * The pictures of a z15 tile that belong to `sequenceId`, as cones draw
+ * them (unsorted).
+ * @param {Uint8Array} bytes
+ * @param {{x: number, y: number, z: number}} address
+ * @param {string} sequenceId
+ * @returns {Array<{id: string, lon: number, lat: number, compassAngle: number, capturedAt: number, isPano: boolean}>}
+ */
+export function decodePictures(bytes, address, sequenceId) {
+  if (!bytes || !bytes.length) return [];
+  const tile = new VectorTile(new PbfReader(bytes));
+  const layer = tile.layers.pictures;
+  if (!layer) return [];
+  const { x, y, z } = address;
+  const wanted = String(sequenceId);
+  const out = [];
+  for (let i = 0; i < layer.length; i++) {
+    const feature = layer.feature(i);
+    const props = feature.properties || {};
+    // A cheap test first: most pictures in a tile are other sequences'.
+    if (
+      typeof props.sequences === 'string' &&
+      !props.sequences.includes(wanted)
+    )
+      continue;
+    if (!sequenceIdsOf(props).includes(wanted) || props.id == null) continue;
+    const point = feature.loadGeometry()?.[0]?.[0];
+    if (!point) continue;
+    const [lon, lat] = tileLocalToLonLat(
+      point.x,
+      point.y,
+      layer.extent,
+      x,
+      y,
+      z,
+    );
+    const heading = Number(props.heading);
+    out.push({
+      id: String(props.id),
+      lon,
+      lat,
+      compassAngle: Number.isFinite(heading) ? heading : 0,
+      capturedAt: panoramaxTimeMs(String(props.ts ?? '')) ?? 0,
+      isPano: props.type === 'equirectangular',
+    });
+  }
+  return out;
+}

src/layers/streetLevel/providers/panoramax/decode.test.mjs

@@ -0,0 +1,275 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import {
+  decodeCoverageTile,
+  decodeCoverageTileSliced,
+  decodePictures,
+  simplifyLine,
+} from './decode.js';
+import { encodePanoramaxTile } from '../../../../testSupport/panoramaxFixtures.mjs';
+import { tileCentre } from '../../../../testSupport/streetLevelFakes.mjs';
+
+const near = (a, b, eps = 1e-4) => Math.abs(a - b) < eps;
+
+test('sequence lines keep their parts apart, with their day and camera type', () => {
+  const { tile, lon, lat } = tileCentre(2.35, 48.85);
+  const bytes = encodePanoramaxTile(tile, {
+    sequences: [
+      {
+        id: 'pano-seq',
+        type: 'equirectangular',
+        date: '2024-03-05',
+        parts: [
+          [
+            [lon - 0.001, lat],
+            [lon, lat],
+          ],
+          [
+            [lon + 0.0005, lat],
+            [lon + 0.001, lat],
+          ],
+        ],
+      },
+      {
+        id: 'flat-seq',
+        parts: [
+          [
+            [lon, lat - 0.001],
+            [lon, lat],
+          ],
+        ],
+      },
+    ],
+  });
+  const { sequences } = decodeCoverageTile(bytes, tile);
+  assert.equal(sequences.length, 2);
+  const pano = sequences.find((s) => s.id === 'pano-seq');
+  const flat = sequences.find((s) => s.id === 'flat-seq');
+  assert.equal(pano.isPano, true);
+  assert.equal(pano.capturedAt, Date.UTC(2024, 2, 5));
+  assert.equal(pano.parts.length, 2, 'the gap is not bridged');
+  assert.ok(near(pano.parts[1][1][0], lon + 0.001));
+  assert.equal(flat.isPano, false);
+  const untyped = decodeCoverageTile(
+    encodePanoramaxTile(tile, {
+      sequences: [
+        {
+          id: 'u',
+          type: '',
+          parts: [
+            [
+              [lon, lat],
+              [lon + 0.001, lat],
+            ],
+          ],
+        },
+      ],
+    }),
+    tile,
+  ).sequences[0];
+  assert.equal(untyped.isPano, null, 'no camera type: neither');
+});
+
+test('the density grid is not read: nothing is drawn from orbit', () => {
+  const tile = { x: 0, y: 0, z: 0 };
+  const grid = [{ lon: 2.35, lat: 48.85, pano: 3, flat: 5 }];
+  assert.deepEqual(
+    decodeCoverageTile(encodePanoramaxTile(tile, { grid }), tile),
+    { sequences: [] },
+  );
+});
+
+test('lines come longest first, so a cap on lines drawn drops the shortest', () => {
+  const { tile, lon, lat } = tileCentre(2.35, 48.85);
+  const span = (id, metres) => ({
+    id,
+    parts: [
+      [
+        [lon, lat],
+        [lon + metres / 73_000, lat],
+      ],
+    ],
+  });
+  const { sequences } = decodeCoverageTile(
+    encodePanoramaxTile(tile, {
+      sequences: [span('short', 20), span('long', 900), span('mid', 300)],
+    }),
+    tile,
+  );
+  assert.deepEqual(
+    sequences.map((s) => s.id),
+    ['long', 'mid', 'short'],
+  );
+});
+
+/** A tile with many lines and a dense grid, for the sliced decode. */
+function busyTile() {
+  const { tile, lon, lat } = tileCentre(2.35, 48.85);
+  const sequences = Array.from({ length: 200 }, (_, i) => ({
+    id: `s${i}`,
+    parts: [
+      [
+        [lon, lat + i / 1e6],
+        [lon + (i + 1) / 73_000, lat + i / 1e6],
+      ],
+    ],
+  }));
+  const grid = Array.from({ length: 500 }, (_, i) => ({
+    lon: lon + (i % 25) / 1e4,
+    lat: lat + Math.floor(i / 25) / 1e4,
+  }));
+  return { tile, bytes: encodePanoramaxTile(tile, { sequences, grid }) };
+}
+
+test('a sliced decode gives the page turns and decodes the same as one in one go', async () => {
+  const { tile, bytes } = busyTile();
+  let clock = 0;
+  let pauses = 0;
+  const sliced = await decodeCoverageTileSliced(bytes, tile, {
+    sliceMs: 8,
+    // Each step "takes" a millisecond: a turn every eight features.
+    now: () => clock++,
+    pause: async () => {
+      pauses++;
+    },
+  });
+  assert.ok(pauses > 20, `${pauses} turns`);
+  assert.deepEqual(sliced, decodeCoverageTile(bytes, tile));
+});
+
+test('a sliced decode stops at the next turn once aborted', async () => {
+  const { tile, bytes } = busyTile();
+  const controller = new AbortController();
+  let clock = 0;
+  let pauses = 0;
+  await assert.rejects(
+    decodeCoverageTileSliced(bytes, tile, {
+      signal: controller.signal,
+      now: () => (clock += 10),
+      pause: async () => {
+        if (++pauses === 2) controller.abort();
+      },
+    }),
+    { name: 'AbortError' },
+  );
+  assert.equal(pauses, 2, 'no work after the abort');
+});
+
+test('a fast sliced decode takes no turns', async () => {
+  const { tile, bytes } = busyTile();
+  let pauses = 0;
+  await decodeCoverageTileSliced(bytes, tile, {
+    now: () => 0,
+    pause: async () => {
+      pauses++;
+    },
+  });
+  assert.equal(pauses, 0);
+});
+
+test('an empty tile decodes to nothing', () => {
+  for (const bytes of [new Uint8Array(0), null, undefined])
+    assert.deepEqual(decodeCoverageTile(bytes, { x: 0, y: 0, z: 0 }), {
+      sequences: [],
+    });
+  assert.deepEqual(
+    decodePictures(new Uint8Array(0), { x: 0, y: 0, z: 15 }, 's'),
+    [],
+  );
+});
+
+test('a z15 tile’s pictures of one sequence become cones; other sequences’ are skipped', () => {
+  const { tile, lon, lat } = tileCentre(2.35, 48.85, 15);
+  const bytes = encodePanoramaxTile(tile, {
+    pictures: [
+      {
+        id: 'a',
+        lon,
+        lat,
+        sequenceId: 's1',
+        heading: 45,
+        type: 'equirectangular',
+        ts: '2023-12-12 07:56:37+00',
+      },
+      { id: 'b', lon: lon + 0.0001, lat, sequenceId: 's2' },
+      { id: 'c', lon: lon + 0.0002, lat, sequenceId: 's1' },
+    ],
+  });
+  const images = decodePictures(bytes, tile, 's1');
+  assert.deepEqual(
+    images.map((i) => i.id),
+    ['a', 'c'],
+  );
+  assert.equal(images[0].compassAngle, 45);
+  assert.equal(images[0].isPano, true);
+  assert.equal(images[0].capturedAt, Date.UTC(2023, 11, 12, 7, 56, 37));
+  assert.ok(near(images[1].lon, lon + 0.0002));
+  assert.deepEqual(decodePictures(bytes, tile, 'nope'), []);
+  // A tile without pictures (below z15) has none to give.
+  const lines = encodePanoramaxTile(tile, {
+    sequences: [
+      {
+        id: 's1',
+        parts: [
+          [
+            [lon, lat],
+            [lon + 0.001, lat],
+          ],
+        ],
+      },
+    ],
+  });
+  assert.deepEqual(decodePictures(lines, tile, 's1'), []);
+});
+
+test('lines are simplified within a few tile units, ends and corners kept', () => {
+  const zigzag = Array.from({ length: 1000 }, (_, i) => ({
+    x: i,
+    y: i % 2 ? 1 : 0,
+  }));
+  assert.deepEqual(
+    simplifyLine(zigzag, 4),
+    [zigzag[0], zigzag.at(-1)],
+    'a 1-unit wobble goes',
+  );
+  const corner = [
+    { x: 0, y: 0 },
+    { x: 50, y: 1 },
+    { x: 100, y: 0 },
+    { x: 100, y: 100 },
+  ];
+  assert.deepEqual(simplifyLine(corner, 4), [corner[0], corner[2], corner[3]]);
+  assert.equal(simplifyLine(corner.slice(0, 2), 4).length, 2);
+  // A loop back to its start (no chord) keeps its far point.
+  const loop = [
+    { x: 0, y: 0 },
+    { x: 40, y: 0 },
+    { x: 0, y: 0 },
+  ];
+  assert.equal(simplifyLine(loop, 4).length, 3);
+  assert.equal(simplifyLine(zigzag, 0).length, 1000, 'no tolerance, no change');
+  // A dead end: out to 100 and back to 50 keeps its far end.
+  const deadEnd = [
+    { x: 0, y: 0 },
+    { x: 100, y: 0 },
+    { x: 50, y: 0 },
+  ];
+  assert.deepEqual(simplifyLine(deadEnd, 4), deadEnd);
+});
+
+test('a decoded GPS track keeps a fraction of its points', () => {
+  const { tile, lon, lat } = tileCentre(2.35, 48.85);
+  const track = Array.from({ length: 500 }, (_, i) => [
+    lon - 0.004 + i * 0.000016,
+    lat + Math.sin(i / 40) * 0.0004,
+  ]);
+  const [sequence] = decodeCoverageTile(
+    encodePanoramaxTile(tile, { sequences: [{ id: 'gps', parts: [track] }] }),
+    tile,
+  ).sequences;
+  assert.ok(
+    sequence.parts[0].length < 100,
+    `${sequence.parts[0].length} points`,
+  );
+  assert.ok(sequence.parts[0].length > 5);
+});

src/layers/streetLevel/providers/panoramax/index.js

@@ -0,0 +1,578 @@
+import {
+  createLineCoverage,
+  freshCoverage,
+  sequenceIdFromPick,
+} from '../../lineCoverage.js';
+import { createSequenceCones, thinImages } from '../../sequenceCones.js';
+import { passesImageryFilter } from '../../filter.js';
+import { lonToTileX, latToTileY, tileBounds } from '../../tileMath.js';
+import { metresBetween } from '../../view.js';
+import { createLru, createTileCache } from '../../tileCache.js';
+import { decodeCoverageTileSliced, decodePictures } from './decode.js';
+import { createPanoramaxSource } from './source.js';
+import { createPanoramaxViewer } from './viewer.js';
+import { msg } from '../../../../i18n/index.js';
+import {
+  COLORS,
+  COVERAGE_LINES_BELOW_M,
+  COVERAGE_TUNING,
+  COVERAGE_Z11_BELOW_M,
+  COVERAGE_Z12_BELOW_M,
+  COVERAGE_Z13_BELOW_M,
+  COVERAGE_Z14_BELOW_M,
+  GONE_MESSAGE,
+  LINE_CLICK_HINT,
+  LINE_CLICK_RADIUS_MAX_M,
+  LINE_CLICK_RADIUS_PER_HEIGHT,
+  NEAREST_LIMIT,
+  NEAREST_RADIUS_M,
+  FILTERED_HINT,
+  NO_COVERAGE_HINT,
+  PANORAMAX_CREDIT_HTML,
+  PANORAMAX_LABEL,
+  PANORAMAX_NAME,
+  PANORAMAX_PROVIDER_ID,
+  PICK_PREFIX,
+  PICTURE_TILE_EDGE_M,
+  PICTURE_TILE_ZOOM,
+  RATE_LIMITED_MESSAGE,
+  UNREADABLE_TILE_MESSAGE,
+  ZOOM_IN_HINT,
+  normalizeItem,
+} from './policy.js';
+
+export { PANORAMAX_PROVIDER_ID } from './policy.js';
+
+/**
+ * A tile's bytes decoded by `decode`; a body that is not a vector tile
+ * (an HTML error page, a cut-off answer) reads as such, not as a parser's
+ * "Unimplemented type: 4".
+ */
+async function readable(decode) {
+  try {
+    return await decode();
+  } catch (error) {
+    if (error?.name === 'AbortError' || error?.status !== undefined)
+      throw error;
+    throw new Error(UNREADABLE_TILE_MESSAGE);
+  }
+}
+
+/** Pictures kept in memory by id (lookups and ‹ › fill it). */
+const PHOTO_CACHE_SIZE = 2000;
+/** Sequences whose cone centre is remembered. */
+const ANCHOR_CACHE_SIZE = 50;
+/** Decoded coverage tiles kept (a simplified dense z10 tile is ~4 MB). */
+const COVERAGE_TILE_CACHE_SIZE = 16;
+/** One sequence's pictures in a z15 tile, kept for re-centring. */
+const PICTURE_LIST_CACHE_SIZE = 32;
+
+/**
+ * Sequence lines at z10–14 below 60 km; above, nothing is drawn (the hint
+ * says to zoom in).
+ */
+export function panoramaxZoomFor(heightM) {
+  if (!Number.isFinite(heightM) || heightM > COVERAGE_LINES_BELOW_M)
+    return null;
+  return heightM <= COVERAGE_Z14_BELOW_M
+    ? 14
+    : heightM <= COVERAGE_Z13_BELOW_M
+      ? 13
+      : heightM <= COVERAGE_Z12_BELOW_M
+        ? 12
+        : heightM <= COVERAGE_Z11_BELOW_M
+          ? 11
+          : 10;
+}
+
+/**
+ * The imagery filter for lines. A line is dated by its sequence's first
+ * day, so a sequence still growing may hide under "since" while its newer
+ * pictures can be opened; a line with no camera type or no day is kept (a
+ * click finds out).
+ */
+export function passesCoverage(record, filter) {
+  if (!filter) return true;
+  return passesImageryFilter(record, {
+    pano: typeof record.isPano === 'boolean' ? filter.pano : 'all',
+    sinceMs: record.capturedAt ? filter.sinceMs : null,
+  });
+}
+
+/** The z15 tile holding a point. */
+function pictureTileOf({ lon, lat }) {
+  const z = PICTURE_TILE_ZOOM;
+  return { x: lonToTileX(lon, z), y: latToTileY(lat, z), z };
+}
+
+/**
+ * The z15 tiles whose pictures surround a point: its own first, and the
+ * neighbours it sits within PICTURE_TILE_EDGE_M of (at most nine).
+ */
+export function pictureTilesAround(point) {
+  const home = pictureTileOf(point);
+  const box = tileBounds(home.x, home.y, home.z);
+  const near = (lon, lat) =>
+    metresBetween(point, { lon, lat }) <= PICTURE_TILE_EDGE_M;
+  // Near both edges at once where tiles are narrow (high latitudes).
+  const dxs = [0];
+  if (near(box.west, point.lat)) dxs.push(-1);
+  if (near(box.east, point.lat)) dxs.push(1);
+  const dys = [0];
+  if (near(point.lon, box.north)) dys.push(-1);
+  if (near(point.lon, box.south)) dys.push(1);
+  const max = 2 ** home.z;
+  const tiles = [];
+  for (const dy of dys)
+    for (const dx of dxs) {
+      const y = home.y + dy;
+      if (y < 0 || y >= max) continue;
+      tiles.push({ x: (home.x + dx + max) % max, y, z: home.z });
+    }
+  return tiles;
+}
+
+const tileKey = ({ x, y, z }) => `${z}/${x}/${y}`;
+
+/**
+ * Panoramax Street Level provider: the federated, keyless, open
+ * street-level commons. Coverage from its vector tiles (sequence lines
+ * near the ground, nothing from orbit); a click on a line opens that
+ * sequence's picture nearest the click, with cones along the sequence
+ * around it and ‹ › to step through it. Flat pictures show as photos, 360°
+ * ones on the shared WebGL panorama.
+ * @param {{source?: ReturnType<typeof createPanoramaxSource>, viewerOptions?: object}} [options]
+ * @returns {import('../../registry.js').StreetLevelProvider}
+ */
+export function createPanoramaxProvider({
+  source = createPanoramaxSource(),
+  viewerOptions = {},
+} = {}) {
+  return Object.freeze({
+    id: PANORAMAX_PROVIDER_ID,
+    name: PANORAMAX_NAME,
+    label: PANORAMAX_LABEL,
+    requiresKeyId: null,
+    pickPrefix: PICK_PREFIX.root,
+    colors: COLORS,
+    credit: Object.freeze({ html: PANORAMAX_CREDIT_HTML }),
+    defaultOn: false,
+    coverageLabel: Object.freeze({
+      noun: 'sequences',
+      action: LINE_CLICK_HINT,
+    }),
+
+    create(context) {
+      const state = {
+        context,
+        services: context.services,
+        viewer: null,
+        coverage: freshCoverage({ keyless: true }),
+        sequence: {
+          selectedId: null,
+          images: [],
+          collection: null,
+          loading: false,
+          error: null,
+          abort: null,
+        },
+      };
+      const photos = createLru(PHOTO_CACHE_SIZE);
+      /** Where each sequence's cones centre: the picture last opened in it, or a click. */
+      const anchors = createLru(ANCHOR_CACHE_SIZE);
+      /** The z15 tiles the cones were drawn from. */
+      let drawn = null;
+      /** A line click: its sequence's pictures win the next nearest lookup there. */
+      let preferred = null;
+
+      function remember(item) {
+        const photo = normalizeItem(item);
+        if (photo) photos.set(photo.id, photo);
+        return photo;
+      }
+
+      /**
+       * Lookups in flight, shared: ‹ › and the viewer ask for the same
+       * picture. A lookup stops once every caller waiting on it has given up
+       * (its search would hold one of the two API connections for nothing).
+       */
+      const inflight = new Map();
+      function getPhoto(photoId, { signal } = {}) {
+        const id = String(photoId);
+        const cached = photos.get(id);
+        if (cached) return Promise.resolve(cached);
+        if (signal?.aborted) return Promise.reject(signal.reason);
+        let lookup = inflight.get(id);
+        if (!lookup) {
+          const controller = new AbortController();
+          lookup = { controller, waiting: 0 };
+          lookup.promise = source
+            .getItem(id, { signal: controller.signal })
+            .catch((error) => {
+              // Ids are UUIDs: the API answers 400 to anything else.
+              if (error?.status === 400) return null;
+              throw error;
+            })
+            .then((item) => {
+              const photo = item && remember(item);
+              if (!photo) throw new Error(GONE_MESSAGE);
+              return photo;
+            })
+            .finally(() => {
+              if (inflight.get(id) === lookup) inflight.delete(id);
+            });
+          lookup.promise.catch(() => {});
+          inflight.set(id, lookup);
+        }
+        const shared = lookup;
+        shared.waiting++;
+        if (!signal) shared.waiting = Infinity;
+        return new Promise((resolve, reject) => {
+          const leave = () => {
+            reject(signal.reason);
+            shared.waiting--;
+            // A caller in the same tick (the same photo opened again) may
+            // still join: stop only if nobody has.
+            queueMicrotask(() => {
+              if (shared.waiting > 0) return;
+              shared.controller.abort(signal.reason);
+              if (inflight.get(id) === shared) inflight.delete(id);
+            });
+          };
+          signal?.addEventListener('abort', leave, { once: true });
+          shared.promise.then(
+            (photo) => {
+              signal?.removeEventListener('abort', leave);
+              resolve(photo);
+            },
+            (error) => {
+              signal?.removeEventListener('abort', leave);
+              reject(error);
+            },
+          );
+        });
+      }
+
+      /**
+       * How far from a line click its sequence's pictures are looked for:
+       * from high up the click may land tens of metres off the line.
+       */
+      function lineClickRadius() {
+        const height = state.viewer?.camera?.positionCartographic?.height;
+        if (!Number.isFinite(height)) return NEAREST_RADIUS_M;
+        return Math.min(
+          LINE_CLICK_RADIUS_MAX_M,
+          Math.max(NEAREST_RADIUS_M, height * LINE_CLICK_RADIUS_PER_HEIGHT),
+        );
+      }
+
+      /** The picture `delta` along its sequence, from its own links (null at an end). */
+      async function step(photo, delta) {
+        if (!photo?.sequenceId) return null;
+        return (delta < 0 ? photo.prevId : photo.nextId) || null;
+      }
+
+      // Decoded tiles, kept a while: panning back, or across a zoom band and
+      // back, neither fetches nor decodes them again.
+      const coverageTiles = createTileCache({
+        size: COVERAGE_TILE_CACHE_SIZE,
+        load: (tile, { signal }) =>
+          readable(async () =>
+            decodeCoverageTileSliced(
+              await source.getTile(tile, { signal }),
+              tile,
+              { signal },
+            ),
+          ),
+      });
+      /** A z15 tile's pictures of one sequence, by `z/x/y:sequence`. */
+      const pictureLists = createLru(PICTURE_LIST_CACHE_SIZE);
+      /**
+       * Only finished lists are kept: a load in flight belongs to its own
+       * selection, whose abort (a re-centre) must not empty the next one's.
+       */
+      async function picturesIn(tile, sequenceId, signal) {
+        const key = `${tileKey(tile)}:${sequenceId}`;
+        const kept = pictureLists.get(key);
+        if (kept) return kept;
+        const list = await readable(async () =>
+          decodePictures(
+            await source.getTile(tile, { signal, lane: 'pictures' }),
+            tile,
+            sequenceId,
+          ),
+        );
+        pictureLists.set(key, list);
+        return list;
+      }
+
+      const coverage = createLineCoverage({
+        state,
+        fetchTile: (tile, options) => coverageTiles.get(tile, options),
+        zoomFor: panoramaxZoomFor,
+        colors: COLORS,
+        pickPrefix: PICK_PREFIX.sequence,
+        renderKey: 'panoramax-coverage',
+        tuning: COVERAGE_TUNING,
+        messages: { rateLimited: RATE_LIMITED_MESSAGE, tooHigh: ZOOM_IN_HINT },
+        passes: passesCoverage,
+      });
+
+      const cones = createSequenceCones({
+        state,
+        async loadImages(sequenceId, { signal }) {
+          const anchor = anchors.get(sequenceId);
+          if (!anchor) return [];
+          const tiles = pictureTilesAround(anchor);
+          // Known from the start: a picture opening while these load is
+          // judged against them (re-centred if outside, left alone inside).
+          const covering = { sequenceId, tiles: new Set(tiles.map(tileKey)) };
+          drawn = covering;
+          const conesOf = (lists) =>
+            thinImages(
+              [
+                ...new Map(
+                  lists.flat().map((image) => [image.id, image]),
+                ).values(),
+              ].sort((a, b) => a.capturedAt - b.capturedAt),
+            );
+          const keyOf = (tile) => `${tileKey(tile)}:${sequenceId}`;
+          // The home tile is needed now (it holds the open picture).
+          const home = await picturesIn(tiles[0], sequenceId, signal);
+          signal?.throwIfAborted();
+          // Neighbours already read draw with it; the rest (each up to
+          // 1.4 MB in central Paris) join the cones as they arrive.
+          const neighbours = tiles.slice(1);
+          const kept = neighbours
+            .map((tile) => pictureLists.get(keyOf(tile)))
+            .filter(Boolean);
+          const missing = neighbours.filter(
+            (tile) => !pictureLists.get(keyOf(tile)),
+          );
+          if (missing.length)
+            Promise.allSettled(
+              missing.map((tile) => picturesIn(tile, sequenceId, signal)),
+            ).then((lists) => {
+              if (signal?.aborted || drawn !== covering) return;
+              dropFailed(covering, missing, lists);
+              // Only a tile that arrived now redraws (no loop on failures).
+              if (lists.some((list) => list.status === 'fulfilled'))
+                cones.select(sequenceId, { force: true });
+            });
+          return conesOf([home, ...kept]);
+        },
+        colors: COLORS,
+        pickPrefix: PICK_PREFIX.image,
+        spriteId: 'street-level:panoramax-cones',
+        renderKey: 'panoramax-sequence',
+        onHighlight: (sequenceId) => coverage.highlight(sequenceId),
+      });
+
+      /**
+       * A tile that failed is not covered: a picture opening in it later
+       * re-centres the cones there (and asks for the tile again).
+       */
+      function dropFailed(covering, tiles, lists) {
+        lists.forEach((list, i) => {
+          if (list.status === 'rejected')
+            covering.tiles.delete(tileKey(tiles[i]));
+        });
+      }
+
+      /**
+       * The cones show the z15 tiles around one picture: once a picture of
+       * the selected sequence opens outside them (‹ ›, a cone), re-centre.
+       */
+      function recentreCones(photo) {
+        if (!photo?.sequenceId) return;
+        if (state.sequence.selectedId !== photo.sequenceId) return;
+        if (drawn?.sequenceId !== photo.sequenceId) return;
+        if (drawn.tiles.has(tileKey(pictureTileOf(photo)))) return;
+        cones.select(photo.sequenceId, { force: true });
+      }
+
+      const viewer = createPanoramaxViewer({
+        getPhoto,
+        // The cones centre on the picture actually shown, never on a
+        // lookup that came back after the user moved on.
+        onShowing: (photo) => {
+          if (photo.sequenceId) anchors.set(photo.sequenceId, photo);
+        },
+        // After a GPU reset the same picture is drawn again by the viewer
+        // itself: through the core it would cancel a lookup the user
+        // started. A failure still shows.
+        onReopen: (photoId) =>
+          viewer
+            .open(photoId)
+            .catch((error) =>
+              context.actions.reportError(
+                error?.message ||
+                  msg('The Panoramax photo could not be loaded'),
+              ),
+            ),
+        step,
+        onStep: (photoId) =>
+          context.actions.openImage(photoId, { frame: false }),
+        onShown: recentreCones,
+        // Esc in the viewer clears the selected sequence, as the panel says.
+        onEscape: () => {
+          if (!state.sequence.selectedId) return false;
+          cones.clearSelection();
+          drawn = null;
+          return true;
+        },
+        render: context.services?.render,
+        ...viewerOptions,
+      });
+
+      /** Nearest of `items` within `radius` metres of a point, or null. */
+      function nearestOf(items, point, radius = NEAREST_RADIUS_M) {
+        let best = null;
+        for (const item of items) {
+          const photo = remember(item);
+          if (!photo) continue;
+          const metres = metresBetween(point, photo);
+          if (metres > radius) continue;
+          if (!best || metres < best.metres) best = { photo, metres };
+        }
+        return best?.photo ?? null;
+      }
+
+      return {
+        async status() {
+          return { configured: true };
+        },
+
+        init(cesiumViewer) {
+          state.viewer = cesiumViewer;
+          cones.ensureCollections(cesiumViewer);
+          cones.setVisible(false);
+        },
+
+        activate(cesiumViewer) {
+          state.viewer = cesiumViewer;
+          cones.setVisible(true);
+          coverage.attach(cesiumViewer);
+        },
+
+        deactivate() {
+          coverage.detach();
+          coverage.clear();
+          coverage.unblock();
+          cones.clearSelection();
+          cones.setVisible(false);
+          drawn = null;
+          preferred = null;
+          // Off: decoded tiles and lists go (several MB each over a city).
+          coverageTiles.clear();
+          pictureLists.clear();
+        },
+
+        destroy(cesiumViewer) {
+          coverage.detach();
+          coverage.clear();
+          coverage.unblock();
+          cones.destroy(cesiumViewer);
+        },
+
+        /** The filter changed: redraw. Each draw reads it from the context. */
+        setFilter() {
+          coverage.rebuild();
+          cones.rerender();
+        },
+
+        coverageStats() {
+          const stats = coverage.stats();
+          let fallback = '';
+          // Lines drawn for the camera (a zoom), all settled, none shown.
+          const settled =
+            state.coverage.zoom != null && !stats.loading && !stats.error;
+          if (settled && stats.count === 0) {
+            // Tiles that held lines the filter hid all of.
+            const filteredOut = [...state.coverage.tiles.values()].some(
+              (tile) => tile.total > 0,
+            );
+            fallback = filteredOut ? FILTERED_HINT : NO_COVERAGE_HINT;
+          }
+          return { ...stats, hint: stats.hint || fallback };
+        },
+
+        /**
+         * A line opens its sequence's picture nearest the click (the cones
+         * follow once it is on screen); a cone opens its picture.
+         */
+        handlePick(pickId, { groundPoint } = {}) {
+          if (pickId.startsWith(PICK_PREFIX.image)) {
+            context.actions.openImage(pickId.slice(PICK_PREFIX.image.length));
+            return true;
+          }
+          const sequenceId = sequenceIdFromPick(pickId, PICK_PREFIX.sequence);
+          if (!sequenceId) return false;
+          const point = groundPoint?.();
+          // No ground under the click (the sky beyond a line): nothing to open.
+          if (!point) return true;
+          anchors.set(sequenceId, { ...point, sequenceId });
+          preferred = {
+            sequenceId,
+            lon: point.lon,
+            lat: point.lat,
+            radius: lineClickRadius(),
+          };
+          context.actions.openNearest(point);
+          return true;
+        },
+
+        selectSequence: (sequenceId) =>
+          cones.select(sequenceId, { force: true }),
+        clearSequence: () => {
+          cones.clearSelection();
+          drawn = null;
+        },
+        sequenceStats: () => ({
+          selectedId: state.sequence.selectedId,
+          images: state.sequence.images.length,
+          loading: state.sequence.loading,
+          error: state.sequence.error,
+        }),
+
+        /**
+         * The nearest picture within the search radius that passes the
+         * imagery filter, or null. After a click on a line, that line's
+         * sequence is asked first.
+         */
+        async nearestImage({ lat, lon }, { signal } = {}) {
+          const point = { lat, lon };
+          const filter = context.getFilter();
+          // Only the lookup the click itself asked for (the same point).
+          const wanted =
+            preferred && metresBetween(preferred, point) < 1 ? preferred : null;
+          preferred = null;
+          const ask = (collections, radius = NEAREST_RADIUS_M) =>
+            source.nearestItems(
+              {
+                lat,
+                lon,
+                radius,
+                limit: NEAREST_LIMIT,
+                collections,
+                pano: filter.pano,
+                sinceMs: filter.sinceMs,
+              },
+              { signal },
+            );
+          if (wanted) {
+            const hit = nearestOf(
+              await ask(wanted.sequenceId, wanted.radius),
+              point,
+              wanted.radius,
+            );
+            if (hit) return hit.id;
+          }
+          return nearestOf(await ask(null), point)?.id ?? null;
+        },
+
+        viewer,
+      };
+    },
+  });
+}

src/layers/streetLevel/providers/panoramax/policy.js

@@ -0,0 +1,312 @@
+import { COLORS as SHARED_COLORS, PROVIDER_COLORS } from '../../policy.js';
+import { msg } from '../../../../i18n/index.js';
+
+export { NEAREST_RADIUS_M } from '../../policy.js';
+
+/** Identity and tuning for the Panoramax street-level provider (keyless). */
+export const PANORAMAX_PROVIDER_ID = 'panoramax';
+export const PANORAMAX_NAME = 'Panoramax';
+export const PANORAMAX_LABEL = 'PANORAMAX';
+
+/**
+ * The Panoramax meta-catalogue: one keyless, CORS-enabled STAC API over
+ * every federated instance (OpenStreetMap France, IGN, MapComplete…). Its
+ * pictures are served by the instance that holds them.
+ */
+export const PANORAMAX_API = 'https://api.panoramax.xyz/api';
+/** The meta-catalogue's web viewer, where the caption link goes. */
+export const PANORAMAX_VIEWER = 'https://api.panoramax.xyz/';
+
+/** Stable id prefixes for picked primitives; every one starts with `pnx:`. */
+export const PICK_PREFIX = Object.freeze({
+  root: 'pnx:',
+  sequence: 'pnx:seq:',
+  image: 'pnx:img:',
+});
+
+export const COLORS = Object.freeze({
+  coverage: PROVIDER_COLORS.panoramax,
+  selected: SHARED_COLORS.selected,
+});
+
+/**
+ * Sequence lines come from z7–15 tiles; z10–14 are drawn below 60 km, as
+ * Mapillary's are (a dense tile over Paris: z10 ~2.1 MB and 8,600
+ * sequences, z11 ~1.4 MB, z12 ~800 kB). Higher up nothing is drawn.
+ */
+export const COVERAGE_Z14_BELOW_M = 1_800;
+export const COVERAGE_Z13_BELOW_M = 5_000;
+export const COVERAGE_Z12_BELOW_M = 12_000;
+export const COVERAGE_Z11_BELOW_M = 30_000;
+export const COVERAGE_LINES_BELOW_M = 60_000;
+export const COVERAGE_TUNING = Object.freeze({
+  maxTiles: 9,
+  // Each tile draws at most 1,600 lines, its longest first (as decoded,
+  // `keepOrder`): a dense z11
+  // tile over Paris holds 3,800, and a lower cap left the city centre
+  // looking emptier than its suburbs. (KartaView draws as many.)
+  maxSequences: 14_400,
+  keepOrder: true,
+  // Points drawn at most, over every tile, a ninth of it a tile (each
+  // becomes ~8 ground-line vertices, ~1.4 kB of geometry): the simplified
+  // Paris z10 tile alone holds 57,000, unsimplified 750,000, which hung
+  // the tab.
+  maxPoints: 90_000,
+  lineWidthPx: 2.5,
+  moveDebounceMs: 320,
+  viewRangeMinM: 2_500,
+  viewRangePerHeight: 10,
+});
+/**
+ * Lines are simplified (Douglas–Peucker) to this many tile units of a
+ * 4,096 extent: about a pixel where each zoom is drawn (1.6 m at z14,
+ * within GPS noise), and 6–10% of the points GPS tracks carry.
+ */
+export const SIMPLIFY_TOLERANCE_UNITS = 4;
+
+/**
+ * Coverage tiles decode in slices of this many ms, the page getting a turn
+ * between them (decode.js `decodeCoverageTileSliced`): under a frame.
+ */
+export const DECODE_SLICE_MS = 8;
+
+export const RATE_LIMITED_MESSAGE = msg(
+  'Panoramax is busy — coverage resumes on its own',
+);
+export const NO_COVERAGE_HINT = msg('no Panoramax photos in view');
+/** Lines in view, all hidden by the imagery filter. */
+export const FILTERED_HINT = msg('no Panoramax photos here match the filters');
+export const UNREADABLE_TILE_MESSAGE = msg(
+  'Panoramax sent a map tile that could not be read',
+);
+export const GONE_MESSAGE = msg('This Panoramax photo is no longer available');
+/** Above the line ceiling nothing is drawn. */
+export const ZOOM_IN_HINT = msg('zoom in to see Panoramax coverage');
+
+/** Cones come from z15 tiles' `pictures` layer (~110 bytes a picture). */
+export const PICTURE_TILE_ZOOM = 15;
+/** Within this of a z15 tile's edge, the neighbouring tile's pictures join. */
+export const PICTURE_TILE_EDGE_M = 150;
+
+export const TILE_TIMEOUT_MS = 20_000;
+/**
+ * Once an answer has started, it may take as long as it keeps coming: a
+ * 2 MB tile on a slow link outlasts any whole-request timeout, so only a
+ * stream silent this long is given up.
+ */
+export const STREAM_IDLE_TIMEOUT_MS = 15_000;
+/** Busy (429/503) without a Retry-After the browser can read: back off from this. */
+export const BUSY_BACKOFF_BASE_SEC = 5;
+export const API_TIMEOUT_MS = 12_000;
+/** Real tiles are under 6 MB (z6 over France); refuse anything absurd. */
+export const MAX_RESPONSE_BYTES = 16 * 1024 * 1024;
+/**
+ * The meta-catalogue speaks HTTP/1.1 only, so the browser opens six
+ * connections to it: coverage tiles take three, searches two and the
+ * cones' tiles one, so a click's lookup never queues behind megabyte tiles
+ * (it timed out doing so).
+ */
+export const API_CONCURRENCY = 2;
+export const TILE_CONCURRENCY = 3;
+/** The selected sequence's z15 tiles (cones) take the sixth. */
+export const PICTURE_TILE_CONCURRENCY = 1;
+
+/** Pictures asked for around a point; the API returns them nearest first. */
+export const NEAREST_LIMIT = 10;
+/**
+ * The widest the API allows: the point may be beside a picture, but a
+ * picture looking away from it is still left out (the bounding-box search
+ * beside it has those).
+ */
+export const NEAREST_FOV_TOLERANCE_DEG = 180;
+/**
+ * Pictures in the bounding box around a click, at most. The API returns
+ * them roughly nearest first (the first ten of 100 are the first ten of
+ * 10), and the browser ranks them exactly: 20 is ~60 kB, 100 ~600 kB.
+ */
+export const NEAREST_BOX_LIMIT = 20;
+/**
+ * A line clicked from high up may be tens of metres off the click: its
+ * sequence is searched within the camera height / 100 (50–400 m).
+ */
+export const LINE_CLICK_RADIUS_PER_HEIGHT = 0.01;
+export const LINE_CLICK_RADIUS_MAX_M = 400;
+
+/** A full-resolution panorama is only fetched up to this width (memory). */
+export const PANO_HD_MAX_WIDTH = 8_192;
+/** An HD panorama can be several megabytes. */
+export const HD_TIMEOUT_MS = 30_000;
+/** Panoramax's SD derivative is 2,048 px wide, its thumbnail 500 px. */
+export const SD_WIDTH = 2_048;
+
+/** On-globe credit: licences are per picture, named in the caption. */
+export const PANORAMAX_CREDIT_HTML =
+  'Street Level: imagery © <a href="https://panoramax.fr" target="_blank" rel="noopener">Panoramax</a> contributors, licence per picture';
+
+export const LINE_CLICK_HINT = 'click a line for its nearest photo';
+
+/** Licence ids Panoramax uses, as the caption names them. */
+const LICENSE_LABELS = Object.freeze({
+  'CC-BY-SA-4.0': 'CC BY-SA 4.0',
+  'CC-BY-4.0': 'CC BY 4.0',
+  'CC0-1.0': 'CC0',
+  'etalab-2.0': 'Licence Ouverte 2.0',
+});
+
+/** The caption's licence name for a STAC licence id, or null. */
+export function licenseLabel(license) {
+  if (typeof license !== 'string' || !license.trim()) return null;
+  const id = license.trim();
+  if (id === 'proprietary' || id === 'other') return null;
+  return LICENSE_LABELS[id] || id.slice(0, 40);
+}
+
+/** Deep link to a picture in the Panoramax web viewer. */
+export function panoramaxPictureUrl(pictureId) {
+  const id = String(pictureId ?? '').trim();
+  if (!id) return PANORAMAX_VIEWER;
+  return `${PANORAMAX_VIEWER}#${new URLSearchParams({ pic: id, focus: 'pic' })}`;
+}
+
+/** Epoch ms for a capture time ('2023-12-12T07:54:47+00:00', '2023-12-12 07:56:37+00'), or null. */
+export function panoramaxTimeMs(value) {
+  if (typeof value !== 'string' || !value) return null;
+  // Tile timestamps are Postgres text: a space and an hour-only offset.
+  const iso = /\d[T ]\d/.test(value)
+    ? value
+        .replace(' ', 'T')
+        .replace(/([+-]\d{2})$/, '$1:00')
+        .replace(/\.(\d{3})\d+/, '.$1')
+    : value;
+  const ms = Date.parse(iso);
+  return Number.isFinite(ms) && ms > Date.UTC(1990, 0, 1) ? ms : null;
+}
+
+/** An https address, or null (asset links come from federated instances). */
+function httpsUrl(value) {
+  try {
+    const url = new URL(String(value));
+    return url.protocol === 'https:' ? url.href : null;
+  } catch {
+    return null;
+  }
+}
+
+/** Last path segment of an item's `rel` link: the linked picture's id. */
+function linkedId(item, rel) {
+  const href = item?.links?.find?.((link) => link?.rel === rel)?.href;
+  if (typeof href !== 'string') return null;
+  const id = href.split(/[?#]/)[0].split('/').filter(Boolean).pop();
+  if (!id) return null;
+  try {
+    return decodeURIComponent(id);
+  } catch {
+    // A malformed escape is no link, not a failed lookup.
+    return null;
+  }
+}
+
+/**
+ * An email address anywhere in a name, at any of its '@'s. Linear: names
+ * come from any instance, and each run between '@'s is scanned once.
+ */
+function looksLikeEmail(name) {
+  return /[^\s@]@[^\s@]+\.[^\s@]/.test(name);
+}
+
+/**
+ * Who took the picture. Producers are account names, and some accounts
+ * are named by an email address: those are not repeated in the caption.
+ */
+function creatorOf(item) {
+  const props = item.properties || {};
+  const names = [
+    props['geovisio:producer'],
+    ...(Array.isArray(item.providers)
+      ? item.providers
+          .filter((p) => p?.roles?.includes?.('producer'))
+          .map((p) => p.name)
+      : []),
+  ];
+  // Every producer is credited (an uploading app and its photographer),
+  // each name once, none that is an email address.
+  const credited = [];
+  const seen = new Set();
+  for (const value of names) {
+    if (typeof value !== 'string') continue;
+    const name = value.trim().slice(0, 80);
+    if (!name || looksLikeEmail(value)) continue;
+    const key = name.toLowerCase();
+    if (seen.has(key)) continue;
+    seen.add(key);
+    credited.push(name);
+  }
+  return credited.length ? credited.join(', ').slice(0, 120) : null;
+}
+
+/** The federated instance holding a picture (its `via` link's host), or null. */
+function instanceOf(item) {
+  const href = item?.links?.find?.((link) => link?.rel === 'via')?.href;
+  try {
+    const url = new URL(String(href));
+    return url.protocol === 'https:' ? url.hostname.slice(0, 80) : null;
+  } catch {
+    return null;
+  }
+}
+
+/** A 360° picture: a full-sphere field of view or an equirectangular projection. */
+export function isEquirectangular(item) {
+  const props = item?.properties || {};
+  const orientation = props['pers:interior_orientation'];
+  if (Number(orientation?.field_of_view) >= 360) return true;
+  return props['pers:projection'] === 'equirectangular';
+}
+
+/**
+ * A STAC item (from search or a collection) in the shape the provider and
+ * viewer use, or null without an id or a position.
+ * @returns {{id: string, sequenceId: string|null, lon: number, lat: number, heading: number|null, isPano: boolean, capturedAt: number|null, creator: string|null, license: string|null, width: number|null, prevId: string|null, nextId: string|null, urls: {thumb: string|null, sd: string|null, hd: string|null}}|null}
+ */
+export function normalizeItem(item) {
+  if (!item || item.id == null) return null;
+  // Only numbers: Number(null) and Number('') would put a picture at 0,0.
+  const [lon, lat] = Array.isArray(item.geometry?.coordinates)
+    ? item.geometry.coordinates.map((value) =>
+        typeof value === 'number' ? value : NaN,
+      )
+    : [NaN, NaN];
+  if (!Number.isFinite(lat) || !Number.isFinite(lon)) return null;
+  if (Math.abs(lat) > 90 || Math.abs(lon) > 180) return null;
+  const props = item.properties || {};
+  const assets = item.assets || {};
+  const azimuth =
+    props['view:azimuth'] === '' || props['view:azimuth'] == null
+      ? NaN
+      : Number(props['view:azimuth']);
+  const width = Number(
+    props['pers:interior_orientation']?.sensor_array_dimensions?.[0],
+  );
+  return {
+    id: String(item.id),
+    sequenceId: item.collection != null ? String(item.collection) : null,
+    lon,
+    lat,
+    heading: Number.isFinite(azimuth) ? ((azimuth % 360) + 360) % 360 : null,
+    isPano: isEquirectangular(item),
+    capturedAt: panoramaxTimeMs(props.datetime),
+    creator: creatorOf(item),
+    // Licences ask for the source to be named: where no author can be
+    // named, the caption names the instance holding the picture.
+    via: instanceOf(item),
+    license: licenseLabel(props.license),
+    width: Number.isFinite(width) && width > 0 ? width : null,
+    prevId: linkedId(item, 'prev'),
+    nextId: linkedId(item, 'next'),
+    urls: {
+      thumb: httpsUrl(assets.thumb?.href),
+      sd: httpsUrl(assets.sd?.href),
+      hd: httpsUrl(assets.hd?.href),
+    },
+  };
+}

src/layers/streetLevel/providers/panoramax/policy.test.mjs

@@ -0,0 +1,281 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import {
+  COLORS,
+  PICK_PREFIX,
+  isEquirectangular,
+  licenseLabel,
+  normalizeItem,
+  panoramaxPictureUrl,
+  panoramaxTimeMs,
+} from './policy.js';
+import { PROVIDER_COLORS } from '../../policy.js';
+import { stacItem } from '../../../../testSupport/panoramaxFixtures.mjs';
+
+test('Panoramax draws in its own orange, and every pick id starts pnx:', () => {
+  assert.equal(COLORS.coverage, '#ff6f00');
+  assert.equal(PROVIDER_COLORS.panoramax, '#ff6f00');
+  for (const prefix of Object.values(PICK_PREFIX))
+    assert.ok(prefix.startsWith('pnx:'));
+  // One colour per source.
+  assert.equal(
+    new Set(Object.values(PROVIDER_COLORS)).size,
+    Object.keys(PROVIDER_COLORS).length,
+  );
+});
+
+test('capture times parse in the API’s ISO form, the tiles’ Postgres form, and as bare days', () => {
+  assert.equal(
+    panoramaxTimeMs('2023-12-12T07:54:47+00:00'),
+    Date.UTC(2023, 11, 12, 7, 54, 47),
+  );
+  assert.equal(
+    panoramaxTimeMs('2023-12-12 07:56:37+00'),
+    Date.UTC(2023, 11, 12, 7, 56, 37),
+  );
+  assert.equal(
+    panoramaxTimeMs('2025-08-13 07:45:51.98+00'),
+    Date.UTC(2025, 7, 13, 7, 45, 51, 980),
+  );
+  // Microseconds are cut to what Date.parse reads.
+  assert.equal(
+    panoramaxTimeMs('2025-08-03T14:38:51.838000+00:00'),
+    Date.UTC(2025, 7, 3, 14, 38, 51, 838),
+  );
+  // A sequence's day: its trailing "-11" is the day, not a UTC offset.
+  assert.equal(panoramaxTimeMs('2025-08-11'), Date.UTC(2025, 7, 11));
+  assert.equal(
+    panoramaxTimeMs('2025-08-13 09:00:00+02'),
+    Date.UTC(2025, 7, 13, 7),
+  );
+  for (const bad of ['', 'junk', '1970-01-01', null, 42])
+    assert.equal(panoramaxTimeMs(bad), null, String(bad));
+});
+
+test('a STAC item becomes a picture: position, heading, 360°, licence, links and assets', () => {
+  const photo = normalizeItem(
+    stacItem({
+      id: 'a',
+      lon: 2.35,
+      lat: 48.85,
+      sequenceId: 's',
+      heading: 370,
+      pano: true,
+      license: 'etalab-2.0',
+      prevId: 'p',
+      nextId: 'n',
+    }),
+  );
+  assert.deepEqual(
+    {
+      id: photo.id,
+      sequenceId: photo.sequenceId,
+      lon: photo.lon,
+      lat: photo.lat,
+      heading: photo.heading,
+      isPano: photo.isPano,
+      license: photo.license,
+      width: photo.width,
+      prevId: photo.prevId,
+      nextId: photo.nextId,
+      creator: photo.creator,
+    },
+    {
+      id: 'a',
+      sequenceId: 's',
+      lon: 2.35,
+      lat: 48.85,
+      heading: 10,
+      isPano: true,
+      license: 'Licence Ouverte 2.0',
+      width: 5760,
+      prevId: 'p',
+      nextId: 'n',
+      creator: 'tester',
+    },
+  );
+  assert.equal(
+    photo.urls.sd,
+    'https://panoramax.example.org/pictures/a/sd.jpg',
+  );
+  assert.equal(photo.capturedAt, Date.UTC(2025, 5, 1, 10));
+});
+
+test('a picture without links, heading or a usable position', () => {
+  const bare = normalizeItem({
+    id: 7,
+    geometry: { coordinates: [1, 2] },
+    properties: {},
+  });
+  assert.equal(bare.id, '7');
+  assert.equal(bare.heading, null);
+  assert.equal(bare.prevId, null);
+  assert.equal(bare.nextId, null);
+  assert.equal(bare.sequenceId, null);
+  assert.equal(bare.isPano, false);
+  assert.equal(bare.capturedAt, null);
+  assert.deepEqual(bare.urls, { thumb: null, sd: null, hd: null });
+  for (const item of [
+    null,
+    { geometry: { coordinates: [1, 2] } },
+    { id: 'x', geometry: { coordinates: ['a', 2] } },
+    { id: 'x', geometry: { coordinates: [181, 2] } },
+    { id: 'x', geometry: { coordinates: [1, 91] } },
+    { id: 'x' },
+  ])
+    assert.equal(normalizeItem(item), null, JSON.stringify(item));
+});
+
+test('asset links that are not https are dropped', () => {
+  const item = stacItem({ id: 'a', lon: 1, lat: 2 });
+  item.assets.sd.href = 'http://insecure.example/sd.jpg';
+  item.assets.hd.href = 'javascript:alert(1)';
+  const photo = normalizeItem(item);
+  assert.equal(photo.urls.sd, null);
+  assert.equal(photo.urls.hd, null);
+  assert.ok(photo.urls.thumb.startsWith('https://'));
+});
+
+test('an account named by an email address is not shown as the creator', () => {
+  const named = (producer) =>
+    normalizeItem(stacItem({ id: 'a', lon: 1, lat: 2, producer })).creator;
+  assert.equal(named('[email protected]'), null);
+  assert.equal(named('Robot8A'), 'Robot8A');
+  assert.equal(named('  padded  '), 'padded');
+  assert.equal(named('x'.repeat(200)).length, 80);
+  // The producer role among the providers serves when the property is missing.
+  const item = stacItem({ id: 'a', lon: 1, lat: 2 });
+  delete item.properties['geovisio:producer'];
+  item.providers = [
+    { name: 'host', roles: ['host'] },
+    { name: 'mapper', roles: ['producer'] },
+  ];
+  assert.equal(normalizeItem(item).creator, 'mapper');
+});
+
+test('360°: a full field of view, or the equirectangular projection', () => {
+  assert.equal(
+    isEquirectangular({
+      properties: { 'pers:interior_orientation': { field_of_view: 360 } },
+    }),
+    true,
+  );
+  assert.equal(
+    isEquirectangular({ properties: { 'pers:projection': 'equirectangular' } }),
+    true,
+  );
+  assert.equal(
+    isEquirectangular({
+      properties: { 'pers:interior_orientation': { field_of_view: 92 } },
+    }),
+    false,
+  );
+  assert.equal(isEquirectangular(null), false);
+});
+
+test('licences read as the caption names them', () => {
+  assert.equal(licenseLabel('CC-BY-SA-4.0'), 'CC BY-SA 4.0');
+  assert.equal(licenseLabel('etalab-2.0'), 'Licence Ouverte 2.0');
+  assert.equal(licenseLabel('CC0-1.0'), 'CC0');
+  assert.equal(licenseLabel('ODbL-1.0'), 'ODbL-1.0');
+  assert.equal(licenseLabel('proprietary'), null);
+  assert.equal(licenseLabel(''), null);
+  assert.equal(licenseLabel(undefined), null);
+  assert.equal(licenseLabel('x'.repeat(100)).length, 40);
+});
+
+test('the caption link opens the picture in the Panoramax viewer', () => {
+  assert.equal(
+    panoramaxPictureUrl('d5467bbb-4357'),
+    'https://api.panoramax.xyz/#pic=d5467bbb-4357&focus=pic',
+  );
+  assert.equal(panoramaxPictureUrl(''), 'https://api.panoramax.xyz/');
+  assert.equal(panoramaxPictureUrl(null), 'https://api.panoramax.xyz/');
+  assert.ok(panoramaxPictureUrl('a&b=c').includes('pic=a%26b%3Dc'));
+});
+
+test('hostile item data: a malformed link escape, null coordinates, a huge producer name', () => {
+  const item = stacItem({ id: 'a', lon: 1, lat: 2, nextId: 'n' });
+  item.links.push({
+    rel: 'prev',
+    href: 'https://api.panoramax.xyz/api/collections/s/items/%E0%A4%A',
+  });
+  const photo = normalizeItem(item);
+  assert.equal(photo.prevId, null, 'no link, no throw');
+  assert.equal(photo.nextId, 'n');
+  for (const coordinates of [[null, null], ['', ''], ['2.35', '48.85'], [2.35]])
+    assert.equal(
+      normalizeItem({ id: 'x', geometry: { coordinates } }),
+      null,
+      JSON.stringify(coordinates),
+    );
+  // A million characters without spaces is checked in linear time.
+  const started = Date.now();
+  const huge = normalizeItem(
+    stacItem({ id: 'a', lon: 1, lat: 2, producer: 'a'.repeat(1_000_000) }),
+  );
+  assert.ok(Date.now() - started < 500, `${Date.now() - started} ms`);
+  assert.equal(huge.creator.length, 80);
+  const named = (producer) =>
+    normalizeItem(stacItem({ id: 'a', lon: 1, lat: 2, producer })).creator;
+  assert.equal(named(`${'x'.repeat(200_000)}@example.org`), null);
+  assert.equal(
+    named('Carto@Cité'),
+    'Carto@Cité',
+    'an @ without a domain is a name',
+  );
+  // The address need not follow the first '@'.
+  assert.equal(named('@team [email protected]'), null);
+  assert.equal(named('Carto@Cité ([email protected])'), null);
+  assert.equal(named(`${'@'.repeat(100_000)}x`), `${'@'.repeat(80)}`);
+});
+
+test('thousands of producers are credited in linear time', () => {
+  const item = stacItem({ id: 'a', lon: 1, lat: 2 });
+  item.providers = Array.from({ length: 50_000 }, (_, i) => ({
+    name: `producer-${i}`,
+    roles: ['producer'],
+  }));
+  const started = performance.now();
+  const { creator } = normalizeItem(item);
+  assert.ok(performance.now() - started < 1000);
+  assert.ok(creator.startsWith('tester, producer-0, producer-1'));
+  assert.ok(creator.length <= 120);
+});
+
+test('the instance holding a picture is named (its via host), never as its author', () => {
+  const item = stacItem({
+    id: 'a',
+    lon: 1,
+    lat: 2,
+    producer: '[email protected]',
+  });
+  item.links.push({ rel: 'via', href: 'https://panoramax.ign.fr' });
+  assert.equal(normalizeItem(item).creator, null);
+  assert.equal(normalizeItem(item).via, 'panoramax.ign.fr');
+  item.links.at(-1).href = 'http://insecure.example';
+  assert.equal(normalizeItem(item).via, null);
+  item.links.at(-1).href = 'not a url';
+  assert.equal(normalizeItem(item).via, null);
+});
+
+test('every producer is credited once: the uploading app and its photographer', () => {
+  const item = stacItem({ id: 'a', lon: 1, lat: 2, producer: 'mapcomplete' });
+  item.providers = [
+    { name: 'mapcomplete', roles: ['producer'] },
+    { name: 'pyrog', roles: ['producer'] },
+    { name: 'MapComplete', roles: ['producer'] },
+    { name: '[email protected]', roles: ['producer'] },
+    { name: 'host', roles: ['host'] },
+  ];
+  assert.equal(normalizeItem(item).creator, 'mapcomplete, pyrog');
+  const hidden = stacItem({ id: 'b', lon: 1, lat: 2, producer: '[email protected]' });
+  hidden.providers = [{ name: '[email protected]', roles: ['producer'] }];
+  assert.equal(normalizeItem(hidden).creator, null);
+  const many = stacItem({ id: 'c', lon: 1, lat: 2 });
+  many.providers = Array.from({ length: 50 }, (_, i) => ({
+    name: `producer-${i}`,
+    roles: ['producer'],
+  }));
+  assert.ok(normalizeItem(many).creator.length <= 120);
+});

src/layers/streetLevel/providers/panoramax/source.js

@@ -0,0 +1,306 @@
+import { createLimiter } from '../../limiter.js';
+import { msg } from '../../../../i18n/index.js';
+import {
+  API_CONCURRENCY,
+  API_TIMEOUT_MS,
+  BUSY_BACKOFF_BASE_SEC,
+  MAX_RESPONSE_BYTES,
+  NEAREST_BOX_LIMIT,
+  NEAREST_FOV_TOLERANCE_DEG,
+  NEAREST_LIMIT,
+  NEAREST_RADIUS_M,
+  PANORAMAX_API,
+  PICTURE_TILE_CONCURRENCY,
+  STREAM_IDLE_TIMEOUT_MS,
+  TILE_CONCURRENCY,
+  TILE_TIMEOUT_MS,
+} from './policy.js';
+
+/** Longest wait a Retry-After (or the backoff) asks for. */
+const RETRY_AFTER_MAX_SEC = 300;
+
+/** An HTTP or API failure; `retryAfterSec` is set while Panoramax is busy. */
+export class PanoramaxSourceError extends Error {
+  constructor(message, { status = 0, retryAfterSec = null } = {}) {
+    super(message);
+    this.name = 'PanoramaxSourceError';
+    this.status = status;
+    this.retryAfterSec = retryAfterSec;
+  }
+}
+
+const NO_ANSWER = msg('Panoramax did not answer in time — try again');
+const UNREACHABLE = msg(
+  'Panoramax could not be reached — check the connection',
+);
+
+/**
+ * Seconds from a Retry-After header (delay seconds or an HTTP date), or
+ * null. The meta-catalogue exposes no headers to the browser, so in the
+ * app this is usually null and the caller backs off on its own.
+ */
+export function retryAfterSeconds(response, now = Date.now()) {
+  const header = response.headers?.get?.('retry-after');
+  if (header == null || header === '') return null;
+  let value = Number(header);
+  if (!Number.isFinite(value)) {
+    const at = Date.parse(header);
+    if (!Number.isFinite(at)) return null;
+    value = Math.ceil((at - now) / 1000);
+  }
+  if (value < 0) return null;
+  // A maintenance page's hour must not freeze coverage for an hour.
+  return Math.min(RETRY_AFTER_MAX_SEC, Math.max(1, value));
+}
+
+/**
+ * The body as bytes, refusing more than MAX_RESPONSE_BYTES whatever the
+ * headers say. `onChunk` hears each piece arrive (the idle timeout).
+ */
+async function readBounded(response, onChunk = () => {}) {
+  const tooMuch = () =>
+    new PanoramaxSourceError(msg('Panoramax sent too much data'), {
+      status: response.status,
+    });
+  const length = Number(response.headers?.get?.('content-length'));
+  if (length > MAX_RESPONSE_BYTES) throw tooMuch();
+  const reader = response.body?.getReader?.();
+  if (!reader) {
+    const bytes = new Uint8Array(await response.arrayBuffer());
+    if (bytes.byteLength > MAX_RESPONSE_BYTES) throw tooMuch();
+    return bytes;
+  }
+  const chunks = [];
+  let total = 0;
+  for (;;) {
+    const { done, value } = await reader.read();
+    if (done) break;
+    onChunk();
+    total += value.byteLength;
+    if (total > MAX_RESPONSE_BYTES) {
+      reader.cancel().catch(() => {});
+      throw tooMuch();
+    }
+    chunks.push(value);
+  }
+  const body = new Uint8Array(total);
+  let offset = 0;
+  for (const chunk of chunks) {
+    body.set(chunk, offset);
+    offset += chunk.byteLength;
+  }
+  return body;
+}
+
+/**
+ * Every network path the Panoramax provider uses, browser-side and keyless:
+ * the meta-catalogue allows any origin. Vector tiles for coverage and
+ * cones, STAC search for single pictures and nearest ones.
+ * @param {{fetchImpl?: typeof fetch, api?: string}} [options]
+ */
+export function createPanoramaxSource({
+  fetchImpl = (...args) => globalThis.fetch(...args),
+  api = PANORAMAX_API,
+} = {}) {
+  const root = api.replace(/\/+$/, '');
+  const apiLimiter = createLimiter(API_CONCURRENCY, { lifo: true });
+  const tileLimiter = createLimiter(TILE_CONCURRENCY);
+  // The cones' z15 tiles have their own connection: a selection never
+  // waits behind coverage tiles.
+  const pictureLimiter = createLimiter(PICTURE_TILE_CONCURRENCY, {
+    lifo: true,
+  });
+
+  /** Busy answers in a row with no readable Retry-After (the backoff grows). */
+  let busyStreak = 0;
+
+  /**
+   * GET: its headers within `timeoutMs`, then a body that may take as long
+   * as it keeps arriving (silent for STREAM_IDLE_TIMEOUT_MS is given up).
+   * The caller's abort wins over both.
+   */
+  async function get(url, { signal, timeoutMs, empty = [] }) {
+    const controller = new AbortController();
+    const onAbort = () => controller.abort(signal.reason);
+    if (signal?.aborted) throw signal.reason;
+    signal?.addEventListener('abort', onAbort, { once: true });
+    const giveUp = () => controller.abort(new PanoramaxSourceError(NO_ANSWER));
+    let timer = setTimeout(giveUp, timeoutMs);
+    try {
+      const response = await fetchImpl(url, { signal: controller.signal });
+      if (empty.includes(response.status)) {
+        busyStreak = 0;
+        return null;
+      }
+      if (response.status === 429 || response.status === 503) {
+        const told = retryAfterSeconds(response);
+        // Not told how long: back off, longer each time (5, 10, 20… 300 s).
+        const wait =
+          told ??
+          Math.min(
+            RETRY_AFTER_MAX_SEC,
+            BUSY_BACKOFF_BASE_SEC * 2 ** Math.min(busyStreak, 8),
+          );
+        busyStreak++;
+        throw new PanoramaxSourceError(msg('Panoramax is busy'), {
+          status: response.status,
+          retryAfterSec: wait,
+        });
+      }
+      if (!response.ok)
+        throw new PanoramaxSourceError(
+          `Panoramax answered HTTP ${response.status}`,
+          { status: response.status },
+        );
+      busyStreak = 0;
+      // The answer has begun: from here only silence is timed.
+      clearTimeout(timer);
+      timer = setTimeout(giveUp, STREAM_IDLE_TIMEOUT_MS);
+      return await readBounded(response, () => {
+        clearTimeout(timer);
+        timer = setTimeout(giveUp, STREAM_IDLE_TIMEOUT_MS);
+      });
+    } catch (error) {
+      if (signal?.aborted) throw signal.reason;
+      if (controller.signal.aborted) throw controller.signal.reason;
+      if (error instanceof PanoramaxSourceError) throw error;
+      // Offline, or a CORS or TLS failure: not a timeout, not worth a retry.
+      throw new PanoramaxSourceError(UNREACHABLE);
+    } finally {
+      clearTimeout(timer);
+      signal?.removeEventListener('abort', onAbort);
+    }
+  }
+
+  /**
+   * A STAC search, through the API gate (newest request first). One that
+   * timed out is asked once more: a search is quick once the connection
+   * is free.
+   */
+  async function search(params, { signal } = {}) {
+    const url = `${root}/search?${new URLSearchParams(params)}`;
+    const once = () =>
+      apiLimiter.run(() => get(url, { signal, timeoutMs: API_TIMEOUT_MS }), {
+        signal,
+      });
+    let bytes;
+    try {
+      bytes = await once();
+    } catch (error) {
+      if (signal?.aborted || error?.message !== NO_ANSWER) throw error;
+      bytes = await once();
+    }
+    let payload;
+    try {
+      payload = JSON.parse(new TextDecoder().decode(bytes));
+    } catch {
+      throw new PanoramaxSourceError(
+        msg('Panoramax sent an unreadable answer'),
+      );
+    }
+    return Array.isArray(payload?.features) ? payload.features : [];
+  }
+
+  return {
+    api: root,
+
+    /** Raw vector-tile bytes; an empty array where there is no coverage. */
+    async getTile({ x, y, z }, { signal, lane = 'coverage' } = {}) {
+      const url = `${root}/map/${z}/${x}/${y}.mvt`;
+      const gate = lane === 'pictures' ? pictureLimiter : tileLimiter;
+      const bytes = await gate.run(
+        () =>
+          get(url, { signal, timeoutMs: TILE_TIMEOUT_MS, empty: [204, 404] }),
+        { signal },
+      );
+      return bytes ?? new Uint8Array(0);
+    },
+
+    /** One picture (a STAC item) by id, or null. */
+    async getItem(id, { signal } = {}) {
+      const [item] = await search({ ids: String(id), limit: '1' }, { signal });
+      return item && String(item.id) === String(id) ? item : null;
+    },
+
+    /**
+     * Pictures within `radius` metres of a point, unranked: the caller ranks
+     * them by distance. Two searches side by side, since neither finds them
+     * all: `place_position` (nearest first) leaves out pictures looking
+     * away from the point, whatever the tolerance; a bounding box has them,
+     * roughly nearest first (not exactly: the caller ranks the union).
+     * `collections` keeps one sequence's, `pano` and `sinceMs` filter as
+     * the imagery filter does.
+     */
+    async nearestItems(
+      {
+        lat,
+        lon,
+        radius = NEAREST_RADIUS_M,
+        limit = NEAREST_LIMIT,
+        collections = null,
+        pano = 'all',
+        sinceMs = null,
+      },
+      { signal } = {},
+    ) {
+      const metres = Math.min(1000, Math.max(1, Math.round(radius)));
+      const shared = {};
+      if (collections) shared.collections = String(collections);
+      if (pano === 'pano') shared.filter = 'field_of_view=360';
+      else if (pano === 'flat') shared.filter = 'field_of_view<360';
+      if (Number.isFinite(sinceMs) && sinceMs > 0)
+        shared.datetime = `${new Date(sinceMs).toISOString()}/..`;
+      const dLat = metres / 111_320;
+      const dLon =
+        metres / (111_320 * Math.max(0.01, Math.cos((lat * Math.PI) / 180)));
+      // Clamped to the map: the API finds nothing in a box past ±180°.
+      const box = [
+        Math.max(-180, lon - dLon),
+        Math.max(-90, lat - dLat),
+        Math.min(180, lon + dLon),
+        Math.min(90, lat + dLat),
+      ].map((v) => v.toFixed(7));
+      // One search failing (busy, no answer) leaves the other's pictures;
+      // only both failing fails the lookup. The caller's abort stops both.
+      const both = new AbortController();
+      const onAbort = () => both.abort(signal.reason);
+      if (signal?.aborted) throw signal.reason;
+      signal?.addEventListener('abort', onAbort, { once: true });
+      const run = (params) =>
+        search(params, { signal: both.signal }).catch((error) => {
+          if (!both.signal.aborted && !signal?.aborted) failures.push(error);
+          throw error;
+        });
+      const failures = [];
+      let settled;
+      try {
+        settled = await Promise.allSettled([
+          run({
+            place_position: `${Number(lon).toFixed(7)},${Number(lat).toFixed(7)}`,
+            place_distance: `0-${metres}`,
+            place_fov_tolerance: String(NEAREST_FOV_TOLERANCE_DEG),
+            limit: String(Math.min(100, Math.max(1, limit))),
+            ...shared,
+          }),
+          run({
+            bbox: box.join(','),
+            limit: String(NEAREST_BOX_LIMIT),
+            ...shared,
+          }),
+        ]);
+      } finally {
+        signal?.removeEventListener('abort', onAbort);
+      }
+      if (signal?.aborted) throw signal.reason;
+      const found = settled
+        .filter((result) => result.status === 'fulfilled')
+        .map((result) => result.value);
+      if (!found.length) throw failures[0] ?? settled[0].reason;
+      const byId = new Map();
+      for (const item of found.flat())
+        if (item?.id != null && !byId.has(String(item.id)))
+          byId.set(String(item.id), item);
+      return [...byId.values()];
+    },
+  };
+}

src/layers/streetLevel/providers/panoramax/source.test.mjs

@@ -0,0 +1,513 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import {
+  PanoramaxSourceError,
+  createPanoramaxSource,
+  retryAfterSeconds,
+} from './source.js';
+import {
+  MAX_RESPONSE_BYTES,
+  NEAREST_BOX_LIMIT,
+  STREAM_IDLE_TIMEOUT_MS,
+  TILE_TIMEOUT_MS,
+} from './policy.js';
+
+/** A fetch answering from `respond(url)`, recording every URL asked. */
+function fakeFetch(respond) {
+  const urls = [];
+  const fetchImpl = async (url, { signal } = {}) => {
+    urls.push(url);
+    const answer = await respond(url, signal);
+    if (answer instanceof Response) return answer;
+    const { status = 200, body = '', headers = {} } = answer;
+    return new Response(status === 204 ? null : body, { status, headers });
+  };
+  return { urls, fetchImpl };
+}
+
+const json = (value) => ({ body: JSON.stringify(value) });
+
+test('a tile is the raw vector-tile bytes; 204 and 404 mean no coverage', async () => {
+  const { urls, fetchImpl } = fakeFetch((url) =>
+    url.includes('/14/')
+      ? { body: new Uint8Array([1, 2, 3]) }
+      : { status: 204 },
+  );
+  const source = createPanoramaxSource({ fetchImpl });
+  assert.deepEqual(
+    [...(await source.getTile({ x: 8299, y: 5634, z: 14 }))],
+    [1, 2, 3],
+  );
+  assert.equal(urls[0], 'https://api.panoramax.xyz/api/map/14/8299/5634.mvt');
+  assert.equal((await source.getTile({ x: 1, y: 1, z: 13 })).length, 0);
+  const missing = createPanoramaxSource({
+    fetchImpl: fakeFetch(() => ({ status: 404 })).fetchImpl,
+  });
+  assert.equal((await missing.getTile({ x: 1, y: 1, z: 13 })).length, 0);
+});
+
+test('a busy API says so and when to come back; other failures name the status', async () => {
+  const busy = createPanoramaxSource({
+    fetchImpl: fakeFetch(() => ({
+      status: 429,
+      headers: { 'retry-after': '12' },
+    })).fetchImpl,
+  });
+  await assert.rejects(busy.getTile({ x: 0, y: 0, z: 0 }), (error) => {
+    assert.ok(error instanceof PanoramaxSourceError);
+    assert.equal(error.status, 429);
+    assert.equal(error.retryAfterSec, 12);
+    return true;
+  });
+  const down = createPanoramaxSource({
+    fetchImpl: fakeFetch(() => ({ status: 503 })).fetchImpl,
+  });
+  await assert.rejects(down.getTile({ x: 0, y: 0, z: 0 }), (error) => {
+    assert.equal(error.retryAfterSec, 5, 'a default wait without the header');
+    return true;
+  });
+  const broken = createPanoramaxSource({
+    fetchImpl: fakeFetch(() => ({ status: 500 })).fetchImpl,
+  });
+  await assert.rejects(broken.getItem('x'), /HTTP 500/);
+});
+
+test('an oversized answer is refused while it streams', async () => {
+  let pulled = 0;
+  const huge = new ReadableStream({
+    pull(controller) {
+      pulled++;
+      controller.enqueue(new Uint8Array(4 * 1024 * 1024));
+    },
+  });
+  const source = createPanoramaxSource({
+    fetchImpl: async () => new Response(huge, { status: 200 }),
+  });
+  await assert.rejects(source.getTile({ x: 0, y: 0, z: 0 }), /too much data/);
+  assert.ok(pulled * 4 * 1024 * 1024 <= MAX_RESPONSE_BYTES + 8 * 1024 * 1024);
+  // A declared length over the cap is refused before reading.
+  const declared = createPanoramaxSource({
+    fetchImpl: fakeFetch(() => ({
+      body: 'x',
+      headers: { 'content-length': String(MAX_RESPONSE_BYTES + 1) },
+    })).fetchImpl,
+  });
+  await assert.rejects(declared.getItem('a'), /too much data/);
+});
+
+test('a picture by id is a STAC search; another id in the answer is not taken for it', async () => {
+  const { urls, fetchImpl } = fakeFetch((url) =>
+    url.includes('ids=good')
+      ? json({ features: [{ id: 'good' }] })
+      : json({ features: [{ id: 'other' }] }),
+  );
+  const source = createPanoramaxSource({ fetchImpl });
+  assert.deepEqual(await source.getItem('good'), { id: 'good' });
+  assert.equal(await source.getItem('bad'), null);
+  const asked = new URL(urls[0]);
+  assert.equal(asked.pathname, '/api/search');
+  assert.equal(asked.searchParams.get('ids'), 'good');
+  assert.equal(asked.searchParams.get('limit'), '1');
+});
+
+test('nearest pictures: a place search and a box search side by side, both filtered as the imagery filter asks', async () => {
+  const { urls, fetchImpl } = fakeFetch(() => json({ features: [] }));
+  const source = createPanoramaxSource({ fetchImpl });
+  await source.nearestItems({ lat: 48.85, lon: 2.35 });
+  await source.nearestItems({
+    lat: 48.85,
+    lon: 2.35,
+    collections: 'seq',
+    pano: 'pano',
+    sinceMs: Date.UTC(2025, 0, 1),
+    radius: 5000,
+    limit: 500,
+  });
+  await source.nearestItems({ lat: 48.85, lon: 2.35, pano: 'flat' });
+  const asked = urls.map((u) => new URL(u).searchParams);
+  assert.equal(asked.length, 6, 'two searches a lookup');
+  const place = asked.filter((q) => q.has('place_position'));
+  const box = asked.filter((q) => q.has('bbox'));
+  assert.equal(place.length, 3);
+  assert.equal(box.length, 3);
+  const [plain, filtered, flat] = place;
+  assert.equal(plain.get('place_position'), '2.3500000,48.8500000');
+  assert.equal(plain.get('place_distance'), '0-50');
+  assert.equal(plain.get('place_fov_tolerance'), '180');
+  assert.equal(plain.get('collections'), null);
+  assert.equal(plain.get('filter'), null);
+  assert.equal(plain.get('datetime'), null);
+  assert.equal(filtered.get('collections'), 'seq');
+  assert.equal(filtered.get('filter'), 'field_of_view=360');
+  assert.equal(filtered.get('datetime'), '2025-01-01T00:00:00.000Z/..');
+  assert.equal(filtered.get('place_distance'), '0-1000', 'capped');
+  assert.equal(filtered.get('limit'), '100', 'capped');
+  assert.equal(flat.get('filter'), 'field_of_view<360');
+  // The box spans the radius each way, and carries the same filters.
+  const [w, s, e, n] = box[0].get('bbox').split(',').map(Number);
+  assert.ok(Math.abs((n - s) * 111_320 - 100) < 1, `${n - s}°`);
+  assert.ok(
+    Math.abs((e - w) * 111_320 * Math.cos((48.85 * Math.PI) / 180) - 100) < 1,
+  );
+  assert.equal(box[1].get('collections'), 'seq');
+  assert.equal(box[1].get('filter'), 'field_of_view=360');
+  assert.equal(box[1].get('datetime'), '2025-01-01T00:00:00.000Z/..');
+  assert.equal(box[2].get('filter'), 'field_of_view<360');
+});
+
+test('a picture both searches find is listed once', async () => {
+  const source = createPanoramaxSource({
+    fetchImpl: fakeFetch((url) =>
+      url.includes('bbox')
+        ? json({ features: [{ id: 'b' }, { id: 'a' }, { id: null }] })
+        : json({ features: [{ id: 'a' }] }),
+    ).fetchImpl,
+  });
+  const items = await source.nearestItems({ lat: 1, lon: 2 });
+  assert.deepEqual(
+    items.map((i) => i.id),
+    ['a', 'b'],
+  );
+});
+
+test('the newest search goes first when the API gate is full', async () => {
+  const waiting = [];
+  const order = [];
+  const source = createPanoramaxSource({
+    fetchImpl: async (url) => {
+      order.push(new URL(url).searchParams.get('ids'));
+      await new Promise((resolve) => waiting.push(resolve));
+      return new Response(JSON.stringify({ features: [] }));
+    },
+  });
+  const all = ['1', '2', '3', '4', '5', '6'].map((id) => source.getItem(id));
+  await new Promise((resolve) => setTimeout(resolve, 0));
+  assert.deepEqual(order, ['1', '2'], 'two at once');
+  waiting.shift()();
+  await new Promise((resolve) => setTimeout(resolve, 0));
+  assert.equal(order.at(-1), '6', 'the latest waiting one next');
+  let done = false;
+  Promise.allSettled(all).then(() => (done = true));
+  while (!done) {
+    waiting.splice(0).forEach((go) => go());
+    await new Promise((resolve) => setTimeout(resolve, 0));
+  }
+});
+
+test('an unreadable search answer, or one with no features, is handled', async () => {
+  const garbled = createPanoramaxSource({
+    fetchImpl: fakeFetch(() => ({ body: '<html>' })).fetchImpl,
+  });
+  await assert.rejects(garbled.getItem('a'), /unreadable/);
+  const empty = createPanoramaxSource({
+    fetchImpl: fakeFetch(() => json({ type: 'FeatureCollection' })).fetchImpl,
+  });
+  assert.deepEqual(await empty.nearestItems({ lat: 0, lon: 0 }), []);
+});
+
+test('the caller’s abort wins; a silent API times out with a readable message', async (t) => {
+  t.mock.timers.enable({ apis: ['setTimeout'] });
+  const hang = (url, signal) =>
+    new Promise((_, reject) =>
+      signal.addEventListener('abort', () => reject(signal.reason)),
+    );
+  const source = createPanoramaxSource({
+    fetchImpl: fakeFetch(hang).fetchImpl,
+  });
+  const controller = new AbortController();
+  const asked = source.getItem('a', { signal: controller.signal });
+  await Promise.resolve();
+  controller.abort(new Error('overtaken'));
+  await assert.rejects(asked, /overtaken/);
+  const slow = source.getTile({ x: 0, y: 0, z: 0 });
+  // Let the request start before the clock runs out.
+  for (let i = 0; i < 5; i++) await Promise.resolve();
+  t.mock.timers.tick(60_000);
+  await assert.rejects(slow, /did not answer in time/);
+});
+
+test('a network failure reads as unreachable, not as a stack trace', async () => {
+  const source = createPanoramaxSource({
+    fetchImpl: async () => {
+      throw new TypeError('Failed to fetch');
+    },
+  });
+  await assert.rejects(source.getTile({ x: 0, y: 0, z: 0 }), (error) => {
+    assert.ok(error instanceof PanoramaxSourceError);
+    assert.match(error.message, /could not be reached/);
+    return true;
+  });
+});
+
+test('a search that timed out is asked once more; a second timeout is reported', async (t) => {
+  t.mock.timers.enable({ apis: ['setTimeout'] });
+  let calls = 0;
+  const hang = (signal) =>
+    new Promise((_, reject) =>
+      signal.addEventListener('abort', () => reject(signal.reason)),
+    );
+  const source = createPanoramaxSource({
+    fetchImpl: async (url, { signal }) => {
+      calls++;
+      if (calls === 1) return hang(signal);
+      return new Response(JSON.stringify({ features: [{ id: 'a' }] }));
+    },
+  });
+  const asked = source.getItem('a');
+  for (let i = 0; i < 5; i++) await Promise.resolve();
+  t.mock.timers.tick(60_000);
+  assert.deepEqual(await asked, { id: 'a' });
+  assert.equal(calls, 2);
+  const stuck = createPanoramaxSource({
+    fetchImpl: async (url, { signal }) => hang(signal),
+  });
+  const never = stuck.getItem('b');
+  for (let round = 0; round < 2; round++) {
+    for (let i = 0; i < 10; i++) await Promise.resolve();
+    t.mock.timers.tick(60_000);
+  }
+  await assert.rejects(never, /did not answer in time/);
+});
+
+test('the HTTP/1.1 API never gets more than five requests at once: three tiles, two searches', async () => {
+  const { API_CONCURRENCY, TILE_CONCURRENCY } = await import('./policy.js');
+  assert.ok(API_CONCURRENCY + TILE_CONCURRENCY <= 5);
+  let open = 0;
+  let most = 0;
+  const waiting = [];
+  const source = createPanoramaxSource({
+    fetchImpl: async (url) => {
+      open++;
+      most = Math.max(most, open);
+      await new Promise((resolve) => waiting.push(resolve));
+      open--;
+      return url.includes('/map/')
+        ? new Response(null, { status: 204 })
+        : new Response(JSON.stringify({ features: [] }));
+    },
+  });
+  const all = [
+    ...Array.from({ length: 8 }, (_, i) =>
+      source.getTile({ x: i, y: 0, z: 14 }),
+    ),
+    ...Array.from({ length: 4 }, (_, i) => source.getItem(String(i))),
+  ];
+  await new Promise((resolve) => setTimeout(resolve, 0));
+  assert.equal(most, 5);
+  let done = false;
+  Promise.allSettled(all).then(() => (done = true));
+  while (!done) {
+    waiting.splice(0).forEach((go) => go());
+    await new Promise((resolve) => setTimeout(resolve, 0));
+  }
+  assert.equal(most, 5, 'never more');
+});
+
+test('one of the two nearest searches failing leaves the other’s pictures; both failing fails the lookup', async () => {
+  const half = createPanoramaxSource({
+    fetchImpl: fakeFetch((url) =>
+      url.includes('bbox')
+        ? { status: 503 }
+        : json({ features: [{ id: 'facing' }] }),
+    ).fetchImpl,
+  });
+  assert.deepEqual(
+    (await half.nearestItems({ lat: 1, lon: 2 })).map((i) => i.id),
+    ['facing'],
+  );
+  const none = createPanoramaxSource({
+    fetchImpl: fakeFetch(() => ({ status: 503 })).fetchImpl,
+  });
+  await assert.rejects(none.nearestItems({ lat: 1, lon: 2 }), /busy/);
+});
+
+test('only a timeout is asked again: a busy or failing API is asked once, an unreachable one says so', async () => {
+  for (const status of [429, 500, 503]) {
+    const { urls, fetchImpl } = fakeFetch(() => ({ status }));
+    const source = createPanoramaxSource({ fetchImpl });
+    await assert.rejects(source.getItem('a'));
+    assert.equal(urls.length, 1, `HTTP ${status}: one fetch`);
+  }
+  let calls = 0;
+  const offline = createPanoramaxSource({
+    fetchImpl: async () => {
+      calls++;
+      throw new TypeError('Failed to fetch');
+    },
+  });
+  await assert.rejects(offline.getItem('a'), /could not be reached/);
+  assert.equal(calls, 1, 'not retried');
+});
+
+test('a Retry-After is honoured up to five minutes', async () => {
+  const wait = async (header) => {
+    const source = createPanoramaxSource({
+      fetchImpl: fakeFetch(() => ({
+        status: 503,
+        headers: { 'retry-after': header },
+      })).fetchImpl,
+    });
+    return source
+      .getTile({ x: 0, y: 0, z: 0 })
+      .catch((error) => error.retryAfterSec);
+  };
+  assert.equal(await wait('3600'), 300);
+  assert.equal(await wait('99999999999'), 300);
+  assert.equal(await wait('0'), 1);
+  assert.equal(await wait('12'), 12);
+});
+
+test('a Retry-After may be an HTTP date', () => {
+  const now = Date.parse('2026-10-15T12:00:00Z');
+  const response = (value) =>
+    new Response(null, { status: 429, headers: { 'retry-after': value } });
+  assert.equal(
+    retryAfterSeconds(response('Thu, 15 Oct 2026 12:01:00 GMT'), now),
+    60,
+  );
+  assert.equal(
+    retryAfterSeconds(response('Thu, 15 Oct 2026 14:00:00 GMT'), now),
+    300,
+  );
+  assert.equal(
+    retryAfterSeconds(response('Thu, 15 Oct 2026 11:00:00 GMT'), now),
+    null,
+    'a date already past',
+  );
+  assert.equal(retryAfterSeconds(response('soon'), now), null);
+  assert.equal(
+    retryAfterSeconds(new Response(null, { status: 429 }), now),
+    null,
+  );
+});
+
+test('busy without a readable Retry-After (the browser hides it): the wait doubles, and resets once answered', async () => {
+  let busy = true;
+  const source = createPanoramaxSource({
+    fetchImpl: fakeFetch(() =>
+      busy ? { status: 429 } : { body: new Uint8Array([1]) },
+    ).fetchImpl,
+  });
+  const wait = () =>
+    source.getTile({ x: 0, y: 0, z: 0 }).then(
+      () => 'ok',
+      (error) => error.retryAfterSec,
+    );
+  const waits = [];
+  for (let i = 0; i < 9; i++) waits.push(await wait());
+  assert.deepEqual(waits, [5, 10, 20, 40, 80, 160, 300, 300, 300]);
+  busy = false;
+  assert.equal(await wait(), 'ok');
+  busy = true;
+  assert.equal(await wait(), 5, 'back to the first wait');
+});
+
+test(
+  'a body that keeps arriving is not cut off by the request timeout; one that stalls is',
+  { timeout: 10_000 },
+  async (t) => {
+    t.mock.timers.enable({ apis: ['setTimeout'] });
+    const settle = async () => {
+      for (let i = 0; i < 20; i++) await Promise.resolve();
+    };
+    // Headers at once, then a chunk every 10 s for twice the tile timeout.
+    const chunks = Math.ceil((2 * TILE_TIMEOUT_MS) / 10_000);
+    let push;
+    const slowBody = (signal) =>
+      new Response(
+        new ReadableStream({
+          start(controller) {
+            push = (last) => {
+              controller.enqueue(new Uint8Array([7]));
+              if (last) controller.close();
+            };
+            signal.addEventListener('abort', () =>
+              controller.error(signal.reason),
+            );
+          },
+        }),
+        { status: 200 },
+      );
+    const source = createPanoramaxSource({
+      fetchImpl: async (url, { signal }) => slowBody(signal),
+    });
+    const slow = source.getTile({ x: 0, y: 0, z: 0 });
+    await settle();
+    for (let i = 1; i <= chunks; i++) {
+      t.mock.timers.tick(10_000);
+      push(i === chunks);
+      await settle();
+    }
+    assert.equal((await slow).length, chunks, 'every chunk read');
+    const stalled = source.getTile({ x: 0, y: 0, z: 0 });
+    await settle();
+    push(false);
+    await settle();
+    t.mock.timers.tick(STREAM_IDLE_TIMEOUT_MS);
+    await assert.rejects(stalled, /did not answer in time/);
+  },
+);
+
+test('the box search asks for a few pictures: the API returns them nearest first', async () => {
+  const { urls, fetchImpl } = fakeFetch(() => json({ features: [] }));
+  const source = createPanoramaxSource({ fetchImpl });
+  await source.nearestItems({ lon: 2.35, lat: 48.85 });
+  const box = urls
+    .map((url) => new URL(url))
+    .find((url) => url.searchParams.has('bbox'));
+  assert.ok(box, 'a box search');
+  assert.equal(box.searchParams.get('limit'), String(NEAREST_BOX_LIMIT));
+  assert.ok(NEAREST_BOX_LIMIT <= 20);
+});
+
+test('the cones’ tiles have their own connection: never behind coverage tiles, the newest first', async () => {
+  const { PICTURE_TILE_CONCURRENCY, TILE_CONCURRENCY } =
+    await import('./policy.js');
+  assert.equal(PICTURE_TILE_CONCURRENCY, 1);
+  const held = new Map();
+  const asked = [];
+  const source = createPanoramaxSource({
+    fetchImpl: (url) => {
+      asked.push(url.replace(/^.*\/map\//, ''));
+      return new Promise((resolve) =>
+        held.set(url.replace(/^.*\/map\//, ''), () =>
+          resolve(new Response(null, { status: 204 })),
+        ),
+      );
+    },
+  });
+  const settle = () => new Promise((resolve) => setTimeout(resolve, 0));
+  // Coverage fills its lane and queues.
+  const coverage = Array.from({ length: TILE_CONCURRENCY + 2 }, (_, i) =>
+    source.getTile({ x: i, y: 0, z: 10 }),
+  );
+  await settle();
+  assert.equal(asked.length, TILE_CONCURRENCY);
+  // A cone tile goes at once; two more wait, the newer first.
+  const pictures = [1, 2, 3].map((x) =>
+    source.getTile({ x, y: 9, z: 15 }, { lane: 'pictures' }),
+  );
+  await settle();
+  assert.deepEqual(asked.slice(TILE_CONCURRENCY), ['15/1/9.mvt']);
+  held.get('15/1/9.mvt')();
+  await settle();
+  assert.deepEqual(asked.slice(TILE_CONCURRENCY), ['15/1/9.mvt', '15/3/9.mvt']);
+  for (let round = 0; round < 6; round++) {
+    for (const go of held.values()) go();
+    await settle();
+  }
+  await Promise.all([...coverage, ...pictures]);
+});
+
+test('a lookup near the antimeridian keeps its box on the map', async () => {
+  const { urls, fetchImpl } = fakeFetch(() => json({ features: [] }));
+  const source = createPanoramaxSource({ fetchImpl });
+  await source.nearestItems({ lat: -16, lon: 179.9999 });
+  const box = urls
+    .map((u) => new URL(u).searchParams.get('bbox'))
+    .find(Boolean)
+    .split(',')
+    .map(Number);
+  assert.equal(box[2], 180);
+  assert.ok(box[0] < 180);
+});

src/layers/streetLevel/providers/panoramax/viewer.js

@@ -0,0 +1,97 @@
+import {
+  PANO_FULL_SIZE,
+  createPhotoViewer,
+  loadImage,
+} from '../../photoViewer.js';
+import {
+  HD_TIMEOUT_MS,
+  PANORAMAX_NAME,
+  PANORAMAX_PROVIDER_ID,
+  PANO_HD_MAX_WIDTH,
+  SD_WIDTH,
+  panoramaxPictureUrl,
+} from './policy.js';
+
+/** An HD original small enough to decode (its width is known and under the cap). */
+function hdDecodable(photo) {
+  return Boolean(
+    photo.urls.hd && photo.width && photo.width <= PANO_HD_MAX_WIDTH,
+  );
+}
+
+/**
+ * Where Panoramax pictures come from: the instance holding each one serves
+ * a 2,048 px SD derivative (equirectangular for a 360° picture) and the HD
+ * original. SD shows first; HD only once the viewer is wide enough to use
+ * it. A 360° original is shrunk to the texture size while it decodes.
+ * @type {import('../../photoViewer.js').PhotoSources}
+ */
+export const PANORAMAX_SOURCES = Object.freeze({
+  hasPano: (photo) =>
+    Boolean(photo.isPano && (photo.urls.sd || hdDecodable(photo))),
+  // Without an SD derivative the original goes straight to the texture size.
+  panoFirst: (photo) => {
+    // Decoded at SD's own size, whatever the host actually serves.
+    if (photo.urls.sd)
+      return {
+        url: photo.urls.sd,
+        width: SD_WIDTH,
+        resize: [SD_WIDTH, SD_WIDTH / 2],
+      };
+    if (!hdDecodable(photo)) return null;
+    const width = Math.min(photo.width, PANO_FULL_SIZE[0]);
+    return { url: photo.urls.hd, width, resize: [width, width / 2] };
+  },
+  // The original is several megabytes with no server to shrink it: only
+  // for the expanded viewer (a docked one on a dense screen asks too).
+  panoSharp: (photo, size, { expanded = false } = {}) => {
+    const width = photo.width || 0;
+    if (!expanded || !photo.urls.hd || !photo.urls.sd) return null;
+    // An original no wider than the SD one adds nothing; a huge one would
+    // take hundreds of megabytes to decode.
+    if (width <= SD_WIDTH || width > PANO_HD_MAX_WIDTH) return null;
+    const target = Math.min(size[0], width);
+    return {
+      url: photo.urls.hd,
+      resize: [target, target / 2],
+      timeoutMs: HD_TIMEOUT_MS,
+    };
+  },
+  // A 360° picture shown flat (no WebGL) is its whole equirectangular image.
+  // When SD fails the thumbnail stands in; the original (megabytes) only
+  // for the expanded viewer, and only one of a size it may decode.
+  flatFirst: (photo, { expanded = false } = {}) => [
+    photo.urls.sd,
+    expanded && hdDecodable(photo) ? photo.urls.hd : null,
+    photo.urls.thumb,
+  ],
+  // The original once the viewer is wider than SD, if its width is known
+  // and decodable (a 200 MP phone photo is 16,000 px across).
+  flatSharp: (photo, pixels) =>
+    photo.urls.sd && hdDecodable(photo) && pixels > SD_WIDTH
+      ? photo.urls.hd
+      : null,
+  describe: (photo) => ({
+    // Where no author can be named, the instance holding the photo is.
+    title: !photo.creator && photo.via ? `via ${photo.via}` : null,
+    creator: photo.creator,
+    license: photo.license,
+    externalUrl: panoramaxPictureUrl(photo.id),
+  }),
+});
+
+/**
+ * Viewer adapter for Panoramax pictures: flat in an <img>, 360° on the
+ * shared WebGL panorama, ‹ › along the sequence (photoViewer.js).
+ * @param {object} options   See photoViewer.js `createPhotoViewer`.
+ * @returns {import('../../registry.js').ViewerAdapter}
+ */
+export function createPanoramaxViewer({ load = loadImage, ...options }) {
+  return createPhotoViewer({
+    providerId: PANORAMAX_PROVIDER_ID,
+    name: PANORAMAX_NAME,
+    sources: PANORAMAX_SOURCES,
+    load,
+    ...options,
+  });
+}

src/layers/streetLevel/providers/panoramax/viewer.test.mjs

@@ -0,0 +1,341 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import { PANORAMAX_SOURCES, createPanoramaxViewer } from './viewer.js';
+import { normalizeItem } from './policy.js';
+import { fakeHost, until } from '../../../../testSupport/kartaViewFakes.mjs';
+import { stacItem } from '../../../../testSupport/panoramaxFixtures.mjs';
+
+const photo = (options) =>
+  normalizeItem(stacItem({ lon: 2.35, lat: 48.85, ...options }));
+
+const PHOTOS = {
+  flat: photo({ id: 'flat', prevId: 'p0', nextId: 'flat2', heading: 30 }),
+  flat2: photo({ id: 'flat2', prevId: 'flat', heading: 40 }),
+  pano: photo({ id: 'pano', pano: true, heading: 100, width: 5760 }),
+  bigPano: photo({ id: 'bigPano', pano: true, width: 11_000 }),
+  smallPano: photo({ id: 'smallPano', pano: true, width: 2048 }),
+  email: photo({ id: 'email', producer: '[email protected]' }),
+};
+
+function fakeRenderer() {
+  const view = { yaw: 0, pitch: 0, fov: 80 };
+  const images = [];
+  return {
+    images,
+    setImage: (image) => images.push(image),
+    setView(next) {
+      Object.assign(view, next);
+    },
+    getView: () => ({ ...view }),
+    resize() {},
+    clear() {},
+    destroy() {},
+  };
+}
+
+function setup() {
+  const loads = [];
+  const renderers = [];
+  const stepped = [];
+  const viewer = createPanoramaxViewer({
+    getPhoto: async (id) => {
+      if (!PHOTOS[id]) throw new Error('no such picture');
+      return PHOTOS[id];
+    },
+    step: async (from, delta) => (delta < 0 ? from.prevId : from.nextId),
+    onStep: (id) => {
+      stepped.push(id);
+      viewer.open(id).catch(() => {});
+    },
+    load: async (url, options) => {
+      loads.push({ url, ...options });
+      return { src: url, width: 1, height: 1 };
+    },
+    createRenderer: () => {
+      const renderer = fakeRenderer();
+      renderers.push(renderer);
+      return renderer;
+    },
+  });
+  const poses = [];
+  viewer.onPose((pose) => poses.push(pose));
+  return { viewer, poses, loads, renderers, stepped, host: fakeHost() };
+}
+
+const parts = (host) => {
+  const root = host.children[0];
+  const [picture, canvas, prev, next] = root.children;
+  return { root, picture, canvas, prev, next };
+};
+
+test('a flat picture shows its SD version with author, licence and a Panoramax link', async () => {
+  const { viewer, poses, loads, host } = setup();
+  await viewer.mount(host);
+  const { root, picture, canvas } = parts(host);
+  assert.equal(root.dataset.provider, 'panoramax', 'its colour in the CSS');
+  assert.match(root.attributes['aria-label'], /^Panoramax photo/);
+  await viewer.open('flat');
+  assert.equal(picture.hidden, false);
+  assert.equal(canvas.hidden, true);
+  assert.equal(
+    picture.src,
+    'https://panoramax.example.org/pictures/flat/sd.jpg',
+  );
+  assert.deepEqual(
+    loads.map((l) => l.url),
+    [PHOTOS.flat.urls.sd],
+  );
+  const pose = poses.at(-1);
+  assert.equal(pose.providerId, 'panoramax');
+  assert.equal(pose.bearing, 30);
+  assert.equal(pose.isPano, false);
+  assert.equal(pose.creator, 'tester');
+  assert.equal(pose.license, 'CC BY-SA 4.0');
+  assert.equal(pose.sequenceId, 'seq-1');
+  assert.equal(
+    pose.externalUrl,
+    'https://api.panoramax.xyz/#pic=flat&focus=pic',
+  );
+  assert.equal(viewer.supportsRenderModes(), true);
+});
+
+test('no creator in the caption for an account named by an email address', async () => {
+  const { viewer, poses, host } = setup();
+  await viewer.mount(host);
+  await viewer.open('email');
+  assert.equal(poses.at(-1).creator, null);
+});
+
+test('HD replaces SD only once the viewer is wide enough to use it', async (t) => {
+  const { viewer, loads, host } = setup();
+  await viewer.mount(host);
+  const { picture, root } = parts(host);
+  t.after(() => delete globalThis.devicePixelRatio);
+  globalThis.devicePixelRatio = 1;
+  picture.clientWidth = 400;
+  await viewer.open('flat');
+  await new Promise((resolve) => setTimeout(resolve, 0));
+  assert.equal(loads.length, 1, 'docked: SD is sharp enough');
+  // EXPAND on a wide screen.
+  picture.clientWidth = root.clientWidth = 2600;
+  viewer.resize();
+  assert.ok(await until(() => picture.src === PHOTOS.flat.urls.hd));
+  viewer.resize();
+  await new Promise((resolve) => setTimeout(resolve, 0));
+  assert.equal(
+    loads.filter((l) => l.url === PHOTOS.flat.urls.hd).length,
+    1,
+    'asked once',
+  );
+});
+
+test('a 360° picture shows its SD equirectangular image, then HD shrunk to 4,096 when expanded', async (t) => {
+  const { viewer, poses, loads, renderers, host } = setup();
+  await viewer.mount(host);
+  const { canvas, picture } = parts(host);
+  t.after(() => delete globalThis.devicePixelRatio);
+  globalThis.devicePixelRatio = 1;
+  canvas.clientWidth = 400;
+  await viewer.open('pano');
+  assert.equal(canvas.hidden, false);
+  assert.equal(picture.hidden, true);
+  assert.equal(viewer.supportsRenderModes(), false, 'no frame to fit');
+  const { signal, ...first } = loads[0];
+  assert.deepEqual(first, {
+    url: PHOTOS.pano.urls.sd,
+    crossOrigin: true,
+    resize: [2048, 1024],
+    failure: 'The Panoramax photo could not be loaded',
+  });
+  assert.equal(signal.aborted, false, 'the open can stop it');
+  assert.equal(poses.at(-1).isPano, true);
+  assert.equal(poses.at(-1).bearing, 100);
+  await new Promise((resolve) => setTimeout(resolve, 0));
+  assert.equal(loads.length, 1, 'docked: the 2,048 px SD is enough');
+  // Docked on a dense screen the canvas wants more, but the original is
+  // megabytes: not until the viewer is expanded.
+  canvas.clientWidth = 1800;
+  viewer.resize();
+  await new Promise((resolve) => setTimeout(resolve, 0));
+  assert.equal(loads.length, 1, 'docked: still SD only');
+  const root = canvas.parentNode;
+  root.closest = (selector) =>
+    selector.includes('sl-viewer-wrap:fullscreen') ? {} : null;
+  // EXPAND resizes more than once while the panel settles.
+  viewer.resize();
+  viewer.resize();
+  viewer.resize();
+  assert.ok(await until(() => renderers[0].images.length === 2));
+  assert.equal(
+    loads.filter((l) => l.url === PHOTOS.pano.urls.hd).length,
+    1,
+    'the original is fetched once',
+  );
+  const hd = loads.at(-1);
+  assert.equal(hd.url, PHOTOS.pano.urls.hd);
+  assert.deepEqual(hd.resize, [4096, 2048]);
+  assert.equal(hd.timeoutMs, 30_000);
+  assert.ok(hd.signal, 'abortable');
+});
+
+test('HD panoramas too big to decode, or no bigger than SD, are never fetched; nor while docked', () => {
+  const size = [4096, 2048];
+  const expanded = { expanded: true };
+  assert.equal(
+    PANORAMAX_SOURCES.panoSharp(PHOTOS.pano, size, { expanded: false }),
+    null,
+  );
+  assert.equal(PANORAMAX_SOURCES.panoSharp(PHOTOS.pano, size), null);
+  assert.equal(
+    PANORAMAX_SOURCES.panoSharp(PHOTOS.bigPano, size, expanded),
+    null,
+  );
+  assert.equal(
+    PANORAMAX_SOURCES.panoSharp(PHOTOS.smallPano, size, expanded),
+    null,
+  );
+  assert.deepEqual(
+    PANORAMAX_SOURCES.panoSharp({ ...PHOTOS.pano, width: 3000 }, size, expanded)
+      .resize,
+    [3000, 1500],
+    'never enlarged',
+  );
+  // Without an SD derivative the HD one is the first and only.
+  const hdOnly = { ...PHOTOS.pano, urls: { ...PHOTOS.pano.urls, sd: null } };
+  assert.deepEqual(PANORAMAX_SOURCES.panoFirst(hdOnly), {
+    url: hdOnly.urls.hd,
+    width: 4096,
+    resize: [4096, 2048],
+  });
+  // …unless it is too big to decode: then no panorama, and the thumbnail.
+  const hugeOnly = { ...hdOnly, width: 11_904 };
+  assert.equal(PANORAMAX_SOURCES.panoFirst(hugeOnly), null);
+  assert.equal(PANORAMAX_SOURCES.hasPano(hugeOnly), false);
+  assert.deepEqual(PANORAMAX_SOURCES.flatFirst(hugeOnly).filter(Boolean), [
+    hugeOnly.urls.thumb,
+  ]);
+  assert.equal(PANORAMAX_SOURCES.panoSharp(hdOnly, size, expanded), null);
+  assert.equal(PANORAMAX_SOURCES.flatSharp(PHOTOS.flat, 2048), null);
+  assert.equal(
+    PANORAMAX_SOURCES.flatSharp(PHOTOS.flat, 2049),
+    PHOTOS.flat.urls.hd,
+  );
+  assert.equal(
+    PANORAMAX_SOURCES.hasPano({ isPano: true, urls: { sd: null, hd: null } }),
+    false,
+  );
+});
+
+test('› and ‹ follow the picture’s own links; the ends disable the buttons', async () => {
+  const { viewer, poses, stepped, host } = setup();
+  await viewer.mount(host);
+  const { next, prev } = parts(host);
+  await viewer.open('flat');
+  next.fire('click');
+  assert.ok(await until(() => poses.at(-1)?.imageId === 'flat2'));
+  assert.deepEqual(stepped, ['flat2']);
+  assert.ok(await until(() => next.disabled), 'flat2 is the last');
+  assert.equal(prev.disabled, false);
+});
+
+test('without WebGL a 360° picture shows its whole equirectangular image flat', async () => {
+  const loads = [];
+  const viewer = createPanoramaxViewer({
+    getPhoto: async () => PHOTOS.pano,
+    step: async () => null,
+    onStep() {},
+    load: async (url) => {
+      loads.push(url);
+      return { src: url };
+    },
+    createRenderer: () => {
+      throw new Error('no WebGL');
+    },
+  });
+  const host = fakeHost();
+  await viewer.mount(host);
+  await viewer.open('pano');
+  const { picture } = parts(host);
+  assert.equal(picture.hidden, false);
+  assert.equal(picture.src, PHOTOS.pano.urls.sd);
+});
+
+test('a picture whose SD fails falls back to the thumbnail; the original only for the expanded viewer', async () => {
+  const tried = [];
+  const viewer = createPanoramaxViewer({
+    getPhoto: async () => PHOTOS.flat,
+    step: async () => null,
+    onStep() {},
+    load: async (url) => {
+      tried.push(url);
+      if (!url.endsWith('thumb.jpg')) throw new Error('gone');
+      return { src: url };
+    },
+  });
+  const host = fakeHost();
+  await viewer.mount(host);
+  await viewer.open('flat');
+  assert.deepEqual(tried, [PHOTOS.flat.urls.sd, PHOTOS.flat.urls.thumb]);
+  assert.equal(parts(host).picture.src, PHOTOS.flat.urls.thumb);
+  // Expanded, the original is worth its megabytes.
+  tried.length = 0;
+  parts(host).root.closest = (selector) =>
+    selector.includes('sl-viewer-wrap:fullscreen') ? {} : null;
+  await viewer.open('flat');
+  assert.deepEqual(tried, [
+    PHOTOS.flat.urls.sd,
+    PHOTOS.flat.urls.hd,
+    PHOTOS.flat.urls.thumb,
+  ]);
+});
+
+test('a photo with no author to name is captioned with the instance holding it', () => {
+  const photo = normalizeItem(
+    stacItem({ id: 'x', lon: 1, lat: 2, producer: '[email protected]' }),
+  );
+  photo.via = 'panoramax.ign.fr';
+  assert.deepEqual(PANORAMAX_SOURCES.describe(photo), {
+    title: 'via panoramax.ign.fr',
+    creator: null,
+    license: 'CC BY-SA 4.0',
+    externalUrl: 'https://api.panoramax.xyz/#pic=x&focus=pic',
+  });
+  const named = { ...photo, creator: 'Robot8A' };
+  assert.equal(PANORAMAX_SOURCES.describe(named).title, null);
+});
+
+test('an SD panorama refused for its size is not fetched again as a flat photo', async () => {
+  const loads = [];
+  const viewer = createPanoramaxViewer({
+    getPhoto: async () => PHOTOS.pano,
+    step: async () => null,
+    onStep() {},
+    load: async (url, options = {}) => {
+      loads.push({ url, crossOrigin: options.crossOrigin });
+      // The picture host's SD file is past the viewer's size limits.
+      if (url === PHOTOS.pano.urls.sd)
+        throw Object.assign(new Error('too big'), { tooLarge: true });
+      return { src: url };
+    },
+    createRenderer: () => ({
+      setImage() {},
+      setView() {},
+      getView: () => ({ yaw: 0, pitch: 0, fov: 80 }),
+      resize() {},
+      clear() {},
+      destroy() {},
+    }),
+  });
+  const host = fakeHost();
+  await viewer.mount(host);
+  await viewer.open('pano');
+  const sdLoads = loads.filter((l) => l.url === PHOTOS.pano.urls.sd);
+  assert.equal(sdLoads.length, 1, 'tried once, as a bitmap, and refused');
+  assert.equal(sdLoads[0].crossOrigin, true);
+  const { picture } = parts(host);
+  assert.equal(picture.hidden, false, 'the flat fallback shows');
+  assert.notEqual(picture.src, PHOTOS.pano.urls.sd);
+  // Opened again later: the refused file is still not asked for.
+  await viewer.open('pano');
+  assert.equal(loads.filter((l) => l.url === PHOTOS.pano.urls.sd).length, 1);
+});

src/layers/streetLevel/registry.js

@@ -1,5 +1,11 @@
 import { encodeIdSwitches } from '../../data/idSwitches.js';
 
+export const IMAGERY_FILTERS = Object.freeze(['pano', 'since']);
+
+export function filtersOf(provider) {
+  return provider?.filters ?? IMAGERY_FILTERS;
+}
+
 /**
  * The contract an imagery provider registers with the Street Level layer.
  *
@@ -9,16 +15,26 @@ import { encodeIdSwitches } from '../../data/idSwitches.js';
  * @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 {{coverage: string}} colors   The source's one colour, from policy.js PROVIDER_COLORS.
  * @property {{html: string}} credit   On-globe attribution while the provider is active.
+ * @property {boolean} [groundClick]   No coverage: a ground click at street zoom opens its nearest image.
+ * @property {string} [requiresMapStack]   Usable only on this map stack.
+ * @property {boolean} [defaultOn]     Default true; the first that defaults on is lit.
+ * @property {{kind: 'view-cone', color: string}} [marker]   Default: GEV's pin.
+ * @property {Array<'pano'|'since'>} [filters]   Filters it honours (default both).
+ * @property {{noun: string, action: string}} [coverageLabel]   How the panel counts its lines and says what a click does (default: sequences, "click a line for its photos").
+ * @property {'capture'|'upload'} [sinceBasis]   What SINCE compares (default 'capture'); 'upload' puts a note under the slider while the provider is lit.
  * @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 {object} services         Scene services: picking, input, render, sprites, scenePick (ground clicks need it).
  * @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
+ * @property {{openImage: (imageId: string, options?: {frame?: boolean}) => Promise<boolean>, openNearest: (point: {lon: number, lat: number}) => Promise<boolean>, reportError: (message: string|null) => void}} actions
+ *   `openNearest` opens this provider's image nearest a point the user picked
+ *   (needs `nearestImage`); `reportError` shows a viewer or key error in the
+ *   panel, or withdraws this provider's own (null).
  *
  * @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`.
@@ -28,10 +44,11 @@ import { encodeIdSwitches } from '../../data/idSwitches.js';
  * @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 {(pickId: string, click?: {groundPoint: () => {lon: number, lat: number}|null}) => boolean} handlePick   The id carries the provider's own prefix; `groundPoint` is where the click met the ground.
  * @property {(sequenceId: string) => Promise<void>} [selectSequence]
  * @property {() => void} [clearSequence]
  * @property {() => {selectedId: string|null, images: number, loading: boolean, error?: string|null}} [sequenceStats]
+ * @property {(point: {lat: number, lon: number}, options?: {signal?: AbortSignal}) => Promise<string|null>} [nearestImage]   For ground clicks and `openNearest`; an aborted lookup gives up (it may reject with an AbortError).
  * @property {ViewerAdapter} viewer
  *
  * @typedef {object} ViewerAdapter
@@ -41,16 +58,22 @@ import { encodeIdSwitches } from '../../data/idSwitches.js';
  * @property {() => void} unmount                             Destroy the instance (host handed to another provider).
  * @property {() => void} resize
  * @property {(mode: 'letterbox'|'fill') => void} [setRenderMode]
+ * @property {() => boolean} [supportsRenderModes]   False while the image has no frame to fit (a panorama): FIT / FILL hide.
  * @property {(listener: (pose: StreetPose) => void) => () => void} onPose
  *
  * @typedef {object} StreetPose
+ * @property {string} providerId
  * @property {string} imageId
  * @property {{lon: number, lat: number}} position
  * @property {number|null} bearing
+ * @property {number|null} tilt
  * @property {number|null} altitude
  * @property {boolean} isPano
  * @property {number|null} capturedAt   Epoch milliseconds.
+ * @property {'day'|'month'} [capturedAtPrecision]   How exactly the provider dates images (default 'day').
+ * @property {string|null} [title]     A place name for the caption, e.g. the address.
  * @property {string|null} creator
+ * @property {string|null} [license]   The image's licence when it is per image, e.g. 'CC BY-SA 4.0'.
  * @property {string|null} sequenceId
  * @property {string} externalUrl      Deep link to the image on the provider's site.
  */
@@ -109,6 +132,34 @@ export function validateProviders(providers) {
       throw new TypeError(
         `Street Level provider ${label} needs a coverage colour`,
       );
+    if (
+      provider.marker !== undefined &&
+      !(
+        provider.marker?.kind === 'view-cone' &&
+        typeof provider.marker.color === 'string'
+      )
+    )
+      throw new TypeError(
+        `Street Level provider ${label}: marker must be {kind: 'view-cone', color}`,
+      );
+    if (
+      provider.filters !== undefined &&
+      !(
+        Array.isArray(provider.filters) &&
+        provider.filters.every((key) => IMAGERY_FILTERS.includes(key))
+      )
+    )
+      throw new TypeError(
+        `Street Level provider ${label}: filters must list ${IMAGERY_FILTERS.join(' or ')}`,
+      );
+    if (
+      provider.sinceBasis !== undefined &&
+      provider.sinceBasis !== 'capture' &&
+      provider.sinceBasis !== 'upload'
+    )
+      throw new TypeError(
+        `Street Level provider ${label}: sinceBasis must be 'capture' or 'upload'`,
+      );
     ids.add(provider.id);
     prefixes.push(provider.pickPrefix);
   }

src/layers/streetLevel/registry.test.mjs

@@ -1,6 +1,6 @@
 import assert from 'node:assert/strict';
 import test from 'node:test';
-import { requiresKeyIdFor, validateProviders } from './registry.js';
+import { filtersOf, requiresKeyIdFor, validateProviders } from './registry.js';
 
 const def = (overrides = {}) => ({
   id: 'mapillary',
@@ -101,3 +101,25 @@ test('requiresKeyIdFor is the shared key, or null once providers differ', () =>
   );
   assert.equal(requiresKeyIdFor([def({ requiresKeyId: null })]), null);
 });
+
+test('a provider may narrow the filters it honours and pick a view-cone marker', () => {
+  assert.deepEqual(filtersOf(def()), ['pano', 'since'], 'both by default');
+  const narrowed = def({
+    filters: [],
+    marker: { kind: 'view-cone', color: '#4285f4' },
+  });
+  assert.deepEqual(filtersOf(validateProviders([narrowed])[0]), []);
+  assert.throws(
+    () => validateProviders([def({ filters: ['colour'] })]),
+    /filters must list pano or since/,
+  );
+  assert.throws(
+    () => validateProviders([def({ marker: { kind: 'pegman' } })]),
+    /marker must be/,
+  );
+  validateProviders([def({ sinceBasis: 'upload' })]);
+  assert.throws(
+    () => validateProviders([def({ sinceBasis: 'shot' })]),
+    /sinceBasis must be 'capture' or 'upload'/,
+  );
+});

src/layers/streetLevel/selection.js

@@ -18,9 +18,32 @@ export function createSelection({ state, parts }) {
     const id = picking?.resolvePickId
       ? picking.resolvePickId(picked)
       : picked?.id;
-    const hit = parts.router.resolve(id);
+    const route = parts.router.resolve(id);
+    // Not ours: the ground handler decides whether it is the map itself.
+    if (!route) {
+      parts.openAtGround?.(click.position, picked);
+      return;
+    }
     // The position marker is the core's own: nothing to select.
-    if (hit?.instance) hit.instance.handlePick(hit.id);
+    if (!route.instance) return;
+    route.instance.handlePick(route.id, {
+      groundPoint: () => groundPointAt(viewer, click.position),
+    });
+  }
+
+  /** Lon/lat of the ground under a screen point, or null (sky, no picker). */
+  function groundPointAt(viewer, screenPosition) {
+    const position = state.services.scenePick?.pickGroundPosition?.(
+      viewer,
+      screenPosition,
+    );
+    const carto = position && Cesium.Cartographic.fromCartesian(position);
+    return carto
+      ? {
+          lon: Cesium.Math.toDegrees(carto.longitude),
+          lat: Cesium.Math.toDegrees(carto.latitude),
+        }
+      : null;
   }
 
   /**

src/layers/streetLevel/selection.test.mjs

@@ -5,7 +5,7 @@ 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 } = {}) {
+function harness({ selected = false, services = {}, providers = [] } = {}) {
   const saved = globalThis.document;
   globalThis.document = new EventTarget();
   // The document's keydown listeners, so a test can hand them any target.
@@ -26,6 +26,7 @@ function harness({ selected = false } = {}) {
   };
   const sequences = { selected, cleared: 0, selects: [] };
   const opened = [];
+  const groundClicks = [];
   /** What the pointer is over: a pick id, or nothing. */
   const scene = { under: null };
   const canvas = Object.assign(new EventTarget(), {
@@ -40,7 +41,7 @@ function harness({ selected = false } = {}) {
     viewer,
     enabled: true,
     clickHandler: null,
-    services: { picking: null, input: null },
+    services: { picking: null, input: null, ...services },
     providers: new Map([
       [
         'mapillary',
@@ -56,6 +57,7 @@ function harness({ selected = false } = {}) {
           },
         },
       ],
+      ...providers,
     ]),
   };
   const parts = {
@@ -63,6 +65,7 @@ function harness({ selected = false } = {}) {
       positionId: 'sl:pos',
     }),
     hasSelectedSequence: () => sequences.selected,
+    openAtGround: (position, picked) => groundClicks.push({ position, picked }),
     clearSequences() {
       sequences.cleared++;
       sequences.selected = false;
@@ -76,8 +79,9 @@ function harness({ selected = false } = {}) {
     state,
     sequences,
     opened,
+    groundClicks,
     scene,
-    click: () => action('LEFT_CLICK')({ position: { x: 10, y: 10 } }),
+    click: (x = 10) => action('LEFT_CLICK')({ position: { x, y: 10 } }),
     /** A keydown reaching the document from `target`; the event as handled. */
     key(key, target, { defaultPrevented = false } = {}) {
       const event = {
@@ -112,6 +116,11 @@ 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']]);
+    // The marker is ours; nothing and another layer's pick go to the ground.
+    assert.deepEqual(
+      h.groundClicks.map(({ picked }) => picked?.id),
+      [undefined, 'cctv:7'],
+    );
   } finally {
     h.restore();
   }
@@ -170,3 +179,64 @@ test('Esc in a text field or rich-text editor keeps the selection (M61)', () =>
     h.restore();
   }
 });
+
+test('a click on nothing of ours goes to the ground handler with the pick, which decides', () => {
+  const h = harness();
+  try {
+    h.click(5);
+    h.scene.under = 'flight:abc';
+    h.click(6);
+    assert.deepEqual(
+      h.groundClicks.map(({ position, picked }) => [position.x, picked?.id]),
+      [
+        [5, undefined],
+        [6, 'flight:abc'],
+      ],
+    );
+  } finally {
+    h.restore();
+  }
+});
+
+test('a click on a provider line hands it the ground under the click, measured only if asked', () => {
+  const handled = [];
+  const groundPicks = [];
+  const h = harness({
+    providers: [
+      [
+        'kartaview',
+        {
+          def: { id: 'kartaview', pickPrefix: 'kv:' },
+          instance: {
+            handlePick: (id, click) => handled.push({ id, click }),
+          },
+        },
+      ],
+    ],
+    services: {
+      scenePick: {
+        pickGroundPosition: (viewer, position) => {
+          groundPicks.push(position);
+          return Cesium.Cartesian3.fromDegrees(-83.0458, 42.3314, 190);
+        },
+      },
+    },
+  });
+  try {
+    h.scene.under = 'kv:line:14/1/2/3';
+    h.click(40);
+    assert.equal(handled.length, 1);
+    assert.equal(handled[0].id, 'kv:line:14/1/2/3');
+    assert.equal(
+      groundPicks.length,
+      0,
+      'no depth read until the provider asks',
+    );
+    const point = handled[0].click.groundPoint();
+    assert.ok(Math.abs(point.lon + 83.0458) < 1e-9);
+    assert.ok(Math.abs(point.lat - 42.3314) < 1e-9);
+    assert.deepEqual(groundPicks, [{ x: 40, y: 10 }]);
+  } finally {
+    h.restore();
+  }
+});

src/layers/streetLevel/sequenceCones.js

@@ -2,28 +2,21 @@ import * as Cesium from 'cesium';
 import { imageConeGlyph } from './glyphs.js';
 import { passesImageryFilter } from './filter.js';
 import { createHorizonCull, metresBetween } from './view.js';
-import {
-  COLORS,
-  IMAGE_CONE_MIN_SPACING_M,
-  IMAGE_CONE_SIZE_PX,
-  PICK_PREFIX,
-} from './policy.js';
+import { msg } from '../../i18n/index.js';
 
-const SPRITE_ID = 'street-level:mapillary-cones';
+/** Cones closer than this to the previous kept one are dropped. */
+export const IMAGE_CONE_MIN_SPACING_M = 3;
+export const IMAGE_CONE_SIZE_PX = 26;
 
-/** Normalize a graph image record into the shape the cones use. */
-function normalizeSequenceImage(record) {
-  const coordinates = record?.geometry?.coordinates;
-  if (!Array.isArray(coordinates) || coordinates.length < 2) return null;
-  return {
-    id: String(record.id),
-    lon: Number(coordinates[0]),
-    lat: Number(coordinates[1]),
-    compassAngle: Number(record.compass_angle) || 0,
-    capturedAt: Number(record.captured_at) || 0,
-    isPano: record.is_pano === true,
-  };
-}
+/**
+ * @typedef {object} ConeImage   One image of a sequence, as the cones draw it.
+ * @property {string} id
+ * @property {number} lon
+ * @property {number} lat
+ * @property {number} compassAngle   Degrees clockwise from north.
+ * @property {number} capturedAt     Epoch ms (0 when unknown).
+ * @property {boolean} isPano
+ */
 
 /** Drop images closer than the spacing to the previous kept one. */
 export function thinImages(images, spacingM = IMAGE_CONE_MIN_SPACING_M) {
@@ -38,16 +31,43 @@ export function thinImages(images, spacingM = IMAGE_CONE_MIN_SPACING_M) {
   return kept;
 }
 
-/** Image cones for one selected sequence. */
-export function createSequences({ state, source, parts }) {
+/**
+ * Image cones for one selected sequence, any provider's, clamped to the
+ * ground. A cone's pick id is `pickPrefix` + the image id; 360° images draw
+ * as rings. Why a sequence could not load stays in `state.sequence.error`
+ * until it goes.
+ *
+ * @param {object} options
+ * @param {object} options.state  Provider state: `context`, `services`, `viewer`, `sequence`.
+ * @param {(sequenceId: string, init: {signal: AbortSignal}) => Promise<Array<ConeImage>>} options.loadImages
+ *   The sequence's images in capture order, thinned (see `thinImages`).
+ * @param {{coverage: string}} options.colors
+ * @param {string} options.pickPrefix   Pick-id prefix of the cones.
+ * @param {string} options.spriteId     Sprite-order id of the cone collection.
+ * @param {string} options.renderKey    Render-governor reason.
+ * @param {(sequenceId: string|null) => void} [options.onHighlight]
+ *   Highlight the sequence's coverage line (null: none).
+ * @param {(image: ConeImage, filter: object) => boolean} [options.passes]
+ *   Whether the imagery filter keeps a cone.
+ */
+export function createSequenceCones({
+  state,
+  loadImages,
+  colors,
+  pickPrefix,
+  spriteId,
+  renderKey,
+  onHighlight = () => {},
+  passes = passesImageryFilter,
+}) {
   const { render, sprites } = state.services;
 
   function requestRender() {
-    render?.governorRequestRender?.('mapillary-sequence');
+    render?.governorRequestRender?.(renderKey);
   }
 
   function notify() {
-    state.notify?.();
+    state.context.notify();
   }
 
   /** Drawn cone billboards. */
@@ -66,7 +86,7 @@ export function createSequences({ state, source, parts }) {
       scene: viewer.scene,
     });
     viewer.scene.primitives.add(state.sequence.collection);
-    sprites?.registerSpriteCollection?.(SPRITE_ID, state.sequence.collection);
+    sprites?.registerSpriteCollection?.(spriteId, state.sequence.collection);
   }
 
   function clearCones() {
@@ -82,22 +102,22 @@ export function createSequences({ state, source, parts }) {
     collection.removeAll();
     cones = [];
     // One colour per source; 360° images keep the ring shape.
-    const cone = imageConeGlyph({ size: 32, color: COLORS.coverage });
+    const cone = imageConeGlyph({ size: 32, color: colors.coverage });
     const ring = imageConeGlyph({
       size: 32,
-      color: COLORS.coverage,
+      color: colors.coverage,
       pano: true,
     });
     // Resolved now, so a "since N days" window keeps up with the clock.
-    const filter = state.getFilter();
+    const filter = state.context.getFilter();
     for (const image of images) {
-      if (!passesImageryFilter(image, filter)) continue;
+      if (!passes(image, filter)) continue;
       const billboard = collection.add({
-        id: `${PICK_PREFIX.image}${image.id}`,
+        id: `${pickPrefix}${image.id}`,
         position: Cesium.Cartesian3.fromDegrees(image.lon, image.lat),
         heightReference: Cesium.HeightReference.CLAMP_TO_GROUND,
         image: image.isPano ? ring : cone,
-        imageId: image.isPano ? 'mly-cone-pano' : 'mly-cone',
+        imageId: image.isPano ? `${spriteId}:pano` : `${spriteId}:flat`,
         width: IMAGE_CONE_SIZE_PX,
         height: IMAGE_CONE_SIZE_PX,
         rotation: -Cesium.Math.toRadians(image.compassAngle),
@@ -112,18 +132,22 @@ export function createSequences({ state, source, parts }) {
     requestRender();
   }
 
-  /** Select a sequence: highlight its line and load its image cones. */
-  async function select(sequenceId) {
+  /**
+   * Select a sequence: highlight its line and load its image cones. `force`
+   * reloads a selected one (a provider that loads part of a sequence moved on).
+   */
+  async function select(sequenceId, { force = false } = {}) {
     if (!sequenceId || !state.viewer) return;
     // Already on screen, or already on its way.
     if (
+      !force &&
       state.sequence.selectedId === sequenceId &&
       (state.sequence.images.length || state.sequence.abort)
     )
       return;
     state.sequence.abort?.abort();
     state.sequence.selectedId = sequenceId;
-    parts.coverage.highlight(sequenceId);
+    onHighlight(sequenceId);
     // The previous sequence's cones must not stay clickable under the new
     // highlight while this one loads, nor after its load fails.
     clearCones();
@@ -135,25 +159,20 @@ export function createSequences({ state, source, parts }) {
     state.sequence.error = null;
     notify();
     try {
-      const records = await source.getSequenceImages(sequenceId, {
+      const images = await loadImages(sequenceId, {
         signal: controller.signal,
       });
       if (controller.signal.aborted) return;
-      const images = thinImages(
-        records
-          .map(normalizeSequenceImage)
-          .filter(Boolean)
-          .sort((a, b) => a.capturedAt - b.capturedAt),
-      );
       state.sequence.images = images;
       renderCones(images);
       state.sequence.error = null;
     } catch (error) {
       if (!controller.signal.aborted) {
         // Nothing to show: drop the highlight, so a click asks again.
-        parts.coverage.highlight(null);
+        onHighlight(null);
         state.sequence.selectedId = null;
-        state.sequence.error = error?.message || 'Sequence images unavailable';
+        state.sequence.error =
+          error?.message || msg('Sequence images unavailable');
       }
     } finally {
       if (state.sequence.abort === controller) {
@@ -167,7 +186,7 @@ export function createSequences({ state, source, parts }) {
   function clearSelection() {
     state.sequence.abort?.abort();
     state.sequence.abort = null;
-    if (state.sequence.selectedId) parts.coverage.highlight(null);
+    if (state.sequence.selectedId) onHighlight(null);
     state.sequence.selectedId = null;
     state.sequence.loading = false;
     clearCones();
@@ -193,7 +212,7 @@ export function createSequences({ state, source, parts }) {
     cones = [];
     const collection = state.sequence.collection;
     if (collection) {
-      sprites?.unregisterSpriteCollection?.(SPRITE_ID, collection);
+      sprites?.unregisterSpriteCollection?.(spriteId, collection);
       viewer?.scene?.primitives?.remove(collection);
       state.sequence.collection = null;
     }

src/layers/streetLevel/sequenceCones.test.mjs

@@ -2,7 +2,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';
+import { createSequenceCones, thinImages } from './sequenceCones.js';
 
 const settle = () => new Promise((resolve) => setTimeout(resolve, 0));
 
@@ -57,8 +57,10 @@ function setup() {
     services: {},
     viewer: {},
     filter: { pano: 'all', sinceDays: 0 },
-    getFilter: () => resolveFilter(state.filter),
-    notify() {},
+    context: {
+      getFilter: () => resolveFilter(state.filter),
+      notify() {},
+    },
     sequence: {
       selectedId: null,
       images: [],
@@ -68,12 +70,27 @@ function setup() {
       abort: null,
     },
   };
-  const parts = {
-    coverage: {
-      highlight: (id) => highlights.push(id),
+  const sequences = createSequenceCones({
+    state,
+    async loadImages(sequenceId, { signal }) {
+      const list = await source.getSequenceImages(sequenceId, { signal });
+      return thinImages(
+        list.map((record) => ({
+          id: String(record.id),
+          lon: record.geometry.coordinates[0],
+          lat: record.geometry.coordinates[1],
+          compassAngle: Number(record.compass_angle) || 0,
+          capturedAt: Number(record.captured_at) || 0,
+          isPano: record.is_pano === true,
+        })),
+      );
     },
-  };
-  const sequences = createSequences({ state, source, parts });
+    colors: { coverage: '#05cb63' },
+    pickPrefix: 'mly:img:',
+    spriteId: 'street-level:test-cones',
+    renderKey: 'test-sequence',
+    onHighlight: (id) => highlights.push(id),
+  });
   const drawn = () =>
     state.sequence.collection.items.map((cone) => cone.id.split(':').at(-1));
   return { state, source, sequences, highlights, drawn };

src/layers/streetLevel/state.js

@@ -13,42 +13,25 @@ export function freshStreet() {
     imageId: null,
     position: null,
     bearing: null,
+    tilt: null,
     altitude: null,
     isPano: false,
     capturedAt: null,
+    /** 'day', or 'month' for providers that date images by month (Google). */
+    capturedAtPrecision: 'day',
+    /** A place name for the caption (Google's address), or null. */
+    title: null,
+    /** Whether the open viewer has FIT/FILL render modes. */
+    renderModes: true,
     sequenceId: null,
     creator: null,
+    license: null,
     externalUrl: null,
     loading: false,
     error: null,
   };
 }
 
-/** A provider's coverage bookkeeping, before the first refresh. */
-export function freshCoverage() {
-  return {
-    zoom: null,
-    /** Current zoom's tiles by `z/x/y` key. */
-    tiles: new Map(),
-    /** The selected sequence drawn over the coverage, or null. */
-    highlight: null,
-    /** Tile key → its request's controller; any entry means LOADING. */
-    pending: new Map(),
-    lastError: null,
-    /**
-     * Why tile requests are paused, or null: 'status' until the key status
-     * answers, 'no-key', 'rejected' (until the provider goes off) or
-     * 'rate-limited' (until `blockTimer` fires).
-     */
-    blocked: 'status',
-    blockTimer: null,
-    debounceTimer: null,
-    removeCameraListener: null,
-    terrainReady: null,
-    hint: '',
-  };
-}
-
 /** Mutable core state, created once per layer instance. */
 export function createState({ services }) {
   return {
@@ -69,7 +52,10 @@ export function createState({ services }) {
       ...freshStreet(),
     },
 
-    marker: { collection: null, billboard: null },
+    /** Whether the camera is low enough for a ground click to open an image. */
+    groundClickReady: false,
+
+    marker: { collection: null, billboard: null, look: null },
     clickHandler: null,
   };
 }

src/layers/streetLevel/street-level-unique-tiles.test.mjs

@@ -0,0 +1,18 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { tilesForBbox } from './tileMath.js';
+
+const keysOf = (tiles) => tiles.map((tile) => `${tile.x}/${tile.y}/${tile.z}`);
+
+test('a polar view across the date line ranks 24 distinct tiles', () => {
+  // The halves of [-10, 60, -20, 85] share a column at z3.
+  const keys = keysOf(tilesForBbox([-10, 60, -20, 85], 3));
+  assert.equal(keys.length, 24);
+  assert.equal(new Set(keys).size, 24);
+});
+
+test('a limit is not spent on repeats', () => {
+  const keys = keysOf(tilesForBbox([-10, 60, -20, 85], 3, { limit: 16 }));
+  assert.equal(keys.length, 16);
+  assert.equal(new Set(keys).size, 16);
+});

src/layers/streetLevel/tileCache.js

@@ -0,0 +1,51 @@
+/** Decoded coverage tiles kept, and for how long. */
+export const TILE_CACHE_SIZE = 24;
+export const TILE_CACHE_TTL_MS = 10 * 60_000;
+
+/** Least-recently-used map: reading an entry renews it. */
+export function createLru(limit) {
+  const map = new Map();
+  return {
+    get(key) {
+      if (!map.has(key)) return undefined;
+      const value = map.get(key);
+      map.delete(key);
+      map.set(key, value);
+      return value;
+    },
+    set(key, value) {
+      map.delete(key);
+      map.set(key, value);
+      while (map.size > limit) map.delete(map.keys().next().value);
+    },
+    delete: (key) => map.delete(key),
+    clear: () => map.clear(),
+  };
+}
+
+/**
+ * Loaded (decoded) coverage tiles by `keyOf` (default `z/x/y`), at most `size`, each for
+ * `ttlMs`: a pan back, or a zoom across bands and back, neither fetches nor
+ * decodes them again. A load that fails is not kept.
+ */
+export function createTileCache({
+  load,
+  size = TILE_CACHE_SIZE,
+  ttlMs = TILE_CACHE_TTL_MS,
+  now = Date.now,
+  keyOf = (tile) => `${tile.z}/${tile.x}/${tile.y}`,
+}) {
+  const kept = createLru(size);
+  return {
+    async get(tile, options) {
+      const key = keyOf(tile);
+      const entry = kept.get(key);
+      if (entry && now() - entry.at < ttlMs) return entry.tile;
+      const loaded = await load(tile, options);
+      kept.set(key, { at: now(), tile: loaded });
+      return loaded;
+    },
+    /** Forget every tile (the layer is off: its memory goes back). */
+    clear: () => kept.clear(),
+  };
+}

src/layers/streetLevel/tileMath.js

@@ -90,10 +90,17 @@ export function tilesForBbox(bbox, z, { limit = Infinity, from = null } = {}) {
         [-180, south, east, north],
       ]
     : [bbox];
-  const grid = halves
-    .map(normalizeBbox)
-    .filter(Boolean)
-    .flatMap((box) => tileGrid(box, z));
+  // The halves share a column when the gap between east and west is
+  // narrower than a tile: count it once, so a capped set holds no repeats.
+  const grid = [
+    ...new Map(
+      halves
+        .map(normalizeBbox)
+        .filter(Boolean)
+        .flatMap((box) => tileGrid(box, z))
+        .map((tile) => [`${tile.x}/${tile.y}`, tile]),
+    ).values(),
+  ];
   const n = 2 ** z;
   const centre = from || {
     lon: wrapLon(west + (east - west + (across ? 360 : 0)) / 2),

src/layers/streetLevel/uiState.js

@@ -1,3 +1,5 @@
+import { msg, t } from '../../i18n/index.js';
+
 /**
  * @typedef {object} ProviderSnapshot
  * @property {string} id
@@ -13,6 +15,10 @@
  * @property {string} hint
  * @property {string|null} error
  * @property {string} color   The source's one colour.
+ * @property {boolean} [groundClick]
+ * @property {Array<'pano'|'since'>} [filters]
+ * @property {{noun: string, action: string}|null} [coverageLabel]
+ * @property {'capture'|'upload'} [sinceBasis]   What its SINCE compares.
  */
 
 /**
@@ -27,9 +33,11 @@ export function summarizeCoverage(providers) {
     loading: active.some((p) => p.loading),
     hint:
       providers.length === 0
-        ? 'No street-level imagery providers configured'
-        : active.find((p) => p.hint)?.hint || '',
+        ? msg('No street-level imagery providers configured')
+        : [...new Set(active.map((p) => p.hint).filter(Boolean))].join(' · '),
     error: active.find((p) => p.error)?.error || null,
+    // One source is lit at a time; its wording counts the lines.
+    label: active.find((p) => p.coverageLabel)?.coverageLabel || null,
     keyRequired:
       active.length > 0 && active.every((p) => p.keyRequired === true),
     keyRejected:
@@ -39,12 +47,52 @@ export function summarizeCoverage(providers) {
   };
 }
 
+/**
+ * Switched-off providers that would draw with a key already set, offered
+ * while the switched-on ones lack theirs.
+ * @param {Array<ProviderSnapshot>} providers
+ * @returns {Array<{id: string, label: string, requiresKeyId: string|null}>}
+ */
+export function keyAlternatives(providers) {
+  if (!summarizeCoverage(providers).keyRequired) return [];
+  return providers
+    .filter((p) => !p.on && p.configured === true && p.keyRequired !== true)
+    .map(({ id, label, requiresKeyId }) => ({ id, label, requiresKeyId }));
+}
+
+/**
+ * The filter controls a switched-on provider honours (both when none is on).
+ * @param {Array<ProviderSnapshot>} providers
+ */
+export function filterControls(providers) {
+  const active = providers.filter((p) => p.on);
+  const honoured = (key) =>
+    active.length === 0 ||
+    active.some((p) => (p.filters ?? ['pano', 'since']).includes(key));
+  return { pano: honoured('pano'), since: honoured('since') };
+}
+
+/**
+ * The note under SINCE when a lit provider dates its imagery by upload,
+ * e.g. "KartaView: by upload date", or null.
+ * @param {Array<ProviderSnapshot>} providers
+ */
+export function sinceNote(providers) {
+  const names = providers
+    .filter((p) => p.on && p.sinceBasis === 'upload')
+    .map((p) => p.name);
+  return names.length
+    ? t('{names}: by upload date', { names: names.join(', ') })
+    : null;
+}
+
 /**
  * The panel snapshot from core state and provider snapshots.
- * @param {{enabled: boolean, filter: object, providers: Array<ProviderSnapshot>, street: object, sequence: object}} input
+ * @param {{enabled: boolean, groundClickReady?: boolean, filter: object, providers: Array<ProviderSnapshot>, street: object, sequence: object}} input
  */
 export function composeUIState({
   enabled,
+  groundClickReady = false,
   filter,
   providers,
   street,
@@ -54,9 +102,13 @@ export function composeUIState({
     summarizeCoverage(providers);
   return {
     enabled,
+    groundClickReady: groundClickReady === true,
     keyRequired,
+    keyAlternatives: keyAlternatives(providers),
     keyRejected,
     filter: { ...filter },
+    filterControls: filterControls(providers),
+    sinceNote: sinceNote(providers),
     providers: providers.map((p) => ({ ...p })),
     coverage,
     sequence: { ...sequence },

src/layers/streetLevel/uiState.test.mjs

@@ -46,6 +46,39 @@ test('the layer is key-gated only when every switched-on provider lacks its key'
   assert.equal(offOnly.keyRequired, false, 'nothing switched on to gate');
 });
 
+test('the filter controls show only for a lit provider that honours them', () => {
+  const streetView = provider({ id: 'google', groundClick: true, filters: [] });
+  const controls = (providers) =>
+    composeUIState({ ...base, providers }).filterControls;
+  assert.deepEqual(controls([streetView]), { pano: false, since: false });
+  assert.deepEqual(controls([provider(), streetView]), {
+    pano: true,
+    since: true,
+  });
+  assert.deepEqual(
+    controls([provider({ on: false }), streetView]),
+    { pano: false, since: false },
+    'Mapillary switched off',
+  );
+  assert.deepEqual(
+    controls([provider({ on: false }), { ...streetView, on: false }]),
+    { pano: true, since: true },
+    'nothing lit: both, ready for the first chip',
+  );
+});
+
+test('a lit provider that dates by upload puts a note under SINCE', () => {
+  const kartaView = provider({
+    id: 'kartaview',
+    name: 'KartaView',
+    sinceBasis: 'upload',
+  });
+  const note = (providers) => composeUIState({ ...base, providers }).sinceNote;
+  assert.equal(note([provider()]), null, 'Mapillary: capture date');
+  assert.equal(note([kartaView]), 'KartaView: by upload date');
+  assert.equal(note([{ ...kartaView, on: false }]), null, 'only while lit');
+});
+
 test('hint and error come from the first active provider that has one', () => {
   const ui = composeUIState({
     ...base,
@@ -72,6 +105,7 @@ test('summarizeCoverage is what getStats reports, without building a snapshot',
       loading: true,
       hint: 'Look down',
       error: 'boom',
+      label: null,
       keyRequired: false,
       keyRejected: false,
     },
@@ -98,3 +132,63 @@ test('a rejected key gates like a missing one and is named as rejected', () => {
     false,
   );
 });
+
+test('every switched-on provider’s hint is kept, once each', async () => {
+  const { summarizeCoverage } = await import('./uiState.js');
+  const { providerSnapshot } =
+    await import('../../testSupport/streetLevelFakes.mjs');
+  const summary = summarizeCoverage([
+    providerSnapshot({ hint: 'zoom in for sequences' }),
+    providerSnapshot({
+      id: 'google',
+      hint: 'click a street to open Street View',
+    }),
+    providerSnapshot({ id: 'off', on: false, hint: 'not shown' }),
+    providerSnapshot({ id: 'dup', hint: 'zoom in for sequences' }),
+  ]);
+  assert.equal(
+    summary.hint,
+    'zoom in for sequences · click a street to open Street View',
+  );
+});
+
+test('a key-gated layer offers the switched-off sources that would draw with a key already set', async () => {
+  const { keyAlternatives } = await import('./uiState.js');
+  const mapillary = providerSnapshot({ keyRequired: true, configured: false });
+  const streetView = providerSnapshot({
+    id: 'google',
+    label: 'STREET VIEW',
+    on: false,
+    configured: true,
+    requiresKeyId: 'google-maps',
+  });
+  assert.deepEqual(keyAlternatives([mapillary, streetView]), [
+    { id: 'google', label: 'STREET VIEW', requiresKeyId: 'google-maps' },
+  ]);
+  // Nothing to offer: Mapillary has its key, or Street View has none either.
+  assert.deepEqual(keyAlternatives([providerSnapshot(), streetView]), []);
+  assert.deepEqual(
+    keyAlternatives([
+      mapillary,
+      { ...streetView, configured: false, keyRequired: true },
+    ]),
+    [],
+  );
+});
+
+test('a source names its own lines', () => {
+  const kartaView = provider({
+    id: 'kartaview',
+    name: 'KartaView',
+    color: '#635bff',
+    coverageLabel: {
+      noun: 'streets',
+      action: 'click a line for its nearest photo',
+    },
+  });
+  const ui = composeUIState({ ...base, providers: [kartaView] });
+  assert.deepEqual(ui.coverage.label, {
+    noun: 'streets',
+    action: 'click a line for its nearest photo',
+  });
+});

src/layers/streetLevel/view.js

@@ -76,6 +76,13 @@ function groundHit(camera, point, ellipsoid, maxRange) {
   return Cesium.Cartographic.fromCartesian(cartesian, ellipsoid) || null;
 }
 
+/** Camera height (m) above the ground under it. */
+export function cameraHeightAboveGround(viewer) {
+  const carto = viewer?.camera?.positionCartographic;
+  if (!carto) return null;
+  return carto.height - (groundUnderCamera(viewer) ?? 0);
+}
+
 /** Screen rays per side, less one, that `visibleBbox` casts. */
 const BBOX_GRID = 5;
 
@@ -256,3 +263,22 @@ export function createHorizonCull({ getViewer, items, onChange }) {
 
   return { update, stop };
 }
+
+/** The middle of the visible ground, else the point under the camera; null without a camera. */
+export function viewCentre(viewer) {
+  if (!viewer) return null;
+  const bbox = visibleBbox(viewer);
+  if (bbox) {
+    // Across the date line (west > east) the middle is on the far side of 0°.
+    const span = bbox[2] - bbox[0] + (bbox[0] > bbox[2] ? 360 : 0);
+    let lon = bbox[0] + span / 2;
+    if (lon > 180) lon -= 360;
+    return { lat: (bbox[1] + bbox[3]) / 2, lon };
+  }
+  const carto = viewer.camera?.positionCartographic;
+  if (!carto) return null;
+  return {
+    lat: Cesium.Math.toDegrees(carto.latitude),
+    lon: Cesium.Math.toDegrees(carto.longitude),
+  };
+}

src/layers/streetLevel/viewerHost.js

@@ -1,3 +1,4 @@
+import { msg } from '../../i18n/index.js';
 import { freshStreet } from './state.js';
 
 /**
@@ -25,11 +26,23 @@ export function createViewerHost({ state, parts }) {
       altitude: Number.isFinite(pose.altitude) ? pose.altitude : null,
       isPano: pose.isPano === true,
       capturedAt: pose.capturedAt ?? null,
+      capturedAtPrecision:
+        pose.capturedAtPrecision === 'month' ? 'month' : 'day',
+      title: pose.title || null,
       sequenceId: pose.sequenceId ?? null,
       creator: pose.creator || null,
+      license: pose.license || null,
       externalUrl: pose.externalUrl || null,
+      // FIT / FILL, unless this image has no frame to fit (a panorama).
+      renderModes:
+        typeof active.adapter.setRenderMode === 'function' &&
+        active.adapter.supportsRenderModes?.() !== false,
     });
-    parts.marker.set(state.street.position, state.street.bearing);
+    parts.marker.set(
+      state.street.position,
+      state.street.bearing,
+      state.providers.get(active.id)?.def.marker,
+    );
     // Select the sequence only once the image is on screen, so its lookup
     // never competes with the image download.
     if (!state.street.loading && state.street.sequenceId !== previousSequence)
@@ -85,19 +98,25 @@ export function createViewerHost({ state, parts }) {
     return promise;
   }
 
-  /** Open an image: true once its first pose is in, false if it failed or was overtaken. */
-  async function open(providerId, imageId) {
+  /**
+   * Open an image: true once its first pose is in, false if it failed or was
+   * overtaken. `frame: false` leaves the camera where it is.
+   */
+  async function open(providerId, imageId, { frame = true } = {}) {
     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';
+      // A nearest-image lookup may have set it; nothing is loading now.
+      state.street.loading = false;
+      // English data: the Street Level panel translates it (translateKnown).
+      state.street.error = msg('Open the Street Level panel to view imagery');
       notify();
       return false;
     }
     const seq = ++openSeq;
     const current = () => seq === openSeq;
     // Claimed now, honoured after loading only if nothing newer took the camera.
-    const ticket = parts.framing.begin();
+    const ticket = frame ? parts.framing.begin() : null;
     Object.assign(state.street, {
       loading: true,
       error: null,
@@ -110,12 +129,14 @@ export function createViewerHost({ state, parts }) {
     try {
       const adapter = await mount(entry);
       if (!current()) return false;
+      // Per open: close() resets it, and a reopen skips mount().
+      state.street.renderModes = typeof adapter.setRenderMode === 'function';
       await adapter.open(String(imageId));
       if (!current()) return false;
       if (ticket) parts.framing.frame(ticket);
     } catch (error) {
       if (current())
-        state.street.error = error?.message || 'Image could not be opened';
+        state.street.error = error?.message || msg('Image could not be opened');
     } finally {
       if (current()) state.street.loading = false;
       notify();

src/layers/streetLevel/viewerHost.test.mjs

@@ -27,7 +27,8 @@ registerHooks({
     return { format: 'module', shortCircuit: true, source };
   },
 });
-const { createMapillaryViewer } = await import('./viewer.js');
+const { createMapillaryViewer } =
+  await import('./providers/mapillary/viewer.js');
 
 /**
  * A viewer host over `adapter`. `marker` records where the position marker
@@ -473,3 +474,81 @@ test('a photo asks for the camera when it starts opening and frames with that ti
   assert.equal(await opening, true);
   assert.equal(framing.started, 1);
 });
+
+/** The harness with a second provider, `google`, whose adapter has no render modes. */
+function twoProviders() {
+  const mapillary = fakeAdapter();
+  mapillary.prewarm = async () => {};
+  mapillary.setRenderMode = () => {};
+  const google = fakeAdapter();
+  google.prewarm = async () => {};
+  const h = harness(mapillary);
+  h.state.providers.set('google', {
+    def: { id: 'google', name: 'Google Street View', label: 'STREET VIEW' },
+    instance: { viewer: google },
+    on: true,
+  });
+  h.state.providers.get('mapillary').on = true;
+  return { ...h, mapillary, google };
+}
+
+test('the render modes follow the viewer that is open', async () => {
+  const { state, host } = twoProviders();
+  await host.open('mapillary', 'm-1');
+  assert.equal(state.street.renderModes, true);
+  await host.open('google', 'g-1');
+  assert.equal(state.street.renderModes, false, 'Google always fills');
+});
+
+test('a pose can date its image by month and name its place', async () => {
+  const { state, host, google } = twoProviders();
+  await host.open('google', 'g-1');
+  google.emitPose('g-1', {
+    providerId: 'google',
+    capturedAtPrecision: 'month',
+    title: '1014 10th St',
+    capturedAt: Date.UTC(2023, 0, 1),
+  });
+  assert.equal(state.street.capturedAtPrecision, 'month');
+  assert.equal(state.street.title, '1014 10th St');
+  host.close();
+  assert.deepEqual(
+    [state.street.capturedAtPrecision, state.street.title],
+    ['day', null],
+  );
+});
+
+test('FIT/FILL stays hidden for a second Street View panorama after a close', async () => {
+  const { state, host } = twoProviders();
+  await host.open('google', 'g-1');
+  assert.equal(state.street.renderModes, false);
+  host.close();
+  await host.open('google', 'g-2');
+  assert.equal(state.street.renderModes, false);
+});
+
+test('an adapter that can frame but says this image has no frame offers no FIT / FILL', async () => {
+  const adapter = fakeAdapter();
+  let frameable = false;
+  adapter.setRenderMode = () => {};
+  adapter.supportsRenderModes = () => frameable;
+  const { state, host } = harness(adapter);
+  await host.open('mapillary', 'pano-1');
+  assert.equal(state.street.imageId, 'pano-1', 'the pose arrived');
+  assert.equal(state.street.renderModes, false);
+  frameable = true;
+  await host.open('mapillary', 'flat-1');
+  assert.equal(state.street.renderModes, true, 'a flat image can be framed');
+});
+
+test('a pose’s licence reaches the caption state, and a closed viewer forgets it', async () => {
+  const { state, host, google } = twoProviders();
+  await host.open('google', 'g-1');
+  google.emitPose('g-1', { providerId: 'google', license: 'CC BY-SA 4.0' });
+  assert.equal(state.street.license, 'CC BY-SA 4.0');
+  google.emitPose('g-1', { providerId: 'google' });
+  assert.equal(state.street.license, null, 'none given: none shown');
+  google.emitPose('g-1', { providerId: 'google', license: 'CC0' });
+  host.close();
+  assert.equal(state.street.license, null);
+});