@walkthru-earth/objex 1.2.1 → 1.3.1

package/dist/utils/stac.js

@@ -0,0 +1,176 @@
+/**
+ * STAC (SpatioTemporal Asset Catalog) detection and parsing.
+ *
+ * Pure TypeScript helpers shared by ViewerRouter, StacMosaicViewer, and
+ * MultiCogViewer. No Svelte dependency, publishable via objex-utils.
+ */
+/** Asset keys providers use for the single "display COG" asset, in priority order. */
+export const STAC_COG_ASSET_KEYS = ['visual', 'image', 'data', 'rendered_preview'];
+/** Shape-check a parsed JSON object as a STAC Item. */
+export function isStacItem(json) {
+    if (!json || typeof json !== 'object')
+        return false;
+    const obj = json;
+    return obj.type === 'Feature' && typeof obj.stac_version === 'string';
+}
+/** Shape-check a parsed JSON object as a STAC FeatureCollection. */
+export function isStacFeatureCollection(json) {
+    if (!json || typeof json !== 'object')
+        return false;
+    const obj = json;
+    if (obj.type !== 'FeatureCollection')
+        return false;
+    if (!Array.isArray(obj.features) || obj.features.length === 0)
+        return false;
+    if (typeof obj.stac_version === 'string')
+        return true;
+    return isStacItem(obj.features[0]);
+}
+/** STAC Collection detection: `type === 'Collection'` + stac_version + links array. */
+export function isStacCollection(json) {
+    if (!json || typeof json !== 'object')
+        return false;
+    const obj = json;
+    return (obj.type === 'Collection' && typeof obj.stac_version === 'string' && Array.isArray(obj.links));
+}
+/** STAC Catalog detection: `type === 'Catalog'` + stac_version + links array. */
+export function isStacCatalog(json) {
+    if (!json || typeof json !== 'object')
+        return false;
+    const obj = json;
+    return obj.type === 'Catalog' && typeof obj.stac_version === 'string' && Array.isArray(obj.links);
+}
+/** Classify an arbitrary parsed JSON into one of the STAC routing buckets. */
+export function classifyStac(json) {
+    if (isStacItem(json))
+        return { kind: 'item', item: json };
+    if (isStacFeatureCollection(json))
+        return { kind: 'item-collection', fc: json };
+    if (isStacCollection(json))
+        return { kind: 'collection', payload: json };
+    if (isStacCatalog(json))
+        return { kind: 'catalog', payload: json };
+    return { kind: 'none' };
+}
+/**
+ * Pick the COG-ish asset href from a STAC Item. Returns the href of the named
+ * asset when `preferred` is given and present, else scans STAC_COG_ASSET_KEYS,
+ * else falls back to any asset whose `type` contains "tiff". Returns null when
+ * nothing matches.
+ */
+export function pickCogAssetHref(item, preferred) {
+    const assets = item.assets ?? {};
+    if (preferred && assets[preferred]?.href)
+        return assets[preferred].href;
+    for (const key of STAC_COG_ASSET_KEYS) {
+        if (assets[key]?.href)
+            return assets[key].href;
+    }
+    for (const asset of Object.values(assets)) {
+        const t = typeof asset?.type === 'string' ? asset.type.toLowerCase() : '';
+        if (asset?.href && t.includes('tiff'))
+            return asset.href;
+    }
+    return null;
+}
+/** True when a single STAC Item exposes a COG-ish asset and a bbox. */
+export function detectMosaicCapable(item) {
+    return stacItemBbox(item) !== null && pickCogAssetHref(item) !== null;
+}
+/** True when a single STAC Item exposes Sentinel-2-style RGB bands (MultiCog). */
+export function detectMultiCogCapable(item) {
+    return hasRgbBands(extractSentinelBandAssets(item));
+}
+/** WGS84 bbox helper. Returns `null` if no bbox can be derived. */
+export function stacItemBbox(item) {
+    if (Array.isArray(item.bbox) && item.bbox.length >= 4) {
+        return [Number(item.bbox[0]), Number(item.bbox[1]), Number(item.bbox[2]), Number(item.bbox[3])];
+    }
+    return null;
+}
+/**
+ * Normalize a STAC Item or a plain `{id?, bbox, href}` record into a
+ * MosaicSourceMeta. Returns null when essentials (bbox / href) are missing.
+ */
+export function buildMosaicSourceMeta(input, assetKey) {
+    if (!input || typeof input !== 'object')
+        return null;
+    if (isStacItem(input)) {
+        const bbox = stacItemBbox(input);
+        if (!bbox)
+            return null;
+        const href = pickCogAssetHref(input, assetKey);
+        if (!href)
+            return null;
+        return {
+            id: String(input.id ?? href),
+            bbox,
+            href
+        };
+    }
+    const raw = input;
+    if (Array.isArray(raw.bbox) && raw.bbox.length >= 4 && typeof raw.href === 'string') {
+        return {
+            id: String(raw.id ?? raw.href),
+            bbox: [Number(raw.bbox[0]), Number(raw.bbox[1]), Number(raw.bbox[2]), Number(raw.bbox[3])],
+            href: raw.href
+        };
+    }
+    return null;
+}
+// Provider-specific asset key conventions. Each entry maps a BandSlot to the
+// asset keys providers are known to use. First match wins, so list more
+// specific keys before generic ones.
+const BAND_KEY_FALLBACKS = {
+    red: ['red', 'B04', 'B4', 'visual-red'],
+    green: ['green', 'B03', 'B3', 'visual-green'],
+    blue: ['blue', 'B02', 'B2', 'visual-blue'],
+    nir: ['nir', 'nir08', 'B08', 'B8', 'B8A'],
+    swir1: ['swir16', 'swir1', 'B11'],
+    swir2: ['swir22', 'swir2', 'B12'],
+    rededge: ['rededge1', 'rededge', 'B05', 'B5']
+};
+/**
+ * Map Sentinel-2 STAC item assets to a BandMap. Recognizes:
+ *  - `eo:bands[0].common_name` (preferred, stable across providers)
+ *  - asset key heuristics for Microsoft PC / Element 84 / AWS S2 L2A buckets
+ * Returns an empty map when no bands are identifiable so callers can fall
+ * back to a different viewer.
+ */
+export function extractSentinelBandAssets(item) {
+    const out = {};
+    const assets = item.assets ?? {};
+    for (const [key, asset] of Object.entries(assets)) {
+        if (!asset?.href)
+            continue;
+        const bands = asset['eo:bands'];
+        if (Array.isArray(bands) && bands.length >= 1) {
+            const common = bands[0]?.common_name?.toLowerCase();
+            if (common && isBandSlot(common)) {
+                if (!out[common])
+                    out[common] = asset.href;
+                continue;
+            }
+        }
+        for (const slot of Object.keys(BAND_KEY_FALLBACKS)) {
+            if (BAND_KEY_FALLBACKS[slot].includes(key) && !out[slot]) {
+                out[slot] = asset.href;
+                break;
+            }
+        }
+    }
+    return out;
+}
+function isBandSlot(value) {
+    return (value === 'red' ||
+        value === 'green' ||
+        value === 'blue' ||
+        value === 'nir' ||
+        value === 'swir1' ||
+        value === 'swir2' ||
+        value === 'rededge');
+}
+/** True when the band map has enough channels for a True Color composite. */
+export function hasRgbBands(map) {
+    return Boolean(map.red && map.green && map.blue);
+}

