@walkthru-earth/objex 1.0.0 → 1.2.0

package/dist/utils/deck.d.ts

@@ -33,24 +33,6 @@ export declare function loadDeckModules(): Promise<{
     MapboxOverlay: typeof import("@deck.gl/mapbox").MapboxOverlay;
     GeoJsonLayer: typeof import("@deck.gl/layers").GeoJsonLayer;
 }>;
-export interface DeckOverlayOptions {
-    layerId: string;
-    data: GeoJSON.FeatureCollection;
-    /** Called with properties and the full GeoJSON Feature (for selection highlight). */
-    onClick?: (properties: Record<string, any>, feature: GeoJSON.Feature) => void;
-    /** Layer-level onHover — use hoverCursor(map) to toggle pointer on MapLibre canvas. */
-    onHover?: (info: {
-        picked?: boolean;
-    }) => void;
-}
-/**
- * Create a MapboxOverlay with a single GeoJsonLayer.
- * Colors are assigned per-feature based on geometry type.
- */
-export declare function createDeckOverlay(modules: {
-    MapboxOverlay: any;
-    GeoJsonLayer: any;
-}, options: DeckOverlayOptions): any;
 /** Lazy-load GeoArrow deck.gl layers + MapboxOverlay + GeoJsonLayer (for selection). */
 export declare function loadGeoArrowModules(): Promise<{
     GeoArrowArcLayer: typeof import("@geoarrow/deck.gl-layers").GeoArrowArcLayer;

package/dist/utils/deck.js

@@ -46,42 +46,6 @@ export async function loadDeckModules() {
     ]);
     return { MapboxOverlay, GeoJsonLayer };
 }
