@tellegen/svelte 0.3.0 → 0.4.1

package/dist/TellegenProvider.svelte

@@ -16,8 +16,17 @@
 		children?: Snippet;
 	}
 
-	let { apiBase, loadDefaultCases, docsHref, orgHref, orgLabel, showFooter, children }: Props =
-		$props();
+	let {
+		apiBase,
+		loadDefaultCases,
+		docsHref,
+		orgHref,
+		orgLabel,
+		showFooter,
+		theme,
+		cartoApiKey,
+		children
+	}: Props = $props();
 
 	const config = untrack(() =>
 		resolveTellegenUiConfig({
@@ -26,17 +35,40 @@
 			docsHref,
 			orgHref,
 			orgLabel,
-			showFooter
+			showFooter,
+			theme,
+			cartoApiKey
 		})
 	);
 	const app = createAppState();
-	const ctrl = createController(app, { apiBase: config.apiBase });
+	const ctrl = createController(app, {
+		apiBase: config.apiBase,
+		loadDefaultCases: config.loadDefaultCases
+	});
+	// A host that opens its own cases never calls load(), so the shell must not
+	// sit in its loading state waiting for a fetch that will not come.
+	if (!config.loadDefaultCases) ctrl.casesLoaded = true;
 
 	setPanelLayout(new PanelLayout());
 	setNoticeCenter(new NoticeCenter());
 	setUiConfig(config);
 	setAppState(app);
 	setController(ctrl);
+
+	// The dark tokens in styles.css hang off `:root[data-theme='dark']`. Set it
+	// only for dark, and only while mounted, so a light host is untouched. A
+	// server-rendered host that wants no light flash can also put the
+	// attribute in its app template.
+	$effect(() => {
+		if (config.theme !== 'dark') return;
+		const root = document.documentElement;
+		const previous = root.dataset.theme;
+		root.dataset.theme = 'dark';
+		return () => {
+			if (previous === undefined) delete root.dataset.theme;
+			else root.dataset.theme = previous;
+		};
+	});
 </script>
 
 {@render children?.()}

package/dist/TellegenShell.svelte

@@ -9,23 +9,22 @@
 	import RestoreDefaultsButton from './components/RestoreDefaultsButton.svelte';
 	import SolveCard from './components/SolveCard.svelte';
 	import PanelHost from './components/PanelHost.svelte';
-	import { PANEL_COMPACT_QUERY } from './panels.svelte.js';
+	import ShellEnvironment from './components/ShellEnvironment.svelte';
 	import { getAppState, getController, getUiConfig } from './context.svelte.js';
 	import TellegenMap from './TellegenMap.svelte';
 
-	// Gates the drag-and-drop affordance only. The upload button in the header
-	// is always rendered: a file picker works on every device, and the plain
-	// `hover`/`pointer` queries resolve false on a touchscreen laptop that also
-	// has a mouse, which hid the whole file flow there (#110). `any-*` match
-	// when at least one attached input can hover and point precisely.
-	const FILE_DROP_QUERY = '(any-hover: hover) and (any-pointer: fine)';
-
 	const app = getAppState();
 	const ctrl = getController();
 	const config = getUiConfig();
 
 	let dragDepth = 0;
 
