@walkthru-earth/objex 1.2.1 → 1.3.1

package/dist/stores/connections.svelte.js

@@ -1,13 +1,56 @@
 import { STORAGE_KEYS } from '../constants.js';
+import { connectionIdentityKey } from '../utils/connection-identity.js';
 import { loadFromStorage, persistToStorage } from '../utils/local-storage.js';
 import { credentialStore, storeToNative } from './credentials.svelte.js';
-// ---------------------------------------------------------------------------
-// Store
-// ---------------------------------------------------------------------------
+function toConnection(id, config) {
+    return {
+        id,
+        name: config.name,
+        provider: config.provider,
+        endpoint: config.endpoint,
+        bucket: config.bucket,
+        region: config.region,
+        anonymous: config.anonymous,
+        authMethod: config.authMethod,
+        rootPrefix: config.rootPrefix
+    };
+}
+function applyCredentials(id, config) {
+    if (config.anonymous) {
+        credentialStore.remove(id);
+        return;
+    }
+    if (config.sas_token) {
+        const creds = { type: 'sas-token', sasToken: config.sas_token };
+        credentialStore.set(id, creds);
+        storeToNative(id, creds).catch(() => { });
+        return;
+    }
+    if (config.access_key && config.secret_key) {
+        const creds = {
+            type: 'sigv4',
+            accessKey: config.access_key,
+            secretKey: config.secret_key
+        };
+        credentialStore.set(id, creds);
+        storeToNative(id, creds).catch(() => { });
+        return;
+    }
+    credentialStore.remove(id);
+}
 function createConnectionsStore() {
     let connections = $state([]);
     let loaded = $state(false);
     let dialogRequest = $state(0);
+    function persist() {
+        persistToStorage(STORAGE_KEYS.CONNECTIONS, connections);
+    }
+    function findByIdentity(input, excludeId) {
+        const key = connectionIdentityKey(input);
+        if (!key)
+            return undefined;
+        return connections.find((c) => c.id !== excludeId && connectionIdentityKey(c) === key);
+    }
     return {
         get items() {
             return connections;
@@ -17,7 +60,7 @@ function createConnectionsStore() {
         },
         /**
          * Load connections from localStorage.
-         * Safe to call multiple times — subsequent calls are no-ops.
+         * Safe to call multiple times, subsequent calls are no-ops.
          */
         async load() {
             if (loaded)
@@ -25,112 +68,58 @@ function createConnectionsStore() {
             connections = loadFromStorage(STORAGE_KEYS.CONNECTIONS, []);
             loaded = true;
         },
-        /**
-         * Force-reload connections.
-         */
         async reload() {
             loaded = false;
             await this.load();
         },
         /**
-         * Save a new connection to localStorage.
+         * Persist a connection. If an existing connection shares the same
+         * identity (see `connectionIdentityKey`), it's reused and its
+         * credentials are refreshed from the new config instead of spawning
+         * a duplicate record. Returns `{ id, existed }` so UI can distinguish
+         * "created" from "merged".
          */
         async save(config) {
-            const id = crypto.randomUUID();
-            const conn = {
-                id,
-                name: config.name,
-                provider: config.provider,
-                endpoint: config.endpoint,
-                bucket: config.bucket,
-                region: config.region,
-                anonymous: config.anonymous,
-                authMethod: config.authMethod,
-                rootPrefix: config.rootPrefix
-            };
-            connections = [...connections, conn];
-            persistToStorage(STORAGE_KEYS.CONNECTIONS, connections);
-            // Store credentials in memory (never persisted to localStorage).
-            if (!config.anonymous) {
-                if (config.sas_token) {
-                    const creds = { type: 'sas-token', sasToken: config.sas_token };
-                    credentialStore.set(id, creds);
-                    storeToNative(id, creds).catch(() => { });
-                }
-                else if (config.access_key && config.secret_key) {
-                    const creds = {
-                        type: 'sigv4',
-                        accessKey: config.access_key,
-                        secretKey: config.secret_key
-                    };
-                    credentialStore.set(id, creds);
-                    storeToNative(id, creds).catch(() => { });
-                }
+            const existing = findByIdentity(config);
+            if (existing) {
+                applyCredentials(existing.id, config);
+                return { id: existing.id, existed: true };
             }
-            return id;
+            const id = crypto.randomUUID();
+            connections = [...connections, toConnection(id, config)];
+            persist();
+            applyCredentials(id, config);
+            return { id, existed: false };
         },
         /**
-         * Update an existing connection.
+         * Update an existing connection. Throws `DuplicateConnectionError`
+         * when the new identity would collide with a different saved row,
+         * rather than silently overwriting and leaving a phantom duplicate.
          */
         async update(id, config) {
             const idx = connections.findIndex((c) => c.id === id);
             if (idx === -1)
                 return false;
-            connections[idx] = {
-                ...connections[idx],
-                name: config.name,
-                provider: config.provider,
-                endpoint: config.endpoint,
-                bucket: config.bucket,
-                region: config.region,
-                anonymous: config.anonymous,
-                authMethod: config.authMethod,
-                rootPrefix: config.rootPrefix
-            };
+            const collision = findByIdentity(config, id);
+            if (collision) {
+                throw new DuplicateConnectionError(collision.id, collision.name);
+            }
+            connections[idx] = toConnection(id, config);
             connections = [...connections];
-            persistToStorage(STORAGE_KEYS.CONNECTIONS, connections);
+            persist();
             // Invalidate cached adapter for this connection
             import('../storage/index.js').then(({ clearAdapterCache }) => clearAdapterCache(id));
-            // Update in-memory credentials.
-            if (!config.anonymous) {
-                if (config.sas_token) {
-                    const creds = { type: 'sas-token', sasToken: config.sas_token };
-                    credentialStore.set(id, creds);
-                    storeToNative(id, creds).catch(() => { });
-                }
-                else if (config.access_key && config.secret_key) {
-                    const creds = {
-                        type: 'sigv4',
-                        accessKey: config.access_key,
-                        secretKey: config.secret_key
-                    };
-                    credentialStore.set(id, creds);
-                    storeToNative(id, creds).catch(() => { });
-                }
-                else {
-                    credentialStore.remove(id);
-                }
-            }
-            else {
-                credentialStore.remove(id);
-            }
+            applyCredentials(id, config);
             return true;
         },
-        /**
-         * Remove a connection by ID.
-         */
         async remove(id) {
             const before = connections.length;
             connections = connections.filter((c) => c.id !== id);
-            persistToStorage(STORAGE_KEYS.CONNECTIONS, connections);
+            persist();
             credentialStore.remove(id);
-            // Invalidate cached adapter for this connection
             import('../storage/index.js').then(({ clearAdapterCache }) => clearAdapterCache(id));
             return connections.length < before;
         },
-        /**
-         * Test whether a connection is reachable via a lightweight list.
-         */
         async test(id) {
             const { getAdapter } = await import('../storage/index.js');
             const adapter = getAdapter('remote', id);
@@ -143,23 +132,11 @@ function createConnectionsStore() {
          */
         async testWithConfig(config, existingId) {
             const tempId = existingId ?? `temp-test-${Date.now()}`;
-            const tempConn = {
-                id: tempId,
-                name: config.name,
-                provider: config.provider,
-                endpoint: config.endpoint,
-                bucket: config.bucket,
-                region: config.region,
-                anonymous: config.anonymous,
-                authMethod: config.authMethod,
-                rootPrefix: config.rootPrefix
-            };
-            // Temporarily register connection + credentials so the adapter can find them
+            const tempConn = toConnection(tempId, config);
             const hadConn = connections.some((c) => c.id === tempId);
             const prevCreds = credentialStore.get(tempId);
             if (!hadConn) {
                 connections = [...connections, tempConn];
-                // Don't persist — this is a temp test connection
             }
             if (!config.anonymous) {
                 if (config.sas_token) {
@@ -180,56 +157,55 @@ function createConnectionsStore() {
                 return true;
             }
             finally {
-                // Cleanup: remove temp connection if we added it
                 if (!hadConn) {
                     connections = connections.filter((c) => c.id !== tempId);
-                    // Don't persist — was never in localStorage
                 }
-                // Restore previous credentials or remove temp ones
                 if (prevCreds) {
                     credentialStore.set(tempId, prevCreds);
                 }
                 else if (!hadConn) {
                     credentialStore.remove(tempId);
                 }
-                // Also clear any cached adapter for the temp connection
                 import('../storage/index.js').then(({ clearAdapterCache }) => clearAdapterCache(tempId));
             }
         },
-        /** True when a dialog open has been requested and not yet consumed. */
         get dialogRequested() {
             return dialogRequest > 0;
         },
-        /** Request opening the new-connection dialog from anywhere. */
         requestDialog() {
             dialogRequest++;
         },
-        /** Mark the dialog request as consumed. */
         clearDialogRequest() {
             dialogRequest = 0;
         },
-        /**
-         * Synchronous lookup by ID (from the already-loaded list).
-         */
         getById(id) {
             return connections.find((c) => c.id === id);
         },
         /**
-         * Find an existing connection that matches bucket + endpoint.
+         * Find an already-saved connection that matches the canonical identity
+         * of `input` (provider + bucket + endpoint/region per provider rules).
+         * Used by auto-detect, manual-add dedup, and edit-collision checks.
          */
-        findByBucketEndpoint(bucket, endpoint) {
-            return connections.find((c) => c.bucket === bucket && c.endpoint === endpoint);
+        findByIdentity(input) {
+            return findByIdentity(input);
         },
         /**
-         * Create a connection from a DetectedHost, deduplicating by bucket+endpoint.
-         * Returns the connection ID (existing or newly created).
+         * Auto-connect path for a URL-detected bucket. Reuses an existing
+         * connection when identity matches, otherwise creates one anonymously.
+         * Always returns the final connection ID.
          */
         async saveHostConnection(detected) {
-            const existing = this.findByBucketEndpoint(detected.bucket, detected.endpoint);
+            const identity = {
+                provider: detected.provider,
+                endpoint: detected.endpoint,
+                bucket: detected.bucket,
+                region: detected.region
+            };
+            const existing = findByIdentity(identity);
             if (existing)
                 return existing.id;
             const name = detected.bucket === '$web' ? `Azure Static Web` : detected.bucket;
-            const id = await this.save({
+            const result = await this.save({
                 name,
                 provider: detected.provider === 'unknown' ? 's3' : detected.provider,
                 endpoint: detected.endpoint,
@@ -238,9 +214,24 @@ function createConnectionsStore() {
                 anonymous: true,
                 rootPrefix: detected.rootPrefix || undefined
             });
-            return id;
+            return result.id;
         }
     };
 }
+/**
+ * Thrown by `update()` when the proposed identity collides with a different
+ * saved connection. Lets the UI tell the user which connection already owns
+ * that identity instead of silently producing a phantom duplicate.
+ */
+export class DuplicateConnectionError extends Error {
+    existingId;
+    existingName;
+    constructor(existingId, existingName) {
+        super(`A connection already exists for this bucket: "${existingName}"`);
+        this.name = 'DuplicateConnectionError';
+        this.existingId = existingId;
+        this.existingName = existingName;
+    }
+}
 export const connectionStore = createConnectionsStore();
 export { connectionStore as connections };

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

@@ -1,17 +1,20 @@
 import type { GetTileDataOptions, MinimalDataT } from '@developmentseed/deck.gl-geotiff';
-import type { RenderTileResult } from '@developmentseed/deck.gl-raster';
+import type { RasterModule, RenderTileResult } from '@developmentseed/deck.gl-raster';
 import type { GeoTIFF as GeoTIFFType, Overview } from '@developmentseed/geotiff';
 import { GeoTIFF } from '@developmentseed/geotiff';
 import type { EpsgResolver } from '@developmentseed/proj';
+import type { Device } from '@luma.gl/core';
 import type maplibregl from 'maplibre-gl';
-/** SampleFormat tag value → human label. */
-export declare const SF_LABELS: Record<number, string>;
-export type ColorRampId = 'grayscale' | 'terrain' | 'viridis' | 'magma' | 'turbo' | 'spectral';
-export declare const COLOR_RAMP_STOPS: Record<ColorRampId, [number, number, number][]>;
-/** Interpolate a normalized value (0..1) into an RGB color from a ramp. */
-export declare function interpolateRamp(stops: [number, number, number][], t: number): [number, number, number];
-/** Generate a CSS linear-gradient string for a color ramp. */
-export declare function rampToGradientCss(id: ColorRampId): string;
+import { buildDataTypeLabel, type CogInfo, clampBounds, type GeoBounds, SF_LABELS, safeClamp } from './cog-pure.js';
+import { type ColormapName } from './colormap-sprite.js';
+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
+ * GPU-side via the `Colormap` shader module; switching ramps is a uniform
+ * update, no tile re-decode.
+ */
+export type ColorRampId = ColormapName;
 export interface BandConfig {
     mode: 'rgb' | 'single';
     /** 0-indexed band indices for RGB channels */
@@ -78,6 +81,18 @@ export declare function createRescaledPipeline(geotiff: GeoTIFFType, rescale: Re
     getTileData: (image: GeoTIFFType | Overview, options: GetTileDataOptions) => Promise<MinimalDataT>;
     renderTile: (data: MinimalDataT) => RenderTileResult;
 };
+export interface BandRenderPipelineOptions {
+    /** Value treated as "no-data" and zeroed out by `FilterNoDataVal`. */
+    noDataVal?: number | null;
+    /** Linear rescale applied after no-data masking. Omit for no rescaling. */
+    rescale?: RescaleConfig;
+}
+/**
+ * Build a `renderPipeline` array for `MultiCOGLayer` / raster mosaics.
+ * Combines optional `FilterNoDataVal` + `LinearRescale` stages in the order
+ * the GPU expects (no-data mask first, then rescale).
+ */
+export declare function buildBandRenderPipeline(opts?: BandRenderPipelineOptions): RasterModule[];
 /**
  * Apply the two upstream-bug workarounds a GeoTIFF needs before being handed
  * to `COGLayer`:
@@ -123,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).
@@ -178,42 +170,95 @@ export interface CustomTileData {
     imageData: ImageData;
     width: number;
     height: number;
+    /**
+     * `sampler2DArray` colormap texture for single-band renders. Set by
+     * `createConfigurableGetTileData` / `createCustomGetTileData` when the
+     * first tile resolves the device-bound sprite texture; `undefined` for
+     * RGB-mode tiles (no colormap needed). Passed through to `renderTile`
+     * so the Colormap shader module can bind it on every layer.
+     */
+    colormapTexture?: Texture;
+    /**
+     * Normalized `color.r` sentinel value for nodata pixels in single-band
+     * mode. The `Colormap` shader module overwrites all 4 output channels
+     * from the 1D ramp sample, destroying the α=0 flag, so we reserve
+     * `r = 0` for nodata and renormalize valid data into `(0, 1]`.
+     * `FilterNoDataVal` then discards matching fragments before the ramp
+     * 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;
 /**
  * Check whether a GeoTIFF needs a custom render pipeline.
  * v0.3's inferRenderPipeline only supports unsigned integers (SampleFormat 1).
  * 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.
+ *
+ * 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;
 /**
  * Create custom getTileData for non-uint COGs.
  * Reads band 0, normalizes using GDAL statistics / per-tile adaptive stretch,
- * applies terrain color ramp for single-band data.
+ * bakes a grayscale `r`-channel image so the GPU `Colormap` shader module
+ * (wired downstream by `selectCogPipeline`) can apply the ramp by sampling
+ * `colormaps.png`. Reserves `r = 0` for nodata so `FilterNoDataVal` can
+ * discard those fragments before the ramp sample.
  */
-export declare function createCustomGetTileData(geotiff: GeoTIFFType): (image: GeoTIFFType | Overview, options: {
+export declare function createCustomGetTileData(geotiff: GeoTIFFType, _opts?: CustomGetTileDataOptions): (image: GeoTIFFType | Overview, options: {
     x: number;
     y: number;
     pool: unknown;
     signal?: AbortSignal;
+    device: Device;
 }) => Promise<CustomTileData>;
 /**
- * Custom renderTile for non-uint COGs.
- * v0.5 RasterLayer requires a RenderTileResult with `image` or `renderPipeline`.
- * We produce an ImageData and pass it through the `image` slot. deck.gl manages
- * the texture lifecycle and prepends a CreateTexture module automatically.
+ * Custom renderTile for COGs that use the CPU pipeline. For RGB mode (and
+ * legacy multi-band non-uint), the `image` slot carries a fully-baked RGBA
+ * `ImageData` and there is nothing to append on the GPU. For single-band
+ * mode, the image carries a normalized `r`-channel and this function
+ * appends `FilterNoDataVal` (to discard r=0 nodata sentinels), optional
+ * `LinearRescale` (brightness/contrast slider), and the sprite-based
+ * `Colormap` module so switching ramps is a uniform update — no tile
+ * re-decode required. The `colormapTexture` is stashed on `data` by the
+ * corresponding `getTileData` factory; if the sprite failed to resolve we
+ * fall back to the plain grayscale image.
  */
-export declare function customRenderTile(data: CustomTileData): {
-    image: ImageData;
-};
+export declare function buildCustomRenderTile(config: BandConfig, rescale?: RescaleConfig): (data: CustomTileData) => RenderTileResult;
 /**
  * Create a configurable getTileData that respects BandConfig.
- * Supports both RGB mode (multi-band → R,G,B) and single-band mode (color ramp).
+ * Supports RGB mode (multi-band → R,G,B with alpha=255, fully baked) and
+ * 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): (image: GeoTIFFType | Overview, options: {
+export declare function createConfigurableGetTileData(geotiff: GeoTIFFType, config: BandConfig, _opts?: CustomGetTileDataOptions): (image: GeoTIFFType | Overview, options: {
     x: number;
     y: number;
     pool: unknown;
     signal?: AbortSignal;
+    device: Device;
 }) => Promise<CustomTileData>;
 export interface PixelValue {
     lng: number;