-/**
- * Create a MapboxOverlay with a single GeoJsonLayer.
- * Colors are assigned per-feature based on geometry type.
- */
-export function createDeckOverlay(modules, options) {
-    const { MapboxOverlay, GeoJsonLayer } = modules;
-    const { layerId, data, onClick, onHover } = options;
-    return new MapboxOverlay({
-        interleaved: false,
-        layers: [
-            new GeoJsonLayer({
-                id: layerId,
-                data,
-                pickable: true,
-                stroked: true,
-                filled: true,
-                pointType: 'circle',
-                getFillColor: geojsonFillColor,
-                getLineColor: geojsonLineColor,
-                getPointRadius: 6,
-                getLineWidth: 2.5,
-                lineWidthMinPixels: 1.5,
-                pointRadiusMinPixels: 4,
-                pointRadiusMaxPixels: 12,
-                autoHighlight: true,
-                highlightColor: [255, 255, 255, 100],
-                onHover,
-                onClick: (info) => {
-                    if (info.object?.properties && onClick) {
-                        onClick({ ...info.object.properties }, info.object);
-                    }
-                }
-            })
-        ]
-    });
-}
 // ─── GeoArrow overlay (GeoParquetMapViewer) ──────────────────────────
 /** Lazy-load GeoArrow deck.gl layers + MapboxOverlay + GeoJsonLayer (for selection). */
 export async function loadGeoArrowModules() {

package/dist/utils/export.d.ts

@@ -1,2 +1,22 @@
-export declare function exportToCsv(columns: string[], rows: Record<string, any>[], filename: string): void;
-export declare function exportToJson(columns: string[], rows: Record<string, any>[], filename: string): void;
+/**
+ * Escape a CSV field value per RFC 4180.
+ */
+export declare function escapeCsvField(value: string): string;
+/**
+ * Serialize column/row data to a CSV string.
+ * Pure function — no browser APIs, works in Node.js.
+ */
+export 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.
+ */
+export declare function serializeToJson(columns: string[], rows: Record<string, unknown>[]): string;
+/**
+ * Export data as CSV file (triggers browser download).
+ */
+export declare function exportToCsv(columns: string[], rows: Record<string, unknown>[], filename: string): void;
+/**
+ * Export data as JSON file (triggers browser download).
+ */
+export declare function exportToJson(columns: string[], rows: Record<string, unknown>[], filename: string): void;

package/dist/utils/export.js

@@ -1,3 +1,4 @@
+import { jsonReplacerBigInt } from './format.js';
 function triggerDownload(content, filename, mimeType) {
     const blob = new Blob([content], { type: mimeType });
     const url = URL.createObjectURL(blob);
@@ -9,30 +10,43 @@ function triggerDownload(content, filename, mimeType) {
     document.body.removeChild(a);
     URL.revokeObjectURL(url);
 }
-function formatValue(value) {
+/** Format a cell value for export (empty string for null/undefined). */
+function formatCellValue(value) {
     if (value === null || value === undefined)
         return '';
     if (value instanceof Date)
         return value.toISOString();
+    if (typeof value === 'bigint')
+        return value.toString();
     if (typeof value === 'object')
-        return JSON.stringify(value);
+        return JSON.stringify(value, jsonReplacerBigInt);
     return String(value);
 }
-function escapeCsvField(value) {
+/**
+ * Escape a CSV field value per RFC 4180.
+ */
+export function escapeCsvField(value) {
     if (value.includes(',') || value.includes('"') || value.includes('\n') || value.includes('\r')) {
         return `"${value.replace(/"/g, '""')}"`;
     }
     return value;
 }
-export function exportToCsv(columns, rows, filename) {
+/**
+ * Serialize column/row data to a CSV string.
+ * Pure function — no browser APIs, works in Node.js.
+ */
+export function serializeToCsv(columns, rows) {
     const header = columns.map(escapeCsvField).join(',');
     const body = rows
-        .map((row) => columns.map((col) => escapeCsvField(formatValue(row[col]))).join(','))
+        .map((row) => columns.map((col) => escapeCsvField(formatCellValue(row[col]))).join(','))
         .join('\n');
-    const csv = `${header}\n${body}`;
-    triggerDownload(csv, filename.endsWith('.csv') ? filename : `${filename}.csv`, 'text/csv;charset=utf-8;');
+    return `${header}\n${body}`;
 }
-export function exportToJson(columns, rows, filename) {
+/**
+ * Serialize column/row data to a formatted JSON string.
+ * Pure function — no browser APIs, works in Node.js.
+ */
+export function serializeToJson(columns, rows) {
     const data = rows.map((row) => {
         const obj = {};
         for (const col of columns) {
@@ -46,6 +60,17 @@ export function exportToJson(columns, rows, filename) {
         }
         return obj;
     });
-    const json = JSON.stringify(data, null, 2);
-    triggerDownload(json, filename.endsWith('.json') ? filename : `${filename}.json`, 'application/json');
+    return JSON.stringify(data, jsonReplacerBigInt, 2);
+}
+/**
+ * Export data as CSV file (triggers browser download).
+ */
+export function exportToCsv(columns, rows, filename) {
+    triggerDownload(serializeToCsv(columns, rows), filename.endsWith('.csv') ? filename : `${filename}.csv`, 'text/csv;charset=utf-8;');
+}
+/**
+ * Export data as JSON file (triggers browser download).
+ */
+export function exportToJson(columns, rows, filename) {
+    triggerDownload(serializeToJson(columns, rows), filename.endsWith('.json') ? filename : `${filename}.json`, 'application/json');
 }

package/dist/utils/file-sort.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Pure file entry sorting — framework-agnostic, works in Node.js.
+ */
+import type { FileEntry } from '../types.js';
+export type SortField = 'name' | 'size' | 'modified' | 'extension';
+export type SortDirection = 'asc' | 'desc';
+export 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).
+ */
+export declare function sortFileEntries(entries: FileEntry[], config: SortConfig): FileEntry[];
+/**
+ * Toggle sort config: same field flips direction, new field starts ascending.
+ */
+export declare function toggleSortField(current: SortConfig, field: SortField): SortConfig;

package/dist/utils/file-sort.js

@@ -0,0 +1,41 @@
+/**
+ * Pure file entry sorting — framework-agnostic, works in Node.js.
+ */
+/**
+ * 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).
+ */
+export function sortFileEntries(entries, config) {
+    const sorted = [...entries];
+    const dir = config.direction === 'asc' ? 1 : -1;
+    sorted.sort((a, b) => {
+        // Directories always come first
+        if (a.is_dir && !b.is_dir)
+            return -1;
+        if (!a.is_dir && b.is_dir)
+            return 1;
+        switch (config.field) {
+            case 'name':
+                return dir * a.name.localeCompare(b.name, undefined, { sensitivity: 'base' });
+            case 'size':
+                return dir * (a.size - b.size);
+            case 'modified':
+                return dir * (a.modified - b.modified);
+            case 'extension':
+                return dir * a.extension.localeCompare(b.extension, undefined, { sensitivity: 'base' });
+            default:
+                return 0;
+        }
+    });
+    return sorted;
+}
+/**
+ * Toggle sort config: same field flips direction, new field starts ascending.
+ */
+export function toggleSortField(current, field) {
+    if (current.field === field) {
+        return { field, direction: current.direction === 'asc' ? 'desc' : 'asc' };
+    }
+    return { field, direction: 'asc' };
+}

package/dist/utils/geometry-type.d.ts

@@ -0,0 +1,52 @@
+/**
+ * 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.
+ */
+export 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.
+ */
+export declare function parseGeometryTypeCrs(typeStr: string | null | undefined): GeometryTypeInfo;
+/** True for EPSG:4326, EPSG:4979, OGC:CRS84 and equivalent strings. */
+export 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.
+ */
+export 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(...)`.
+ */
+export declare function wrapWkbWithCrs(wkbExpr: string, sourceCrs: string | null | undefined): string;

package/dist/utils/geometry-type.js

@@ -0,0 +1,76 @@
+/**
+ * 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.
+ */
+import { WGS84_CODES } from '../constants.js';
+const GEOMETRY_PREFIX = /^GEOMETRY(\s*\(\s*'?([^')]+)'?\s*\))?/i;
+/**
+ * Parse a DuckDB type string and report whether it is a GEOMETRY type, and
+ * whether a CRS parameter is attached.
+ */
+export function parseGeometryTypeCrs(typeStr) {
+    if (!typeStr)
+        return { isGeometry: false, hasCrs: false, rawCrs: null, nonWgs84Crs: null };
+    const match = typeStr.match(GEOMETRY_PREFIX);
+    if (!match)
+        return { isGeometry: false, hasCrs: false, rawCrs: null, nonWgs84Crs: null };
+    const rawCrs = match[2]?.trim() ?? null;
+    if (!rawCrs)
+        return { isGeometry: true, hasCrs: false, rawCrs: null, nonWgs84Crs: null };
+    return {
+        isGeometry: true,
+        hasCrs: true,
+        rawCrs,
+        nonWgs84Crs: isWgs84Crs(rawCrs) ? null : rawCrs
+    };
+}
+/** True for EPSG:4326, EPSG:4979, OGC:CRS84 and equivalent strings. */
+export function isWgs84Crs(crs) {
+    if (!crs)
+        return true;
+    const trimmed = crs.trim();
+    if (trimmed === 'OGC:CRS84' || trimmed === 'OGC:CRS83')
+        return true;
+    const epsgMatch = trimmed.match(/^EPSG:(\d+)$/i);
+    if (epsgMatch && WGS84_CODES.has(Number(epsgMatch[1])))
+        return true;
+    return false;
+}
+/**
+ * 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.
+ */
+export function buildTransformExpr(innerExpr, sourceType, sourceCrs, targetCrs) {
+    const info = parseGeometryTypeCrs(sourceType);
+    if (info.hasCrs) {
+        return `ST_Transform(${innerExpr}, '${targetCrs}')`;
+    }
+    return `ST_Transform(${innerExpr}, '${sourceCrs}', '${targetCrs}')`;
+}
+/**
+ * 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(...)`.
+ */
+export function wrapWkbWithCrs(wkbExpr, sourceCrs) {
+    if (!sourceCrs)
+        return `ST_GeomFromWKB(${wkbExpr})`;
+    return `ST_SetCRS(ST_GeomFromWKB(${wkbExpr}), '${sourceCrs}')`;
+}

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

@@ -0,0 +1,16 @@
+/**
+ * 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.
+ */
+export 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).
+ */
+export declare function persistToStorage(key: string, value: unknown): void;

package/dist/utils/local-storage.js

@@ -0,0 +1,37 @@
+/**
+ * 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.
+ */
+export function loadFromStorage(key, defaultValue) {
+    if (typeof window === 'undefined')
+        return defaultValue;
+    try {
+        const raw = localStorage.getItem(key);
+        if (raw)
+            return JSON.parse(raw);
+    }
+    catch {
+        // ignore parse errors
+    }
+    return defaultValue;
+}
+/**
+ * Persist a JSON-serializable value to localStorage.
+ * Silently no-ops on SSR or storage errors (quota, private browsing).
+ */
+export function persistToStorage(key, value) {
+    if (typeof window === 'undefined')
+        return;
+    try {
+        localStorage.setItem(key, JSON.stringify(value));
+    }
+    catch {
+        // ignore storage errors
+    }
+}

package/dist/utils/markdown-sql.d.ts

@@ -17,7 +17,7 @@ export interface ParsedMarkdownDocument {
  * SELECT * FROM table
  * ```
  */
-export declare function parseMarkdownDocument(markdown: string): ParsedMarkdownDocument;
+export declare function parseMarkdownDocument(markdown: string): Promise<ParsedMarkdownDocument>;
 /**
  * Interpolate template variables in markdown text.
  * Supports {queryName.rows[0].columnName} syntax.

package/dist/utils/markdown-sql.js

@@ -1,4 +1,3 @@
-import YAML from 'yaml';
 /**
  * Parse a markdown document with YAML frontmatter and SQL code blocks.
  *
@@ -7,17 +6,17 @@ import YAML from 'yaml';
  * SELECT * FROM table
  * ```
  */
-export function parseMarkdownDocument(markdown) {
+export async function parseMarkdownDocument(markdown) {
     let frontmatter = {};
     let content = markdown;
-    // Extract YAML frontmatter
     const fmMatch = markdown.match(/^---\n([\s\S]*?)\n---\n/);
     if (fmMatch) {
         try {
+            const { default: YAML } = await import('yaml');
             frontmatter = YAML.parse(fmMatch[1]) || {};
         }
         catch {
-            // Invalid YAML — ignore
+            // Invalid YAML or yaml peer dep not installed, ignore frontmatter
         }
         content = markdown.slice(fmMatch[0].length);
     }

package/dist/utils/pmtiles-tile.d.ts

@@ -30,8 +30,6 @@ export interface DecodedFeature {
  * Returns null if the tile does not exist or for raster archives.
  */
 export declare function decodeMvtTile(pmtiles: PMTiles, z: number, x: number, y: number): Promise<DecodedTile | null>;
-/** Convert tile bytes to a Blob URL for raster tile preview. */
-export declare function tileToImageUrl(pmtiles: PMTiles, z: number, x: number, y: number, mimeType: string): Promise<string | null>;
 /** MIME type for a PMTiles tile format string. */
 export declare function tileMimeType(format: string): string;
 /** Compute the hue for layer index i (same palette as buildPmtilesLayers). */

package/dist/utils/pmtiles-tile.js

@@ -41,14 +41,6 @@ export async function decodeMvtTile(pmtiles, z, x, y) {
     }
     return { z, x, y, layers, rawSize };
 }
-/** Convert tile bytes to a Blob URL for raster tile preview. */
-export async function tileToImageUrl(pmtiles, z, x, y, mimeType) {
-    const resp = await pmtiles.getZxy(z, x, y);
-    if (!resp)
-        return null;
-    const blob = new Blob([resp.data], { type: mimeType });
-    return URL.createObjectURL(blob);
-}
 /** MIME type for a PMTiles tile format string. */
 export function tileMimeType(format) {
     const map = {

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

@@ -34,6 +34,12 @@ export declare function getUrlView(): string;
  * Read the prefix (file/folder path) from the ?url= param.
  */
 export declare function getUrlPrefix(): string;
+/**
+ * True when a `?url=` param is present. Single source of truth, used by
+ * the tab-sync effect and Sidebar auto-detection to decide whether an
+ * auto-migration is in progress (see `+page.svelte` tab-sync effect).
+ */
+export declare function hasUrlParam(): boolean;
 /**
  * Clear all URL state params.
  */

package/dist/utils/url-state.js

@@ -28,43 +28,43 @@ export function buildUrlParam(conn, prefix) {
     return `${base}/${prefix.replace(/^\//, '')}`;
 }
 /**
- * Set the ?url= param to a raw URL string (for direct URL tabs).
+ * Apply a URL mutation, skipping `replaceState` if nothing changed.
+ * Every public mutator below funnels through this to avoid `replaceState`
+ * thrash when the tab-sync effect re-fires on unrelated reactive changes.
  */
-export function setRawUrlParam(rawUrl) {
+function writeLocation(mutate) {
     try {
         const url = new URL(window.location.href);
-        url.searchParams.set('url', rawUrl);
-        replaceState(url.pathname + url.search + url.hash, {});
+        const before = url.pathname + url.search + url.hash;
+        mutate(url);
+        const after = url.pathname + url.search + url.hash;
+        if (before === after)
+            return;
+        replaceState(after, {});
     }
     catch {
         /* ignore */
     }
 }
+/**
+ * Set the ?url= param to a raw URL string (for direct URL tabs).
+ */
+export function setRawUrlParam(rawUrl) {
+    writeLocation((url) => url.searchParams.set('url', rawUrl));
+}
 /**
  * Sync the ?url= param in the browser URL.
  */
 export function syncUrlParam(conn, prefix) {
-    try {
-        const url = new URL(window.location.href);
-        url.searchParams.set('url', buildUrlParam(conn, prefix));
-        replaceState(url.pathname + url.search + url.hash, {});
-    }
-    catch {
-        /* ignore */
-    }
+    writeLocation((url) => url.searchParams.set('url', buildUrlParam(conn, prefix)));
 }
 /**
  * Update the #hash in the URL to reflect the current view mode.
  */
 export function updateUrlView(view) {
-    try {
-        const url = new URL(window.location.href);
+    writeLocation((url) => {
         url.hash = view || '';
-        replaceState(url.pathname + url.search + url.hash, {});
-    }
-    catch {
-        /* ignore */
-    }
+    });
 }
 /**
  * Read the current #hash view mode from the URL.
@@ -93,16 +93,24 @@ export function getUrlPrefix() {
     }
 }
 /**
- * Clear all URL state params.
+ * True when a `?url=` param is present. Single source of truth, used by
+ * the tab-sync effect and Sidebar auto-detection to decide whether an
+ * auto-migration is in progress (see `+page.svelte` tab-sync effect).
  */
-export function clearUrlState() {
+export function hasUrlParam() {
     try {
-        const url = new URL(window.location.href);
-        url.searchParams.delete('url');
-        url.hash = '';
-        replaceState(url.pathname + url.search, {});
+        return new URL(window.location.href).searchParams.has('url');
     }
     catch {
-        /* ignore */
+        return false;
     }
 }
+/**
+ * Clear all URL state params.
+ */
+export function clearUrlState() {
+    writeLocation((url) => {
+        url.searchParams.delete('url');
+        url.hash = '';
+    });
+}

package/dist/utils/url.d.ts

@@ -4,38 +4,26 @@ import type { Tab } from '../types.js';
  * Works for any viewer that needs an HTTP-accessible URL (COG, PMTiles, Zarr, etc.)
  */
 export declare function buildHttpsUrl(tab: Tab): string;
-/**
- * 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).
- */
-export declare function getNativeScheme(provider: string): string;
 /**
  * Build a provider-native protocol URL (s3://bucket/path, sj://bucket/path, etc.).
  */
 export declare function buildStorageUrl(tab: Tab): string;
 /**
- * Build the URL that DuckDB should use for queries.
- * - Azure: always HTTPS URL with SAS token appended
- * - Anonymous with custom endpoint (Storj, R2, etc.): HTTPS URL — no S3 config needed,
- *   avoids endpoint/auth complexity, works directly via httpfs
- * - AWS S3 (no endpoint): s3:// — DuckDB routes via configured region
- * - Authenticated with endpoint: s3:// — needs S3 endpoint config for SigV4 signing
+ * Build the URL DuckDB should query. Derived from the connection's access mode:
+ *
+ * | Access mode     | DuckDB URL                        | Why                                       |
+ * |-----------------|-----------------------------------|-------------------------------------------|
+ * | `sas-https`     | HTTPS with SAS token              | No DuckDB Azure support; SAS in URL works |
+ * | `public-https`  | HTTPS (no auth)                   | httpfs fetches directly, no signing needed|
+ * | `signed-s3`     | `s3://bucket/key`                 | DuckDB signs with configured S3 settings  |
+ *
+ * Path is percent-decoded so DuckDB's httpfs doesn't double-encode
+ * (e.g. Arabic filenames `%D9%85` → `%25D9%2585`).
  */
 export declare function buildDuckDbUrl(tab: Tab): string;
 /**
- * Check if a tab's file can be loaded directly via HTTPS URL (streaming).
- * True for URL-sourced tabs, anonymous buckets, and Azure (SAS token in URL).
- * False for authenticated S3 (needs signed URLs or blob download via adapter).
+ * True when any HTTP client (fetch/img/video/deck.gl/COG/Zarr/PMTiles) can
+ * load the tab's file directly via its HTTPS URL. False when SigV4 signing
+ * is required and the viewer must go through the storage adapter instead.
  */
 export declare function canStreamDirectly(tab: Tab): boolean;
-/**
- * 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, e.g. "us-west-2.opendata.source.coop")
- * - `gs://bucket/key` → `https://storage.googleapis.com/{bucket}/{key}`
- */
-export declare function resolveCloudUrl(url: string): string;