+	// ShellEnvironment drops the affordance when no fine pointer is attached;
+	// forget any drag that was in flight so the next one counts from zero.
+	$effect(() => {
+		if (!ctrl.showFileDropUi) dragDepth = 0;
+	});
+
 	$effect(() => {
 		if (app.studyView) return;
 		let hasDisplayMode = false;
@@ -41,44 +40,13 @@
 	});
 
 	onMount(() => {
+		// The provider already marked the shell loaded when default cases are
+		// off, and load() itself is gated; this only frames whatever is there.
 		if (config.loadDefaultCases) {
 			if (!ctrl.casesLoaded) void ctrl.load();
 		} else {
-			ctrl.casesLoaded = true;
-			app.requestFrame('all');
+			void app.requestFrame('all');
 		}
-
-		const query = window.matchMedia(FILE_DROP_QUERY);
-		const syncFileDropUi = () => {
-			ctrl.showFileDropUi = query.matches;
-			if (!ctrl.showFileDropUi) {
-				dragDepth = 0;
-				app.dragOver = false;
-			}
-		};
-		syncFileDropUi();
-		query.addEventListener('change', syncFileDropUi);
-
-		const compact = window.matchMedia(PANEL_COMPACT_QUERY);
-		const syncCompact = () => {
-			app.compactLayout = compact.matches;
-			if (!compact.matches) app.sheetInset = 0;
-		};
-		syncCompact();
-		compact.addEventListener('change', syncCompact);
-
-		// Shared viewport measurements keep panel and map framing dimensions aligned.
-		const syncViewport = () => (app.viewportHeight = window.innerHeight);
-		syncViewport();
-		window.addEventListener('resize', syncViewport);
-		window.addEventListener('orientationchange', syncViewport);
-
-		return () => {
-			query.removeEventListener('change', syncFileDropUi);
-			compact.removeEventListener('change', syncCompact);
-			window.removeEventListener('resize', syncViewport);
-			window.removeEventListener('orientationchange', syncViewport);
-		};
 	});
 
 	function dragHasFiles(e: DragEvent): boolean {
@@ -122,6 +90,8 @@
 	ondrop={onDrop}
 />
 
+<ShellEnvironment />
+
 <main>
 	<TellegenMap
 		onbusclick={ctrl.selectBus}
@@ -132,6 +102,8 @@
 		onmultiedgeclick={ctrl.selectMultiEdge}
 		onplacecase={ctrl.placeCase}
 		onmapclick={ctrl.clearSelection}
+		theme={config.theme}
+		cartoApiKey={config.cartoApiKey || undefined}
 	/>
 
 	<AppHeader />

package/dist/TellegenViewer.svelte

@@ -3,8 +3,16 @@
 	import TellegenShell from './TellegenShell.svelte';
 	import type { TellegenUiOptions } from './context.svelte.js';
 
-	let { apiBase, loadDefaultCases, docsHref, orgHref, orgLabel, showFooter }: TellegenUiOptions =
-		$props();
+	let {
+		apiBase,
+		loadDefaultCases,
+		docsHref,
+		orgHref,
+		orgLabel,
+		showFooter,
+		theme,
+		cartoApiKey
+	}: TellegenUiOptions = $props();
 </script>
 
 <TellegenProvider
@@ -14,6 +22,8 @@
 	{orgHref}
 	{orgLabel}
 	{showFooter}
+	{theme}
+	{cartoApiKey}
 >
 	<TellegenShell />
 </TellegenProvider>

package/dist/api.d.ts

@@ -2,7 +2,9 @@ import type { CaseSummary, DemandDeltas, Network, SensitivityColumn, Solution, S
 export type { BranchRatingDeltas, CaseSummary, DemandDeltas, Network, NetworkBranch, NetworkBus, SensitivityColumn, Solution, SolveIteration } from '@tellegen/engine';
 type FetchLike = (input: string, init?: RequestInit) => Promise<Response>;
 export interface TellegenApiClientOptions {
-    apiBase?: string;
+    /** Backend base path, default `/api`. `null` means no backend: the
+     * factory returns `null` instead of a client. */
+    apiBase?: string | null;
     fetch?: FetchLike;
     EventSource?: typeof EventSource;
 }
@@ -47,4 +49,10 @@ export interface SolveStreamHandlers {
     onfail?: (message: string) => void;
     ondone?: () => void;
 }
-export declare function createApiClient(options?: TellegenApiClientOptions): TellegenApiClient;
+export declare function createApiClient(options: TellegenApiClientOptions & {
+    apiBase: null;
+}): null;
+export declare function createApiClient(options?: TellegenApiClientOptions & {
+    apiBase?: string;
+}): TellegenApiClient;
+export declare function createApiClient(options?: TellegenApiClientOptions): TellegenApiClient | null;

package/dist/api.js

@@ -72,6 +72,8 @@ async function getJson(fetchImpl, url, signal) {
     return res.json();
 }
 export function createApiClient(options = {}) {
+    if (options.apiBase === null)
+        return null;
     const apiBase = options.apiBase ?? '/api';
     const fetchImpl = options.fetch ?? defaultFetch();
     return {

package/dist/basemap.d.ts

@@ -0,0 +1,192 @@
+import type { StyleSpecification } from 'maplibre-gl';
+/** Basemap selection, fallback and tuning for `TellegenMap`.
+ *
+ * CARTO's vector styles sit quietly under a network overlay, and CARTO's
+ * basemap terms ask for an API key (free for non-commercial use, from
+ * carto.com/basemaps/apikey). With a key, the CARTO style leads and
+ * OpenFreeMap (no key, CORS open) is the fallback. Without one, OpenFreeMap
+ * leads and the keyless CARTO style is the fallback. Whenever an OpenFreeMap
+ * style renders, `openFreeMapEdits` tunes it towards CARTO's look. A host can
+ * replace either style with its own URL or inline `StyleSpecification`, or
+ * disable the fallback with `null`. */
+export type BasemapTheme = 'light' | 'dark';
+export type BasemapStyle = string | StyleSpecification;
+/** `TellegenMap`'s `theme` prop: the basemap theme, which also picks the
+ * overlay palette. */
+export type MapTheme = BasemapTheme;
+/** `TellegenMap`'s `projection` prop. MapLibre's globe falls back to
+ * Mercator at high zoom on its own. */
+export type MapProjection = 'mercator' | 'globe';
+/** Who serves a basemap style: one of the two default providers, or
+ * `'custom'` for a style the host supplied. */
+export type BasemapProvider = 'carto' | 'openfreemap' | 'custom';
+export interface BasemapSpec {
+    primary: BasemapStyle;
+    fallback: BasemapStyle | null;
+    /** Hide the style's `symbol` layers after every `style.load`. */
+    hideLabels: boolean;
+    /** Who serves `primary`. Absent counts as `'custom'`. */
+    primaryProvider?: BasemapProvider;
+    /** Who serves `fallback`, `null` with no fallback. Absent counts as
+     * `'custom'`. */
+    fallbackProvider?: BasemapProvider | null;
+}
+/** A `BasemapSpec` that names both providers, as `defaultBasemap` and
+ * `resolveBasemap` return it. A host words its credits and fallback notice
+ * from these instead of reading style URLs. */
+export interface ResolvedBasemap extends BasemapSpec {
+    primaryProvider: BasemapProvider;
+    fallbackProvider: BasemapProvider | null;
+}
+/** What `defaultBasemap` returns: one CARTO and one OpenFreeMap style URL,
+ * in the order the key decides. Never `'custom'`, and never without a
+ * fallback. */
+export interface DefaultBasemap extends ResolvedBasemap {
+    primary: string;
+    fallback: string;
+    primaryProvider: 'carto' | 'openfreemap';
+    fallbackProvider: 'carto' | 'openfreemap';
+}
+export declare const OPENFREEMAP_STYLES: {
+    readonly light: "https://tiles.openfreemap.org/styles/positron";
+    readonly dark: "https://tiles.openfreemap.org/styles/dark";
+};
+export declare const CARTO_STYLES: {
+    readonly light: "https://basemaps.cartocdn.com/gl/positron-gl-style/style.json";
+    readonly 'light-nolabels': "https://basemaps.cartocdn.com/gl/positron-nolabels-gl-style/style.json";
+    readonly dark: "https://basemaps.cartocdn.com/gl/dark-matter-gl-style/style.json";
+    readonly 'dark-nolabels': "https://basemaps.cartocdn.com/gl/dark-matter-nolabels-gl-style/style.json";
+};
+/** A CARTO key with surrounding whitespace removed, or `undefined` when
+ * nothing is left. A variable saved with a stray newline or space must not
+ * count as a key. */
+export declare function normalizeCartoApiKey(apiKey: string | undefined): string | undefined;
+/** A CARTO style URL with the optional API key appended as `key=`. A blank
+ * key appends nothing. */
+export declare function cartoStyleUrl(style: string, apiKey?: string): string;
+export interface DefaultBasemapOptions {
+    /** CARTO basemap key, sent as `key=`. With one, CARTO leads and
+     * OpenFreeMap is the fallback; without one, the order flips. The key is
+     * trimmed, and a blank one counts as none. Restrict the key to the hosts
+     * that serve your app. */
+    cartoApiKey?: string;
+    /** Default `true`: the CARTO style uses its `-nolabels` variant, and label
+     * layers are hidden on load whichever style renders. */
+    hideLabels?: boolean;
+}
+/** The default primary and fallback for a theme, ordered by whether a CARTO
+ * key is at hand. */
+export declare function defaultBasemap(theme: BasemapTheme, options?: DefaultBasemapOptions): DefaultBasemap;
+export interface ResolveBasemapInput {
+    /** Overrides the default primary. */
+    mapStyle?: BasemapStyle;
+    /** Overrides the default fallback; `null` disables the fallback. */
+    fallbackMapStyle?: BasemapStyle | null;
+    theme: BasemapTheme;
+    hideBasemapLabels: boolean;
+    cartoApiKey?: string;
+}
+/** The spec `TellegenMap` renders from its props: explicit styles win, the
+ * theme fills in whatever is left, and `null` turns the fallback off. An
+ * explicit style is `'custom'`, whichever host serves it. */
+export declare function resolveBasemap(input: ResolveBasemapInput): ResolvedBasemap;
+/** Whether a style draws on OpenFreeMap's tiles, whichever URL loaded it. */
+export declare function isOpenFreeMapStyle(style: StyleSpecification): boolean;
+/** One change to a loaded style, applied through the map's own API. */
+export type StyleEdit = {
+    kind: 'zoom-range';
+    layer: string;
+    minzoom: number;
+    maxzoom: number;
+} | {
+    kind: 'paint';
+    layer: string;
+    property: 'fill-color' | 'line-color';
+    value: string;
+};
+/** Edits that let an OpenFreeMap style sit under a network overlay the way
+ * CARTO's styles do.
+ *
+ * - Road lines (`transportation`) start at z8.
+ * - In the dark theme, water and waterways take Dark Matter's colours, and
+ *   plain land fills (`landuse`, `landcover`, `park`) take the style's
+ *   background colour, so the water stands out against one tone of land.
+ *
+ * Layers are matched by `source-layer`, not by id, so the edits still apply
+ * when OpenFreeMap renames its layers. */
+export declare function openFreeMapEdits(style: StyleSpecification, theme: BasemapTheme): StyleEdit[];
+/** The providers a fallback event concerns. */
+export interface BasemapSwitch {
+    /** The provider whose style failed. */
+    from: BasemapProvider;
+    /** The provider switched to; `null` when no basemap is left to show. */
+    to: BasemapProvider | null;
+}
+type BasemapFailure = {
+    kind: 'style-load';
+    message: string;
+    status?: number;
+} | {
+    kind: 'source-forbidden';
+    message: string;
+    status: number;
+    sourceId: string;
+} | {
+    kind: 'tiles-unavailable';
+    message: string;
+    sourceId: string;
+} | {
+    kind: 'webgl';
+    message: string;
+};
+export type BasemapFallbackReason = BasemapFailure & BasemapSwitch;
+/** The fields of a MapLibre `error` or `sourcedata` event the fallback reads. */
+export interface BasemapMapEvent {
+    error?: unknown;
+    sourceId?: string;
+    tile?: unknown;
+    dataType?: string;
+    isSourceLoaded?: boolean;
+}
+/** The slice of `maplibregl.Map` the fallback needs; a test drives a fake. */
+export interface BasemapMapLike {
+    on(type: string, listener: (event: BasemapMapEvent) => void): unknown;
+    off(type: string, listener: (event: BasemapMapEvent) => void): unknown;
+    setStyle(style: BasemapStyle, options?: {
+        diff?: boolean;
+    }): unknown;
+    /** MapLibre types this `boolean | void`; only `true` counts as loaded. */
+    isStyleLoaded(): boolean | void;
+}
+export interface BasemapFallbackHandlers {
+    /** The primary failed and the fallback style was requested. `from` is the
+     * spec's primary provider and `to` its fallback provider. */
+    onFallback?(reason: BasemapFallbackReason): void;
+    /** No basemap can be shown: the fallback failed too, none was configured,
+     * or WebGL is unavailable. `from` is the provider on screen, `to` is
+     * `null`. */
+    onFailure?(reason: BasemapFallbackReason): void;
+}
+export interface BasemapFallbackOptions {
+    /** Clock for the tile failure window; tests inject one. */
+    now?: () => number;
+}
+/** Watch a map's `error` stream and switch to `spec.fallback` when the
+ * primary basemap cannot be shown. Rules, in order:
+ *
+ * 1. an error with no `sourceId` before the first `style.load` is a style
+ *    fetch failure: switch to the fallback once;
+ * 2. a source or tile error with status 401, 403 or 429, or a message naming
+ *    an API key, forbidden or unauthorized access: switch;
+ * 3. more than six tile fetch failures within ten seconds while no tile of
+ *    any source has arrived: switch. A failure is a network error with no
+ *    status, or an HTTP 5xx answer;
+ * 4. a WebGL error: report failure, no style can help;
+ * 5. everything else is logged the way MapLibre logs an unhandled error,
+ *    because registering this listener silences that default.
+ *
+ * After the switch the same rules report `onFailure` instead of switching
+ * again, as they do when `spec.fallback` is `null`. Returns a detach
+ * function. */
+export declare function attachBasemapFallback(map: BasemapMapLike, spec: BasemapSpec, handlers?: BasemapFallbackHandlers, options?: BasemapFallbackOptions): () => void;
+export {};

package/dist/basemap.js

@@ -0,0 +1,259 @@
+export const OPENFREEMAP_STYLES = {
+    light: 'https://tiles.openfreemap.org/styles/positron',
+    dark: 'https://tiles.openfreemap.org/styles/dark'
+};
+export const CARTO_STYLES = {
+    light: 'https://basemaps.cartocdn.com/gl/positron-gl-style/style.json',
+    'light-nolabels': 'https://basemaps.cartocdn.com/gl/positron-nolabels-gl-style/style.json',
+    dark: 'https://basemaps.cartocdn.com/gl/dark-matter-gl-style/style.json',
+    'dark-nolabels': 'https://basemaps.cartocdn.com/gl/dark-matter-nolabels-gl-style/style.json'
+};
+/** A CARTO key with surrounding whitespace removed, or `undefined` when
+ * nothing is left. A variable saved with a stray newline or space must not
+ * count as a key. */
+export function normalizeCartoApiKey(apiKey) {
+    return apiKey?.trim() || undefined;
+}
+/** A CARTO style URL with the optional API key appended as `key=`. A blank
+ * key appends nothing. */
+export function cartoStyleUrl(style, apiKey) {
+    const key = normalizeCartoApiKey(apiKey);
+    if (!key)
+        return style;
+    const separator = style.includes('?') ? '&' : '?';
+    return `${style}${separator}key=${encodeURIComponent(key)}`;
+}
+/** The default primary and fallback for a theme, ordered by whether a CARTO
+ * key is at hand. */
+export function defaultBasemap(theme, options = {}) {
+    const hideLabels = options.hideLabels ?? true;
+    const variant = hideLabels ? `${theme}-nolabels` : theme;
+    const key = normalizeCartoApiKey(options.cartoApiKey);
+    const carto = cartoStyleUrl(CARTO_STYLES[variant], key);
+    const openFreeMap = OPENFREEMAP_STYLES[theme];
+    return key
+        ? {
+            primary: carto,
+            fallback: openFreeMap,
+            hideLabels,
+            primaryProvider: 'carto',
+            fallbackProvider: 'openfreemap'
+        }
+        : {
+            primary: openFreeMap,
+            fallback: carto,
+            hideLabels,
+            primaryProvider: 'openfreemap',
+            fallbackProvider: 'carto'
+        };
+}
+/** The spec `TellegenMap` renders from its props: explicit styles win, the
+ * theme fills in whatever is left, and `null` turns the fallback off. An
+ * explicit style is `'custom'`, whichever host serves it. */
+export function resolveBasemap(input) {
+    const defaults = defaultBasemap(input.theme, {
+        cartoApiKey: input.cartoApiKey,
+        hideLabels: input.hideBasemapLabels
+    });
+    const fallback = input.fallbackMapStyle;
+    return {
+        primary: input.mapStyle ?? defaults.primary,
+        fallback: fallback === undefined ? defaults.fallback : fallback,
+        hideLabels: input.hideBasemapLabels,
+        primaryProvider: input.mapStyle === undefined ? defaults.primaryProvider : 'custom',
+        fallbackProvider: fallback === undefined ? defaults.fallbackProvider : fallback === null ? null : 'custom'
+    };
+}
+const OPENFREEMAP_TILES = 'https://tiles.openfreemap.org/';
+/** Road lines start here on an OpenFreeMap style. Below it, the road web
+ * reads like grid lines under a network overlay. */
+const ROAD_MIN_ZOOM = 8;
+/** CARTO Dark Matter's water and waterway colours, which stand clear of
+ * near-black land. */
+const DARK_WATER = '#2c353c';
+const DARK_WATERWAY = '#3f5a6d';
+const LAND_SOURCE_LAYERS = new Set(['landuse', 'landcover', 'park']);
+/** Whether a style draws on OpenFreeMap's tiles, whichever URL loaded it. */
+export function isOpenFreeMapStyle(style) {
+    return Object.values(style.sources ?? {}).some((source) => {
+        const urls = [
+            'url' in source ? source.url : undefined,
+            ...('tiles' in source ? (source.tiles ?? []) : [])
+        ];
+        return urls.some((url) => typeof url === 'string' && url.startsWith(OPENFREEMAP_TILES));
+    });
+}
+/** Edits that let an OpenFreeMap style sit under a network overlay the way
+ * CARTO's styles do.
+ *
+ * - Road lines (`transportation`) start at z8.
+ * - In the dark theme, water and waterways take Dark Matter's colours, and
+ *   plain land fills (`landuse`, `landcover`, `park`) take the style's
+ *   background colour, so the water stands out against one tone of land.
+ *
+ * Layers are matched by `source-layer`, not by id, so the edits still apply
+ * when OpenFreeMap renames its layers. */
+export function openFreeMapEdits(style, theme) {
+    const paintOf = (layer) => (layer.paint ?? {});
+    const background = style.layers.find((layer) => layer.type === 'background');
+    const backgroundColor = background ? paintOf(background)['background-color'] : undefined;
+    // A plain colour only; an expression is left alone rather than guessed at.
+    const land = typeof backgroundColor === 'string' ? backgroundColor : undefined;
+    const edits = [];
+    for (const layer of style.layers) {
+        const sourceLayer = 'source-layer' in layer ? layer['source-layer'] : undefined;
+        if (sourceLayer === undefined)
+            continue;
+        if (sourceLayer === 'transportation' && layer.type === 'line') {
+            if ((layer.minzoom ?? 0) < ROAD_MIN_ZOOM) {
+                edits.push({
+                    kind: 'zoom-range',
+                    layer: layer.id,
+                    minzoom: ROAD_MIN_ZOOM,
+                    maxzoom: layer.maxzoom ?? 24
+                });
+            }
+        }
+        else if (theme === 'dark' && sourceLayer === 'water' && layer.type === 'fill') {
+            edits.push({ kind: 'paint', layer: layer.id, property: 'fill-color', value: DARK_WATER });
+        }
+        else if (theme === 'dark' && sourceLayer === 'waterway' && layer.type === 'line') {
+            edits.push({ kind: 'paint', layer: layer.id, property: 'line-color', value: DARK_WATERWAY });
+        }
+        else if (theme === 'dark' &&
+            land !== undefined &&
+            layer.type === 'fill' &&
+            LAND_SOURCE_LAYERS.has(sourceLayer) &&
+            paintOf(layer)['fill-pattern'] === undefined) {
+            edits.push({ kind: 'paint', layer: layer.id, property: 'fill-color', value: land });
+        }
+    }
+    return edits;
+}
+/** Tile fetch failures from one source, with no tile of any source arriving,
+ * that trip the fallback inside the window. */
+const TILE_FAILURE_LIMIT = 6;
+const TILE_FAILURE_WINDOW_MS = 10_000;
+const FORBIDDEN_STATUSES = new Set([401, 403, 429]);
+const FORBIDDEN_MESSAGE = /api key|forbidden|unauthorized/i;
+const NETWORK_MESSAGE = /failed to fetch|load failed|network ?error|network request failed/i;
+const WEBGL_MESSAGE = /webgl/i;
+function errorMessage(error) {
+    if (error instanceof Error)
+        return error.message;
+    if (typeof error === 'string')
+        return error;
+    if (error && typeof error === 'object' && 'message' in error)
+        return String(error.message);
+    return error === undefined || error === null ? '' : String(error);
+}
+function errorStatus(error) {
+    if (error && typeof error === 'object' && 'status' in error) {
+        const status = error.status;
+        if (typeof status === 'number')
+            return status;
+    }
+    return undefined;
+}
+/** Watch a map's `error` stream and switch to `spec.fallback` when the
+ * primary basemap cannot be shown. Rules, in order:
+ *
+ * 1. an error with no `sourceId` before the first `style.load` is a style
+ *    fetch failure: switch to the fallback once;
+ * 2. a source or tile error with status 401, 403 or 429, or a message naming
+ *    an API key, forbidden or unauthorized access: switch;
+ * 3. more than six tile fetch failures within ten seconds while no tile of
+ *    any source has arrived: switch. A failure is a network error with no
+ *    status, or an HTTP 5xx answer;
+ * 4. a WebGL error: report failure, no style can help;
+ * 5. everything else is logged the way MapLibre logs an unhandled error,
+ *    because registering this listener silences that default.
+ *
+ * After the switch the same rules report `onFailure` instead of switching
+ * again, as they do when `spec.fallback` is `null`. Returns a detach
+ * function. */
+export function attachBasemapFallback(map, spec, handlers = {}, options = {}) {
+    const now = options.now ?? (() => Date.now());
+    const primaryProvider = spec.primaryProvider ?? 'custom';
+    const fallbackProvider = spec.fallback === null ? null : (spec.fallbackProvider ?? 'custom');
+    let styleLoaded = map.isStyleLoaded() === true;
+    let fellBack = false;
+    let failed = false;
+    let tileFailures = 0;
+    let tileWindowStart = 0;
+    let tileArrived = false;
+    const fail = (reason) => {
+        if (failed)
+            return;
+        failed = true;
+        const from = fellBack && fallbackProvider !== null ? fallbackProvider : primaryProvider;
+        handlers.onFailure?.({ ...reason, from, to: null });
+    };
+    const fallBack = (reason) => {
+        if (fellBack || spec.fallback === null) {
+            fail(reason);
+            return;
+        }
+        fellBack = true;
+        styleLoaded = false;
+        tileFailures = 0;
+        tileArrived = false;
+        handlers.onFallback?.({ ...reason, from: primaryProvider, to: fallbackProvider });
+        map.setStyle(spec.fallback, { diff: false });
+    };
+    const passThrough = (event) => {
+        console.error(event?.error ?? event ?? 'Empty error event');
+    };
+    const onStyleLoad = () => {
+        styleLoaded = true;
+    };
+    const onSourceData = (event) => {
+        if (event?.tile || event?.isSourceLoaded === true)
+            tileArrived = true;
+    };
+    const onError = (event) => {
+        const message = errorMessage(event?.error);
+        const status = errorStatus(event?.error);
+        if (WEBGL_MESSAGE.test(message)) {
+            fail({ kind: 'webgl', message });
+            return;
+        }
+        const sourceId = typeof event?.sourceId === 'string' ? event.sourceId : undefined;
+        if (sourceId === undefined) {
+            if (!styleLoaded) {
+                fallBack({ kind: 'style-load', message, status });
+                return;
+            }
+            passThrough(event);
+            return;
+        }
+        if ((status !== undefined && FORBIDDEN_STATUSES.has(status)) ||
+            FORBIDDEN_MESSAGE.test(message)) {
+            fallBack({ kind: 'source-forbidden', message, status: status ?? 0, sourceId });
+            return;
+        }
+        const transient = status === undefined || status === 0 ? NETWORK_MESSAGE.test(message) : status >= 500;
+        if (event.tile && transient) {
+            const t = now();
+            if (tileFailures === 0 || t - tileWindowStart > TILE_FAILURE_WINDOW_MS) {
+                tileWindowStart = t;
+                tileFailures = 0;
+                tileArrived = false;
+            }
+            tileFailures++;
+            if (tileFailures > TILE_FAILURE_LIMIT && !tileArrived) {
+                fallBack({ kind: 'tiles-unavailable', message, sourceId });
+                return;
+            }
+        }
+        passThrough(event);
+    };
+    map.on('style.load', onStyleLoad);
+    map.on('sourcedata', onSourceData);
+    map.on('error', onError);
+    return () => {
+        map.off('style.load', onStyleLoad);
+        map.off('sourcedata', onSourceData);
+        map.off('error', onError);
+    };
+}