@walkthru-earth/objex-utils 1.3.0 → 1.4.0

package/dist/index.d.ts

@@ -39,7 +39,7 @@ declare const COPY_FEEDBACK_MS = 2000;
  * Single source of truth for extension → icon, color, label, category,
  * viewer, DuckDB read function, MIME type, and queryability.
  *
- * Used by: FileRow, FileTreeSidebar, ViewerRouter, TableViewer, WasmQueryEngine, etc.
+ * Used by: FileTreeSidebar, ViewerRouter, TableViewer, WasmQueryEngine, etc.
  */
 type FileCategory = 'data' | 'geo' | 'code' | 'document' | 'config' | 'image' | 'video' | 'audio' | 'archive' | 'database' | '3d' | 'other';
 type ViewerKind = 'table' | 'image' | 'video' | 'audio' | 'markdown' | 'code' | 'cog' | 'pmtiles' | 'flatgeobuf' | 'pdf' | '3d' | 'archive' | 'database' | 'zarr' | 'copc' | 'notebook' | 'raw';
@@ -149,6 +149,16 @@ interface QueryEngine {
         crs: string | null;
     }>;
     queryCancellable?(connId: string, sql: string): QueryHandle;
+    /**
+     * Streaming variant of `queryCancellable`. Yields one `QueryResult`-shaped
+     * chunk per Arrow RecordBatch instead of materializing the full row set
+     * before returning. Peak memory tracks one batch (~64 KiB rows) rather
+     * than the full result, which avoids DuckDB-WASM OOMs on large parquet
+     * scans. The first chunk carries the schema (`columns` / `types`); later
+     * chunks repeat them so consumers don't need to track first-batch state.
+     * Cancellation aborts the inner DuckDB cursor.
+     */
+    queryStream?(connId: string, sql: string, signal?: AbortSignal): AsyncIterable<QueryResult>;
     queryForMapCancellable?(connId: string, sql: string, geomCol: string, geomColType: string, sourceCrs?: string | null): MapQueryHandle;
     forceCancel?(): Promise<void>;
     /** Register a file buffer in DuckDB-WASM's virtual filesystem for ATTACH. */
@@ -344,6 +354,431 @@ declare class UrlAdapter implements StorageAdapter {
     copy(): Promise<WriteResult>;
 }
 
