@walkthru-earth/objex 1.3.0 → 1.3.1

package/dist/components/viewers/CogViewer.svelte

@@ -11,12 +11,14 @@ import {
 	type BandConfig,
 	buildDataTypeLabel,
 	type CogInfo,
+	type CustomTileData,
 	clampBounds,
 	cleanupNativeBitmap,
 	createEpsgResolver,
 	DEFAULT_RESCALE,
 	defaultBandConfig,
 	fitCogBounds,
+	HISTOGRAM_BIN_COUNT,
 	inspectCogTags,
 	needsCustomPipelineForConfig,
 	normalizeCogGeotiff,
@@ -273,16 +275,7 @@ function buildAndAddLayer(
 	// Pick the library-default or one of three custom pipelines. Empty when the
 	// library-default uint path runs unchanged.
 	const customProps = preflightGeotiff
-		? selectCogPipeline(preflightGeotiff, {
-				bandConfig,
-				rescale,
-				onHistogram: (bins) => {
-					// Copy once so the derived UI sees an immutable snapshot
-					// and the accumulating worker buffer is not observed mid-mutation.
-					histogram = new Uint32Array(bins);
-					histogramTick++;
-				}
-			})
+		? selectCogPipeline(preflightGeotiff, { bandConfig, rescale })
 		: {};
 
 	// Apply upstream-bug workarounds in place (overview filter, 4326 bbox clamp).
@@ -290,7 +283,10 @@ function buildAndAddLayer(
 
 	const cogInput = preflightGeotiff ?? resolvedHttpsUrl ?? '';
 
-	const layer = new COGLayer({
+	// Cast: `onViewportLoad` is forwarded by our pnpm patch to the inner
+	// TileLayer, but COGLayer's generated .d.ts does not expose it.
+	// biome-ignore lint/suspicious/noExplicitAny: upstream prop not yet in types
+	const cogProps: any = {
 		// Stable id per tab so rebuilds on band/style change don't force deck.gl
 		// to treat this as a brand-new layer and drop cached tile state.
 		id: `cog-layer-${tab.id}`,
@@ -299,6 +295,15 @@ function buildAndAddLayer(
 		epsgResolver,
 		signal,
 		...customProps,
+		// COG-native histogram: sum `content.histogram` over tiles currently
+		// visible in the viewport. Fires after every pan/zoom settles and
+		// reuses deck.gl's tile cache for free, cached tiles still carry
+		// their per-tile histogram so no rebake is needed on revisit.
+		onViewportLoad: (visibleTiles: unknown) => {
+			aggregateVisibleHistogram(
+				visibleTiles as ReadonlyArray<{ content?: unknown } | null | undefined>
+			);
+		},
 		onGeoTIFFLoad: (
 			loadedTiff: GeoTIFF,
 			{
@@ -345,7 +350,8 @@ function buildAndAddLayer(
 			}
 			loading = false;
 		}
-	});
+	};
+	const layer = new COGLayer(cogProps);
 
 	const overlay = new MapboxOverlay({
 		interleaved: false,
@@ -362,10 +368,54 @@ function buildAndAddLayer(
 	map.addControl(overlay as unknown as maplibregl.IControl);
 }
 
+// ─── Viewport-scoped histogram aggregation ───────────────────────
+
+/**
+ * Sum per-tile histograms from tiles currently visible in the viewport. COG
+ * pyramid semantics map cleanly: zoomed out → a handful of low-res overview
+ * tiles cover the whole scene; zoomed in → only the tiles intersecting the
+ * AOI are decoded. deck.gl reuses its tile cache on revisits so each cached
+ * tile still carries `content.histogram`, no rebake needed.
+ */
+function aggregateVisibleHistogram(
+	visibleTiles: ReadonlyArray<{ content?: unknown } | null | undefined>
+): void {
+	if (!visibleTiles || visibleTiles.length === 0) {
+		histogram = null;
+		histogramTick++;
+		return;
+	}
+	const summed = new Uint32Array(HISTOGRAM_BIN_COUNT);
+	let found = false;
+	for (const tile of visibleTiles) {
+		// COGLayer wraps our baker's return as `{data, forwardTransform,
+		// inverseTransform}` in `_getTileData`, so the histogram lives at
+		// `content.data.histogram`. MosaicLayer's sub-COGs follow the same
+		// shape. Fall back to `content.histogram` for future-proofing if
+		// upstream ever stops wrapping.
+		const content = tile?.content as
+			| { data?: CustomTileData; histogram?: Uint32Array }
+			| null
+			| undefined;
+		const bins = content?.data?.histogram ?? content?.histogram;
+		if (!bins || bins.length !== HISTOGRAM_BIN_COUNT) continue;
+		for (let i = 0; i < HISTOGRAM_BIN_COUNT; i++) summed[i] += bins[i];
+		found = true;
+	}
+	histogram = found ? summed : null;
+	histogramTick++;
+}
+
 // ─── Rebuild layer on band config change ─────────────────────────
 
 function handleConfigChange(newConfig: BandConfig) {
 	bandConfig = newConfig;
+	// Only the single-band CPU baker emits `onHistogram`. Clear the buffer on
+	// every mode/band change so (a) switching back to RGB hides stale bars
+	// that the rescale slider would otherwise draw on top of, and (b) picking
+	// a different single band starts a fresh distribution.
+	histogram = null;
+	histogramTick = 0;
 	if (!mapRef || !geotiffRef || !isTiledRef) return;
 
 	// Remove old overlay

package/dist/components/viewers/StacMapViewer.svelte

@@ -22,7 +22,15 @@ $effect(() => {
 const iframeSrc = $derived.by(() => {
 	if (!fileUrl) return '';
 	if (variant === 'stac-browser') {
-		return `https://radiantearth.github.io/stac-browser/#/external/${encodeURIComponent(fileUrl)}`;
+		// Radiant Earth STAC Browser is a Vue Router SPA. Its
+		// `#/external/<url>` route takes the catalog URL verbatim, splitting on
+		// `/`. Feeding it an `encodeURIComponent`-encoded URL makes the router
+		// hand `https%3A%2F%2F…` to `new URL()`, which reads the collapsed
+		// authority as a malformed port and throws
+		// `Port "%2F%2Fstorage.googleapis.com%2F…" is not a valid port`.
+		// Only escape the `#` character (which would otherwise terminate the
+		// hash route) so the rest of the URL flows through intact.
+		return `https://radiantearth.github.io/stac-browser/#/external/${fileUrl.replace(/#/g, '%23')}`;
 	}
 	return `https://developmentseed.org/stac-map?href=${encodeURIComponent(fileUrl)}`;
 });

package/dist/components/viewers/StacMosaicViewer.svelte

@@ -11,15 +11,18 @@ import { buildProviderBaseUrl, type ProviderId } from '../../storage/providers.j
 import { connectionStore } from '../../stores/connections.svelte.js';
 import { tabResources } from '../../stores/tab-resources.svelte.js';
 import type { Tab } from '../../types.js';
+import { resolveCloudUrl } from '../../utils/cloud-url.js';
 import {
 	type BandConfig,
 	buildDataTypeLabel,
+	type CustomTileData,
 	clampBounds,
 	cleanupNativeBitmap,
 	createEpsgResolver,
 	DEFAULT_RESCALE,
 	defaultBandConfig,
 	fitCogBounds,
+	HISTOGRAM_BIN_COUNT,
 	normalizeCogGeotiff,
 	type PixelValue,
 	type RescaleConfig,
@@ -72,6 +75,11 @@ let lastRebuildAt = 0;
 let layerVersion = 0;
 let presignCache = new Map<string, Promise<string>>();
 let loadGen = 0;
+// Per-source visible-tile histograms. Each sub-COGLayer's `onViewportLoad`
+// writes its own summed-visible histogram here, and the outer aggregator
+// sums across all sources currently contributing. Cleared on resetViewer
+// and on band/config changes to avoid leaking stale distributions.
+let sourceHistograms = new Map<string, Uint32Array>();
 
 // MosaicLayer builds a Flatbush spatial index at construction; deck.gl reuses
 // the existing internal tileset when only props change, so the index never
@@ -114,6 +122,7 @@ function resetViewer(): void {
 	itemsRef = [];
 	presignCache = new Map();
 	geotiffCache = new Map();
+	sourceHistograms = new Map();
 	loading = true;
 	error = null;
 	sourceCount = 0;
@@ -222,19 +231,24 @@ function extractConnectionKey(href: string): string | null {
 function presignHref(href: string): Promise<string> {
 	let cached = presignCache.get(href);
 	if (!cached) {
-		if (/^https?:\/\//i.test(href)) {
+		// Convert cloud-protocol hrefs (s3://, gs://) to HTTPS before anything
+		// else. stac-geoparquet catalogs like source.coop's aef_index store
+		// absolute `s3://...` asset hrefs, and GeoTIFF.fromUrl / fetch cannot
+		// reach them. `resolveCloudUrl` is a no-op for already-https URLs.
+		const normalized = resolveCloudUrl(href);
+		if (/^https?:\/\//i.test(normalized)) {
 			// Absolute URLs that belong to the tab's own bucket still need SigV4
-			// presigning on private buckets (GCS/S3) — `new URL(rel, base)` strips
+			// presigning on private buckets (GCS/S3), `new URL(rel, base)` strips
 			// the base's query string when absolutizing asset hrefs, so the
 			// signature is lost and the bare URL 403s.
-			const key = extractConnectionKey(href);
+			const key = extractConnectionKey(normalized);
 			if (key !== null) {
-				cached = buildHttpsUrlAsync({ ...tab, path: key } as Tab).catch(() => href);
+				cached = buildHttpsUrlAsync({ ...tab, path: key } as Tab).catch(() => normalized);
 			} else {
-				cached = Promise.resolve(href);
+				cached = Promise.resolve(normalized);
 			}
 		} else {
-			cached = buildHttpsUrlAsync({ ...tab, path: href } as Tab).catch(() => href);
+			cached = buildHttpsUrlAsync({ ...tab, path: normalized } as Tab).catch(() => normalized);
 		}
 		presignCache.set(href, cached);
 	}
@@ -441,7 +455,7 @@ function buildOrUpdateLayer(map: maplibregl.Map, signal: AbortSignal): void {
 			// (version bumps) and pixel-click handlers; otherwise every layer
 			// rebuild would re-fetch every source's header.
 			const cached = geotiffCache.get(source.id);
-			if (cached) return cached;
+			if (cached) return cached.catch(() => undefined as unknown as GeoTIFF);
 			const promise = (async () => {
 				const url = await presignHref(source.href);
 				const geotiff = await GeoTIFF.fromUrl(url);
@@ -449,7 +463,17 @@ function buildOrUpdateLayer(map: maplibregl.Map, signal: AbortSignal): void {
 				return geotiff;
 			})();
 			geotiffCache.set(source.id, promise);
-			const geotiff = await promise;
+			let geotiff: GeoTIFF;
+			try {
+				geotiff = await promise;
+			} catch {
+				// Swallow per-source fetch/decode failures so deck.gl's TileLayer
+				// gets `data: undefined` (renderSource returns null for it) instead
+				// of a rejected promise, which surfaces as "v is null" during the
+				// TileLayer update when a mosaic covers hundreds of unreachable
+				// sources (e.g. the 302k-item aef_index global catalog).
+				return undefined as unknown as GeoTIFF;
+			}
 			if (opts.signal?.aborted) throw new DOMException('Aborted', 'AbortError');
 			// Seed band config from the first COG that resolves so the UI and
 			// the pipeline match the actual raster (e.g. 4-band NAIP RGB+NIR),
@@ -470,21 +494,30 @@ function buildOrUpdateLayer(map: maplibregl.Map, signal: AbortSignal): void {
 		},
 		renderSource: (source, { data }) => {
 			if (!data) return null;
-			const customProps = selectCogPipeline(data, {
-				bandConfig: bc,
-				rescale: rs,
-				onHistogram: (bins) => {
-					histogram = new Uint32Array(bins);
-				}
-			});
-			return new COGLayer({
+			const customProps = selectCogPipeline(data, { bandConfig: bc, rescale: rs });
+			// Cast: `onViewportLoad` is forwarded by our pnpm patch to the
+			// inner TileLayer, but COGLayer's generated .d.ts does not expose
+			// it in `COGLayerProps`. Use `any` for the constructor arg so we
+			// can pass the extra prop without polluting the library types.
+			// biome-ignore lint/suspicious/noExplicitAny: upstream prop not yet in types
+			const cogProps: any = {
 				id: `mosaic-${tab.id}-v${version}-${source.id}`,
 				geotiff: data,
 				pool: pool ?? undefined,
 				epsgResolver,
 				signal,
-				...customProps
-			});
+				...customProps,
+				// Viewport-scoped histogram per sub-COG. Sub-COGLayer fires this
+				// with the currently-visible tiles of THIS source at the active
+				// overview. We sum across all sources in `aggregateSources`.
+				onViewportLoad: (visibleTiles: unknown) => {
+					recordSourceHistogram(
+						source.id,
+						visibleTiles as ReadonlyArray<{ content?: unknown } | null | undefined>
+					);
+				}
+			};
+			return new COGLayer(cogProps);
 		}
 	});
 
@@ -511,10 +544,63 @@ function buildOrUpdateLayer(map: maplibregl.Map, signal: AbortSignal): void {
 
 function handleConfigChange(next: BandConfig): void {
 	bandConfig = next;
+	// Histogram is only emitted by the single-band CPU baker. Reset on every
+	// mode/band change so (a) switching to RGB hides stale bars under the
+	// rescale slider and (b) a new single-band selection does not paint on
+	// top of the previous band's distribution.
+	histogram = null;
+	sourceHistograms.clear();
 	if (!mapRef) return;
 	scheduleLayerRebuild(mapRef, abortController.signal);
 }
 
+/**
+ * Record one sub-COG's viewport-scoped histogram and re-sum across all
+ * sources currently contributing. COG-native: each source only decodes the
+ * overview tiles covering its part of the viewport, so the union across
+ * sources is exactly the pixels the viewer sees at this zoom.
+ */
+function recordSourceHistogram(
+	sourceId: string,
+	visibleTiles: ReadonlyArray<{ content?: unknown } | null | undefined>
+): void {
+	if (!visibleTiles || visibleTiles.length === 0) {
+		if (sourceHistograms.delete(sourceId)) aggregateSources();
+		return;
+	}
+	const summed = new Uint32Array(HISTOGRAM_BIN_COUNT);
+	let found = false;
+	for (const tile of visibleTiles) {
+		// COGLayer's `_getTileData` wraps our baker output as `{data, forward-
+		// Transform, inverseTransform}`, so the per-tile histogram lives at
+		// `content.data.histogram`. Fall back to `content.histogram` if the
+		// library ever stops wrapping.
+		const content = tile?.content as
+			| { data?: CustomTileData; histogram?: Uint32Array }
+			| null
+			| undefined;
+		const bins = content?.data?.histogram ?? content?.histogram;
+		if (!bins || bins.length !== HISTOGRAM_BIN_COUNT) continue;
+		for (let i = 0; i < HISTOGRAM_BIN_COUNT; i++) summed[i] += bins[i];
+		found = true;
+	}
+	if (found) sourceHistograms.set(sourceId, summed);
+	else sourceHistograms.delete(sourceId);
+	aggregateSources();
+}
+
+function aggregateSources(): void {
+	if (sourceHistograms.size === 0) {
+		histogram = null;
+		return;
+	}
+	const summed = new Uint32Array(HISTOGRAM_BIN_COUNT);
+	for (const bins of sourceHistograms.values()) {
+		for (let i = 0; i < HISTOGRAM_BIN_COUNT; i++) summed[i] += bins[i];
+	}
+	histogram = summed;
+}
+
 function handleRescaleChange(next: RescaleConfig): void {
 	rescale = next;
 	if (!mapRef) return;
@@ -623,7 +709,7 @@ onDestroy(cleanup);
 				{bandConfig}
 				onConfigChange={handleConfigChange}
 				{rescale}
-				rescaleApplicable={true}
+				rescaleApplicable={bandConfig?.mode === 'single'}
 				onRescaleChange={handleRescaleChange}
 				{histogram}
 			/>

package/dist/utils/cog-pure.d.ts

@@ -0,0 +1,25 @@
+/** SampleFormat tag value → human label. */
+export declare const SF_LABELS: Record<number, string>;
+export interface GeoBounds {
+    west: number;
+    south: number;
+    east: number;
+    north: number;
+}
+export interface CogInfo {
+    width: number;
+    height: number;
+    bandCount: number;
+    dataType: string;
+    bounds: GeoBounds;
+    downsampled?: boolean;
+}
+/** Safely clamp a number to a range, treating NaN/Infinity as the fallback. */
+export declare function safeClamp(v: number, lo: number, hi: number, fallback: number): number;
+/** Clamp geographic bounds to valid MapLibre web-Mercator range. */
+export declare function clampBounds(b: GeoBounds): GeoBounds;
+/**
+ * Build a data-type label from GeoTIFF sample format and bits per sample.
+ * e.g. "uint8", "float32", "int16"
+ */
+export declare function buildDataTypeLabel(sampleFormat: number, bitsPerSample: number): string;

package/dist/utils/cog-pure.js

@@ -0,0 +1,35 @@
+// Dependency-free subset of `cog.ts` so that `@walkthru-earth/objex-utils`
+// can re-export these helpers without dragging in `@developmentseed/epsg`,
+// `@developmentseed/geotiff`, `@developmentseed/proj`, `proj4`, or
+// `maplibre-gl`. tsup preserves bare side-effect imports from externalized
+// modules even when all named bindings are tree-shaken, so the pure surface
+// MUST live in a module that has zero heavy imports.
+/** SampleFormat tag value → human label. */
+export const SF_LABELS = {
+    1: 'uint',
+    2: 'int',
+    3: 'float',
+    4: 'void',
+    5: 'complex int',
+    6: 'complex float'
+};
+/** Safely clamp a number to a range, treating NaN/Infinity as the fallback. */
+export function safeClamp(v, lo, hi, fallback) {
+    return Number.isFinite(v) ? Math.max(lo, Math.min(hi, v)) : fallback;
+}
+/** Clamp geographic bounds to valid MapLibre web-Mercator range. */
+export function clampBounds(b) {
+    return {
+        west: safeClamp(b.west, -180, 180, -180),
+        south: safeClamp(b.south, -85.051129, 85.051129, -85.051129),
+        east: safeClamp(b.east, -180, 180, 180),
+        north: safeClamp(b.north, -85.051129, 85.051129, 85.051129)
+    };
+}
+/**
+ * Build a data-type label from GeoTIFF sample format and bits per sample.
+ * e.g. "uint8", "float32", "int16"
+ */
+export function buildDataTypeLabel(sampleFormat, bitsPerSample) {
+    return `${SF_LABELS[sampleFormat] ?? `sf${sampleFormat}`}${bitsPerSample ?? ''}`;
+}

package/dist/utils/cog.d.ts

@@ -5,9 +5,9 @@ import { GeoTIFF } from '@developmentseed/geotiff';
 import type { EpsgResolver } from '@developmentseed/proj';
 import type { Device } from '@luma.gl/core';
 import type maplibregl from 'maplibre-gl';
+import { buildDataTypeLabel, type CogInfo, clampBounds, type GeoBounds, SF_LABELS, safeClamp } from './cog-pure.js';
 import { type ColormapName } from './colormap-sprite.js';
-/** SampleFormat tag value → human label. */
-export declare const SF_LABELS: Record<number, string>;
+export { buildDataTypeLabel, type CogInfo, clampBounds, type GeoBounds, SF_LABELS, safeClamp };
 /**
  * Any of the 107 named ramps shipped in `@developmentseed/deck.gl-raster`'s
  * `colormaps.png` sprite (matplotlib + rio-tiler + cmocean). Rendering is
@@ -120,11 +120,6 @@ export interface SelectCogPipelineOptions {
     bandConfig?: BandConfig | null;
     /** Linear rescale GPU module values. No-op when omitted or at defaults. */
     rescale?: RescaleConfig;
-    /**
-     * Forwarded to the CPU bake factories in single-band mode; receives a
-     * 64-bin histogram of normalized data after each tile for slider UI.
-     */
-    onHistogram?: (bins: Uint32Array) => void;
 }
 /**
  * Decide which getTileData/renderTile pair COGLayer should use for a GeoTIFF.
@@ -143,29 +138,6 @@ export interface SelectCogPipelineOptions {
  * viewers can call it per sub-COG without re-implementing the decision tree.
  */
 export declare function selectCogPipeline(geotiff: GeoTIFFType, opts?: SelectCogPipelineOptions): ResolvedCogPipeline;
-export interface GeoBounds {
-    west: number;
-    south: number;
-    east: number;
-    north: number;
-}
-export interface CogInfo {
-    width: number;
-    height: number;
-    bandCount: number;
-    dataType: string;
-    bounds: GeoBounds;
-    downsampled?: boolean;
-}
-/** Safely clamp a number to a range, treating NaN/Infinity as the fallback. */
-export declare function safeClamp(v: number, lo: number, hi: number, fallback: number): number;
-/** Clamp geographic bounds to valid MapLibre web-Mercator range. */
-export declare function clampBounds(b: GeoBounds): GeoBounds;
-/**
- * Build a data-type label from GeoTIFF sample format and bits per sample.
- * e.g. "uint8", "float32", "int16"
- */
-export declare function buildDataTypeLabel(sampleFormat: number, bitsPerSample: number): string;
 /**
  * Query the GPU's MAX_TEXTURE_SIZE from MapLibre's WebGL context.
  * Falls back to 4096 (lowest common denominator for mobile GPUs).
@@ -215,6 +187,16 @@ export interface CustomTileData {
      * lookup. `undefined` for RGB tiles.
      */
     nodataSentinel?: number;
+    /**
+     * Per-tile 64-bin normalized histogram (0..1, nodata excluded) baked during
+     * single-band CPU decoding. `undefined` for RGB tiles. deck.gl's TileLayer
+     * caches the returned tile object, so this array is retained alongside the
+     * bitmap without a rebake on pan/zoom revisits. Summing the histograms of
+     * currently-visible tiles, via the TileLayer `onViewportLoad` hook, gives a
+     * cloud-native "histogram of what COG tiles the viewport currently shows at
+     * the active overview level", matching COG pyramid behavior.
+     */
+    histogram?: Uint32Array;
 }
 type Texture = import('@luma.gl/core').Texture;
 /**
@@ -223,16 +205,18 @@ type Texture = import('@luma.gl/core').Texture;
  * Signed int (2) and float (3) need custom getTileData/renderTile.
  */
 export declare function needsCustomPipeline(geotiff: GeoTIFFType): boolean;
-/** Shared options for the CPU tile-baking factories. */
-export interface CustomGetTileDataOptions {
-    /**
-     * Called after each baked tile with a 64-bin histogram of normalized
-     * single-band values (0..1, nodata excluded). Bins accumulate across
-     * tiles; receivers should treat the array as monotonically growing and
-     * debounce UI updates. Never invoked in RGB mode.
-     */
-    onHistogram?: (bins: Uint32Array) => void;
-}
+/**
+ * Shared options for the CPU tile-baking factories.
+ *
+ * The previous `onHistogram` callback accumulated a single closure-owned buffer
+ * across every tile ever baked, which grew unbounded on pan/zoom and never
+ * reflected "what the viewport currently shows". Histograms are now attached
+ * per tile to `CustomTileData.histogram` and aggregated by the viewer from
+ * TileLayer's `onViewportLoad(visibleTiles)` hook, matching COG overview-level
+ * behavior (few big tiles when zoomed out, small AOI-scoped tiles when zoomed
+ * in) and reusing deck.gl's tile cache for free.
+ */
+export type CustomGetTileDataOptions = Record<string, never>;
 /** Number of histogram buckets produced by the CPU bake. */
 export declare const HISTOGRAM_BIN_COUNT = 64;
 /**
@@ -243,7 +227,7 @@ export declare const HISTOGRAM_BIN_COUNT = 64;
  * `colormaps.png`. Reserves `r = 0` for nodata so `FilterNoDataVal` can
  * discard those fragments before the ramp sample.
  */
-export declare function createCustomGetTileData(geotiff: GeoTIFFType, opts?: CustomGetTileDataOptions): (image: GeoTIFFType | Overview, options: {
+export declare function createCustomGetTileData(geotiff: GeoTIFFType, _opts?: CustomGetTileDataOptions): (image: GeoTIFFType | Overview, options: {
     x: number;
     y: number;
     pool: unknown;
@@ -269,7 +253,7 @@ export declare function buildCustomRenderTile(config: BandConfig, rescale?: Resc
  * single-band mode (band N normalized into the `r` channel; the ramp is
  * applied downstream by the GPU `Colormap` module via `buildCustomRenderTile`).
  */
-export declare function createConfigurableGetTileData(geotiff: GeoTIFFType, config: BandConfig, opts?: CustomGetTileDataOptions): (image: GeoTIFFType | Overview, options: {
+export declare function createConfigurableGetTileData(geotiff: GeoTIFFType, config: BandConfig, _opts?: CustomGetTileDataOptions): (image: GeoTIFFType | Overview, options: {
     x: number;
     y: number;
     pool: unknown;
@@ -303,4 +287,3 @@ export declare function resolveProj4Def(crs: number | unknown, _signal: AbortSig
  * Converts WGS84 → source CRS → pixel coords, fetches the tile, reads all bands.
  */
 export declare function readPixelAtLngLat(geotiff: GeoTIFFType, lng: number, lat: number, proj4Def: string | null, pool: any, signal?: AbortSignal): Promise<PixelValue | null>;
-export {};

package/dist/utils/cog.js

@@ -5,7 +5,9 @@ import epsgCsvUrl from '@developmentseed/epsg/all.csv.gz?url';
 import { GeoTIFF } from '@developmentseed/geotiff';
 import { parseWkt } from '@developmentseed/proj';
 import proj4Lib from 'proj4';
+import { buildDataTypeLabel, clampBounds, SF_LABELS, safeClamp } from './cog-pure.js';
 import { COLORMAP_INDEX, getColormapTexture } from './colormap-sprite.js';
+export { buildDataTypeLabel, clampBounds, SF_LABELS, safeClamp };
 // ─── Constants ───────────────────────────────────────────────────
 /**
  * Patches a GLSL ES 3.00 compile error in `@developmentseed/deck.gl-raster`
@@ -27,15 +29,6 @@ const Sampler2DArrayPrecision = {
         'fs:#decl': 'precision highp sampler2DArray;\n'
     }
 };
-/** SampleFormat tag value → human label. */
-export const SF_LABELS = {
-    1: 'uint',
-    2: 'int',
-    3: 'float',
-    4: 'void',
-    5: 'complex int',
-    6: 'complex float'
-};
 /** Create a sensible default band config based on COG metadata. */
 export function defaultBandConfig(bandCount, sampleFormat) {
     if (bandCount >= 3 && bandCount <= 4) {
@@ -248,9 +241,7 @@ export function selectCogPipeline(geotiff, opts = {}) {
         : needsCustomPipeline(geotiff);
     if (useCustom && bandConfig) {
         return {
-            getTileData: createConfigurableGetTileData(geotiff, bandConfig, {
-                onHistogram: opts.onHistogram
-            }),
+            getTileData: createConfigurableGetTileData(geotiff, bandConfig),
             renderTile: buildCustomRenderTile(bandConfig, rescale)
         };
     }
@@ -260,7 +251,7 @@ export function selectCogPipeline(geotiff, opts = {}) {
         const fallbackSf = geotiff.cachedTags.sampleFormat?.[0] ?? 1;
         const fallbackConfig = defaultBandConfig(geotiff.count, fallbackSf);
         return {
-            getTileData: createCustomGetTileData(geotiff, { onHistogram: opts.onHistogram }),
+            getTileData: createCustomGetTileData(geotiff),
             renderTile: buildCustomRenderTile(fallbackConfig, rescale)
         };
     }
@@ -275,27 +266,9 @@ export function selectCogPipeline(geotiff, opts = {}) {
 }
 const BITMAP_SOURCE = 'geotiff-bitmap-src';
 const BITMAP_LAYER = 'geotiff-bitmap-layer';
-// ─── Pure helpers ────────────────────────────────────────────────
-/** Safely clamp a number to a range, treating NaN/Infinity as the fallback. */
-export function safeClamp(v, lo, hi, fallback) {
-    return Number.isFinite(v) ? Math.max(lo, Math.min(hi, v)) : fallback;
-}
-/** Clamp geographic bounds to valid MapLibre web-Mercator range. */
-export function clampBounds(b) {
-    return {
-        west: safeClamp(b.west, -180, 180, -180),
-        south: safeClamp(b.south, -85.051129, 85.051129, -85.051129),
-        east: safeClamp(b.east, -180, 180, 180),
-        north: safeClamp(b.north, -85.051129, 85.051129, 85.051129)
-    };
-}
-/**
- * Build a data-type label from GeoTIFF sample format and bits per sample.
- * e.g. "uint8", "float32", "int16"
- */
-export function buildDataTypeLabel(sampleFormat, bitsPerSample) {
-    return `${SF_LABELS[sampleFormat] ?? `sf${sampleFormat}`}${bitsPerSample ?? ''}`;
-}
+// ─── Types & pure helpers ────────────────────────────────────────
+// `GeoBounds`, `CogInfo`, `safeClamp`, `clampBounds`, `buildDataTypeLabel`
+// live in `./cog-pure.ts` and are re-exported at the top of this file.
 // ─── Map helpers (depend on maplibre-gl) ─────────────────────────
 /**
  * Query the GPU's MAX_TEXTURE_SIZE from MapLibre's WebGL context.
@@ -614,7 +587,7 @@ export const HISTOGRAM_BIN_COUNT = 64;
  * `colormaps.png`. Reserves `r = 0` for nodata so `FilterNoDataVal` can
  * discard those fragments before the ramp sample.
  */
-export function createCustomGetTileData(geotiff, opts = {}) {
+export function createCustomGetTileData(geotiff, _opts = {}) {
     // Read Scale/Offset TIFF tags (GDAL convention for scaled datasets like DEMs)
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
     const tags = geotiff.cachedTags;
@@ -649,7 +622,6 @@ export function createCustomGetTileData(geotiff, opts = {}) {
     let sharedMax = globalMax;
     // Resolve the sprite texture from the first tile's device; reuse per-device.
     let texturePromise = null;
-    const histogram = isSingleBand ? new Uint32Array(HISTOGRAM_BIN_COUNT) : null;
     return async (image, options) => {
         if (isSingleBand && !texturePromise) {
             texturePromise = getColormapTexture(options.device);
@@ -669,6 +641,10 @@ export function createCustomGetTileData(geotiff, opts = {}) {
         const pixelCount = width * height;
         const scale = gdalScale ?? 1;
         const offset = gdalOffset ?? 0;
+        // Allocate per-tile histogram so deck.gl's tile cache retains it with
+        // the tile object. The viewer sums histograms of visible tiles from
+        // TileLayer's `onViewportLoad` hook, no shared accumulator needed.
+        const histogram = isSingleBand ? new Uint32Array(HISTOGRAM_BIN_COUNT) : null;
         // When no global stats, scan this tile and widen the shared range
         if (sharedMin === null || sharedMax === null) {
             let tMin = Infinity;
@@ -734,14 +710,13 @@ export function createCustomGetTileData(geotiff, opts = {}) {
             }
             rgba[idx + 3] = 255;
         }
-        if (histogram && opts.onHistogram)
-            opts.onHistogram(histogram);
         return {
             imageData: new ImageData(rgba, width, height),
             width,
             height,
             colormapTexture: isSingleBand ? colormapTexture : undefined,
-            nodataSentinel: isSingleBand ? 0 : undefined
+            nodataSentinel: isSingleBand ? 0 : undefined,
+            histogram: histogram ?? undefined
         };
     };
 }
@@ -849,14 +824,13 @@ function computeBandRanges(bands, bandIndices, pixelCount, nodata) {
  * single-band mode (band N normalized into the `r` channel; the ramp is
  * applied downstream by the GPU `Colormap` module via `buildCustomRenderTile`).
  */
-export function createConfigurableGetTileData(geotiff, config, opts = {}) {
+export function createConfigurableGetTileData(geotiff, config, _opts = {}) {
     const bandCount = geotiff.count;
     // Shared per-band ranges across tiles (seeded on first tile, widened by subsequent)
     const sharedMins = new Map();
     const sharedMaxs = new Map();
     // Resolve the sprite texture from the first tile's device; reuse per-device.
     let texturePromise = null;
-    const histogram = config.mode === 'single' ? new Uint32Array(HISTOGRAM_BIN_COUNT) : null;
     return async (image, options) => {
         if (config.mode === 'single' && !texturePromise) {
             texturePromise = getColormapTexture(options.device);
@@ -875,6 +849,11 @@ export function createConfigurableGetTileData(geotiff, config, opts = {}) {
         const pixelCount = width * height;
         const bands = extractBands(arr, bandCount, pixelCount);
         const rgba = new Uint8ClampedArray(pixelCount * 4);
+        // Per-tile histogram, cached by deck.gl's tile cache with the tile
+        // object. Cloud-native by construction: at each zoom level, COG only
+        // decodes the overview tiles that cover the viewport, so the summed
+        // histogram naturally reflects "what the user is looking at right now".
+        const histogram = config.mode === 'single' ? new Uint32Array(HISTOGRAM_BIN_COUNT) : null;
         if (config.mode === 'rgb') {
             // RGB mode: map 3 bands to R, G, B
             const indices = [config.rBand, config.gBand, config.bBand];
@@ -955,15 +934,14 @@ export function createConfigurableGetTileData(geotiff, config, opts = {}) {
                     }
                 }
             }
-            if (histogram && opts.onHistogram)
-                opts.onHistogram(histogram);
         }
         return {
             imageData: new ImageData(rgba, width, height),
             width,
             height,
             colormapTexture: config.mode === 'single' ? colormapTexture : undefined,
-            nodataSentinel: config.mode === 'single' ? 0 : undefined
+            nodataSentinel: config.mode === 'single' ? 0 : undefined,
+            histogram: histogram ?? undefined
         };
     };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@walkthru-earth/objex",
-  "version": "1.3.0",
+  "version": "1.3.1",
   "description": "Svelte 5 components and utilities for exploring geospatial object storage — S3, GCS, Azure, R2",
   "author": "Youssef Harby <yharby@walkthru.earth>",
   "license": "CC-BY-4.0",