@walkthru-earth/objex-utils 1.0.0 → 1.2.0

package/dist/index.d.cts

@@ -11,8 +11,12 @@ declare const STORAGE_KEYS: {
 };
 /** EPSG codes considered WGS84 (no reprojection needed). */
 declare const WGS84_CODES: Set<number>;
-/** Default target CRS for ST_Transform. */
-declare const DEFAULT_TARGET_CRS = "EPSG:4326";
+/**
+ * Default target CRS for ST_Transform. Uses OGC:CRS84 (longitude, latitude)
+ * to match GeoParquet 1.1+ spec and DuckDB v1.5's canonical form.
+ * Functionally equivalent to EPSG:4326 under `geometry_always_xy = true`.
+ */
+declare const DEFAULT_TARGET_CRS = "OGC:CRS84";
 /** DuckDB-WASM initialization timeout in ms. */
 declare const DUCKDB_INIT_TIMEOUT_MS = 30000;
 /** Maximum entries kept in query history. */
@@ -119,15 +123,27 @@ interface SchemaField {
     type: string;
     nullable: boolean;
 }
+/**
+ * Abstraction over a DuckDB query source. Decouples schema / CRS / count
+ * helpers from assuming a file-backed path. `ref` is the FROM-clause target
+ * inserted into generated SQL (e.g. `read_parquet('url')` for files, or
+ * `attached_db."schema"."table"` for attached databases). `filePath` is
+ * optional and only used as a shortcut for Parquet file-level metadata
+ * queries (`parquet_kv_metadata`, `parquet_file_metadata`), not for SQL.
+ */
+interface QuerySource {
+    ref: string;
+    filePath?: string;
+}
 interface QueryEngine {
     query(connId: string, sql: string): Promise<QueryResult>;
     queryForMap(connId: string, sql: string, geomCol: string, geomColType: string, sourceCrs?: string | null): Promise<MapQueryResult>;
-    getSchema(connId: string, path: string): Promise<SchemaField[]>;
-    getRowCount(connId: string, path: string): Promise<number>;
+    getSchema(connId: string, source: QuerySource): Promise<SchemaField[]>;
+    getRowCount(connId: string, source: QuerySource): Promise<number>;
     /** Detect CRS from GeoParquet metadata. Returns e.g. 'EPSG:27700' or null if WGS84/unknown. */
-    detectCrs(connId: string, path: string, geomCol: string): Promise<string | null>;
+    detectCrs(connId: string, source: QuerySource, geomCol: string): Promise<string | null>;
     /** Combined schema + CRS detection in a single connection (fewer web worker round-trips). */
-    getSchemaAndCrs?(connId: string, path: string, findGeoCol: (schema: SchemaField[]) => string | null): Promise<{
+    getSchemaAndCrs?(connId: string, source: QuerySource, findGeoCol: (schema: SchemaField[]) => string | null): Promise<{
         schema: SchemaField[];
         geomCol: string | null;
         crs: string | null;
@@ -135,6 +151,10 @@ interface QueryEngine {
     queryCancellable?(connId: string, sql: string): QueryHandle;
     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. */
+    registerFileBuffer?(name: string, buffer: Uint8Array): Promise<void>;
+    /** Drop a previously registered file from DuckDB-WASM's virtual filesystem. */
+    dropFile?(name: string): Promise<void>;
     releaseMemory(): Promise<void>;
     dispose(): Promise<void>;
 }
@@ -179,6 +199,17 @@ interface Tab {
     connectionId?: string;
     extension: string;
     size?: number;
+    /**
+     * When set, the tab reads data from a SQL FROM-clause target (e.g. an
+     * attached DuckLake/DuckDB/SQLite table) rather than a file URL. The ref
+     * is inserted directly into generated SQL, so it must be fully-qualified
+     * and pre-quoted, e.g. `__objex_db__."main"."air_quality"`.
+     *
+     * When `sourceRef` is set, file-specific loading paths (hyparquet
+     * metadata, `parquet_kv_metadata`, etc.) are skipped, and schema / CRS /
+     * row count are derived from the SQL source directly via DuckDB.
+     */
+    sourceRef?: string;
 }
 interface WriteResult {
     key: string;
@@ -208,6 +239,60 @@ interface StorageAdapter {
     readonly supportsWrite: boolean;
 }
 
+/**
+ * Provider registry — single source of truth for all cloud storage providers.
+ *
+ * Centralizes endpoint patterns, regions, auth methods, and UI metadata.
+ * Used by ConnectionDialog, browser-cloud adapter, host-detection, url-state, etc.
+ */
+type ProviderId = 's3' | 'gcs' | 'r2' | 'minio' | 'azure' | 'storj' | 'b2' | 'digitalocean' | 'wasabi' | 'contabo' | 'hetzner' | 'linode' | 'ovhcloud';
+interface ProviderRegion {
+    code: string;
+    label: string;
+}
+interface ProviderDef {
+    /** Display label in the UI. */
+    label: string;
+    /** Short description shown as helper text. */
+    description: string;
+    /** Auth method used by this provider. */
+    authMethod: 'sigv4' | 'sas-token';
+    /** Whether the region field is relevant for this provider. */
+    needsRegion: boolean;
+    /** Whether the endpoint field is required. */
+    needsEndpoint: boolean;
+    /** Default region when creating a new connection. */
+    defaultRegion: string;
+    /**
+     * Endpoint template with `{region}` placeholder.
+     * If null, the user must provide a custom endpoint (e.g. MinIO).
+     * If a fixed string (no `{region}`), it's always the same (e.g. GCS).
+     */
+    endpointTemplate: string | null;
+    /** Known regions with labels. Empty = free-form region input. */
+    regions: ProviderRegion[];
+    /** Bucket label override (e.g. Azure uses "Container"). */
+    bucketLabel?: string;
+    /** Default endpoint placeholder shown in the input. */
+    endpointPlaceholder: string;
+    /** URI schemes that map to this provider (lowercase, without "://"). */
+    schemes: string[];
+}
+declare const PROVIDERS: Record<ProviderId, ProviderDef>;
+/** All provider IDs, ordered for the UI. */
+declare const PROVIDER_IDS: ProviderId[];
+/** Get provider def, falling back to S3 for unknown. */
+declare function getProvider(id: string): ProviderDef;
+/** Build endpoint URL from template + region. */
+declare function buildEndpointFromTemplate(id: ProviderId, region: string): string;
+/**
+ * Build the base URL for API requests (endpoint + bucket).
+ * Used by browser-cloud adapter and url-state.
+ */
+declare function buildProviderBaseUrl(provider: ProviderId, endpoint: string, bucket: string, region: string): string;
+/** Check if a provider uses the GCS JSON API (not S3 XML). */
+declare function isGcsProvider(provider: string, endpoint: string): boolean;
+
 /**
  * Minimal adapter for direct HTTPS URLs (source: 'url').
  * Only supports read/head — no listing or writing.
@@ -226,6 +311,60 @@ declare class UrlAdapter implements StorageAdapter {
     copy(): Promise<WriteResult>;
 }
 
+/**
+ * Cloud storage protocol URL utilities — pure TS, no Svelte dependency.
+ *
+ * Converts cloud protocol URLs (s3://, gs://) to HTTPS URLs for browser access.
+ * Provider-aware native scheme lookup.
+ */
+/**
+ * Map provider to its native URI scheme prefix.
+ * Derived from the registry's `schemes` array (first entry is the primary scheme).
+ * Falls back to 's3' for providers without a scheme (S3-compatible).
+ */
+declare function getNativeScheme(provider: string): string;
+/**
+ * Safely decode a percent-encoded URI component.
+ * Returns the original string if decoding fails (malformed sequences).
+ */
+declare function safeDecodeURIComponent(s: string): string;
+/**
+ * Convert a cloud storage protocol URL (s3://, gs://) to an HTTPS URL
+ * for browser access. Returns the original URL if already HTTP(S) or unknown.
+ *
+ * Supported:
+ * - `s3://bucket/key` → `https://s3.{region}.amazonaws.com/{bucket}/{key}`
+ *   (region auto-detected from bucket name when possible)
+ * - `gs://bucket/key` → `https://storage.googleapis.com/{bucket}/{key}`
+ */
+declare function resolveCloudUrl(url: string): string;
+
+/** SampleFormat tag value → human label. */
+declare const SF_LABELS: Record<number, string>;
+interface GeoBounds {
+    west: number;
+    south: number;
+    east: number;
+    north: number;
+}
+interface CogInfo {
+    width: number;
+    height: number;
+    bandCount: number;
+    dataType: string;
+    bounds: GeoBounds;
+    downsampled?: boolean;
+}
+/** Safely clamp a number to a range, treating NaN/Infinity as the fallback. */
+declare function safeClamp(v: number, lo: number, hi: number, fallback: number): number;
+/** Clamp geographic bounds to valid MapLibre web-Mercator range. */
+declare function clampBounds(b: GeoBounds): GeoBounds;
+/**
+ * Build a data-type label from GeoTIFF sample format and bits per sample.
+ * e.g. "uint8", "float32", "int16"
+ */
+declare function buildDataTypeLabel(sampleFormat: number, bitsPerSample: number): string;
+
 type TypeCategory = 'number' | 'string' | 'date' | 'boolean' | 'geo' | 'binary' | 'json' | 'other';
 declare function classifyType(duckdbType: string): TypeCategory;
 declare function typeColor(category: TypeCategory): string;
@@ -241,6 +380,42 @@ declare function typeLabel(category: TypeCategory): string;
  */
 declare function handleLoadError(err: unknown): string | null;
 
+/**
+ * Escape a CSV field value per RFC 4180.
+ */
+declare function escapeCsvField(value: string): string;
+/**
+ * Serialize column/row data to a CSV string.
+ * Pure function — no browser APIs, works in Node.js.
+ */
+declare function serializeToCsv(columns: string[], rows: Record<string, unknown>[]): string;
+/**
+ * Serialize column/row data to a formatted JSON string.
+ * Pure function — no browser APIs, works in Node.js.
+ */
+declare function serializeToJson(columns: string[], rows: Record<string, unknown>[]): string;
+
+/**
+ * Pure file entry sorting — framework-agnostic, works in Node.js.
+ */
+
+type SortField = 'name' | 'size' | 'modified' | 'extension';
+type SortDirection = 'asc' | 'desc';
+interface SortConfig {
+    field: SortField;
+    direction: SortDirection;
+}
+/**
+ * Sort file entries by the given config.
+ * Directories always sort before files regardless of sort field.
+ * Returns a new array (does not mutate the input).
+ */
+declare function sortFileEntries(entries: FileEntry[], config: SortConfig): FileEntry[];
+/**
+ * Toggle sort config: same field flips direction, new field starts ascending.
+ */
+declare function toggleSortField(current: SortConfig, field: SortField): SortConfig;
+
 /**
  * Formats a byte count into a human-readable string.
  */
@@ -310,6 +485,54 @@ interface HexRow {
  */
 declare function generateHexDump(data: Uint8Array, bytesPerRow?: number): HexRow[];
 
+/**
+ * Generic localStorage helpers with SSR safety.
+ *
+ * Used by connection, settings, and query-history stores to avoid
+ * repeating the same load/persist/try-catch/SSR-guard pattern.
+ */
+/**
+ * Load a JSON value from localStorage.
+ * Returns `defaultValue` on SSR, missing key, or parse error.
+ */
+declare function loadFromStorage<T>(key: string, defaultValue: T): T;
+/**
+ * Persist a JSON-serializable value to localStorage.
+ * Silently no-ops on SSR or storage errors (quota, private browsing).
+ */
+declare function persistToStorage(key: string, value: unknown): void;
+
+interface SqlBlock {
+    name: string;
+    sql: string;
+    startLine: number;
+    endLine: number;
+}
+interface ParsedMarkdownDocument {
+    frontmatter: Record<string, any>;
+    content: string;
+    sqlBlocks: SqlBlock[];
+}
+/**
+ * Parse a markdown document with YAML frontmatter and SQL code blocks.
+ *
+ * Evidence-compatible syntax:
+ * ```sql query_name
+ * SELECT * FROM table
+ * ```
+ */
+declare function parseMarkdownDocument(markdown: string): Promise<ParsedMarkdownDocument>;
+/**
+ * Interpolate template variables in markdown text.
+ * Supports {queryName.rows[0].columnName} syntax.
+ */
+declare function interpolateTemplates(text: string, queryResults: Map<string, Record<string, any>[]>): string;
+/**
+ * Replace SQL blocks in markdown content with placeholder markers
+ * that can be replaced with rendered components.
+ */
+declare function markSqlBlocks(content: string): string;
+
 /**
  * Lightweight Parquet metadata reader using hyparquet.
  *
@@ -478,4 +701,4 @@ declare function findGeoColumnFromRows(rows: Record<string, unknown>[], schema:
     type: string;
 }[]): string | null;
 
-export { COPY_FEEDBACK_MS, 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 GeoColumnMeta, type GeoParquetMeta, type GeoType, type HexRow, LAYER_HUE_MULTIPLIER, type ListPage, MAX_QUERY_HISTORY_ENTRIES, type MapQueryHandle, type MapQueryResult, type ParquetFileMetadata, type ParsedGeometry, type ParsedStorageUrl, QueryCancelledError, type QueryEngine, type QueryHandle, type QueryResult, SQL_PREVIEW_LENGTH, STORAGE_KEYS, type SchemaField, type StorageAdapter, type StorageProvider, type Tab, type Theme, type TypeCategory, UrlAdapter, VIEWER_DIR_EXTENSIONS, type ViewerKind, WGS84_CODES, type WriteResult, buildDuckDbSource, buildGeoArrowTables, classifyType, describeParseResult, extractBounds, extractEpsgFromGeoMeta, extractGeometryTypes, findGeoColumn, findGeoColumnFromRows, formatDate, formatFileSize, formatValue, generateHexDump, getDuckDbReadFn, getFileExtension, getFileTypeInfo, getMimeType, getViewerKind, handleLoadError, isCloudNativeFormat, isQueryable, jsonReplacerBigInt, looksLikeUrl, normalizeGeomType, parseStorageUrl, parseWKB, readParquetMetadata, toBinary, typeBadgeClass, typeColor, typeLabel };
+export { 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, SF_LABELS, SQL_PREVIEW_LENGTH, STORAGE_KEYS, type SchemaField, type SortConfig, type SortDirection, type SortField, type SqlBlock, 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, extractBounds, extractEpsgFromGeoMeta, extractGeometryTypes, findGeoColumn, findGeoColumnFromRows, formatDate, formatFileSize, formatValue, generateHexDump, getDuckDbReadFn, getFileExtension, getFileTypeInfo, getMimeType, getNativeScheme, getProvider, getViewerKind, handleLoadError, interpolateTemplates, isCloudNativeFormat, isGcsProvider, isQueryable, jsonReplacerBigInt, loadFromStorage, looksLikeUrl, markSqlBlocks, normalizeGeomType, parseMarkdownDocument, parseStorageUrl, parseWKB, persistToStorage, readParquetMetadata, resolveCloudUrl, safeClamp, safeDecodeURIComponent, serializeToCsv, serializeToJson, sortFileEntries, toBinary, toggleSortField, typeBadgeClass, typeColor, typeLabel };

package/dist/index.d.ts

@@ -11,8 +11,12 @@ declare const STORAGE_KEYS: {
 };
 /** EPSG codes considered WGS84 (no reprojection needed). */
 declare const WGS84_CODES: Set<number>;
-/** Default target CRS for ST_Transform. */
-declare const DEFAULT_TARGET_CRS = "EPSG:4326";
+/**
+ * Default target CRS for ST_Transform. Uses OGC:CRS84 (longitude, latitude)
+ * to match GeoParquet 1.1+ spec and DuckDB v1.5's canonical form.
+ * Functionally equivalent to EPSG:4326 under `geometry_always_xy = true`.
+ */
+declare const DEFAULT_TARGET_CRS = "OGC:CRS84";
 /** DuckDB-WASM initialization timeout in ms. */
 declare const DUCKDB_INIT_TIMEOUT_MS = 30000;
 /** Maximum entries kept in query history. */
@@ -119,15 +123,27 @@ interface SchemaField {
     type: string;
     nullable: boolean;
 }
+/**
+ * Abstraction over a DuckDB query source. Decouples schema / CRS / count
+ * helpers from assuming a file-backed path. `ref` is the FROM-clause target
+ * inserted into generated SQL (e.g. `read_parquet('url')` for files, or
+ * `attached_db."schema"."table"` for attached databases). `filePath` is
+ * optional and only used as a shortcut for Parquet file-level metadata
+ * queries (`parquet_kv_metadata`, `parquet_file_metadata`), not for SQL.
+ */
+interface QuerySource {
+    ref: string;
+    filePath?: string;
+}
 interface QueryEngine {
     query(connId: string, sql: string): Promise<QueryResult>;
     queryForMap(connId: string, sql: string, geomCol: string, geomColType: string, sourceCrs?: string | null): Promise<MapQueryResult>;
-    getSchema(connId: string, path: string): Promise<SchemaField[]>;
-    getRowCount(connId: string, path: string): Promise<number>;
+    getSchema(connId: string, source: QuerySource): Promise<SchemaField[]>;
+    getRowCount(connId: string, source: QuerySource): Promise<number>;
     /** Detect CRS from GeoParquet metadata. Returns e.g. 'EPSG:27700' or null if WGS84/unknown. */
-    detectCrs(connId: string, path: string, geomCol: string): Promise<string | null>;
+    detectCrs(connId: string, source: QuerySource, geomCol: string): Promise<string | null>;
     /** Combined schema + CRS detection in a single connection (fewer web worker round-trips). */
-    getSchemaAndCrs?(connId: string, path: string, findGeoCol: (schema: SchemaField[]) => string | null): Promise<{
+    getSchemaAndCrs?(connId: string, source: QuerySource, findGeoCol: (schema: SchemaField[]) => string | null): Promise<{
         schema: SchemaField[];
         geomCol: string | null;
         crs: string | null;
@@ -135,6 +151,10 @@ interface QueryEngine {
     queryCancellable?(connId: string, sql: string): QueryHandle;
     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. */
+    registerFileBuffer?(name: string, buffer: Uint8Array): Promise<void>;
+    /** Drop a previously registered file from DuckDB-WASM's virtual filesystem. */
+    dropFile?(name: string): Promise<void>;
     releaseMemory(): Promise<void>;
     dispose(): Promise<void>;
 }
@@ -179,6 +199,17 @@ interface Tab {
     connectionId?: string;
     extension: string;
     size?: number;
+    /**
+     * When set, the tab reads data from a SQL FROM-clause target (e.g. an
+     * attached DuckLake/DuckDB/SQLite table) rather than a file URL. The ref
+     * is inserted directly into generated SQL, so it must be fully-qualified
+     * and pre-quoted, e.g. `__objex_db__."main"."air_quality"`.
+     *
+     * When `sourceRef` is set, file-specific loading paths (hyparquet
+     * metadata, `parquet_kv_metadata`, etc.) are skipped, and schema / CRS /
+     * row count are derived from the SQL source directly via DuckDB.
+     */
+    sourceRef?: string;
 }
 interface WriteResult {
     key: string;
@@ -208,6 +239,60 @@ interface StorageAdapter {
     readonly supportsWrite: boolean;
 }
 
+/**
+ * Provider registry — single source of truth for all cloud storage providers.
+ *
+ * Centralizes endpoint patterns, regions, auth methods, and UI metadata.
+ * Used by ConnectionDialog, browser-cloud adapter, host-detection, url-state, etc.
+ */
+type ProviderId = 's3' | 'gcs' | 'r2' | 'minio' | 'azure' | 'storj' | 'b2' | 'digitalocean' | 'wasabi' | 'contabo' | 'hetzner' | 'linode' | 'ovhcloud';
+interface ProviderRegion {
+    code: string;
+    label: string;
+}
+interface ProviderDef {
+    /** Display label in the UI. */
+    label: string;
+    /** Short description shown as helper text. */
+    description: string;
+    /** Auth method used by this provider. */
+    authMethod: 'sigv4' | 'sas-token';
+    /** Whether the region field is relevant for this provider. */
+    needsRegion: boolean;
+    /** Whether the endpoint field is required. */
+    needsEndpoint: boolean;
+    /** Default region when creating a new connection. */
+    defaultRegion: string;
+    /**
+     * Endpoint template with `{region}` placeholder.
+     * If null, the user must provide a custom endpoint (e.g. MinIO).
+     * If a fixed string (no `{region}`), it's always the same (e.g. GCS).
+     */
+    endpointTemplate: string | null;
+    /** Known regions with labels. Empty = free-form region input. */
+    regions: ProviderRegion[];
+    /** Bucket label override (e.g. Azure uses "Container"). */
+    bucketLabel?: string;
+    /** Default endpoint placeholder shown in the input. */
+    endpointPlaceholder: string;
+    /** URI schemes that map to this provider (lowercase, without "://"). */
+    schemes: string[];
+}
+declare const PROVIDERS: Record<ProviderId, ProviderDef>;
+/** All provider IDs, ordered for the UI. */
+declare const PROVIDER_IDS: ProviderId[];
+/** Get provider def, falling back to S3 for unknown. */
+declare function getProvider(id: string): ProviderDef;
+/** Build endpoint URL from template + region. */
+declare function buildEndpointFromTemplate(id: ProviderId, region: string): string;
+/**
+ * Build the base URL for API requests (endpoint + bucket).
+ * Used by browser-cloud adapter and url-state.
+ */
+declare function buildProviderBaseUrl(provider: ProviderId, endpoint: string, bucket: string, region: string): string;
+/** Check if a provider uses the GCS JSON API (not S3 XML). */
+declare function isGcsProvider(provider: string, endpoint: string): boolean;
+
 /**
  * Minimal adapter for direct HTTPS URLs (source: 'url').
  * Only supports read/head — no listing or writing.
@@ -226,6 +311,60 @@ declare class UrlAdapter implements StorageAdapter {
     copy(): Promise<WriteResult>;
 }
 
+/**
+ * Cloud storage protocol URL utilities — pure TS, no Svelte dependency.
+ *
+ * Converts cloud protocol URLs (s3://, gs://) to HTTPS URLs for browser access.
+ * Provider-aware native scheme lookup.
+ */
+/**
+ * Map provider to its native URI scheme prefix.
+ * Derived from the registry's `schemes` array (first entry is the primary scheme).
+ * Falls back to 's3' for providers without a scheme (S3-compatible).
+ */
+declare function getNativeScheme(provider: string): string;
+/**
+ * Safely decode a percent-encoded URI component.
+ * Returns the original string if decoding fails (malformed sequences).
+ */
+declare function safeDecodeURIComponent(s: string): string;
+/**
+ * Convert a cloud storage protocol URL (s3://, gs://) to an HTTPS URL
+ * for browser access. Returns the original URL if already HTTP(S) or unknown.
+ *
+ * Supported:
+ * - `s3://bucket/key` → `https://s3.{region}.amazonaws.com/{bucket}/{key}`
+ *   (region auto-detected from bucket name when possible)
+ * - `gs://bucket/key` → `https://storage.googleapis.com/{bucket}/{key}`
+ */
+declare function resolveCloudUrl(url: string): string;
+
+/** SampleFormat tag value → human label. */
+declare const SF_LABELS: Record<number, string>;
+interface GeoBounds {
+    west: number;
+    south: number;
+    east: number;
+    north: number;
+}
+interface CogInfo {
+    width: number;
+    height: number;
+    bandCount: number;
+    dataType: string;
+    bounds: GeoBounds;
+    downsampled?: boolean;
+}
+/** Safely clamp a number to a range, treating NaN/Infinity as the fallback. */
+declare function safeClamp(v: number, lo: number, hi: number, fallback: number): number;
+/** Clamp geographic bounds to valid MapLibre web-Mercator range. */
+declare function clampBounds(b: GeoBounds): GeoBounds;
+/**
+ * Build a data-type label from GeoTIFF sample format and bits per sample.
+ * e.g. "uint8", "float32", "int16"
+ */
+declare function buildDataTypeLabel(sampleFormat: number, bitsPerSample: number): string;
+
 type TypeCategory = 'number' | 'string' | 'date' | 'boolean' | 'geo' | 'binary' | 'json' | 'other';
 declare function classifyType(duckdbType: string): TypeCategory;
 declare function typeColor(category: TypeCategory): string;
@@ -241,6 +380,42 @@ declare function typeLabel(category: TypeCategory): string;
  */
 declare function handleLoadError(err: unknown): string | null;
 
+/**
+ * Escape a CSV field value per RFC 4180.
+ */
+declare function escapeCsvField(value: string): string;
+/**
+ * Serialize column/row data to a CSV string.
+ * Pure function — no browser APIs, works in Node.js.
+ */
+declare function serializeToCsv(columns: string[], rows: Record<string, unknown>[]): string;
+/**
+ * Serialize column/row data to a formatted JSON string.
+ * Pure function — no browser APIs, works in Node.js.
+ */
+declare function serializeToJson(columns: string[], rows: Record<string, unknown>[]): string;
+
+/**
+ * Pure file entry sorting — framework-agnostic, works in Node.js.
+ */
+
+type SortField = 'name' | 'size' | 'modified' | 'extension';
+type SortDirection = 'asc' | 'desc';
+interface SortConfig {
+    field: SortField;
+    direction: SortDirection;
+}
+/**
+ * Sort file entries by the given config.
+ * Directories always sort before files regardless of sort field.
+ * Returns a new array (does not mutate the input).
+ */
+declare function sortFileEntries(entries: FileEntry[], config: SortConfig): FileEntry[];
+/**
+ * Toggle sort config: same field flips direction, new field starts ascending.
+ */
+declare function toggleSortField(current: SortConfig, field: SortField): SortConfig;
+
 /**
  * Formats a byte count into a human-readable string.
  */
@@ -310,6 +485,54 @@ interface HexRow {
  */
 declare function generateHexDump(data: Uint8Array, bytesPerRow?: number): HexRow[];
 
+/**
+ * Generic localStorage helpers with SSR safety.
+ *
+ * Used by connection, settings, and query-history stores to avoid
+ * repeating the same load/persist/try-catch/SSR-guard pattern.
+ */
+/**
+ * Load a JSON value from localStorage.
+ * Returns `defaultValue` on SSR, missing key, or parse error.
+ */
+declare function loadFromStorage<T>(key: string, defaultValue: T): T;
+/**
+ * Persist a JSON-serializable value to localStorage.
+ * Silently no-ops on SSR or storage errors (quota, private browsing).
+ */
+declare function persistToStorage(key: string, value: unknown): void;
+
+interface SqlBlock {
+    name: string;
+    sql: string;
+    startLine: number;
+    endLine: number;
+}
+interface ParsedMarkdownDocument {
+    frontmatter: Record<string, any>;
+    content: string;
+    sqlBlocks: SqlBlock[];
+}
+/**
+ * Parse a markdown document with YAML frontmatter and SQL code blocks.
+ *
+ * Evidence-compatible syntax:
+ * ```sql query_name
+ * SELECT * FROM table
+ * ```
+ */
+declare function parseMarkdownDocument(markdown: string): Promise<ParsedMarkdownDocument>;
+/**
+ * Interpolate template variables in markdown text.
+ * Supports {queryName.rows[0].columnName} syntax.
+ */
+declare function interpolateTemplates(text: string, queryResults: Map<string, Record<string, any>[]>): string;
+/**
+ * Replace SQL blocks in markdown content with placeholder markers
+ * that can be replaced with rendered components.
+ */
+declare function markSqlBlocks(content: string): string;
+
 /**
  * Lightweight Parquet metadata reader using hyparquet.
  *
@@ -478,4 +701,4 @@ declare function findGeoColumnFromRows(rows: Record<string, unknown>[], schema:
     type: string;
 }[]): string | null;
 
-export { COPY_FEEDBACK_MS, 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 GeoColumnMeta, type GeoParquetMeta, type GeoType, type HexRow, LAYER_HUE_MULTIPLIER, type ListPage, MAX_QUERY_HISTORY_ENTRIES, type MapQueryHandle, type MapQueryResult, type ParquetFileMetadata, type ParsedGeometry, type ParsedStorageUrl, QueryCancelledError, type QueryEngine, type QueryHandle, type QueryResult, SQL_PREVIEW_LENGTH, STORAGE_KEYS, type SchemaField, type StorageAdapter, type StorageProvider, type Tab, type Theme, type TypeCategory, UrlAdapter, VIEWER_DIR_EXTENSIONS, type ViewerKind, WGS84_CODES, type WriteResult, buildDuckDbSource, buildGeoArrowTables, classifyType, describeParseResult, extractBounds, extractEpsgFromGeoMeta, extractGeometryTypes, findGeoColumn, findGeoColumnFromRows, formatDate, formatFileSize, formatValue, generateHexDump, getDuckDbReadFn, getFileExtension, getFileTypeInfo, getMimeType, getViewerKind, handleLoadError, isCloudNativeFormat, isQueryable, jsonReplacerBigInt, looksLikeUrl, normalizeGeomType, parseStorageUrl, parseWKB, readParquetMetadata, toBinary, typeBadgeClass, typeColor, typeLabel };
+export { 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, SF_LABELS, SQL_PREVIEW_LENGTH, STORAGE_KEYS, type SchemaField, type SortConfig, type SortDirection, type SortField, type SqlBlock, 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, extractBounds, extractEpsgFromGeoMeta, extractGeometryTypes, findGeoColumn, findGeoColumnFromRows, formatDate, formatFileSize, formatValue, generateHexDump, getDuckDbReadFn, getFileExtension, getFileTypeInfo, getMimeType, getNativeScheme, getProvider, getViewerKind, handleLoadError, interpolateTemplates, isCloudNativeFormat, isGcsProvider, isQueryable, jsonReplacerBigInt, loadFromStorage, looksLikeUrl, markSqlBlocks, normalizeGeomType, parseMarkdownDocument, parseStorageUrl, parseWKB, persistToStorage, readParquetMetadata, resolveCloudUrl, safeClamp, safeDecodeURIComponent, serializeToCsv, serializeToJson, sortFileEntries, toBinary, toggleSortField, typeBadgeClass, typeColor, typeLabel };