+/** A basemap option a host can offer. Consumed in Phase 2. */
+interface BasemapConfig {
+    id: string;
+    label: string;
+    type: 'vector' | 'raster';
+    url: string;
+    variant?: 'light' | 'dark';
+}
+/** A preloaded connection definition. Never carries secrets. Consumed in Phase 2. */
+interface ConnectionSeed {
+    name: string;
+    provider: string;
+    bucket: string;
+    region?: string;
+    endpoint?: string;
+    anonymous?: boolean;
+    authMethod?: 'sigv4' | 'sas-token';
+    rootPrefix?: string;
+}
+interface AppConfigDefaults {
+    theme: Theme;
+    locale: string;
+    featureLimit: number;
+    mosaicItemLimit: number;
+}
+interface AppConfigUi {
+    showConnectionRail: boolean;
+    showFileTree: boolean;
+    showSettings: boolean;
+}
+interface AppConfig {
+    defaults: AppConfigDefaults;
+    ui: AppConfigUi;
+    basemaps: BasemapConfig[];
+    defaultBasemap: {
+        light?: string;
+        dark?: string;
+    };
+    connections: ConnectionSeed[];
+}
+/** Hardcoded fallback. Matches current app behaviour when no config is present. */
+declare const DEFAULT_APP_CONFIG: AppConfig;
+declare function coerceTheme(v: unknown): Theme | undefined;
+declare function coerceString(v: unknown): string | undefined;
+declare function coercePositiveInt(v: unknown): number | undefined;
+declare function coerceBool(v: unknown): boolean | undefined;
+/** First defined (non-null, non-undefined) candidate wins. Encodes the precedence chain. */
+declare function resolveSetting<T>(...candidates: (T | null | undefined)[]): T | undefined;
+/** Maps the ?sidebar / ?tree visibility param to a boolean, or undefined when absent or invalid. */
+declare function parseVisibilityParam(value: string | null): boolean | undefined;
+/**
+ * Pick the basemap a map should render. Precedence: explicit user pick (when it
+ * still exists in the configured list) > the configured default for the theme
+ * variant > the first basemap matching the variant > the first basemap of any
+ * variant. Returns undefined when no basemaps are configured, signalling the
+ * caller to fall back to its hardcoded default.
+ */
+declare function resolveBasemap(config: AppConfig, variant: 'light' | 'dark', userId: string | undefined): BasemapConfig | undefined;
+/**
+ * Merge an untrusted JSON value over a base config, field by field.
+ * Unknown fields are ignored. Malformed values fall back to the base.
+ * Never reads secrets.
+ */
+declare function mergeAppConfig(base: AppConfig, override: unknown): AppConfig;
+
+/**
+ * STAC (SpatioTemporal Asset Catalog) detection and parsing.
+ *
+ * Pure TypeScript helpers shared by ViewerRouter, StacMosaicViewer, and
+ * MultiCogViewer. No Svelte dependency, publishable via objex-utils.
+ */
+/** STAC Link (shared by Catalog/Collection/Item). */
+interface StacLink {
+    rel: string;
+    href: string;
+    type?: string;
+    title?: string;
+}
+/** STAC Item (GeoJSON Feature shape with stac_version). */
+interface StacItem {
+    type: 'Feature';
+    stac_version: string;
+    id: string;
+    bbox?: [number, number, number, number];
+    geometry?: unknown;
+    properties?: Record<string, unknown>;
+    assets?: Record<string, StacAsset>;
+    collection?: string;
+    links?: StacLink[];
+}
+/** STAC FeatureCollection (collection of Items). Also used for STAC API responses. */
+interface StacFeatureCollection {
+    type: 'FeatureCollection';
+    stac_version?: string;
+    features: StacItem[];
+    links?: StacLink[];
+}
+/** STAC Collection (a grouping of Items with its own metadata and links). */
+interface StacCollection {
+    type: 'Collection';
+    stac_version: string;
+    id: string;
+    description?: string;
+    extent?: {
+        spatial?: {
+            bbox?: number[][];
+        };
+        temporal?: unknown;
+    };
+    links: StacLink[];
+}
+/** STAC Catalog (a directory-like grouping of Catalogs/Collections/Items via links). */
+interface StacCatalog {
+    type: 'Catalog';
+    stac_version: string;
+    id: string;
+    description?: string;
+    links: StacLink[];
+}
+/** Single asset entry within a STAC item. */
+interface StacAsset {
+    href: string;
+    type?: string;
+    title?: string;
+    roles?: string[];
+    /** Set when the asset carries `eo:bands`. */
+    'eo:bands'?: {
+        name?: string;
+        common_name?: string;
+    }[];
+}
+/** Sentinel-2 band slot identifier, shared with utils/cog.ts composites. */
+type BandSlot = 'red' | 'green' | 'blue' | 'nir' | 'swir1' | 'swir2' | 'rededge';
+/** Parsed band map: slot name → HTTPS asset URL. */
+type BandMap = Partial<Record<BandSlot, string>>;
+/** Asset keys providers use for the single "display COG" asset, in priority order. */
+declare const STAC_COG_ASSET_KEYS: readonly ["visual", "image", "data", "rendered_preview"];
+/** Shape-check a parsed JSON object as a STAC Item. */
+declare function isStacItem(json: unknown): json is StacItem;
+/** Shape-check a parsed JSON object as a STAC FeatureCollection. */
+declare function isStacFeatureCollection(json: unknown): json is StacFeatureCollection;
+/** STAC Collection detection: `type === 'Collection'` + stac_version + links array. */
+declare function isStacCollection(json: unknown): json is StacCollection;
+/** STAC Catalog detection: `type === 'Catalog'` + stac_version + links array. */
+declare function isStacCatalog(json: unknown): json is StacCatalog;
+/** Routing verdict for any STAC-shaped JSON payload. */
+type StacRoutableKind = {
+    kind: 'item';
+    item: StacItem;
+} | {
+    kind: 'item-collection';
+    fc: StacFeatureCollection;
+} | {
+    kind: 'collection';
+    payload: StacCollection;
+} | {
+    kind: 'catalog';
+    payload: StacCatalog;
+} | {
+    kind: 'none';
+};
+/** Classify an arbitrary parsed JSON into one of the STAC routing buckets. */
+declare function classifyStac(json: unknown): StacRoutableKind;
+/**
+ * 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.
+ */
+declare function pickCogAssetHref(item: StacItem, preferred?: string): string | null;
+/** True when a single STAC Item exposes a COG-ish asset and a bbox. */
+declare function detectMosaicCapable(item: StacItem): boolean;
+/** True when a single STAC Item exposes ≥3 single-band raster COG assets,
+ *  whether tagged with S2-style common names or not. The MultiCogViewer's
+ *  band picker fills in the gap when presets don't auto-resolve. */
+declare function detectMultiCogCapable(item: StacItem): boolean;
+/** WGS84 bbox helper. Returns `null` if no bbox can be derived. */
+declare function stacItemBbox(item: StacItem): [number, number, number, number] | null;
+/** Normalized mosaic source entry consumed by MosaicLayer. */
+interface MosaicSourceMeta {
+    id: string;
+    bbox: [number, number, number, number];
+    href: string;
+}
+/**
+ * Normalize a STAC Item or a plain `{id?, bbox, href}` record into a
+ * MosaicSourceMeta. Returns null when essentials (bbox / href) are missing.
+ */
+declare function buildMosaicSourceMeta(input: StacItem | {
+    id?: string;
+    bbox: [number, number, number, number] | number[];
+    href: string;
+}, assetKey?: string): MosaicSourceMeta | null;
+/**
+ * Stable spatial cell key for an item, used to dedupe revisits when the
+ * caller wants only the freshest scene per footprint. STAC providers
+ * default to descending-datetime sort, so the first item per key is the
+ * newest. Prefers STAC `grid:code`, then Sentinel-2 MGRS triplet, then
+ * `s2:mgrs_tile`, then a rounded bbox so non-S2 providers still dedupe.
+ */
+declare function spatialCellKey(item: StacItem, bbox: [number, number, number, number]): string;
+/**
+ * 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.
+ */
+declare function extractSentinelBandAssets(item: StacItem): BandMap;
+/** True when the band map has enough channels for a True Color composite. */
+declare function hasRgbBands(map: BandMap): boolean;
+/**
+ * Generic raster band asset description, vendor-neutral. Carries the bits a
+ * MultiCOG band picker needs to populate dropdowns and resolve presets.
+ *
+ * `key` is the STAC asset key as it appears in `item.assets` (`red`, `B04`,
+ * `image`, `analytic`, ...). It is the natural identifier and lines up 1:1
+ * with `MultiCOGLayer.sources`'s record key.
+ */
+interface RasterBandAsset {
+    key: string;
+    href: string;
+    commonName?: string;
+    bandCount?: number;
+    roles?: string[];
+    mediaType?: string;
+    title?: string;
+}
+/**
+ * Enumerate every asset on a STAC Item that looks like a single-band raster
+ * COG suitable for compositing in MultiCOGLayer. Used by the band picker UI.
+ *
+ * Inclusion: `media_type` matches `image/tiff*` (drops JP2 mirrors, PNGs,
+ * thumbnails) AND it is not a thumbnail / overview / metadata role. Pre-baked
+ * multi-band visuals (`raster:bands.length > 1` or `eo:bands.length > 1`) are
+ * dropped because compositing needs single-band sources, not a 3-band visual
+ * COG; that asset belongs in `CogViewer`.
+ *
+ * `bandCount` is reported as `1` when neither tag is present and the asset
+ * media type is COG-like, so vendor catalogs that omit `eo:bands` are still
+ * pickable. Callers wanting to be strict can filter on `bandCount === 1`.
+ */
+declare function extractRasterBandAssets(item: StacItem): RasterBandAsset[];
+/**
+ * Resolve a semantic band slot to an asset key on this Item.
+ *
+ * Priority:
+ *   1. First asset whose `eo:bands[0].common_name` (lowercased) equals the slot.
+ *   2. First asset whose key appears in `BAND_KEY_FALLBACKS[slot]` (vendor key
+ *      conventions: `B04`, `red-jp2`, etc.).
+ *
+ * Returns the asset key (NOT the href) so callers can plumb it into
+ * `composite: { r, g, b }` and look it up in `extractRasterBandAssets()`.
+ */
+declare function resolveBandSlotAssetKey(assets: RasterBandAsset[], slot: BandSlot): string | undefined;
+/**
+ * Resolve a preset's R/G/B BandSlot triple into asset keys for this Item.
+ * Returns null when any of the three required slots cannot be resolved, so
+ * the caller can disable the preset rather than half-apply it.
+ */
+declare function resolvePresetComposite(assets: RasterBandAsset[], composite: {
+    r: BandSlot;
+    g: BandSlot;
+    b: BandSlot;
+}): {
+    r: string;
+    g: string;
+    b: string;
+} | null;
+/** True when ≥3 single-band raster COG assets exist, so manual RGB pick is viable. */
+declare function hasCompositableBands(assets: RasterBandAsset[]): boolean;
+/**
+ * Same shape as `extractRasterBandAssets`, but does NOT drop multi-band assets.
+ * Used by the mosaic asset picker, where a 3-band pre-baked `visual` TCI is a
+ * legitimate choice alongside the per-band single-band COGs.
+ *
+ * `bandCount` is reported when known (`raster:bands.length` or `eo:bands.length`),
+ * else left undefined so the consuming UI can fall back to probing the COG.
+ */
+declare function extractMosaicAssets(item: StacItem): RasterBandAsset[];
+
+/**
+ * Generic per-channel asset descriptor for the unified RGB picker.
+ *
+ * Pure TypeScript. No Svelte dependency. Publishable via objex-utils.
+ *
+ * `CogAsset` is the canonical shape every viewer (CogViewer, MultiCogViewer,
+ * StacMosaicViewer) hands to the shared ChannelPicker UI. Each entry records
+ * the STAC asset key (`red`, `B04`, `image`, `visual`, ... or `self` when the
+ * viewer is a single bare COG file with no STAC context), the href, the band
+ * count (from `raster:bands.length` when STAC populates it, lazily probed from
+ * the COG header otherwise), and the optional `eo:bands` common name.
+ */
+
+interface CogAsset {
+    /** STAC asset key, or `self` for a single bare COG without STAC context. */
+    key: string;
+    /** Absolute or relative href as it appears in the STAC item / URL. */
+    href: string;
+    /** Number of bands in the asset. 1 by default until probed. */
+    bandCount: number;
+    /** True when bandCount came from STAC metadata or a probe; false → trust default. */
+    bandCountKnown: boolean;
+    /** `raster:bands[0].data_type` if known. */
+    dtype?: string;
+    /** `eo:bands[].common_name` lowercased, aligned to bandIndex order. */
+    eoCommon: string[];
+    /** STAC asset roles (`data`, `visual`, `reflectance`, ...). */
+    roles: string[];
+    /** Optional human title. */
+    title?: string;
+    /** Asset media_type as advertised by STAC. */
+    mediaType?: string;
+}
+/** Per-channel pixel coordinate inside a STAC item. */
+interface ChannelRef {
+    assetKey: string;
+    bandIndex: number;
+}
+/** RGB(A) composite expressed as `(asset, bandIndex)` per channel. */
+interface ChannelComposite {
+    r: ChannelRef;
+    g: ChannelRef;
+    b: ChannelRef;
+    a?: ChannelRef;
+}
+/**
+ * Enumerate every TIFF/COG asset on a STAC Item, keeping multi-band assets
+ * (NAIP `image`, S2 `visual` TCI) alongside single-band per-band assets.
+ *
+ * Reads band metadata from (in priority order):
+ *   1. `asset.bands` (STAC 1.1 unified bands array)
+ *   2. `asset['raster:bands']` (STAC 1.0 raster extension)
+ *   3. `asset['eo:bands']` (STAC 1.0 eo extension)
+ *   4. `item.properties.bands` (STAC 1.1 item-level bands, applies to all
+ *      assets that do not override) — covers catalogs like the Hamilton
+ *      NAIP-style 3-inch where each item has 4 bands but the single `data`
+ *      asset carries no band metadata of its own.
+ *
+ * `bandCount` is set when any of the above provides one; otherwise defaults
+ * to 1 with `bandCountKnown: false` so callers can lazily probe on first pick.
+ */
+declare function extractCogAssets(item: StacItem): CogAsset[];
+/**
+ * For `CogViewer` (single bare COG file, no STAC context). Returns one synthetic
+ * asset with key `self` so the same ChannelPicker UI works without special-casing.
+ * `bandCount` defaults to 1, set to the probed `geotiff.count` once known.
+ */
+declare function syntheticSelfAsset(href: string, probedBandCount?: number): CogAsset;
+/**
+ * Pick the most natural and most performant default composite for an item.
+ *
+ * Priority (first match wins):
+ *   1. A 3-band uint8 pre-baked visual asset (`visual` / `image` / `tci` etc):
+ *      all three channels bind to it, bands 0/1/2. Single COGLayer path,
+ *      one decoder, fastest.
+ *   2. Common-name red/green/blue resolvable across separate single-band assets.
+ *      MultiCOGLayer path.
+ *   3. Fallback: first three raster assets, band 0 each.
+ *
+ * Returns null when no raster assets exist.
+ */
+declare function pickNaturalColorComposite(assets: CogAsset[]): {
+    composite: ChannelComposite;
+    source: 'visual-asset' | 'rgb-bands' | 'fallback';
+} | null;
+/** True when all three RGB channels target the same asset key. */
+declare function isSingleAssetComposite(c: ChannelComposite): boolean;
+/** True when all three channels are at band index 0 (the MultiCOGLayer-compatible case). */
+declare function allChannelsBand0(c: ChannelComposite): boolean;
+
+/**
+ * Preset definitions, URL round-trip, and preset application for the unified
+ * RGB picker. Pure TypeScript, publishable via objex-utils.
+ *
+ * Presets describe a SEMANTIC band slot triple (`red`/`green`/`blue` for
+ * Natural Color, `nir`/`red`/`green` for False-Color IR, ...). Resolving a
+ * preset against a specific item walks `BAND_KEY_FALLBACKS` in `utils/stac.ts`
+ * to map slots to actual asset keys on that item. NDVI and other single-band
+ * derived presets are intentionally NOT in this list for this slice.
+ */
+
+interface PresetDef {
+    id: string;
+    labelKey: string;
+    slots: {
+        r: BandSlot;
+        g: BandSlot;
+        b: BandSlot;
+    };
+}
+declare const PRESETS: PresetDef[];
+/** Subset of PRESETS whose slot triple resolves on this item. */
+declare function availablePresets(assets: CogAsset[]): PresetDef[];
+/** Resolve a preset to a ChannelComposite for this item. Returns null when not applicable. */
+declare function applyPreset(assets: CogAsset[], preset: PresetDef): ChannelComposite | null;
+/** True when the preset's resolved composite still matches the user's current picks. */
+declare function presetMatchesComposite(preset: PresetDef, c: ChannelComposite, assets: CogAsset[]): boolean;
+/**
+ * Decode a `URLSearchParams` chunk into a ChannelComposite.
+ *
+ * Format: `r=<asset>&g=<asset>&b=<asset>&band_r=<n>&band_g=<n>&band_b=<n>` plus
+ * optional `a=<asset>&band_a=<n>`. `band_*` defaults to 0 when absent so
+ * legacy MultiCog URLs (`?r=red&g=green&b=blue&preset=true-color`) keep
+ * round-tripping. Returns null when any required asset key is missing from
+ * the current item's asset list.
+ */
+declare function compositeFromUrl(params: URLSearchParams, assets: CogAsset[]): ChannelComposite | null;
+/** Encode a composite + active preset id into URLSearchParams for the hash. */
+declare function compositeToUrl(c: ChannelComposite, presetId: string | null): URLSearchParams;
+
+/**
+ * Copy text to clipboard and run a feedback callback for COPY_FEEDBACK_MS.
+ * Silently catches clipboard errors (e.g. insecure context).
+ *
+ * @returns true if copy succeeded, false otherwise.
+ */
+declare function copyToClipboard(text: string, onFeedback?: (copied: boolean) => void): Promise<boolean>;
+/**
+ * Wire click-to-copy on all elements matching `selector` inside `root`.
+ * Each element must have `data-code` (URI-encoded) with the text to copy.
+ * Adds/removes a `copied` CSS class for visual feedback.
+ */
+declare function wireCodeCopyButtons(root: Element, selector: string): void;
+
 /**
  * Cloud storage protocol URL utilities — pure TS, no Svelte dependency.
  *
@@ -404,9 +839,69 @@ declare function typeColor(category: TypeCategory): string;
 declare function typeBadgeClass(category: TypeCategory): string;
 declare function typeLabel(category: TypeCategory): string;
 
+/**
+ * Canonical connection identity.
+ *
+ * Single source of truth for deciding when two connection configs point at
+ * the same bucket. Used by the connections store to deduplicate auto-detect,
+ * manual add, and edit flows, so one physical bucket never ends up with
+ * multiple competing local records.
+ *
+ * Identity rules, per provider:
+ *
+ *   azure  → (provider, endpoint, bucket)     endpoint carries the account
+ *   gcs    → (provider, bucket)               GCS bucket names are global
+ *   s3     → (provider, bucket, region)       AWS native: same bucket name
+ *                                             can exist in exactly one region,
+ *                                             but the region is load-bearing
+ *                                             for signing, so a paste with a
+ *                                             different region is a distinct
+ *                                             connection until the user merges
+ *   other  → (provider, endpoint, bucket)     r2, b2, minio, wasabi, storj,
+ *                                             digitalocean, contabo, hetzner,
+ *                                             linode, ovhcloud, custom
+ *
+ * Endpoint normalization is aggressive: scheme + host + non-default port +
+ * pathname, with trailing slashes and default ports stripped, host lowercased.
+ * That collapses the common trip hazards — http vs https, :443 vs empty,
+ * trailing slash drift, mixed case host.
+ */
+
+interface ConnectionIdentityInput {
+    provider: string;
+    endpoint: string;
+    bucket: string;
+    region: string;
+}
+/**
+ * Normalize an endpoint URL to a canonical form suitable for equality checks.
+ * Empty / whitespace-only input returns `''` (the "no endpoint" sentinel).
+ * Non-URL strings are lowercased and stripped of trailing slashes as a best
+ * effort so the comparison is still deterministic.
+ */
+declare function normalizeEndpoint(raw: string | undefined | null): string;
+/** Collapse unknown / empty providers to `'s3'`; otherwise lowercase. */
+declare function normalizeProvider(provider: string | undefined | null): ProviderId;
+/**
+ * Produce a canonical key for a connection's identity. Two connection
+ * configs with the same identity key point at the same physical bucket.
+ * Returns `''` when the config is too incomplete to identify a bucket.
+ */
+declare function connectionIdentityKey(input: ConnectionIdentityInput): string;
+/** Convenience: true when both inputs share the same non-empty identity. */
+declare function isSameConnectionIdentity(a: ConnectionIdentityInput, b: ConnectionIdentityInput): boolean;
+
 /**
  * Shared error handling for async viewer load operations.
  */
