@walkthru-earth/objex 1.2.1 → 1.3.0

package/dist/components/viewers/StacTabViewer.svelte

@@ -0,0 +1,254 @@
+<script lang="ts">
+import CodeIcon from '@lucide/svelte/icons/file-code';
+import GlobeIcon from '@lucide/svelte/icons/globe';
+import LayersIcon from '@lucide/svelte/icons/layers';
+import MapIcon from '@lucide/svelte/icons/map';
+import { t } from '../../i18n/index.svelte.js';
+import { connectionStore } from '../../stores/connections.svelte.js';
+import type { Tab } from '../../types.js';
+import type { StacRoutableKind } from '../../utils/stac.js';
+import { canStreamDirectly } from '../../utils/url.js';
+import { getUrlView, updateUrlView } from '../../utils/url-state.js';
+import { Badge } from '../ui/badge/index.js';
+import { Button } from '../ui/button/index.js';
+import * as Tooltip from '../ui/tooltip/index.js';
+import CodeViewer from './CodeViewer.svelte';
+import StacMapViewer from './StacMapViewer.svelte';
+import TableViewer from './TableViewer.svelte';
+
+type MapKind = 'mosaic' | 'multicog' | null;
+
+interface Props {
+	tab: Tab;
+	/** Which map viewer to mount when the user switches to `#map`. */
+	mapKind: MapKind;
+	/** Pre-classified STAC payload, forwarded to map viewers to skip re-parsing. */
+	classified?: StacRoutableKind;
+}
+
+let { tab, mapKind, classified }: Props = $props();
+
+type ViewMode = 'map' | 'stac-map' | 'stac-browser' | 'code';
+
+interface CodeActions {
+	toggleFormat: () => Promise<void>;
+	copyCode: () => Promise<void>;
+	canFormat: boolean;
+	formatted: boolean;
+	copied: boolean;
+}
+
+// Cross-origin STAC iframes (Radiant Earth stac-browser, DevSeed stac-map)
+// crawl sibling items with their own fetch client and have no access to our
+// presigned URLs. On signed-s3 connections the top manifest still renders but
+// every child link 403s — keep the buttons available and surface a warning
+// tooltip so the user can still preview the root document and knows why
+// crawling children fails.
+const iframeCrawlReachable = $derived.by(() => {
+	if (tab.source === 'url') return true;
+	if (!tab.connectionId) return true;
+	const conn = connectionStore.getById(tab.connectionId);
+	if (!conn) return true;
+	return canStreamDirectly(tab);
+});
+
+const isParquet = $derived.by(() => {
+	const ext = (tab.extension ?? '').toLowerCase();
+	return ext === 'parquet' || ext === 'geoparquet';
+});
+
+const formatBadge = $derived(isParquet ? 'Parquet' : 'JSON');
+
+const stacBadgeKey = $derived.by(() => {
+	if (isParquet) return 'code.stacGeoparquet';
+	const kind = classified?.kind;
+	if (kind === 'item') return 'code.stacItem';
+	if (kind === 'item-collection') return 'code.stacItem';
+	if (kind === 'collection') return 'code.stacCollection';
+	if (kind === 'catalog') return 'code.stacCatalog';
+	return null;
+});
+
+function initialView(): ViewMode {
+	const urlView = getUrlView();
+	if (urlView === 'map' && mapKind) return 'map';
+	if (urlView === 'stac-map') return 'stac-map';
+	if (urlView === 'stac-browser') return 'stac-browser';
+	if (urlView === 'code') return 'code';
+	if (mapKind) return 'map';
+	return 'stac-map';
+}
+
+let viewMode = $state<ViewMode>(initialView());
+let wordWrap = $state(false);
+let codeActions = $state<CodeActions | null>(null);
+
+function setView(next: ViewMode) {
+	if (viewMode === next) return;
+	viewMode = next;
+	updateUrlView(next === 'map' ? 'map' : next);
+}
+</script>
+
+<Tooltip.Provider>
+<div class="flex h-full flex-col overflow-hidden">
+	{#key tab.id}
+		<div
+			class="flex items-center gap-1 border-b border-zinc-200 px-2 py-1.5 sm:gap-2 sm:px-4 dark:border-zinc-800"
+		>
+			<span
+				class="max-w-[120px] truncate text-sm font-medium text-zinc-700 sm:max-w-none dark:text-zinc-300"
+			>
+				{tab.name}
+			</span>
+			<Badge variant="secondary">{formatBadge}</Badge>
+			{#if stacBadgeKey}
+				<Badge
+					variant="outline"
+					class="hidden border-emerald-200 text-emerald-600 sm:inline-flex dark:border-emerald-800 dark:text-emerald-300"
+				>
+					{t(stacBadgeKey)}
+				</Badge>
+			{/if}
+
+			<div class="ms-auto flex items-center gap-1 sm:gap-2">
+				{#if mapKind}
+					<Button
+						size="sm"
+						variant={viewMode === 'map' ? 'default' : 'ghost'}
+						class="h-7 gap-1 px-2"
+						onclick={() => setView('map')}
+					>
+						<MapIcon class="size-3.5" />
+						{mapKind === 'multicog' ? t('stac.viewMultiCog') : t('stac.viewMosaic')}
+					</Button>
+				{/if}
+				{#if iframeCrawlReachable}
+					<Button
+						size="sm"
+						variant={viewMode === 'stac-map' ? 'default' : 'ghost'}
+						class="h-7 gap-1 px-2"
+						onclick={() => setView('stac-map')}
+					>
+						<LayersIcon class="size-3.5" />
+						{t('stac.viewStacMap')}
+					</Button>
+					{#if isParquet}
+						<Tooltip.Root>
+							<Tooltip.Trigger>
+								<Button
+									size="sm"
+									variant="ghost"
+									class="h-7 gap-1 px-2 opacity-50"
+									disabled
+								>
+									<GlobeIcon class="size-3.5" />
+									{t('stac.viewBrowser')}
+								</Button>
+							</Tooltip.Trigger>
+							<Tooltip.Content>{t('stac.stacBrowserJsonOnly')}</Tooltip.Content>
+						</Tooltip.Root>
+					{:else}
+						<Button
+							size="sm"
+							variant={viewMode === 'stac-browser' ? 'default' : 'ghost'}
+							class="h-7 gap-1 px-2"
+							onclick={() => setView('stac-browser')}
+						>
+							<GlobeIcon class="size-3.5" />
+							{t('stac.viewBrowser')}
+						</Button>
+					{/if}
+				{:else}
+					<Tooltip.Root>
+						<Tooltip.Trigger>
+							<Button
+								size="sm"
+								variant={viewMode === 'stac-map' ? 'default' : 'ghost'}
+								class="h-7 gap-1 px-2"
+								onclick={() => setView('stac-map')}
+							>
+								<LayersIcon class="size-3.5" />
+								{t('stac.viewStacMap')}
+							</Button>
+						</Tooltip.Trigger>
+						<Tooltip.Content>{t('stac.iframePrivateBucketWarning')}</Tooltip.Content>
+					</Tooltip.Root>
+					<Tooltip.Root>
+						<Tooltip.Trigger>
+							<Button
+								size="sm"
+								variant={viewMode === 'stac-browser' ? 'default' : 'ghost'}
+								class="h-7 gap-1 px-2"
+								onclick={() => setView('stac-browser')}
+							>
+								<GlobeIcon class="size-3.5" />
+								{t('stac.viewBrowser')}
+							</Button>
+						</Tooltip.Trigger>
+						<Tooltip.Content>{t('stac.iframePrivateBucketWarning')}</Tooltip.Content>
+					</Tooltip.Root>
+				{/if}
+				<Button
+					size="sm"
+					variant={viewMode === 'code' ? 'default' : 'ghost'}
+					class="h-7 gap-1 px-2"
+					onclick={() => setView('code')}
+				>
+					<CodeIcon class="size-3.5" />
+					{isParquet ? t('stac.viewTable') : t('stac.viewJson')}
+				</Button>
+
+				{#if viewMode === 'code' && !isParquet && codeActions}
+					{#if codeActions.canFormat}
+						<Button
+							variant="ghost"
+							size="sm"
+							class="h-7 px-2 text-xs"
+							onclick={() => codeActions?.toggleFormat()}
+						>
+							{codeActions.formatted ? t('code.raw') : t('code.format')}
+						</Button>
+					{/if}
+					<Button
+						variant="ghost"
+						size="sm"
+						class="h-7 px-2 text-xs"
+						onclick={() => (wordWrap = !wordWrap)}
+					>
+						{wordWrap ? t('code.noWrap') : t('code.wrap')}
+					</Button>
+					<Button
+						variant="ghost"
+						size="sm"
+						class="h-7 px-2 text-xs"
+						onclick={() => codeActions?.copyCode()}
+					>
+						{codeActions.copied ? t('code.copied') : t('code.copy')}
+					</Button>
+				{/if}
+			</div>
+		</div>
+
+		<div class="relative flex-1 overflow-hidden">
+			{#if viewMode === 'map' && mapKind === 'mosaic'}
+				{#await import('./StacMosaicViewer.svelte') then { default: StacMosaicViewer }}
+					<StacMosaicViewer {tab} {classified} />
+				{/await}
+			{:else if viewMode === 'map' && mapKind === 'multicog'}
+				{#await import('./MultiCogViewer.svelte') then { default: MultiCogViewer }}
+					<MultiCogViewer {tab} {classified} />
+				{/await}
+			{:else if viewMode === 'stac-map'}
+				<StacMapViewer {tab} variant="stac-map" />
+			{:else if viewMode === 'stac-browser'}
+				<StacMapViewer {tab} variant="stac-browser" />
+			{:else if isParquet}
+				<TableViewer {tab} />
+			{:else}
+				<CodeViewer {tab} nested bind:wordWrap bind:actions={codeActions} />
+			{/if}
+		</div>
+	{/key}
+</div>
+</Tooltip.Provider>

package/dist/components/viewers/StacTabViewer.svelte.d.ts

@@ -0,0 +1,13 @@
+import type { Tab } from '../../types.js';
+import type { StacRoutableKind } from '../../utils/stac.js';
+type MapKind = 'mosaic' | 'multicog' | null;
+interface Props {
+    tab: Tab;
+    /** Which map viewer to mount when the user switches to `#map`. */
+    mapKind: MapKind;
+    /** Pre-classified STAC payload, forwarded to map viewers to skip re-parsing. */
+    classified?: StacRoutableKind;
+}
+declare const StacTabViewer: import("svelte").Component<Props, {}, "">;
+type StacTabViewer = ReturnType<typeof StacTabViewer>;
+export default StacTabViewer;

package/dist/components/viewers/ViewerRouter.svelte

@@ -1,19 +1,170 @@
 <script lang="ts">
 import { getViewerKind } from '../../file-icons/index.js';
-import type { Tab } from '../../types';
+import { getAdapter } from '../../storage/index.js';
+import type { Tab } from '../../types.js';
+import { readParquetMetadata } from '../../utils/parquet-metadata.js';
+import {
+	classifyStac,
+	detectMosaicCapable,
+	detectMultiCogCapable,
+	type StacRoutableKind
+} from '../../utils/stac.js';
+import { isStacGeoparquetSchema } from '../../utils/stac-geoparquet.js';
+import { STAC_API_PATH_RE } from '../../utils/storage-url.js';
+import { buildHttpsUrlAsync } from '../../utils/url.js';
 import CodeViewer from './CodeViewer.svelte';
 import ImageViewer from './ImageViewer.svelte';
 import MediaViewer from './MediaViewer.svelte';
 import RawViewer from './RawViewer.svelte';
+import StacTabViewer from './StacTabViewer.svelte';
 import TableViewer from './TableViewer.svelte';
 
 let { tab }: { tab: Tab } = $props();
 
 const ext = $derived(tab?.extension ?? '');
 const viewerKind = $derived(getViewerKind(ext));
+
+type StacRoute =
+	| { kind: 'pending' }
+	| { kind: 'none' }
+	| { kind: 'stac'; mapKind: 'mosaic' | 'multicog' | null; classified: StacRoutableKind };
+const MAX_STAC_PEEK = 256 * 1024;
+
+let stacRoute = $state<StacRoute>({ kind: 'none' });
+let stacSignalCtrl: AbortController | null = null;
+
+$effect(() => {
+	// Track the full tab identity so auto-migration (eager `url` tab → remote
+	// tab with a real connectionId) re-runs classification with the now-valid
+	// adapter. Without these reads the effect only depends on `ext`, and a
+	// stale 403 would leave the file stuck on the non-STAC CodeViewer path.
+	const tabId = tab.id;
+	const tabPath = tab.path;
+	const tabSource = tab.source;
+	const tabConn = tab.connectionId;
+	void tabId;
+	void tabPath;
+	void tabSource;
+	void tabConn;
+
+	const currentExt = ext.toLowerCase().replace(/^\./, '');
+	const isJsonExt = currentExt === 'json' || currentExt === 'geojson';
+	// STAC API endpoints return `application/geo+json` at extensionless paths
+	// like `/v1/collections/.../items/S2B_18TVK_20240928_0_L2A`, so we still
+	// peek when the basename has no dot.
+	const isExtensionless = !currentExt;
+	const viewerEligible = viewerKind === 'code' || viewerKind === 'raw';
+	let isStacPath = false;
+	if (isExtensionless) {
+		try {
+			isStacPath = STAC_API_PATH_RE.test(new URL(tab.path).pathname);
+		} catch {
+			isStacPath = false;
+		}
+	}
+	const isParquetExt = currentExt === 'parquet' || currentExt === 'geoparquet';
+	const shouldPeek = viewerEligible && (isJsonExt || (isExtensionless && isStacPath));
+	stacSignalCtrl?.abort();
+	if (!shouldPeek && !isParquetExt) {
+		stacRoute = { kind: 'none' };
+		return;
+	}
+	stacRoute = { kind: 'pending' };
+	const ctrl = new AbortController();
+	stacSignalCtrl = ctrl;
+	const detector = isParquetExt
+		? detectStacGeoparquet(tab, ctrl.signal)
+		: detectStac(tab, ctrl.signal);
+	void detector.then((result) => {
+		if (ctrl.signal.aborted) return;
+		stacRoute = result;
+	});
+	return () => ctrl.abort();
+});
+
+async function detectStacGeoparquet(current: Tab, signal: AbortSignal): Promise<StacRoute> {
+	try {
+		const url = await buildHttpsUrlAsync(current);
+		if (signal.aborted) return { kind: 'none' };
+		const meta = await readParquetMetadata(url);
+		if (signal.aborted) return { kind: 'none' };
+		// Use top-level column names so struct parents (`assets`, `bbox`) are
+		// visible. `meta.schema` flattens structs away, which hides the very
+		// columns stac-geoparquet detection keys on.
+		const topLevel = meta.topLevelColumns.map((name) => ({ name }));
+		if (!isStacGeoparquetSchema(topLevel)) return { kind: 'none' };
+		return {
+			kind: 'stac',
+			mapKind: 'mosaic',
+			classified: { kind: 'item-collection', fc: { type: 'FeatureCollection', features: [] } }
+		};
+	} catch {
+		return { kind: 'none' };
+	}
+}
+
+async function detectStac(current: Tab, signal: AbortSignal): Promise<StacRoute> {
+	const adapter = getAdapter(current.source, current.connectionId);
+	const decoder = new TextDecoder('utf-8', { fatal: false });
+
+	// Peek the first 256 KB first; a small catalog/collection parses outright.
+	// STAC Items with detailed asset metadata + dense footprint coordinates
+	// frequently blow past that, so on a parse failure we fall back to the
+	// full file. Network errors (403, CORS) short-circuit to `none`.
+	// `classifyStac` already returns `{ kind: 'none' }` for any JSON that
+	// isn't a STAC Item/Collection/Catalog/ItemCollection — propagate that
+	// so plain JSON files don't route through StacTabViewer (which exposes
+	// the stac-map / STAC Browser buttons).
+	try {
+		const peek = await adapter.read(current.path, 0, MAX_STAC_PEEK, signal);
+		if (signal.aborted) return { kind: 'none' };
+		try {
+			const parsed = JSON.parse(decoder.decode(peek));
+			const classified = classifyStac(parsed);
+			if (classified.kind === 'none') return { kind: 'none' };
+			return { kind: 'stac', mapKind: pickMapKind(classified), classified };
+		} catch {
+			if (peek.byteLength < MAX_STAC_PEEK) return { kind: 'none' };
+		}
+	} catch {
+		return { kind: 'none' };
+	}
+
+	try {
+		const full = await adapter.read(current.path, undefined, undefined, signal);
+		if (signal.aborted) return { kind: 'none' };
+		const parsed = JSON.parse(decoder.decode(full));
+		const classified = classifyStac(parsed);
+		if (classified.kind === 'none') return { kind: 'none' };
+		return { kind: 'stac', mapKind: pickMapKind(classified), classified };
+	} catch {
+		return { kind: 'none' };
+	}
+}
+
+function pickMapKind(classified: StacRoutableKind): 'mosaic' | 'multicog' | null {
+	switch (classified.kind) {
+		case 'item':
+			if (detectMultiCogCapable(classified.item)) return 'multicog';
+			if (detectMosaicCapable(classified.item)) return 'mosaic';
+			return null;
+		case 'item-collection': {
+			const first = classified.fc.features[0];
+			if (first && detectMultiCogCapable(first)) return 'multicog';
+			return 'mosaic';
+		}
+		case 'collection':
+		case 'catalog':
+			return 'mosaic';
+		case 'none':
+			return null;
+	}
+}
 </script>
 
-{#if viewerKind === 'table'}
+{#if stacRoute.kind === 'stac' && viewerKind === 'table'}
+	<StacTabViewer {tab} mapKind={stacRoute.mapKind} classified={stacRoute.classified} />
+{:else if viewerKind === 'table'}
 	<TableViewer {tab} />
 {:else if viewerKind === 'image'}
 	<ImageViewer {tab} />
@@ -23,6 +174,8 @@ const viewerKind = $derived(getViewerKind(ext));
 	{#await import('./MarkdownViewer.svelte') then { default: MarkdownViewer }}
 		<MarkdownViewer {tab} />
 	{/await}
+{:else if stacRoute.kind === 'stac' && (viewerKind === 'code' || viewerKind === 'raw')}
+	<StacTabViewer {tab} mapKind={stacRoute.mapKind} classified={stacRoute.classified} />
 {:else if viewerKind === 'code'}
 	<CodeViewer {tab} />
 {:else if viewerKind === 'cog'}

package/dist/components/viewers/ViewerRouter.svelte.d.ts

@@ -1,4 +1,4 @@
-import type { Tab } from '../../types';
+import type { Tab } from '../../types.js';
 type $$ComponentProps = {
     tab: Tab;
 };

package/dist/components/viewers/ZarrMapViewer.svelte

@@ -1,15 +1,20 @@
 <script lang="ts">
+import { MapboxOverlay } from '@deck.gl/mapbox';
 import type maplibregl from 'maplibre-gl';
 import maplibreModule from 'maplibre-gl';
 import { onDestroy, untrack } from 'svelte';
 import { t } from '../../i18n/index.svelte.js';
 import { tabResources } from '../../stores/tab-resources.svelte.js';
-import type { Tab } from '../../types';
+import type { Tab } from '../../types.js';
+import { createEpsgResolver } from '../../utils/cog.js';
 import { buildHttpsUrlAsync } from '../../utils/url.js';
 import {
+	detectGeoZarr,
 	ensureCodecsRegistered,
 	extractZarrStoreUrl,
+	type GeoZarrInfo,
 	inferDims,
+	type ZarrHierarchy,
 	type ZarrNode
 } from '../../utils/zarr.js';
 import MapContainer from './map/MapContainer.svelte';
@@ -40,21 +45,40 @@ let {
 	variables,
 	coords = [],
 	spatialRefAttrs,
-	zarrVersion = null
+	zarrVersion = null,
+	hierarchy = null
 }: {
 	tab: Tab;
 	variables: ZarrNode[];
 	coords?: ZarrNode[];
 	spatialRefAttrs: Record<string, any> | null;
 	zarrVersion?: number | null;
+	/**
+	 * Full pre-loaded hierarchy. When present, `detectGeoZarr` can short-circuit
+	 * to the `@developmentseed/deck.gl-zarr` path for GeoZarr-valid stores.
+	 * Non-GeoZarr stores fall through to `@carbonplan/zarr-layer`.
+	 */
+	hierarchy?: ZarrHierarchy | null;
 } = $props();
 
+// GeoZarr detection runs once per hierarchy so the branch decision is stable
+// across selector-slider tweaks. Returns null for non-GeoZarr stores, which
+// sends everything through the existing carbonplan path.
+const geoZarrInfo = $derived<GeoZarrInfo | null>(hierarchy ? detectGeoZarr(hierarchy) : null);
+
+// MapboxOverlay holder for the deck.gl-zarr path. Separate from zarrLayer so
+// the two paths can be cleaned up independently.
+let dsZarrOverlay: MapboxOverlay | null = null;
+const dsZarrEpsg = createEpsgResolver();
+
 let loading = $state(true);
 let error = $state<string | null>(null);
 let selectedVar = $state('');
 let zarrLayer: any = null;
 let mapRef: maplibregl.Map | null = null;
 let inspectPopup: maplibregl.Popup | null = null;
+let loadGen = 0;
+let addAbort = new AbortController();
 
 // Extract proj4 from spatial_ref if available
 const proj4String = $derived(extractProj4(spatialRefAttrs));
@@ -359,20 +383,39 @@ async function onMapReady(map: maplibregl.Map) {
 }
 
 async function addZarrLayer(map: maplibregl.Map) {
+	addAbort.abort();
+	addAbort = new AbortController();
+	const signal = addAbort.signal;
+	const gen = ++loadGen;
 	loading = true;
 	error = null;
 
 	try {
-		// Remove existing layer
 		if (zarrLayer && map.getLayer(zarrLayer.id)) {
 			map.removeLayer(zarrLayer.id);
 		}
+		if (dsZarrOverlay) {
+			try {
+				map.removeControl(dsZarrOverlay as unknown as maplibregl.IControl);
+			} catch {
+				/* already removed */
+			}
+			dsZarrOverlay = null;
+		}
+
+		if (geoZarrInfo) {
+			const used = await tryAddGeoZarrLayer(map, gen, signal);
+			if (gen !== loadGen || signal.aborted) return;
+			if (used) return;
+		}
 
-		// Ensure numcodecs codecs (shuffle, zlib, etc.) are registered before zarr-layer uses zarrita
 		await ensureCodecsRegistered();
+		if (gen !== loadGen || signal.aborted) return;
 		const { ZarrLayer } = await import('@carbonplan/zarr-layer');
+		if (gen !== loadGen || signal.aborted) return;
 
 		const storeUrl = await buildStoreUrl();
+		if (gen !== loadGen || signal.aborted) return;
 		const selector = buildSelector();
 
 		const opts: any = {
@@ -457,6 +500,97 @@ async function buildStoreUrl(): Promise<string> {
 	return extractZarrStoreUrl(rawUrl) ?? rawUrl;
 }
 
+/**
+ * Attempt to render via `@developmentseed/deck.gl-zarr`. Returns true on
+ * success (carbonplan fallback is skipped), false on any setup error so the
+ * caller can fall through to the legacy path. Errors thrown inside the layer
+ * after setup propagate through the overlay's `onError`.
+ */
+async function tryAddGeoZarrLayer(
+	map: maplibregl.Map,
+	gen: number,
+	signal: AbortSignal
+): Promise<boolean> {
+	if (!geoZarrInfo) return false;
+	try {
+		const zarrita = await import('zarrita');
+		if (gen !== loadGen || signal.aborted) return false;
+		const { ZarrLayer } = await import('@developmentseed/deck.gl-zarr');
+		if (gen !== loadGen || signal.aborted) return false;
+		const storeUrl = await buildStoreUrl();
+		if (gen !== loadGen || signal.aborted) return false;
+		const store = new zarrita.FetchStore(storeUrl);
+		const group = await zarrita.open(store, { kind: 'group' });
+		if (gen !== loadGen || signal.aborted) return false;
+
+		const zarrInfoSnapshot = $state.snapshot(geoZarrInfo) as GeoZarrInfo;
+		const layer = new ZarrLayer({
+			id: `geozarr-${tab.id}`,
+			source: group,
+			variable: zarrInfoSnapshot.variantPath || undefined,
+			selection: {},
+			epsgResolver: dsZarrEpsg,
+			getTileData: async (arr, options) => {
+				const chunk = await zarrita.get(arr, options.sliceSpec);
+				if (gen !== loadGen || signal.aborted) {
+					throw new DOMException('Aborted', 'AbortError');
+				}
+				const data = chunk.data as unknown as ArrayLike<number> & { length: number };
+				return {
+					width: options.width,
+					height: options.height,
+					data,
+					byteLength: data.length
+				};
+			},
+			renderTile: (data) => {
+				const raw = (data as unknown as { data: ArrayLike<number> & { length: number } }).data;
+				if (!raw) return { image: undefined } as never;
+				let clamped: Uint8ClampedArray;
+				const asTyped = raw as unknown as {
+					buffer?: ArrayBufferLike;
+					byteOffset?: number;
+					byteLength?: number;
+				};
+				if (
+					asTyped.buffer &&
+					typeof asTyped.byteOffset === 'number' &&
+					typeof asTyped.byteLength === 'number'
+				) {
+					clamped = new Uint8ClampedArray(asTyped.buffer, asTyped.byteOffset, asTyped.byteLength);
+				} else {
+					clamped = new Uint8ClampedArray(raw as unknown as Uint8Array);
+				}
+				const img = new ImageData(
+					clamped as unknown as Uint8ClampedArray<ArrayBuffer>,
+					data.width,
+					data.height
+				);
+				return { image: img };
+			}
+		});
+
+		const overlay = new MapboxOverlay({
+			interleaved: false,
+			layers: [layer],
+			onError: (err) => {
+				error = err?.message || String(err);
+				loading = false;
+			}
+		});
+		dsZarrOverlay = overlay;
+		map.addControl(overlay as unknown as maplibregl.IControl);
+		loading = false;
+		return true;
+	} catch {
+		// Fall back to carbonplan path on any setup failure (e.g. the store
+		// looked like GeoZarr by shape but zarrita open failed, or the group
+		// attrs don't actually parse). Silent by design, the caller will mount
+		// carbonplan's ZarrLayer which surfaces its own errors.
+		return false;
+	}
+}
+
 // Re-render when selector changes
 async function updateSelector() {
 	if (!zarrLayer) return;
@@ -476,6 +610,7 @@ async function changeVariable() {
 }
 
 function cleanup() {
+	addAbort.abort();
 	inspectPopup?.remove();
 	inspectPopup = null;
 	try {
@@ -483,10 +618,14 @@ function cleanup() {
 		if (zarrLayer && mapRef?.getLayer('zarr-data')) {
 			mapRef.removeLayer('zarr-data');
 		}
+		if (mapRef && dsZarrOverlay) {
+			mapRef.removeControl(dsZarrOverlay as unknown as maplibregl.IControl);
+		}
 	} catch {
 		// map may already be destroyed
 	}
 	zarrLayer = null;
+	dsZarrOverlay = null;
 	mapRef = null;
 }