package/dist/utils/storage-url.d.ts

@@ -44,6 +44,13 @@ export interface ParsedStorageUrl {
     /** Original prefix/path after bucket, if any */
     prefix: string;
 }
+/** STAC API path test, one source of truth. Tests pathname only. */
+export declare const STAC_API_PATH_RE: RegExp;
+/**
+ * Returns true when the host matches any of the provider host patterns
+ * that `parseStorageUrl` recognizes on the HTTPS branch.
+ */
+export declare function isKnownBucketHost(host: string): boolean;
 export interface Defaults {
     region?: string;
     endpoint?: string;
@@ -62,3 +69,22 @@ export declare function looksLikeUrl(input: string): boolean;
  * Given a parsed URL result, build a human-readable summary of what was detected.
  */
 export declare function describeParseResult(parsed: ParsedStorageUrl): string;
+export type UrlClassification = {
+    kind: 'scheme';
+    parsed: ParsedStorageUrl;
+} | {
+    kind: 'object-storage';
+    parsed: ParsedStorageUrl;
+} | {
+    kind: 'stac-api';
+    url: URL;
+} | {
+    kind: 'remote-file';
+    url: URL;
+};
+/**
+ * Classify a user-supplied URL/URI into one of four buckets. Unparseable or
+ * plain inputs fall through to `remote-file` with a best-effort URL parse,
+ * returning a synthetic `https://` URL when `new URL()` would throw.
+ */
+export declare function classifyUrl(input: string): UrlClassification;

package/dist/utils/storage-url.js

@@ -54,6 +54,96 @@ function buildSchemeMap() {
 }
 /** All recognized URI scheme prefixes (lowercase), derived from provider registry */
 const SCHEME_MAP = buildSchemeMap();
+/**
+ * Shared host matchers. Used by both `parseStorageUrl` and `isKnownBucketHost`
+ * so provider recognition has a single source of truth.
+ */
+const AWS_VHOST_RE = /^(.+)\.s3[.-]([a-z0-9-]+)\.amazonaws\.com$/;
+const AWS_PATH_RE = /^s3[.-]([a-z0-9-]+)\.amazonaws\.com$/;
+const AWS_GLOBAL_HOST = 's3.amazonaws.com';
+const R2_RE = /^([a-z0-9]+)\.r2\.cloudflarestorage\.com$/;
+const GCS_GLOBAL_HOST = 'storage.googleapis.com';
+const GCS_VHOST_RE = /^(.+)\.storage\.googleapis\.com$/;
+const DO_VHOST_RE = /^(.+)\.([a-z0-9-]+)\.digitaloceanspaces\.com$/;
+const DO_PATH_RE = /^([a-z0-9-]+)\.digitaloceanspaces\.com$/;
+const WASABI_RE = /^s3\.([a-z0-9-]+)\.wasabisys\.com$/;
+const B2_S3_RE = /^(.+)\.s3\.([a-z0-9-]+)\.backblazeb2\.com$/;
+const B2_NATIVE_RE = /^f[a-z0-9]+\.backblazeb2\.com$/;
+const OSS_RE = /^(.+)\.(oss-[a-z0-9-]+)\.aliyuncs\.com$/;
+const COS_RE = /^(.+)\.cos\.([a-z0-9-]+)\.myqcloud\.com$/;
+const YANDEX_HOST = 'storage.yandexcloud.net';
+const CONTABO_RE = /^([a-z0-9]+)\.contabostorage\.com$/;
+const HETZNER_RE = /^([a-z0-9]+)\.your-objectstorage\.com$/;
+const LINODE_VHOST_RE = /^(.+)\.([a-z0-9-]+)\.linodeobjects\.com$/;
+const LINODE_PATH_RE = /^([a-z0-9-]+)\.linodeobjects\.com$/;
+const OVH_RE = /^s3\.([a-z0-9-]+)\.io\.cloud\.ovh\.(?:net|us)$/;
+const AZURE_BLOB_RE = /^([a-z0-9]+)\.blob\.core\.windows\.net$/;
+const STORJ_GATEWAY_RE = /^gateway\.(?:([a-z0-9]+)\.)?storjshare\.io$/;
+const STORJ_LINK_RE = /^link\.(?:([a-z0-9]+)\.)?storjshare\.io$/;
+function isMinioLikeHost(host) {
+    return (host.includes('minio') ||
+        host === 'localhost' ||
+        host === '127.0.0.1' ||
+        host.startsWith('192.168.') ||
+        host.startsWith('10.'));
+}
+/** STAC API path test, one source of truth. Tests pathname only. */
+export const STAC_API_PATH_RE = /\/(collections|items|catalogs|search)(\/|\?|$)/i;
+/**
+ * Returns true when the host matches any of the provider host patterns
+ * that `parseStorageUrl` recognizes on the HTTPS branch.
+ */
+export function isKnownBucketHost(host) {
+    if (!host)
+        return false;
+    if (AWS_VHOST_RE.test(host))
+        return true;
+    if (AWS_PATH_RE.test(host))
+        return true;
+    if (host === AWS_GLOBAL_HOST)
+        return true;
+    if (R2_RE.test(host))
+        return true;
+    if (host === GCS_GLOBAL_HOST)
+        return true;
+    if (GCS_VHOST_RE.test(host))
+        return true;
+    if (DO_VHOST_RE.test(host))
+        return true;
+    if (DO_PATH_RE.test(host))
+        return true;
+    if (WASABI_RE.test(host))
+        return true;
+    if (B2_S3_RE.test(host))
+        return true;
+    if (B2_NATIVE_RE.test(host))
+        return true;
+    if (OSS_RE.test(host))
+        return true;
+    if (COS_RE.test(host))
+        return true;
+    if (host === YANDEX_HOST)
+        return true;
+    if (CONTABO_RE.test(host))
+        return true;
+    if (HETZNER_RE.test(host))
+        return true;
+    if (LINODE_VHOST_RE.test(host))
+        return true;
+    if (LINODE_PATH_RE.test(host))
+        return true;
+    if (OVH_RE.test(host))
+        return true;
+    if (AZURE_BLOB_RE.test(host))
+        return true;
+    if (STORJ_GATEWAY_RE.test(host))
+        return true;
+    if (STORJ_LINK_RE.test(host))
+        return true;
+    if (isMinioLikeHost(host))
+        return true;
+    return false;
+}
 function defaultResult(defaults) {
     return {
         bucket: '',
@@ -101,7 +191,7 @@ export function parseStorageUrl(input, defaults = {}) {
             const pathParts = url.pathname.replace(/^\//, '').split('/').filter(Boolean);
             // --- AWS S3 ---
             // Virtual-hosted: <bucket>.s3.<region>.amazonaws.com
-            const awsVhost = host.match(/^(.+)\.s3[.-]([a-z0-9-]+)\.amazonaws\.com$/);
+            const awsVhost = host.match(AWS_VHOST_RE);
             if (awsVhost) {
                 return {
                     bucket: awsVhost[1],
@@ -112,7 +202,7 @@ export function parseStorageUrl(input, defaults = {}) {
                 };
             }
             // Path-style: s3.<region>.amazonaws.com/<bucket>
-            const awsPath = host.match(/^s3[.-]([a-z0-9-]+)\.amazonaws\.com$/);
+            const awsPath = host.match(AWS_PATH_RE);
             if (awsPath && pathParts.length > 0) {
                 return {
                     bucket: pathParts[0],
@@ -123,7 +213,7 @@ export function parseStorageUrl(input, defaults = {}) {
                 };
             }
             // Global: s3.amazonaws.com/<bucket>
-            if (host === 's3.amazonaws.com' && pathParts.length > 0) {
+            if (host === AWS_GLOBAL_HOST && pathParts.length > 0) {
                 return {
                     bucket: pathParts[0],
                     region: defaults.region || 'us-east-1',
@@ -134,7 +224,7 @@ export function parseStorageUrl(input, defaults = {}) {
             }
             // --- Cloudflare R2 ---
             // <account>.r2.cloudflarestorage.com/<bucket>
-            const r2Match = host.match(/^([a-z0-9]+)\.r2\.cloudflarestorage\.com$/);
+            const r2Match = host.match(R2_RE);
             if (r2Match && pathParts.length > 0) {
                 return {
                     bucket: pathParts[0],
@@ -146,7 +236,7 @@ export function parseStorageUrl(input, defaults = {}) {
             }
             // --- Google Cloud Storage ---
             // storage.googleapis.com/<bucket>
-            if (host === 'storage.googleapis.com' && pathParts.length > 0) {
+            if (host === GCS_GLOBAL_HOST && pathParts.length > 0) {
                 return {
                     bucket: pathParts[0],
                     region: defaults.region || 'us',
@@ -156,7 +246,7 @@ export function parseStorageUrl(input, defaults = {}) {
                 };
             }
             // <bucket>.storage.googleapis.com
-            const gcsVhost = host.match(/^(.+)\.storage\.googleapis\.com$/);
+            const gcsVhost = host.match(GCS_VHOST_RE);
             if (gcsVhost) {
                 return {
                     bucket: gcsVhost[1],
@@ -168,7 +258,7 @@ export function parseStorageUrl(input, defaults = {}) {
             }
             // --- DigitalOcean Spaces ---
             // <bucket>.<region>.digitaloceanspaces.com
-            const doVhost = host.match(/^(.+)\.([a-z0-9-]+)\.digitaloceanspaces\.com$/);
+            const doVhost = host.match(DO_VHOST_RE);
             if (doVhost) {
                 return {
                     bucket: doVhost[1],
@@ -179,7 +269,7 @@ export function parseStorageUrl(input, defaults = {}) {
                 };
             }
             // <region>.digitaloceanspaces.com/<bucket>
-            const doPath = host.match(/^([a-z0-9-]+)\.digitaloceanspaces\.com$/);
+            const doPath = host.match(DO_PATH_RE);
             if (doPath && pathParts.length > 0) {
                 return {
                     bucket: pathParts[0],
@@ -191,7 +281,7 @@ export function parseStorageUrl(input, defaults = {}) {
             }
             // --- Wasabi ---
             // s3.<region>.wasabisys.com/<bucket>
-            const wasabiMatch = host.match(/^s3\.([a-z0-9-]+)\.wasabisys\.com$/);
+            const wasabiMatch = host.match(WASABI_RE);
             if (wasabiMatch && pathParts.length > 0) {
                 return {
                     bucket: pathParts[0],
@@ -203,7 +293,7 @@ export function parseStorageUrl(input, defaults = {}) {
             }
             // --- Backblaze B2 ---
             // <bucket>.s3.<region>.backblazeb2.com (S3-compatible)
-            const b2S3 = host.match(/^(.+)\.s3\.([a-z0-9-]+)\.backblazeb2\.com$/);
+            const b2S3 = host.match(B2_S3_RE);
             if (b2S3) {
                 return {
                     bucket: b2S3[1],
@@ -214,7 +304,7 @@ export function parseStorageUrl(input, defaults = {}) {
                 };
             }
             // f<id>.backblazeb2.com/file/<bucket>
-            const b2Native = host.match(/^f[a-z0-9]+\.backblazeb2\.com$/);
+            const b2Native = host.match(B2_NATIVE_RE);
             if (b2Native && pathParts[0] === 'file' && pathParts.length > 1) {
                 return {
                     bucket: pathParts[1],
@@ -226,7 +316,7 @@ export function parseStorageUrl(input, defaults = {}) {
             }
             // --- Alibaba Cloud OSS ---
             // <bucket>.oss-<region>.aliyuncs.com
-            const ossMatch = host.match(/^(.+)\.(oss-[a-z0-9-]+)\.aliyuncs\.com$/);
+            const ossMatch = host.match(OSS_RE);
             if (ossMatch) {
                 return {
                     bucket: ossMatch[1],
@@ -238,7 +328,7 @@ export function parseStorageUrl(input, defaults = {}) {
             }
             // --- Tencent Cloud COS ---
             // <bucket>.cos.<region>.myqcloud.com
-            const cosMatch = host.match(/^(.+)\.cos\.([a-z0-9-]+)\.myqcloud\.com$/);
+            const cosMatch = host.match(COS_RE);
             if (cosMatch) {
                 return {
                     bucket: cosMatch[1],
@@ -250,7 +340,7 @@ export function parseStorageUrl(input, defaults = {}) {
             }
             // --- Yandex Cloud ---
             // storage.yandexcloud.net/<bucket>
-            if (host === 'storage.yandexcloud.net' && pathParts.length > 0) {
+            if (host === YANDEX_HOST && pathParts.length > 0) {
                 return {
                     bucket: pathParts[0],
                     region: defaults.region || 'ru-central1',
@@ -261,7 +351,7 @@ export function parseStorageUrl(input, defaults = {}) {
             }
             // --- Contabo ---
             // <region>.contabostorage.com/<bucket>
-            const contaboMatch = host.match(/^([a-z0-9]+)\.contabostorage\.com$/);
+            const contaboMatch = host.match(CONTABO_RE);
             if (contaboMatch && pathParts.length > 0) {
                 return {
                     bucket: pathParts[0],
@@ -273,7 +363,7 @@ export function parseStorageUrl(input, defaults = {}) {
             }
             // --- Hetzner ---
             // <region>.your-objectstorage.com/<bucket>
-            const hetznerMatch = host.match(/^([a-z0-9]+)\.your-objectstorage\.com$/);
+            const hetznerMatch = host.match(HETZNER_RE);
             if (hetznerMatch && pathParts.length > 0) {
                 return {
                     bucket: pathParts[0],
@@ -285,7 +375,7 @@ export function parseStorageUrl(input, defaults = {}) {
             }
             // --- Linode / Akamai ---
             // <bucket>.<region>.linodeobjects.com or <region>.linodeobjects.com/<bucket>
-            const linodeVhost = host.match(/^(.+)\.([a-z0-9-]+)\.linodeobjects\.com$/);
+            const linodeVhost = host.match(LINODE_VHOST_RE);
             if (linodeVhost) {
                 return {
                     bucket: linodeVhost[1],
@@ -295,7 +385,7 @@ export function parseStorageUrl(input, defaults = {}) {
                     prefix: pathParts.join('/')
                 };
             }
-            const linodePath = host.match(/^([a-z0-9-]+)\.linodeobjects\.com$/);
+            const linodePath = host.match(LINODE_PATH_RE);
             if (linodePath && pathParts.length > 0) {
                 return {
                     bucket: pathParts[0],
@@ -307,7 +397,7 @@ export function parseStorageUrl(input, defaults = {}) {
             }
             // --- OVHcloud ---
             // s3.<region>.io.cloud.ovh.net/<bucket>
-            const ovhMatch = host.match(/^s3\.([a-z0-9-]+)\.io\.cloud\.ovh\.(?:net|us)$/);
+            const ovhMatch = host.match(OVH_RE);
             if (ovhMatch && pathParts.length > 0) {
                 return {
                     bucket: pathParts[0],
@@ -319,12 +409,7 @@ export function parseStorageUrl(input, defaults = {}) {
             }
             // --- MinIO ---
             // Common patterns: minio.<domain>, localhost with port
-            const isMinioLike = host.includes('minio') ||
-                host === 'localhost' ||
-                host === '127.0.0.1' ||
-                host.startsWith('192.168.') ||
-                host.startsWith('10.');
-            if (isMinioLike && pathParts.length > 0) {
+            if (isMinioLikeHost(host) && pathParts.length > 0) {
                 return {
                     bucket: pathParts[0],
                     region: defaults.region || 'us-east-1',
@@ -335,7 +420,7 @@ export function parseStorageUrl(input, defaults = {}) {
             }
             // --- Azure Blob Storage ---
             // <account>.blob.core.windows.net/<container>
-            const azureBlob = host.match(/^([a-z0-9]+)\.blob\.core\.windows\.net$/);
+            const azureBlob = host.match(AZURE_BLOB_RE);
             if (azureBlob && pathParts.length > 0) {
                 return {
                     bucket: pathParts[0],
@@ -347,7 +432,7 @@ export function parseStorageUrl(input, defaults = {}) {
             }
             // --- Storj ---
             // S3 gateway: gateway.storjshare.io/<bucket> (or gateway.<region>.storjshare.io)
-            const storjGateway = host.match(/^gateway\.(?:([a-z0-9]+)\.)?storjshare\.io$/);
+            const storjGateway = host.match(STORJ_GATEWAY_RE);
             if (storjGateway && pathParts.length > 0) {
                 return {
                     bucket: pathParts[0],
@@ -358,7 +443,7 @@ export function parseStorageUrl(input, defaults = {}) {
                 };
             }
             // Linksharing: link.storjshare.io/raw/<access>/<bucket>/... or /s/<access>/<bucket>/...
-            const storjLink = host.match(/^link\.(?:([a-z0-9]+)\.)?storjshare\.io$/);
+            const storjLink = host.match(STORJ_LINK_RE);
             if (storjLink && pathParts.length >= 3 && (pathParts[0] === 'raw' || pathParts[0] === 's')) {
                 return {
                     bucket: pathParts[2],
@@ -368,6 +453,17 @@ export function parseStorageUrl(input, defaults = {}) {
                     prefix: pathParts.slice(3).join('/')
                 };
             }
+            // --- STAC API endpoints (Element 84, MPC, etc.) ---
+            // Paths like /v1/collections/.../items/... are not S3 buckets, the
+            // first path segment is an API version, not a bucket name. Return
+            // no bucket so detectHostBucket() falls through and the URL opens
+            // as a direct remote fetch.
+            if (STAC_API_PATH_RE.test(url.pathname)) {
+                return {
+                    ...defaultResult(defaults),
+                    endpoint: `${url.protocol}//${url.host}`
+                };
+            }
             // --- Generic custom endpoint with bucket in path ---
             if (pathParts.length > 0) {
                 const endpoint = `${url.protocol}//${url.host}`;
@@ -430,3 +526,43 @@ export function describeParseResult(parsed) {
         parts.push(`prefix="${parsed.prefix}"`);
     return parts.length > 0 ? `Detected: ${parts.join(', ')}` : '';
 }
+/**
+ * Classify a user-supplied URL/URI into one of four buckets. Unparseable or
+ * plain inputs fall through to `remote-file` with a best-effort URL parse,
+ * returning a synthetic `https://` URL when `new URL()` would throw.
+ */
+export function classifyUrl(input) {
+    const trimmed = input.trim();
+    const lower = trimmed.toLowerCase();
+    for (const scheme of Object.keys(SCHEME_MAP)) {
+        if (lower.startsWith(scheme)) {
+            return { kind: 'scheme', parsed: parseStorageUrl(trimmed) };
+        }
+    }
+    if (lower.startsWith('http://') || lower.startsWith('https://')) {
+        let url;
+        try {
+            url = new URL(trimmed);
+        }
+        catch {
+            return {
+                kind: 'remote-file',
+                url: new URL(`https://${trimmed.replace(/^https?:\/\//i, '')}`)
+            };
+        }
+        const parsed = parseStorageUrl(trimmed);
+        if (parsed.bucket && isKnownBucketHost(url.hostname)) {
+            return { kind: 'object-storage', parsed };
+        }
+        if (STAC_API_PATH_RE.test(url.pathname)) {
+            return { kind: 'stac-api', url };
+        }
+        return { kind: 'remote-file', url };
+    }
+    try {
+        return { kind: 'remote-file', url: new URL(trimmed) };
+    }
+    catch {
+        return { kind: 'remote-file', url: new URL(`https://${trimmed}`) };
+    }
+}

package/dist/utils/zarr.d.ts

@@ -44,6 +44,40 @@ export interface ZarrHierarchy {
     storeAttrs: Record<string, any>;
     spatialRefAttrs: Record<string, any> | null;
 }
+export interface GeoZarrInfo {
+    /** Relative path within the store to the group carrying GeoZarr attrs. */
+    variantPath: string;
+    /** Raw attributes object that parses as GeoZarr (for caller re-use). */
+    attrs: Record<string, any>;
+}
+/**
+ * Walk the hierarchy looking for a node whose attributes satisfy the core
+ * GeoZarr convention: `multiscales` + a spatial convention (`spatial` /
+ * `spatial:dimensions`) + CRS info (`geo-proj`, `proj:code`, or `crs_wkt`).
+ *
+ * Check is shape-only (no zarrita I/O), so it's safe to call synchronously
+ * after `fetchHierarchy`. A non-null return indicates the store should be
+ * rendered via `@developmentseed/deck.gl-zarr`; a null return sends the
+ * caller to the `@carbonplan/zarr-layer` fallback.
+ */
+export declare function detectGeoZarr(hierarchy: ZarrHierarchy): GeoZarrInfo | null;
+/**
+ * Convert a decoded GeoZarr tile (band-planar or packed RGB) into RGBA
+ * `ImageData` for deck.gl-zarr's `renderTile` callback. Input is expected to
+ * be a Uint8 or Uint16 typed array with either 3 interleaved bytes per pixel
+ * or 3 planar bands of width*height values.
+ *
+ * For 16-bit data the caller supplies the rescale range so the CPU
+ * normalization matches what the GPU `LinearRescale` module would produce.
+ */
+export declare function zarrTileToImageData(raw: ArrayLike<number> & {
+    length: number;
+}, width: number, height: number, opts?: {
+    layout?: 'packed' | 'planar';
+    bands?: 1 | 3;
+    rescaleMin?: number;
+    rescaleMax?: number;
+}): ImageData;
 /** Dimension-like variable names treated as coordinates. */
 export declare const DIM_LIKE_NAMES: Set<string>;
 /** Guess dimension names from shape length when metadata is absent. */