+/**
+ * True for any abort cascade. Recognizes raw `DOMException(AbortError)`,
+ * objects whose `.name` is `AbortError`, deck.gl's `_SourceError("Failed
+ * to fetch")` wrapper whose `cause` is an AbortError, and free-text errors
+ * from `@developmentseed/geotiff` that mention "aborted". Used to silence
+ * cancellation noise without swallowing real failures.
+ */
+declare function isAbortError(err: unknown): boolean;
 /**
  * Extract an error message from an unknown caught value.
  * Returns null for AbortError (caller should silently return).
@@ -515,6 +1010,59 @@ declare function buildGeoArrowTables(wkbArrays: Uint8Array[], attributes: Map<st
     type: string;
 }>, knownGeomType?: GeoArrowGeomType): GeoArrowResult[];
 
+/**
+ * Helpers for parsing DuckDB v1.5 parameterized GEOMETRY type strings.
+ *
+ * DuckDB v1.5 made GEOMETRY a core type with an optional CRS parameter:
+ *   GEOMETRY                  — no CRS attached
+ *   GEOMETRY('EPSG:4326')     — EPSG form
+ *   GEOMETRY('OGC:CRS84')     — OGC form (canonical for GeoParquet 1.1+)
+ *   GEOMETRY('EPSG:27700')    — projected CRS
+ *
+ * Type strings may come from `DESCRIBE`, from the Arrow schema, or from a
+ * legacy code path that still reports `BLOB`. Use these helpers everywhere
+ * instead of ad-hoc regex so behaviour stays consistent.
+ */
+interface GeometryTypeInfo {
+    /** True if the type is some form of GEOMETRY (with or without CRS). */
+    isGeometry: boolean;
+    /** True if the type carries a CRS parameter, e.g. GEOMETRY('EPSG:4326'). */
+    hasCrs: boolean;
+    /** The CRS string if present, otherwise null. Raw value, including WGS84. */
+    rawCrs: string | null;
+    /**
+     * The CRS string if present and NOT a WGS84 variant (EPSG:4326, EPSG:4979,
+     * OGC:CRS84). Returns null for WGS84 so callers can skip ST_Transform.
+     */
+    nonWgs84Crs: string | null;
+}
+/**
+ * Parse a DuckDB type string and report whether it is a GEOMETRY type, and
+ * whether a CRS parameter is attached.
+ */
+declare function parseGeometryTypeCrs(typeStr: string | null | undefined): GeometryTypeInfo;
+/** True for EPSG:4326, EPSG:4979, OGC:CRS84 and equivalent strings. */
+declare function isWgs84Crs(crs: string | null | undefined): boolean;
+/**
+ * Build a `ST_Transform(...)` SQL expression choosing the 2-arg form when the
+ * input already carries its CRS in the GEOMETRY type (DuckDB v1.5), and the
+ * 3-arg form otherwise.
+ *
+ * `geometry_always_xy` is set globally at DB init, so no per-call `always_xy`
+ * argument is needed.
+ */
+declare function buildTransformExpr(innerExpr: string, sourceType: string, sourceCrs: string, targetCrs: string): string;
+/**
+ * Wrap a bare WKB expression with `ST_SetCRS(ST_GeomFromWKB(...))` so that the
+ * resulting GEOMETRY value carries a CRS through the rest of the pipeline.
+ * Used in the legacy GeoParquet fallback where we read the geometry column as
+ * BLOB but still know the source CRS from hyparquet metadata or the GeoParquet
+ * footer.
+ *
+ * If `sourceCrs` is null/empty, returns a plain `ST_GeomFromWKB(...)`.
+ */
+declare function wrapWkbWithCrs(wkbExpr: string, sourceCrs: string | null | undefined): string;
+
 interface HexRow {
     offset: string;
     hex: string[];
@@ -526,6 +1074,142 @@ interface HexRow {
  */
 declare function generateHexDump(data: Uint8Array, bytesPerRow?: number): HexRow[];
 
+/**
+ * Universal cloud storage URL / bucket parser.
+ *
+ * Accepts the many URI/URL formats that users commonly paste and extracts
+ * the correct bucket, region, endpoint, and provider.
+ *
+ * Supported URI schemes:
+ *   s3://   s3a://   s3n://   aws://   — Amazon S3 / S3-compatible
+ *   r2://                              — Cloudflare R2
+ *   gs://   gcs://                     — Google Cloud Storage
+ *   azure://  az://                    — Azure Blob Storage
+ *   abfs://   abfss://                — Azure Data Lake (ADLS Gen2)
+ *   wasbs://                           — Azure Blob (Hadoop WASB driver)
+ *   swift://                           — OpenStack Swift
+ *   file://  filesystem://             — Local filesystem
+ *
+ * Supported HTTPS URL patterns:
+ *   https://<bucket>.s3.<region>.amazonaws.com[/prefix]     — AWS virtual-hosted
+ *   https://s3.<region>.amazonaws.com/<bucket>[/prefix]     — AWS path-style
+ *   https://s3.amazonaws.com/<bucket>                       — AWS global
+ *   https://<account>.r2.cloudflarestorage.com/<bucket>     — Cloudflare R2
+ *   https://storage.googleapis.com/<bucket>                 — Google Cloud Storage
+ *   https://<bucket>.storage.googleapis.com[/prefix]        — GCS virtual-hosted
+ *   https://<bucket>.<region>.digitaloceanspaces.com        — DigitalOcean Spaces
+ *   https://<region>.digitaloceanspaces.com/<bucket>        — DO Spaces path-style
+ *   https://s3.<region>.wasabisys.com/<bucket>              — Wasabi
+ *   https://f<id>.backblazeb2.com/file/<bucket>             — Backblaze B2
+ *   https://<bucket>.s3.<region>.backblazeb2.com            — B2 S3-compatible
+ *   https://<bucket>.oss-<region>.aliyuncs.com              — Alibaba Cloud OSS
+ *   https://<bucket>.cos.<region>.myqcloud.com              — Tencent COS
+ *   https://storage.yandexcloud.net/<bucket>                — Yandex Cloud
+ *   https://gateway.storjshare.io/<bucket>                   — Storj S3 gateway
+ *   https://link.storjshare.io/raw/<access>/<bucket>        — Storj linksharing
+ *   https://<custom-endpoint>/<bucket>                      — Generic S3-compatible
+ *
+ * Also handles plain bucket names (no protocol).
+ */
+type StorageProvider = string;
+interface ParsedStorageUrl {
+    bucket: string;
+    region: string;
+    endpoint: string;
+    provider: StorageProvider;
+    /** Original prefix/path after bucket, if any */
+    prefix: string;
+}
+/** STAC API path test, one source of truth. Tests pathname only. */
+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.
+ */
+declare function isKnownBucketHost(host: string): boolean;
+interface Defaults {
+    region?: string;
+    endpoint?: string;
+    provider?: StorageProvider;
+}
+/**
+ * Parse a user-provided bucket/URL string into structured storage connection parts.
+ */
+declare function parseStorageUrl(input: string, defaults?: Defaults): ParsedStorageUrl;
+/**
+ * Returns true if the input looks like a URL/URI rather than a plain bucket name.
+ * Covers all recognized cloud storage URI schemes.
+ */
+declare function looksLikeUrl(input: string): boolean;
+/**
+ * Given a parsed URL result, build a human-readable summary of what was detected.
+ */
+declare function describeParseResult(parsed: ParsedStorageUrl): string;
+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.
+ */
+declare function classifyUrl(input: string): UrlClassification;
+
+/**
+ * Auto-detect hosting bucket from URL search params and window.location.
+ *
+ * Detection priority:
+ * 1. `?url=<storage-url>` query parameter (highest priority)
+ * 2. `window.location.hostname` pattern matching (fallback)
+ *
+ * Also extracts `rootPrefix` when the app is hosted inside a subfolder.
+ */
+
+interface DetectedHost {
+    provider: StorageProvider;
+    bucket: string;
+    region: string;
+    endpoint: string;
+    rootPrefix: string;
+    bucketUrl: string;
+}
+/**
+ * Detect hosting bucket from current URL.
+ * Returns null when no hosting bucket can be determined.
+ */
+declare function detectHostBucket(): DetectedHost | null;
+/**
+ * Enrich an in-progress connection-config draft with hints from a STAC Item
+ * that declares the Storage Extension (`storage:region`,
+ * `storage:requester_pays`, `storage:platform`, v2 `storage:schemes`).
+ *
+ * Modular by design, callers opt in. The existing `detectHostBucket` flow
+ * does NOT know about STAC, so call sites that already hold a representative
+ * `StacItem` (e.g. classification just after fetching a Catalog / Collection /
+ * ItemCollection) should funnel through this helper before handing the draft
+ * to `connectionStore.saveHostConnection` / `connectionStore.save`. Existing
+ * non-empty fields on the draft are preserved (this never clobbers a
+ * user-set value).
+ *
+ * Returns a shallow copy of `input` with hint fields filled in. Safe to call
+ * with an unrelated item, returns `input` untouched when the extension is
+ * absent or unparseable.
+ */
+declare function applyStacItemStorageHints<T extends {
+    region?: string;
+    endpoint?: string;
+}>(input: T, item: StacItem): T;
+
 /**
  * Generic localStorage helpers with SSR safety.
  *
@@ -543,6 +1227,93 @@ declare function loadFromStorage<T>(key: string, defaultValue: T): T;
  */
 declare function persistToStorage(key: string, value: unknown): void;
 
+/**
+ * Tiny insertion-order LRU built on top of `Map`. `get` / `has` move the entry
+ * to the most-recent slot, `set` evicts the oldest (and runs `onEvict`) once
+ * the cap is exceeded.
+ *
+ * Keeps the implementation deliberately small. Used by viewer modules that
+ * cache per-source resources (GeoTIFF headers, presigned URLs) which would
+ * otherwise leak across long pan / viewport-reload sessions.
+ */
+interface LruCacheOptions<K, V> {
+    /** Maximum number of entries. Must be > 0. */
+    max: number;
+    /** Called when an entry is evicted (LRU overflow or `delete()`). */
+    onEvict?: (key: K, value: V) => void;
+}
+declare class LruCache<K, V> {
+    private map;
+    readonly max: number;
+    private onEvict?;
+    constructor(opts: LruCacheOptions<K, V>);
+    get size(): number;
+    has(key: K): boolean;
+    get(key: K): V | undefined;
+    set(key: K, value: V): void;
+    delete(key: K): boolean;
+    clear(): void;
+}
+
+/**
+ * Framework-agnostic helper that wires a "click on map, run a probe, surface the
+ * result" flow used by every COG-style viewer (`CogViewer`, `StacMosaicViewer`,
+ * `MultiCogViewer`).
+ *
+ * The viewers differ in what the probe returns (a single pixel sample, a per-
+ * channel fan-out, or a topmost-source bbox hit), but they share the same
+ * boilerplate: subscribe to `click`, mark inspecting, await the probe, surface
+ * the payload, abort the previous probe if a new click arrives mid-flight, and
+ * tear the listener down on cleanup.
+ *
+ * No dependency on Svelte, MapLibre, or deck.gl. The `MapLike` shape captures
+ * only what the helper needs from the underlying map so this can be unit-tested
+ * with a tiny stub if needed.
+ */
+interface PixelInspectClickEvent {
+    lngLat: {
+        lng: number;
+        lat: number;
+    };
+}
+type PixelInspectClickHandler = (event: PixelInspectClickEvent) => void;
+/**
+ * Minimal subset of MapLibre's map API used by the inspector. Anything that
+ * dispatches a `click` event with `{lngLat}` and supports symmetric on/off
+ * registration plugs in.
+ */
+interface MapLike {
+    on(type: 'click', handler: PixelInspectClickHandler): unknown;
+    off(type: 'click', handler: PixelInspectClickHandler): unknown;
+}
+interface PixelInspectProbeRequest {
+    lng: number;
+    lat: number;
+    signal: AbortSignal;
+}
+type PixelInspectProbe<T> = (req: PixelInspectProbeRequest) => Promise<T | null>;
+interface PixelInspectCallbacks<T> {
+    /** Called synchronously when a click is accepted, before the probe is awaited. */
+    onStart(): void;
+    /**
+     * Called once per click after the probe settles. Receives `null` when the
+     * probe returned `null` or threw a non-helper-driven error (including an
+     * `AbortError` that did not originate from this helper's own controller).
+     */
+    onResult(result: T | null): void;
+}
+interface AttachPixelInspectorOptions<T> {
+    probe: PixelInspectProbe<T>;
+    onStart: PixelInspectCallbacks<T>['onStart'];
+    onResult: PixelInspectCallbacks<T>['onResult'];
+}
+/**
+ * Wire a click-to-inspect probe onto `map`. Returns a `detach()` function that
+ * removes the listener AND aborts any in-flight probe. Subsequent clicks abort
+ * the previous probe so a fast double-click never leaves a stale result behind.
+ */
+declare function attachPixelInspector<T>(map: MapLike, { probe, onStart, onResult }: AttachPixelInspectorOptions<T>): () => void;
+
 interface SqlBlock {
     name: string;
     sql: string;
@@ -574,6 +1345,92 @@ declare function interpolateTemplates(text: string, queryResults: Map<string, Re
  */
 declare function markSqlBlocks(content: string): string;
 
+/**
+ * Executes the SQL blocks parsed out of a markdown document (Evidence.dev style)
+ * against an injected query engine, and caches the results by block name. Pairs
+ * with `markdown-sql.ts` (the parser). Pure TypeScript, the engine is supplied by
+ * the host so this module never imports DuckDB or any other heavy dependency.
+ */
+declare class MarkdownSqlContext {
+    private engine;
+    private connId;
+    private prefix;
+    private results;
+    constructor(engine: QueryEngine, connId: string, prefix?: string);
+    /** Execute a SQL query and store the result under the given name. */
+    executeSql(sql: string, queryName: string): Promise<Record<string, any>[]>;
+    /**
+     * Transform relative file paths in SQL to full S3 URLs.
+     * e.g. read_parquet('data.parquet') becomes read_parquet('s3://bucket/prefix/data.parquet').
+     */
+    private transformPaths;
+    getResult(queryName: string): {
+        result: QueryResult;
+        rows: Record<string, any>[];
+    } | undefined;
+    getAllResults(): Map<string, Record<string, any>[]>;
+    getColumns(queryName: string): string[];
+}
+
+/**
+ * Lightweight browser-native Jupyter notebook renderer.
+ * Replaces `notebookjs` which depends on jsdom/Buffer (Node.js only).
+ * Handles nbformat 2, 3, 4, and 5.
+ */
+interface NotebookConfig {
+    markdown: (md: string) => string;
+    ansi: (text: string) => string;
+    highlighter: (code: string, lang: string) => string;
+}
+interface RawNotebook {
+    nbformat: number;
+    nbformat_minor?: number;
+    metadata?: Record<string, any>;
+    cells?: RawCell[];
+    worksheets?: {
+        cells: RawCell[];
+    }[];
+}
+interface RawCell {
+    cell_type: string;
+    source?: string | string[];
+    input?: string | string[];
+    outputs?: RawOutput[];
+    prompt_number?: number;
+    execution_count?: number | null;
+    level?: number;
+    language?: string;
+}
+interface RawOutput {
+    output_type: string;
+    data?: Record<string, string | string[]>;
+    text?: string | string[];
+    stream?: string;
+    name?: string;
+    png?: string;
+    jpeg?: string;
+    svg?: string;
+    html?: string;
+    latex?: string;
+    traceback?: string[];
+    ename?: string;
+    evalue?: string;
+    [key: string]: any;
+}
+interface NotebookMeta {
+    kernelName: string;
+    language: string;
+    cellCount: number;
+}
+/**
+ * Parse and render a Jupyter notebook JSON to a DOM element.
+ * Returns the rendered element and metadata.
+ */
+declare function renderNotebook(raw: RawNotebook, config: NotebookConfig): {
+    element: HTMLElement;
+    meta: NotebookMeta;
+};
+
 /**
  * Lightweight Parquet metadata reader using hyparquet.
  *
@@ -640,42 +1497,185 @@ declare function extractGeometryTypes(geo: GeoParquetMeta): GeoArrowGeomType[];
 declare function extractBounds(geo: GeoParquetMeta): [number, number, number, number] | null;
 
 /**
- * STAC (SpatioTemporal Asset Catalog) detection and parsing.
+ * STAC item facets, filtering, and sorting. Pure TS, framework-agnostic.
  *
- * Pure TypeScript helpers shared by ViewerRouter, StacMosaicViewer, and
- * MultiCogViewer. No Svelte dependency, publishable via objex-utils.
+ * Inputs are STAC Items (or any subset compatible with `StacItem`). Outputs
+ * are slim views, auto-detected facet descriptors, and filtered/sorted view
+ * arrays. No DOM, no Svelte, no fetch, no maplibre, safe to publish via
+ * `@walkthru-earth/objex-utils`.
+ *
+ * The flow is intentionally one-directional:
+ *   StacItem[]  --extractItemView-->  StacItemView[]
+ *   StacItemView[]  --buildFacets-->  FacetSet
+ *   StacItemView[] + FacetState  --applyFacets-->  StacItemView[]
+ *   StacItemView[] + FacetSort  --sortViews-->  StacItemView[]
+ *
+ * Callers (any framework) can hold the views array, derive a FacetSet on
+ * change, and reactively filter / sort it without re-touching the original
+ * StacItems.
  */
-/** STAC Link (shared by Catalog/Collection/Item). */
-interface StacLink {
-    rel: string;
-    href: string;
-    type?: string;
-    title?: string;
-}
-/** STAC Item (GeoJSON Feature shape with stac_version). */
-interface StacItem {
-    type: 'Feature';
-    stac_version: string;
+
+/**
+ * Compact, render-ready projection of a STAC Item. Keeps only the fields
+ * needed for facet UI, sorting, footprint rendering, and the inspector
+ * panel. The full original item is retained on `raw` for callers that need
+ * to inspect arbitrary properties without a re-extract pass.
+ */
+interface StacItemView {
     id: string;
-    bbox?: [number, number, number, number];
-    geometry?: unknown;
-    properties?: Record<string, unknown>;
-    assets?: Record<string, StacAsset>;
-    collection?: string;
-    links?: StacLink[];
+    collection: string | null;
+    bbox: [number, number, number, number] | null;
+    /** ISO 8601 datetime, or `start_datetime` when only an interval is given. */
+    datetime: string | null;
+    /** End of `start_datetime` / `end_datetime` interval, when present. */
+    endDatetime: string | null;
+    /** `eo:cloud_cover` percent (0-100), null when absent. */
+    cloudCover: number | null;
+    /** Ground sample distance in meters, null when absent. */
+    gsd: number | null;
+    platform: string | null;
+    constellation: string | null;
+    instruments: string[];
+    /** EPSG code from `proj:epsg`, null when absent or non-numeric. */
+    epsg: number | null;
+    /** Best-effort thumbnail / overview href, null when no preview asset. */
+    thumbnailHref: string | null;
+    /** Asset role set across all assets on the item. */
+    assetRoles: string[];
+    /** Original item, retained so the inspector can show the raw JSON. */
+    raw: StacItem;
 }
-/** Single asset entry within a STAC item. */
-interface StacAsset {
-    href: string;
-    type?: string;
-    title?: string;
-    roles?: string[];
-    /** Set when the asset carries `eo:bands`. */
-    'eo:bands'?: {
-        name?: string;
-        common_name?: string;
+/** Project a STAC Item into a `StacItemView`. Always succeeds. */
+declare function extractItemView(item: StacItem): StacItemView;
+/**
+ * Numeric facet, e.g. cloud cover. `min`/`max` are derived from the loaded
+ * views so the UI can use them as slider bounds. `count` is how many of the
+ * input views had this field at all.
+ */
+interface NumericFacet {
+    kind: 'numeric';
+    field: NumericFacetField;
+    min: number;
+    max: number;
+    count: number;
+}
+/**
+ * Enum facet, e.g. platform. `values` is sorted by descending count so the
+ * most common values surface first in chip lists.
+ */
+interface EnumFacet {
+    kind: 'enum';
+    field: EnumFacetField;
+    values: {
+        value: string;
+        count: number;
     }[];
 }
+/**
+ * Calendar-aligned bin granularity for the datetime histogram. Picked
+ * automatically from the loaded items' time span so callers never see a
+ * span-vs-resolution mismatch (e.g. month bins on a 30-day window or day bins
+ * on a 20-year archive). See `pickGranularity` for the breakpoints.
+ */
+type DatetimeGranularity = 'day' | 'week' | 'month' | 'year';
+/**
+ * Datetime facet, with min/max for slider bounds and a calendar-aligned
+ * histogram the UI can render under a range slider. Each bin spans one
+ * `granularity` unit (UTC day, ISO week starting Monday, calendar month, or
+ * calendar year). `bins[i]` is the count of items whose `datetime` falls
+ * inside the bin starting at `binEdges[i]` (epoch ms, UTC). `bins.length ===
+ * binEdges.length`, capped at `DATETIME_HISTOGRAM_BINS_MAX`.
+ */
+interface DatetimeFacet {
+    kind: 'datetime';
+    field: 'datetime';
+    /** Earliest datetime, ISO 8601. */
+    min: string;
+    /** Latest datetime, ISO 8601. */
+    max: string;
+    count: number;
+    /** Per-bin counts. Length matches `binEdges.length`. */
+    bins: number[];
+    /** Auto-picked calendar granularity for each histogram bucket. */
+    granularity: DatetimeGranularity;
+    /** Epoch ms (UTC) of each bin's start boundary. Same length as `bins`. */
+    binEdges: number[];
+}
+type Facet = NumericFacet | EnumFacet | DatetimeFacet;
+type NumericFacetField = 'cloudCover' | 'gsd';
+type EnumFacetField = 'collection' | 'platform' | 'constellation' | 'instruments' | 'assetRoles';
+/**
+ * Soft cap on histogram bin count. The actual count is derived from the span
+ * + granularity (e.g. a 5-year span at month granularity emits 60 bins, a
+ * 90-day span at day granularity emits 90 bins). Spans that would exceed the
+ * cap are clamped here, the next coarser granularity should already have been
+ * picked by `pickGranularity` so this only protects against pathological
+ * inputs.
+ */
+declare const DATETIME_HISTOGRAM_BINS_MAX = 64;
+/** @deprecated Retained for backward compatibility. Use `DATETIME_HISTOGRAM_BINS_MAX`. */
+declare const DATETIME_HISTOGRAM_BINS = 32;
+/** Result of `buildFacets`: every facet that has variance in the input set. */
+interface FacetSet {
+    datetime: DatetimeFacet | null;
+    numeric: NumericFacet[];
+    enums: EnumFacet[];
+    /** Total number of views the facet set was built from. */
+    total: number;
+}
+/**
+ * Pick a calendar granularity from the time span. Inspired by lazycogs's
+ * `_TemporalGrouper` family: short windows surface daily / weekly cadence,
+ * long archives roll up to month / year so each bin still represents a
+ * meaningful slice of data.
+ */
+declare function pickGranularity(spanMs: number): DatetimeGranularity;
+/**
+ * Scan a list of views and emit only those facets that have meaningful
+ * variance. A facet is omitted when:
+ *   - numeric: fewer than two distinct finite values
+ *   - enum: fewer than two distinct values
+ *   - datetime: fewer than two parseable timestamps with distinct values
+ *
+ * The intent is "render only the controls that will narrow this dataset",
+ * so callers can map each returned facet to a UI component without further
+ * checks.
+ */
+declare function buildFacets(views: StacItemView[]): FacetSet;
+/**
+ * Mutable filter state, intended to be held by the UI layer. Each entry is
+ * optional, omitting an entry means "no filter on this field". Numeric
+ * ranges are inclusive on both ends. Enum sets are union-match (any value
+ * in the set passes).
+ */
+interface FacetState {
+    datetime?: {
+        min?: string;
+        max?: string;
+    };
+    numeric?: Partial<Record<NumericFacetField, {
+        min?: number;
+        max?: number;
+    }>>;
+    enums?: Partial<Record<EnumFacetField, string[]>>;
+}
+/**
+ * Filter views by `state`. Empty / missing entries are no-ops. Returns a new
+ * array, the input is never mutated. Order is preserved, run `sortViews`
+ * afterwards if a different order is needed.
+ */
+declare function applyFacets(views: StacItemView[], state: FacetState | null | undefined): StacItemView[];
+type FacetSort = 'datetime-desc' | 'datetime-asc' | 'cloud-asc' | 'cloud-desc' | 'gsd-asc' | 'gsd-desc' | 'id-asc';
+/**
+ * Sort views by one of a fixed set of strategies. Items missing the sort
+ * field always sink to the bottom (regardless of asc/desc) so a `cloud-asc`
+ * sort never surfaces "items with no cloud cover" above the cleanest scenes.
+ */
+declare function sortViews(views: StacItemView[], sort: FacetSort): StacItemView[];
+/** True when any filter in `state` would actually narrow the input. */
+declare function hasActiveFilters(state: FacetState | null | undefined): boolean;
+/** Return `state` with every filter cleared. Useful for reset buttons. */
+declare function emptyFacetState(): FacetState;
 
 /**
  * stac-geoparquet helpers.
@@ -769,69 +1769,449 @@ declare function pickStacPrimaryAsset(assets: Record<string, StacAsset> | null |
 declare function stacRowToItem(row: StacGeoparquetRow, baseUrl: string, opts?: StacRowToItemOptions): StacItem;
 
 /**
- * Universal cloud storage URL / bucket parser.
+ * STAC link-following hydrator. Walks `links[rel=item]` (Collection),
+ * `links[rel=child]` → `links[rel=item]` (Catalog), and `links[rel=next]`
+ * (paginated FeatureCollection / STAC API) into a flat list of StacItems.
+ */
+
+interface HydrateOptions {
+    signal: AbortSignal;
+    /** Max parallel fetches. Default 12. */
+    concurrency?: number;
+    /** Hard cap on items; catalogs larger than this are truncated. Default 2000. */
+    limit?: number;
+    /** Follow `links[rel=next]` pagination in FeatureCollections. Default true. */
+    followPagination?: boolean;
+    /** Emit fetched items in batches for progressive rendering. */
+    onBatch?: (items: StacItem[]) => void;
+    /** Emit progress totals for UI. */
+    onProgress?: (fetched: number, totalHinted: number | undefined) => void;
+    /**
+     * Map an absolute HTTPS URL to a bucket-relative key when it belongs to the
+     * caller's connection. When provided and it returns a non-null string,
+     * `fetchJson` routes through the storage adapter (which handles SigV4) instead
+     * of a raw cross-origin `fetch`, so private-bucket catalogs can be walked.
+     */
+    urlToKey?: (absoluteUrl: string) => string | null;
+    /**
+     * Optional native STAC API filters appended to the `rel="items"` endpoint
+     * (and applied to `links[rel=next]` pages). Lets callers narrow a
+     * collection by spatial / temporal extent before hydration.
+     */
+    itemsQuery?: StacItemsQuery;
+}
+/** Native filters supported by OGC API Features / STAC API on `/items`. */
+interface StacItemsQuery {
+    /** WGS84 bbox `[west, south, east, north]`. */
+    bbox?: [number, number, number, number];
+    /** RFC 3339 instant or interval `start/end` (use `..` for open ends). */
+    datetime?: string;
+    /** Per-page item count hint, the server may cap this. */
+    limit?: number;
+    /**
+     * CQL2-JSON filter expression (STAC API Filter extension). When set, gets
+     * appended as `?filter=<json>&filter-lang=cql2-json` and re-stamped onto
+     * every `rel="next"` page so cursor URLs cannot strip it.
+     */
+    filter?: unknown;
+}
+interface HydrateResult {
+    items: StacItem[];
+    truncated: boolean;
+    rootBaseHref: string;
+}
+declare function hydrateStacItems(root: StacRoutableKind, baseHref: string, adapter: StorageAdapter, opts: HydrateOptions): Promise<HydrateResult>;
+/**
+ * True when the payload exposes a `rel="items"` link (OGC API Features /
+ * STAC API convention). Lets callers switch to viewport-scoped fetching
+ * instead of walking every page.
+ */
+declare function hasStacItemsEndpoint(payload: StacCollection | StacCatalog): boolean;
+/**
+ * Resolve a possibly-relative href against a base. STAC catalogs commonly use
+ * `./child/foo.json` or `../foo.json`. `new URL(relative, base)` handles both.
+ */
+declare function absolutizeHref(href: string, baseHref: string): string;
+
+/**
+ * Translate a `FacetState` into native STAC API parameters and CQL2 filters,
+ * gated by what the endpoint advertises in `conformsTo`. Pure TS, framework
+ * and transport agnostic.
  *
- * Accepts the many URI/URL formats that users commonly paste and extracts
- * the correct bucket, region, endpoint, and provider.
+ * The split between this module and `stac-facets.ts` is intentional. Facets
+ * own discovery and client-side filtering (works for any source). This
+ * module owns *server-side push-down*, which only makes sense when the
+ * source is a STAC API that supports OGC API Features query params or the
+ * STAC API filter extension.
  *
- * Supported URI schemes:
- *   s3://   s3a://   s3n://   aws://   — Amazon S3 / S3-compatible
- *   r2://                              — Cloudflare R2
- *   gs://   gcs://                     — Google Cloud Storage
- *   azure://  az://                    — Azure Blob Storage
- *   abfs://   abfss://                — Azure Data Lake (ADLS Gen2)
- *   wasbs://                           — Azure Blob (Hadoop WASB driver)
- *   swift://                           — OpenStack Swift
- *   file://  filesystem://             — Local filesystem
+ * Callers that want push-down:
+ *   1. Fetch the API root, read `conformsTo`.
+ *   2. `caps = sniffApiCapabilities(conformsTo)` once per session.
+ *   3. On each pan / filter change:
+ *        const native = toNativeQuery(state, caps);
+ *        const filter = caps.cql2 ? toCql2Filter(state, caps) : null;
+ *      Pass `native` to the items endpoint and apply `filter` via
+ *      `?filter=<json-encoded>` when present. Anything that could not be
+ *      pushed down stays in `state` and is filtered client-side via
+ *      `applyFacets`.
+ */
+
+/**
+ * Subset of STAC API capabilities relevant to filter push-down. Read once
+ * per session from the API root's `conformsTo` array.
+ */
+interface StacApiCapabilities {
+    /** Supports `bbox=` query param (OGC API Features core). */
+    bbox: boolean;
+    /** Supports `datetime=` query param (OGC API Features core). */
+    datetime: boolean;
+    /** Supports `collections=` filter (STAC API Item Search). */
+    collections: boolean;
+    /** Supports the STAC API Filter extension via `filter=` + `filter-lang=cql2-json`. */
+    cql2: boolean;
+    /** Queryables endpoint advertised, lets clients sniff filterable property names. */
+    queryables: boolean;
+}
+/**
+ * Parse a STAC API `conformsTo` array into a capability flag set. Tolerant
+ * of unknown URIs, missing entries, and casing differences. Defaults to all
+ * `false` when given an empty / non-array input, so a caller that hasn't
+ * fetched the root yet never accidentally pushes down something the API
+ * cannot honor.
+ */
+declare function sniffApiCapabilities(conformsTo: unknown): StacApiCapabilities;
+/**
+ * Generic STAC items query, compatible with both OGC API Features
+ * (`/collections/{id}/items`) and STAC API Item Search (`/search`). Mirrors
+ * the shape `stac-hydrate.ts::StacItemsQuery` expects, plus optional
+ * `collections` and `filter` for the search endpoint.
+ */
+interface StacNativeQuery {
+    bbox?: [number, number, number, number];
+    datetime?: string;
+    collections?: string[];
+    limit?: number;
+    /** CQL2-JSON object, encode with `JSON.stringify` when serializing. */
+    filter?: unknown;
+    'filter-lang'?: 'cql2-json';
+}
+interface ToNativeQueryOptions {
+    bbox?: [number, number, number, number];
+    limit?: number;
+}
+/**
+ * Translate `state` into the subset of native query params the API supports.
+ * Anything that can't be pushed down is silently dropped here, the caller is
+ * expected to keep applying it client-side via `applyFacets`. This is safe
+ * because client filtering is always a superset, never a contradiction.
  *
- * Supported HTTPS URL patterns:
- *   https://<bucket>.s3.<region>.amazonaws.com[/prefix]     — AWS virtual-hosted
- *   https://s3.<region>.amazonaws.com/<bucket>[/prefix]     — AWS path-style
- *   https://s3.amazonaws.com/<bucket>                       — AWS global
- *   https://<account>.r2.cloudflarestorage.com/<bucket>     — Cloudflare R2
- *   https://storage.googleapis.com/<bucket>                 — Google Cloud Storage
- *   https://<bucket>.storage.googleapis.com[/prefix]        — GCS virtual-hosted
- *   https://<bucket>.<region>.digitaloceanspaces.com        — DigitalOcean Spaces
- *   https://<region>.digitaloceanspaces.com/<bucket>        — DO Spaces path-style
- *   https://s3.<region>.wasabisys.com/<bucket>              — Wasabi
- *   https://f<id>.backblazeb2.com/file/<bucket>             — Backblaze B2
- *   https://<bucket>.s3.<region>.backblazeb2.com            — B2 S3-compatible
- *   https://<bucket>.oss-<region>.aliyuncs.com              — Alibaba Cloud OSS
- *   https://<bucket>.cos.<region>.myqcloud.com              — Tencent COS
- *   https://storage.yandexcloud.net/<bucket>                — Yandex Cloud
- *   https://gateway.storjshare.io/<bucket>                   — Storj S3 gateway
- *   https://link.storjshare.io/raw/<access>/<bucket>        — Storj linksharing
- *   https://<custom-endpoint>/<bucket>                      — Generic S3-compatible
+ * `bbox` / `limit` are accepted as overrides because they typically come
+ * from the viewer's viewport + user setting, not from `state`.
+ */
+declare function toNativeQuery(state: FacetState | null | undefined, caps: StacApiCapabilities, opts?: ToNativeQueryOptions): StacNativeQuery;
+/**
+ * CQL2-JSON expression node (very loose typing because the spec allows
+ * arbitrary nesting and we only emit a small subset). Use `unknown` at the
+ * boundary, cast inside this module.
+ */
+type Cql2Node = unknown;
+/**
+ * Build a CQL2-JSON `and` expression from a `FacetState`, covering the
+ * filters that aren't already handled by native params. Returns `null` when
+ * nothing in `state` requires CQL2 (so the caller can omit `filter=`).
  *
- * Also handles plain bucket names (no protocol).
+ * Currently emits:
+ *   - eo:cloud_cover  (between)
+ *   - gsd             (between)
+ *   - proj:epsg       (=)
+ *   - platform        (in)
+ *   - constellation   (in)
+ *   - instruments     (a_overlaps)
+ *
+ * `collection` and `datetime` are skipped here when the corresponding native
+ * cap is set, since those are cheaper to push as plain query params. They
+ * fall through to CQL2 only when the API advertises CQL2 but not the
+ * matching native capability (rare but legal).
  */
-type StorageProvider = string;
-interface ParsedStorageUrl {
-    bucket: string;
-    region: string;
-    endpoint: string;
-    provider: StorageProvider;
-    /** Original prefix/path after bucket, if any */
-    prefix: string;
+declare function toCql2Filter(state: FacetState | null | undefined, caps: StacApiCapabilities): Cql2Node | null;
+/**
+ * Subtract everything that was pushed down from `state`, returning the
+ * remaining state that the caller still has to apply client-side. Lets the
+ * UI avoid double-filtering (which would just be a no-op but wastes work).
+ *
+ * This is a structural diff, not a deep clone, the input is not mutated.
+ */
+declare function residualState(state: FacetState | null | undefined, caps: StacApiCapabilities): FacetState;
+
+/**
+ * StacSource contract. Unified interface for the three STAC ingestion paths
+ * (STAC API, stac-geoparquet, self-contained static catalog) so the viewer
+ * has a single orchestration loop and the UI can branch on capability flags
+ * instead of hard-coded discovery modes.
+ *
+ * Pure TypeScript. No Svelte / maplibre / deck.gl / DuckDB on this import
+ * graph. The DuckDB-bound parquet implementation lives under `query/` so the
+ * `utils/` side stays publishable via `@walkthru-earth/objex-utils` (slice 6).
+ *
+ * Per-batch `pushedDown` / `residual` reporting lets the caller skip
+ * client-side filtering for dimensions the engine already narrowed, and lets
+ * the UI render capability badges. A parquet file with a STRUCT
+ * `properties` column can push `eo:cloud_cover` while a sibling file with
+ * an opaque `properties` cannot, so the report is per batch, not per source.
+ */
+
+/** Which underlying engine drives this source. Used by the viewer to pick
+ * atomic-swap-vs-append, by the UI to choose copy / badges, and by tests. */
+type StacSourceKind = 'api' | 'parquet' | 'static';
+/**
+ * Per-source capability surface. Read by the viewer at construction (no await
+ * — sources are synchronous to construct so the orchestrator can branch on
+ * `kind` before any I/O) and by the filter UI to decide which controls to
+ * disable / badge as "client-side only".
+ *
+ * The `pushdown` map is exhaustive: every facet field listed in
+ * `FacetState` has a flag here, so adding a new facet is a compile-time
+ * error in every consumer until they handle it.
+ */
+interface StacSourceCapabilities {
+    kind: StacSourceKind;
+    /** Human-readable label for HUD copy. e.g. "STAC API", "stac-geoparquet". */
+    label: string;
+    /** True when count(filter, bbox) is cheap. UI surfaces "Y of X". */
+    countAvailable: boolean;
+    /** True when query() yields multiple batches before completing. */
+    streaming: boolean;
+    /**
+     * True when the underlying source is a hive-partitioned parquet directory
+     * (e.g. `s3://bucket/prefix/year=2023/month=01/...`). Set by the parquet
+     * source when the factory detects a directory layout (or the SDK passes
+     * `hivePartitioned: true`). Lets the viewer surface a HUD hint without
+     * inspecting `kind === 'parquet'` alone, since the same `kind` covers
+     * single-file stac-geoparquet.
+     */
+    hivePartitioned?: boolean;
+    pushdown: {
+        bbox: boolean;
+        datetime: boolean;
+        collection: boolean;
+        cloudCover: boolean;
+        gsd: boolean;
+        epsg: boolean;
+        platform: boolean;
+        constellation: boolean;
+        instruments: boolean;
+        assetRoles: boolean;
+    };
 }
-interface Defaults {
-    region?: string;
-    endpoint?: string;
-    provider?: StorageProvider;
+/** Per-query inputs. The signal is required, sources MUST throw
+ * `DOMException("Aborted", "AbortError")` on abort, never silently complete. */
+interface StacSourceRequest {
+    /** WGS84 viewport bbox `[west, south, east, north]`. Required. Sources that
+     * cannot push down bbox still receive it so they can stream the whole set
+     * and rely on the caller's residual filter. */
+    bbox: [number, number, number, number];
+    filter: FacetState;
+    limit: number;
+    /** Per-page hint for sources that paginate. Server may ignore. */
+    pageSize?: number;
+    signal: AbortSignal;
+}
+/** One yielded batch of items. */
+interface StacSourceBatch {
+    items: StacItem[];
+    /** Subset of filter the source / engine applied. UI reports as "pushed". */
+    pushedDown: FacetState;
+    /** Subset of filter the caller still has to apply via applyFacets(). */
+    residual: FacetState;
+    /** True when no more batches will arrive for this request. The async
+     * iterator's own end-of-iteration also signals done; this flag lets a
+     * caller break the loop at the moment a single-yield source completes. */
+    done: boolean;
+    /** Best-effort hint of total matching items, when the source knows. */
+    totalHinted?: number;
 }
+interface StacSource {
+    capabilities: StacSourceCapabilities;
+    query(req: StacSourceRequest): AsyncIterable<StacSourceBatch>;
+    /** Optional cheap count(filter, bbox). Surfaced as "Y of X" when set. */
+    count?(filter: FacetState, bbox: StacSourceRequest['bbox'], signal: AbortSignal): Promise<number>;
+}
+/** All-false push-down flags. Helper to keep capability declarations terse. */
+declare function emptyPushdown(): StacSourceCapabilities['pushdown'];
+
 /**
- * Parse a user-provided bucket/URL string into structured storage connection parts.
+ * STAC API implementation of the StacSource contract. Wraps `hydrateStacItems`
+ * link-walking with `itemsQuery: {bbox, datetime, limit, filter}` push-down and
+ * yields each `onBatch` as a `StacSourceBatch`.
+ *
+ * Slice 2 sniffs the catalog/collection's `conformsTo` array once per source
+ * instance, builds a CQL2-JSON filter (cloud cover / gsd / platform /
+ * constellation / instruments / collection) via `toCql2Filter`, and reports
+ * the actually-pushed subset of `FacetState` plus the residual the caller still
+ * has to apply via `applyFacets`. When the sniff fails or `conformsTo` lacks
+ * the Filter extension, behavior degrades gracefully to slice-1 (bbox+datetime
+ * only).
+ *
+ * Pure TypeScript. No DuckDB / Svelte / maplibre / deck.gl import. The
+ * `StorageAdapter` import is structural (an interface), and the actual
+ * adapter is injected via `deps`.
  */
-declare function parseStorageUrl(input: string, defaults?: Defaults): ParsedStorageUrl;
+
+interface StacApiSourceDeps {
+    adapter: StorageAdapter;
+    baseHref: string;
+    urlToKey?: (absoluteUrl: string) => string | null;
+    concurrency?: number;
+}
 /**
- * Returns true if the input looks like a URL/URI rather than a plain bucket name.
- * Covers all recognized cloud storage URI schemes.
+ * Construct a STAC API source. `kind` is the classified payload from
+ * `classifyStac` (Collection / Catalog with `rel="items"`, or a STAC API
+ * `item-collection` page). The factory checks before dispatching here, this
+ * function does not re-validate.
+ *
+ * The advertised `capabilities.pushdown` flags reflect the *ceiling* of what a
+ * STAC API can push (everything CQL2 covers). The actual push-down per request
+ * depends on the `conformsTo` sniff and is reported per-batch in
+ * `pushedDown` / `residual` so the caller can re-filter only what's left.
  */
-declare function looksLikeUrl(input: string): boolean;
+declare function createApiSource(kind: StacRoutableKind, deps: StacApiSourceDeps): StacSource;
+
 /**
- * Given a parsed URL result, build a human-readable summary of what was detected.
+ * Self-contained static catalog implementation of the StacSource contract.
+ * Wraps `hydrateStacItems` link-walking with no `itemsQuery`, so the entire
+ * advertised tree is fetched and the caller filters client-side.
+ *
+ * Slice 1 reports zero push-down. Slice 4 adds extent-pruning (skip child
+ * links whose `extent.spatial` / `extent.temporal` does not intersect the
+ * request bbox / datetime), which lifts `bbox` and `datetime` to true.
+ *
+ * Pure TypeScript. No DuckDB / Svelte / maplibre / deck.gl import.
  */
-declare function describeParseResult(parsed: ParsedStorageUrl): string;
+
+interface StacStaticSourceDeps {
+    adapter: StorageAdapter;
+    baseHref: string;
+    urlToKey?: (absoluteUrl: string) => string | null;
+    concurrency?: number;
+}
+declare function createStaticSource(kind: StacRoutableKind, deps: StacStaticSourceDeps): StacSource;
+
+/**
+ * STAC Storage Extension parser.
+ *
+ * Detects the Storage Extension version on a STAC Item and extracts
+ * connection-relevant hints (region, requester-pays, custom-S3 endpoint).
+ *
+ * Inspired by lazycogs's `_storage_ext.py`. Pure TypeScript, no fetch, no
+ * Svelte dependency. Suitable for `@walkthru-earth/objex-utils` re-export.
+ *
+ * Supported schema URLs:
+ *  - https://stac-extensions.github.io/storage/v1.0.0/schema.json
+ *  - https://stac-extensions.github.io/storage/v2.0.0/schema.json
+ *
+ * v1 (item / asset properties)
+ *   storage:platform        e.g. "AWS", "GCP", "AZURE"
+ *   storage:region
+ *   storage:requester_pays  boolean
+ *   storage:tier            (ignored — no obstore equivalent)
+ *
+ * v2 (item-level scheme map + asset-level refs)
+ *   properties.storage:schemes = {
+ *     <ref>: { type, platform, region?, requester_pays?, endpoint? }
+ *   }
+ *   asset.storage:refs = ["primary", ...]   (first matching ref wins)
+ *
+ * Asset-level fields take precedence over item-level fields in v1.
+ */
+
+/** Recognized Storage Extension schema versions. */
+type StorageExtensionVersion = '1.0.0' | '2.0.0';
+/**
+ * Connection-relevant hints extracted from the Storage Extension. All fields
+ * are nullable so callers can merge selectively into existing config without
+ * clobbering user-set values.
+ */
+interface StorageHints {
+    /** e.g. "AWS", "GCP", "AZURE", "MINIO". Uppercased. Null when absent. */
+    platform: string | null;
+    /** Region code, e.g. "us-west-2". Null when absent. */
+    region: string | null;
+    /** True when requester-pays must be set. False when absent or false. */
+    requesterPays: boolean;
+    /** Concrete S3-compatible endpoint URL. Null unless v2 `custom-s3` with
+     *  a non-templated `platform` value. */
+    endpoint: string | null;
+}
+/** Empty hints record. Returned when extension absent or unparseable. */
+declare function emptyStorageHints(): StorageHints;
+/**
+ * Scan `item.stac_extensions[]` for the Storage Extension schema URL and
+ * return its parsed version. Returns null when the extension is absent or
+ * the version is not one we recognize.
+ */
+declare function detectStorageExtensionVersion(item: StacItem): StorageExtensionVersion | null;
+/**
+ * Extract connection hints from a STAC Item. Dispatches on the detected
+ * Storage Extension version. Returns `emptyStorageHints()` when the
+ * extension is absent or fails to parse.
+ *
+ * `assetKey` is optional. When given:
+ *  - v1: that asset's overrides take precedence over item-level fields.
+ *  - v2: that asset's `storage:refs[0]` resolves the item scheme.
+ *  When omitted in v2, the first scheme found in any asset's refs wins.
+ */
+declare function extractStorageHints(item: StacItem, assetKey?: string): StorageHints;
+/**
+ * TODO(host-detection): a future PR should call this from the connection
+ * auto-fill path so a STAC Item carrying Storage Extension metadata can
+ * pre-populate `region` and (for `custom-s3`) `endpoint` on a new
+ * connection.
+ *
+ * Today this lives next to the parser so consumers can opt-in without
+ * touching `host-detection.ts` or the connection store. The function is
+ * intentionally generic — it takes any object with `region` / `endpoint`
+ * keys and returns a shallow copy with hint fields filled only when the
+ * existing value is empty.
+ */
+declare function applyStorageHintsToConnection<T extends {
+    region?: string;
+    endpoint?: string;
+}>(conn: T, hints: StorageHints): T;
+
+/**
+ * Open-time storage probe. Issues a single ranged GET against a presigned
+ * asset URL to surface auth, CORS, and bucket-misconfiguration errors at
+ * viewer load time, before any tile read kicks off.
+ *
+ * Inspired by lazycogs `_smoketest_store` (developmentseed/lazycogs). The
+ * Python library calls `store.head()` on a representative asset during
+ * `open()` so credential or region misconfiguration fails in <1s instead of
+ * mid-mosaic when the first COG range fetch errors out.
+ *
+ * We use ranged GET instead of HEAD because:
+ *   - Many private buckets allow GET but block HEAD via CORS.
+ *   - Range `bytes=0-0` is one byte, cheaper than a full body fetch.
+ *   - Successful 206 / 200 confirms BOTH auth and CORS headers are correct,
+ *     which a HEAD response sometimes lies about under bucket policies that
+ *     return mismatched `Access-Control-Expose-Headers`.
+ *
+ * Pure TS, no Svelte / framework deps. Safe to publish via objex-utils.
+ */
+type SmokeTestResult = {
+    ok: true;
+} | {
+    ok: false;
+    status: number | null;
+    reason: string;
+};
+/**
+ * Probe a presigned URL with a one-byte Range GET. Resolves to `{ ok: true }`
+ * on 200 / 206, otherwise returns a structured failure with the HTTP status
+ * (or null when the request never reached a server, e.g. CORS preflight
+ * failure or DNS error). AbortError is re-thrown so callers can distinguish
+ * intentional cancellation from real failures.
+ */
+declare function smokeTestHref(href: string, signal?: AbortSignal): Promise<SmokeTestResult>;
 
 /**
  * Lightweight WKB (Well-Known Binary) parser for extracting coordinates.
@@ -877,4 +2257,4 @@ declare function findGeoColumnFromRows(rows: Record<string, unknown>[], schema:
     type: string;
 }[]): string | null;
 
-export { type AccessMode, type AccessModeInput, COPY_FEEDBACK_MS, type CogInfo, type Connection, type ConnectionConfig, DEFAULT_TARGET_CRS, DUCKDB_INIT_TIMEOUT_MS, type Defaults, type DuckDbReadFn, type FileCategory, type FileEntry, type FileTypeInfo, type GeoArrowGeomType, type GeoArrowResult, type GeoBounds, type GeoColumnMeta, type GeoParquetMeta, type GeoType, type HexRow, LAYER_HUE_MULTIPLIER, type ListPage, MAX_QUERY_HISTORY_ENTRIES, type MapQueryHandle, type MapQueryResult, PROVIDERS, PROVIDER_IDS, type ParquetFileMetadata, type ParsedGeometry, type ParsedMarkdownDocument, type ParsedStorageUrl, type ProviderDef, type ProviderId, type ProviderRegion, QueryCancelledError, type QueryEngine, type QueryHandle, type QueryResult, type QuerySource, SF_LABELS, SQL_PREVIEW_LENGTH, STAC_GEOPARQUET_REQUIRED_COLUMNS, STORAGE_KEYS, type SchemaField, type SortConfig, type SortDirection, type SortField, type SqlBlock, type StacBboxStruct, type StacGeoparquetRow, type StacGeoparquetSchemaColumn, type StacRowToItemOptions, type StorageAdapter, type StorageProvider, type Tab, type Theme, type TypeCategory, UrlAdapter, VIEWER_DIR_EXTENSIONS, type ViewerKind, WGS84_CODES, type WriteResult, buildDataTypeLabel, buildDuckDbSource, buildEndpointFromTemplate, buildGeoArrowTables, buildProviderBaseUrl, clampBounds, classifyType, describeParseResult, escapeCsvField, exportToCsv, exportToJson, extractBounds, extractEpsgFromGeoMeta, extractGeometryTypes, findGeoColumn, findGeoColumnFromRows, flattenStacBbox, formatDate, formatFileSize, formatValue, generateHexDump, getAccessMode, getDuckDbReadFn, getFileExtension, getFileTypeInfo, getMimeType, getNativeScheme, getProvider, getViewerKind, handleLoadError, interpolateTemplates, isCloudNativeFormat, isGcsProvider, isPubliclyStreamable, isQueryable, isStacGeoparquetSchema, jsonReplacerBigInt, loadFromStorage, looksLikeUrl, markSqlBlocks, normalizeGeomType, parseMarkdownDocument, parseStorageUrl, parseWKB, persistToStorage, pickStacPrimaryAsset, readParquetMetadata, resolveCloudUrl, resolveProviderEndpoint, resolveStacAssetHref, safeClamp, safeDecodeURIComponent, serializeToCsv, serializeToJson, sortFileEntries, stacRowToItem, toBinary, toggleSortField, typeBadgeClass, typeColor, typeLabel };
+export { type AccessMode, type AccessModeInput, type AppConfig, type AppConfigDefaults, type AppConfigUi, type AttachPixelInspectorOptions, type BandMap, type BandSlot, type BasemapConfig, COPY_FEEDBACK_MS, type ChannelComposite, type ChannelRef, type CogAsset, type CogInfo, type Connection, type ConnectionConfig, type ConnectionIdentityInput, type ConnectionSeed, DATETIME_HISTOGRAM_BINS, DATETIME_HISTOGRAM_BINS_MAX, DEFAULT_APP_CONFIG, DEFAULT_TARGET_CRS, DUCKDB_INIT_TIMEOUT_MS, type DatetimeFacet, type DatetimeGranularity, type Defaults, type DetectedHost, type DuckDbReadFn, type EnumFacet, type EnumFacetField, type Facet, type FacetSet, type FacetSort, type FacetState, type FileCategory, type FileEntry, type FileTypeInfo, type GeoArrowGeomType, type GeoArrowResult, type GeoBounds, type GeoColumnMeta, type GeoParquetMeta, type GeoType, type GeometryTypeInfo, type HexRow, type HydrateOptions, type HydrateResult, LAYER_HUE_MULTIPLIER, type ListPage, LruCache, type LruCacheOptions, MAX_QUERY_HISTORY_ENTRIES, type MapLike, type MapQueryHandle, type MapQueryResult, MarkdownSqlContext, type MosaicSourceMeta, type NotebookConfig, type NotebookMeta, type NumericFacet, type NumericFacetField, PRESETS, PROVIDERS, PROVIDER_IDS, type ParquetFileMetadata, type ParsedGeometry, type ParsedMarkdownDocument, type ParsedStorageUrl, type PixelInspectCallbacks, type PixelInspectClickEvent, type PixelInspectClickHandler, type PixelInspectProbe, type PixelInspectProbeRequest, type PresetDef, type ProviderDef, type ProviderId, type ProviderRegion, QueryCancelledError, type QueryEngine, type QueryHandle, type QueryResult, type QuerySource, type RasterBandAsset, SF_LABELS, SQL_PREVIEW_LENGTH, STAC_API_PATH_RE, STAC_COG_ASSET_KEYS, STAC_GEOPARQUET_REQUIRED_COLUMNS, STORAGE_KEYS, type SchemaField, type SmokeTestResult, type SortConfig, type SortDirection, type SortField, type SqlBlock, type StacApiCapabilities, type StacApiSourceDeps, type StacAsset, type StacBboxStruct, type StacCatalog, type StacCollection, type StacFeatureCollection, type StacGeoparquetRow, type StacGeoparquetSchemaColumn, type StacItem, type StacItemView, type StacItemsQuery, type StacLink, type StacNativeQuery, type StacRoutableKind, type StacRowToItemOptions, type StacSource, type StacSourceBatch, type StacSourceCapabilities, type StacSourceKind, type StacSourceRequest, type StacStaticSourceDeps, type StorageAdapter, type StorageExtensionVersion, type StorageHints, type StorageProvider, type Tab, type Theme, type ToNativeQueryOptions, type TypeCategory, UrlAdapter, type UrlClassification, VIEWER_DIR_EXTENSIONS, type ViewerKind, WGS84_CODES, type WriteResult, absolutizeHref, allChannelsBand0, applyFacets, applyPreset, applyStacItemStorageHints, applyStorageHintsToConnection, attachPixelInspector, availablePresets, buildDataTypeLabel, buildDuckDbSource, buildEndpointFromTemplate, buildFacets, buildGeoArrowTables, buildMosaicSourceMeta, buildProviderBaseUrl, buildTransformExpr, clampBounds, classifyStac, classifyType, classifyUrl, coerceBool, coercePositiveInt, coerceString, coerceTheme, compositeFromUrl, compositeToUrl, connectionIdentityKey, copyToClipboard, createApiSource, createStaticSource, describeParseResult, detectHostBucket, detectMosaicCapable, detectMultiCogCapable, detectStorageExtensionVersion, emptyFacetState, emptyPushdown, emptyStorageHints, escapeCsvField, exportToCsv, exportToJson, extractBounds, extractCogAssets, extractEpsgFromGeoMeta, extractGeometryTypes, extractItemView, extractMosaicAssets, extractRasterBandAssets, extractSentinelBandAssets, extractStorageHints, findGeoColumn, findGeoColumnFromRows, flattenStacBbox, formatDate, formatFileSize, formatValue, generateHexDump, getAccessMode, getDuckDbReadFn, getFileExtension, getFileTypeInfo, getMimeType, getNativeScheme, getProvider, getViewerKind, handleLoadError, hasActiveFilters, hasCompositableBands, hasRgbBands, hasStacItemsEndpoint, hydrateStacItems, interpolateTemplates, isAbortError, isCloudNativeFormat, isGcsProvider, isKnownBucketHost, isPubliclyStreamable, isQueryable, isSameConnectionIdentity, isSingleAssetComposite, isStacCatalog, isStacCollection, isStacFeatureCollection, isStacGeoparquetSchema, isStacItem, isWgs84Crs, jsonReplacerBigInt, loadFromStorage, looksLikeUrl, markSqlBlocks, mergeAppConfig, normalizeEndpoint, normalizeGeomType, normalizeProvider, parseGeometryTypeCrs, parseMarkdownDocument, parseStorageUrl, parseVisibilityParam, parseWKB, persistToStorage, pickCogAssetHref, pickGranularity, pickNaturalColorComposite, pickStacPrimaryAsset, presetMatchesComposite, readParquetMetadata, renderNotebook, residualState, resolveBandSlotAssetKey, resolveBasemap, resolveCloudUrl, resolvePresetComposite, resolveProviderEndpoint, resolveSetting, resolveStacAssetHref, safeClamp, safeDecodeURIComponent, serializeToCsv, serializeToJson, smokeTestHref, sniffApiCapabilities, sortFileEntries, sortViews, spatialCellKey, stacItemBbox, stacRowToItem, syntheticSelfAsset, toBinary, toCql2Filter, toNativeQuery, toggleSortField, typeBadgeClass, typeColor, typeLabel, wireCodeCopyButtons, wrapWkbWithCrs };