@walkthru-earth/objex 1.3.1 → 1.5.0

package/dist/query/wasm.js

@@ -1,7 +1,7 @@
-import { DEFAULT_TARGET_CRS, DUCKDB_INIT_TIMEOUT_MS, WGS84_CODES } from '../constants.js';
+import { buildTransformExpr, wrapWkbWithCrs } from '@walkthru-earth/objex-utils';
+import { DEFAULT_TARGET_CRS, DUCKDB_INIT_TIMEOUT_MS, STORAGE_KEYS, WGS84_CODES } from '../constants.js';
 import { getAccessMode, resolveProviderEndpoint } from '../storage/providers.js';
 import { credentialStore } from '../stores/credentials.svelte.js';
-import { buildTransformExpr, wrapWkbWithCrs } from '../utils/geometry-type.js';
 import { QueryCancelledError } from './engine';
 import { isHttpsSourceRef } from './source.js';
 const DUCKDB_VERSION = __DUCKDB_WASM_VERSION__;
@@ -23,6 +23,22 @@ function elapsed(start) {
     return `${(performance.now() - start).toFixed(1)}ms`;
 }
 let dbPromise = null;
+const opfsState = { active: false, reasons: [] };
+let initSummaryLogged = false;
+function logInitSummary() {
+    if (initSummaryLogged)
+        return;
+    initSummaryLogged = true;
+    const coi = typeof globalThis !== 'undefined' && globalThis.crossOriginIsolated === true;
+    if (opfsState.active) {
+        log(`▶ DB mode: OPFS-backed (spill enabled), crossOriginIsolated=${coi}`);
+    }
+    else {
+        logWarn(`▶ DB mode: IN-MEMORY (no spill — OOMs at WASM heap ceiling), crossOriginIsolated=${coi}`);
+        for (const r of opfsState.reasons)
+            logWarn(`  ↳ ${r}`);
+    }
+}
 function withTimeout(promise, ms, label) {
     return new Promise((resolve, reject) => {
         const timer = setTimeout(() => reject(new Error(`${label} timed out after ${ms}ms`)), ms);
@@ -37,7 +53,7 @@ function withTimeout(promise, ms, label) {
 }
 async function getDB() {
     if (dbPromise) {
-        log('getDB → cached');
+        logInitSummary();
         return dbPromise;
     }
     dbPromise = (async () => {
@@ -64,6 +80,139 @@ async function getDB() {
         const db = new duckdb.AsyncDuckDB(logger, worker);
         await withTimeout(db.instantiate(bundle.mainModule, bundle.pthreadWorker), INIT_TIMEOUT_MS, 'DuckDB WASM instantiation');
         log(`getDB → instantiated in ${elapsed(t0)}`);
+        // Open an OPFS-backed database so DuckDB can spill blocks to disk under
+        // memory pressure. In-memory mode caps at the WASM heap (~1.3-3.1 GiB
+        // depending on browser), with no temp_directory backing — large
+        // aggregations / sorts then OOM. OPFS gives DuckDB a real filesystem
+        // for paged storage, lifting the budget to the user's disk quota.
+        //
+        // Why register a handle instead of just `path: 'opfs://...'`: on the
+        // pinned 1.33.1-dev53.0 build, the URL-scheme path opens silently as a
+        // virtual MEMFS file, so the DB stays in-memory. Registering the handle
+        // via DuckDBDataProtocol.BROWSER_FSACCESS (OPFS) and opening it by the
+        // registered name forces DuckDB onto OPFS and lets it spill blocks.
+        // Falls back to in-memory if OPFS is unavailable (private mode, older
+        // browsers, cross-origin isolation issues).
+        const hasOpfs = typeof navigator !== 'undefined' &&
+            typeof navigator.storage !== 'undefined' &&
+            typeof navigator.storage.getDirectory === 'function';
+        const isCOI = typeof globalThis !== 'undefined' && globalThis.crossOriginIsolated === true;
+        if (!isCOI) {
+            opfsState.reasons.push('crossOriginIsolated=false — page is missing COOP/COEP headers. OPFS sync handles will throw inside the worker. Restart the dev server so vite.config.ts headers take effect, then hard-reload.');
+        }
+        let opfsActive = false;
+        if (hasOpfs) {
+            // Pin the OPFS filename to the duckdb-wasm version. Bumping
+            // duckdb-wasm can change the on-disk storage version, and reusing a
+            // stale file then throws "not a valid DuckDB database file" inside
+            // the worker. Worse, on Chrome the failed open keeps the
+            // FileSystemSyncAccessHandle alive, so even a same-tab retry
+            // (`removeEntry` + recreate) reads back the old state and trips
+            // "Access Handles cannot be created if there is another open Access
+            // Handle" on every fallback path. A version-pinned filename sidesteps
+            // the whole recovery problem: a new wasm build always gets a fresh
+            // file, and the old file just becomes an orphan we can reap below.
+            // Sanitize the version into a filename-safe slug.
+            const dbVersionSlug = DUCKDB_VERSION.replace(/[^a-zA-Z0-9._-]/g, '-');
+            const dbName = `objex-duckdb-v${dbVersionSlug}.db`;
+            const accessMode = duckdb.DuckDBAccessMode?.READ_WRITE ?? 1;
+            const protocol = duckdb.DuckDBDataProtocol?.BROWSER_FSACCESS;
+            // Firefox exposes `navigator.storage.getDirectory` in Private Browsing
+            // but throws `SecurityError: Security error when calling GetDirectory`
+            // when invoked. The `hasOpfs` check above only verifies the function
+            // exists, so we must guard the actual call. Other "exists-but-throws"
+            // environments (older Safari WKWebView, restricted enterprise policies,
+            // non-secure contexts that still expose the API) hit the same path.
+            let root = null;
+            try {
+                root = await navigator.storage.getDirectory();
+            }
+            catch (err) {
+                const msg = err?.message ?? String(err);
+                logWarn('getDB → navigator.storage.getDirectory() threw:', msg);
+                opfsState.reasons.push(`navigator.storage.getDirectory() threw: ${msg} — likely Firefox Private Browsing, non-secure context, or storage permission denied`);
+            }
+            if (root) {
+                // Reap orphan DBs from prior wasm versions. They are unreachable
+                // once the version slug bumps, so leaving them around silently
+                // burns OPFS quota. removeEntry throws NoModificationAllowedError
+                // while a sync access handle is still open against the file —
+                // that only matters for the file we're actively using, and we
+                // skip that one.
+                try {
+                    const orphans = [];
+                    for await (const [name, handle] of root.entries()) {
+                        if (handle.kind === 'file' &&
+                            /^objex-duckdb(-.*)?\.db$/.test(name) &&
+                            name !== dbName) {
+                            orphans.push(name);
+                        }
+                    }
+                    for (const name of orphans) {
+                        try {
+                            await root.removeEntry(name);
+                            log(`getDB → reaped orphan OPFS db "${name}"`);
+                        }
+                        catch (rmErr) {
+                            logWarn(`getDB → could not reap orphan OPFS db "${name}":`, rmErr?.message ?? rmErr);
+                        }
+                    }
+                }
+                catch (enumErr) {
+                    logWarn('getDB → could not enumerate OPFS root for orphan cleanup:', enumErr?.message ?? enumErr);
+                }
+                // Path A — registered FileSystemFileHandle. This is the fully wired
+                // OPFS path on duckdb-wasm 1.29+. It needs the real handle (passing
+                // null silently registers a non-OPFS file and the open() reverts to
+                // MEMFS, which is why earlier attempts kept reporting "in-memory
+                // mode" in OOM errors).
+                if (protocol !== undefined) {
+                    const tOpenA = performance.now();
+                    try {
+                        const fileHandle = await root.getFileHandle(dbName, { create: true });
+                        await db.registerFileHandle(dbName, fileHandle, protocol, true);
+                        await withTimeout(db.open({ path: dbName, accessMode }), INIT_TIMEOUT_MS, 'DuckDB OPFS open (registered handle)');
+                        opfsActive = true;
+                        log(`getDB → OPFS via registered handle in ${elapsed(tOpenA)}`);
+                    }
+                    catch (err) {
+                        const msg = err?.message ?? String(err);
+                        logWarn('getDB → OPFS via registered handle failed:', msg);
+                        opfsState.reasons.push(`registered-handle path: ${msg}`);
+                    }
+                }
+                else {
+                    logWarn('getDB → DuckDBDataProtocol.BROWSER_FSACCESS missing in this build');
+                    opfsState.reasons.push('DuckDBDataProtocol.BROWSER_FSACCESS missing in this WASM build');
+                }
+                // Path B — URL-scheme fallback. Some duckdb-wasm builds wire OPFS
+                // internally on `opfs://` paths without needing manual registration.
+                if (!opfsActive) {
+                    const tOpenB = performance.now();
+                    try {
+                        await withTimeout(db.open({ path: `opfs://${dbName}`, accessMode }), INIT_TIMEOUT_MS, 'DuckDB OPFS open (url scheme)');
+                        opfsActive = true;
+                        log(`getDB → OPFS via opfs:// scheme in ${elapsed(tOpenB)}`);
+                    }
+                    catch (err) {
+                        const msg = err?.message ?? String(err);
+                        logWarn('getDB → OPFS via opfs:// scheme failed:', msg);
+                        opfsState.reasons.push(`opfs:// scheme path: ${msg}`);
+                    }
+                }
+                if (!opfsActive) {
+                    logWarn('getDB → all OPFS paths failed, falling back to in-memory');
+                }
+            }
+            else {
+                logWarn('getDB → OPFS root unavailable, falling back to in-memory');
+            }
+        }
+        else {
+            log('getDB → OPFS unavailable (no navigator.storage), using in-memory DB');
+            opfsState.reasons.push('navigator.storage.getDirectory is unavailable (private mode, older browser, or non-secure context)');
+        }
+        opfsState.active = opfsActive;
         // Load httpfs for remote file access and spatial for ST_ReadSHP
         const conn = await db.connect();
         try {
@@ -92,12 +241,84 @@ async function getDB() {
             catch {
                 logWarn('force_download_threshold not available');
             }
+            // Memory tuning is only applied when OPFS spill is actually wired.
+            // Without OPFS, capping memory_limit below the WASM heap ceiling
+            // just makes queries OOM sooner with no upside (DuckDB still cannot
+            // spill, and TableViewer's existing workloads need the full ~3 GiB
+            // heap). preserve_insertion_order = false is the one tuning that
+            // helps both modes — it skips buffering full result sets to re-sort
+            // on output, a real OOM source on big scans.
+            // Mobile WebKit / Android Chrome run in a much smaller WASM heap
+            // (~1.8 GiB on iOS Safari, ~2 GiB on Android) than desktop
+            // (~3.1 GiB), AND mobile Safari < 17.6 has no `credentialless`
+            // COEP, so OPFS engages on far fewer devices. Detect with the UA
+            // hint + screen-size heuristic so we can ratchet down the limits
+            // on mobile-in-memory before the first OOM and so the user sees
+            // a usable session instead of a hard failure on the first
+            // pan/scan. Heuristic, not load-bearing for correctness.
+            const isMobileLike = typeof navigator !== 'undefined' &&
+                (/Mobi|Android|iPhone|iPad|iPod/i.test(navigator.userAgent) ||
+                    (typeof window !== 'undefined' &&
+                        Math.min(window.innerWidth, window.innerHeight) <= 820));
+            try {
+                const sets = [`SET preserve_insertion_order = false`];
+                const cores = navigator.hardwareConcurrency || 4;
+                if (opfsActive) {
+                    // OPFS spill works: room to use multiple threads + a real
+                    // memory_limit. On mobile the OPFS quota is also smaller
+                    // (typically a few hundred MB by default), so still
+                    // half-cap threads + memory_limit to reduce concurrent
+                    // thread-local buffers.
+                    const threads = Math.max(1, Math.min(isMobileLike ? 2 : 4, Math.floor(cores / 2)));
+                    sets.push(`SET memory_limit = '${isMobileLike ? '900MB' : '2GB'}'`);
+                    sets.push(`SET threads = ${threads}`);
+                    sets.push(`SET temp_directory = '.tmp'`);
+                }
+                else if (isMobileLike) {
+                    // Mobile + no OPFS spill is the worst case: the heap caps
+                    // at ~1.8 GiB on iOS Safari, queries cannot offload, and
+                    // the previous "leave memory_limit at defaults" path
+                    // reproduces the OOM the user is seeing. Cap memory_limit
+                    // well under the heap ceiling so DuckDB's planner picks
+                    // streaming / out-of-core operator variants and surfaces
+                    // `Out of Memory` from inside the planner (recoverable,
+                    // the worker keeps running) instead of from the WASM heap
+                    // allocator (kills the worker and forces a tab reload).
+                    // Threads are pinned at 1 for the same reason — every
+                    // extra thread doubles the per-pipeline scratch buffers.
+                    sets.push(`SET memory_limit = '900MB'`);
+                    sets.push(`SET threads = 1`);
+                    sets.push(`SET temp_directory = '.tmp'`);
+                }
+                else {
+                    // Desktop + no OPFS spill: leave memory_limit at defaults
+                    // so the full WASM heap (~3.1 GiB) is available for big
+                    // scans. Cap threads conservatively because each thread
+                    // keeps its own hash-aggregate / sort buffer alive.
+                    const threads = Math.max(1, Math.min(2, Math.floor(cores / 2)));
+                    sets.push(`SET threads = ${threads}`);
+                    sets.push(`SET temp_directory = '.tmp'`);
+                }
+                await conn.query(`${sets.join('; ')};`);
+                log(opfsActive
+                    ? `getDB → OPFS, memory_limit=${isMobileLike ? '900MB' : '2GB'}, mobile=${isMobileLike}`
+                    : isMobileLike
+                        ? `getDB → mobile in-memory, memory_limit=900MB, threads=1 (no OPFS spill)`
+                        : `getDB → desktop in-memory, threads capped, memory_limit at defaults`);
+                if (isMobileLike && !opfsActive) {
+                    opfsState.reasons.push('mobile session with no OPFS spill: memory_limit clamped to 900MB to surface OOMs from the planner instead of the WASM heap allocator. Some large-catalog stac-geoparquet queries may still fail; reduce mosaicItemLimit or open on desktop.');
+                }
+            }
+            catch (err) {
+                logWarn('memory tuning not available:', err?.message ?? err);
+            }
             log(`getDB → extensions loaded in ${elapsed(tExt)}`);
         }
         finally {
             await conn.close();
         }
         log(`getDB → ready (total ${elapsed(t0)})`);
+        logInitSummary();
         return db;
     })();
     // If init fails, clear the promise so it can be retried
@@ -358,67 +579,10 @@ function isBinaryType(typeStr) {
 }
 export class WasmQueryEngine {
     async query(connId, sql) {
-        const t0 = performance.now();
-        const sqlPreview = sql.length > 120 ? `${sql.slice(0, 120)}…` : sql;
-        log(`query → ${sqlPreview}`);
-        const db = await getDB();
-        const conn = await db.connect();
-        const tConn = performance.now();
-        log(`query → connected in ${elapsed(t0)}`);
-        try {
-            if (connId) {
-                await this.configureStorage(conn, connId, sql);
-                log(`query → storage configured in ${elapsed(tConn)}`);
-            }
-            const tQuery = performance.now();
-            const result = await conn.query(sql);
-            log(`query → executed in ${elapsed(tQuery)}, rows: ${result.numRows}`);
-            // DuckDB WASM returns an Arrow Table (bundled apache-arrow@17).
-            // Our project uses apache-arrow@21 — cross-version tableToIPC/tableFromIPC
-            // loses data rows. Extract rows directly from DuckDB's own Arrow Table.
-            const numRows = result.numRows;
-            const cols = result.schema.fields.map((f) => f.name);
-            const types = result.schema.fields.map((f) => String(f.type));
-            if (numRows === 0) {
-                log(`query → done (empty) in ${elapsed(t0)}`);
-                return {
-                    columns: cols,
-                    types,
-                    rowCount: 0,
-                    rows: []
-                };
-            }
-            // Arrow emits DECIMAL columns as multi-word BigInt / Uint32Array buffers.
-            // `String(rawDecimal)` yields the unscaled integer (or "0,0,0,0"),
-            // so rewrite each decimal cell through formatDecimal with the column scale.
-            const decimalCols = [];
-            for (let i = 0; i < cols.length; i++) {
-                const s = decimalScale(types[i]);
-                if (s >= 0)
-                    decimalCols.push({ name: cols[i], scale: s });
-            }
-            // Extract rows directly — avoids Arrow version mismatch
-            const rows = result.toArray().map((row) => {
-                const obj = typeof row.toJSON === 'function' ? row.toJSON() : {};
-                if (typeof row.toJSON !== 'function') {
-                    for (const col of cols)
-                        obj[col] = row[col];
-                }
-                for (const { name, scale } of decimalCols) {
-                    obj[name] = formatDecimal(obj[name], scale);
-                }
-                return obj;
-            });
-            log(`query → done in ${elapsed(t0)}, ${numRows} rows, ${cols.length} cols`);
-            return { columns: cols, types, rowCount: numRows, rows };
-        }
-        catch (err) {
-            logWarn(`query → failed after ${elapsed(t0)}:`, err?.message ?? err);
-            throw err;
-        }
-        finally {
-            await conn.close();
-        }
+        // Delegate to the send()-based path so a data query never blocks the
+        // single DuckDB worker (conn.query() is blocking). Same return shape.
+        const { result } = this.queryCancellable(connId, sql);
+        return result;
     }
     async queryForMap(connId, sql, geomCol, geomColType, sourceCrs) {
         const t0 = performance.now();
@@ -634,7 +798,7 @@ export class WasmQueryEngine {
                 log('configureStorage → presigned HTTPS source, skipping S3 config');
                 return;
             }
-            const stored = localStorage.getItem('obstore-explore-connections');
+            const stored = localStorage.getItem(STORAGE_KEYS.CONNECTIONS);
             if (!stored) {
                 log('configureStorage → no connections in localStorage');
                 return;
@@ -877,6 +1041,87 @@ export class WasmQueryEngine {
         };
         return { result, cancel };
     }
+    /**
+     * Streaming variant of `queryCancellable`. Yields one chunk per Arrow
+     * RecordBatch so peak memory tracks one batch instead of the full result.
+     * Used by `stac-source-parquet` to ingest large catalogs progressively
+     * without OOMing the WASM heap. Cancellation routes through `conn.cancelSent`
+     * and `signal.aborted`; the connection is always closed in `finally`.
+     */
+    async *queryStream(connId, sql, signal) {
+        const t0 = performance.now();
+        const sqlPreview = sql.length > 120 ? `${sql.slice(0, 120)}…` : sql;
+        log(`queryStream → ${sqlPreview}`);
+        const db = await getDB();
+        const conn = await db.connect();
+        const onAbort = () => {
+            try {
+                conn?.cancelSent?.();
+            }
+            catch {
+                /* noop */
+            }
+        };
+        signal?.addEventListener('abort', onAbort, { once: true });
+        try {
+            if (connId) {
+                await this.configureStorage(conn, connId, sql);
+            }
+            const reader = await conn.send(sql);
+            let cols = [];
+            let types = [];
+            let decimalCols = [];
+            let first = true;
+            let total = 0;
+            const batches = reader[Symbol.asyncIterator]();
+            while (true) {
+                if (signal?.aborted)
+                    throw new QueryCancelledError();
+                const { value: batch, done } = await batches.next();
+                if (done)
+                    break;
+                if (first && batch.schema) {
+                    cols = batch.schema.fields.map((f) => f.name);
+                    types = batch.schema.fields.map((f) => String(f.type));
+                    decimalCols = [];
+                    for (let i = 0; i < cols.length; i++) {
+                        const s = decimalScale(types[i]);
+                        if (s >= 0)
+                            decimalCols.push({ name: cols[i], scale: s });
+                    }
+                    first = false;
+                }
+                const rows = [];
+                for (const row of batch.toArray()) {
+                    const json = typeof row.toJSON === 'function' ? row.toJSON() : { ...row };
+                    for (const key in json) {
+                        if (json[key] instanceof Uint8Array) {
+                            json[key] = json[key].slice();
+                        }
+                    }
+                    for (const { name, scale } of decimalCols) {
+                        json[name] = formatDecimal(json[name], scale);
+                    }
+                    rows.push(json);
+                }
+                total += rows.length;
+                yield { columns: cols, types, rowCount: rows.length, rows };
+            }
+            log(`queryStream → done in ${elapsed(t0)}, ${total} rows total`);
+        }
+        catch (err) {
+            if (signal?.aborted || err instanceof QueryCancelledError) {
+                log(`queryStream → cancelled after ${elapsed(t0)}`);
+                throw new QueryCancelledError();
+            }
+            logWarn(`queryStream → failed after ${elapsed(t0)}:`, err?.message ?? err);
+            throw err;
+        }
+        finally {
+            signal?.removeEventListener('abort', onAbort);
+            await conn?.close?.();
+        }
+    }
     queryForMapCancellable(connId, sql, geomCol, geomColType, sourceCrs) {
         let cancelled = false;
         let conn = null;

package/dist/storage/presign.js

@@ -1,5 +1,6 @@
+import { safeDecodeURIComponent } from '@walkthru-earth/objex-utils';
+import { DEFAULT_AWS_REGION } from '../constants.js';
 import { credentialStore } from '../stores/credentials.svelte.js';
-import { safeDecodeURIComponent } from '../utils/cloud-url.js';
 import { buildProviderBaseUrl, getAccessMode } from './providers.js';
 // 7 days is the SigV4 protocol maximum and is the hard cap on every
 // S3-compatible provider we support (AWS, GCS, R2, B2, DO, Wasabi, Storj,
@@ -38,7 +39,7 @@ export async function presignHttpsUrl(conn, key, expiresIn = DEFAULT_EXPIRES_IN_
         accessKeyId: creds.accessKey,
         secretAccessKey: creds.secretKey,
         service: 's3',
-        region: conn.region || 'us-east-1'
+        region: conn.region || DEFAULT_AWS_REGION
     });
     const signed = await client.sign(url.toString(), {
         method: 'GET',

package/dist/storage/providers.js

@@ -4,6 +4,7 @@
  * Centralizes endpoint patterns, regions, auth methods, and UI metadata.
  * Used by ConnectionDialog, browser-cloud adapter, host-detection, url-state, etc.
  */
+import { DEFAULT_AWS_REGION } from '../constants.js';
 // ---------------------------------------------------------------------------
 // Registry
 // ---------------------------------------------------------------------------
@@ -87,15 +88,15 @@ export const PROVIDERS = {
         schemes: ['azure', 'az', 'abfs', 'abfss', 'wasbs', 'adl']
     },
     minio: {
-        label: 'MinIO',
-        description: 'Self-hosted MinIO or S3-compatible',
+        label: 'MinIO / RustFS / Custom',
+        description: 'MinIO, RustFS, or any custom S3-compatible endpoint',
         authMethod: 'sigv4',
         needsRegion: false,
         needsEndpoint: true,
         defaultRegion: 'us-east-1',
         endpointTemplate: null,
         regions: [],
-        endpointPlaceholder: 'https://minio.example.com or http://localhost:9000',
+        endpointPlaceholder: 'https://s3.example.com or http://localhost:9000',
         schemes: []
     },
     storj: {
@@ -297,7 +298,7 @@ export const CORS_HELP = {
     minio: {
         defaultEnabled: true,
         docsUrl: 'https://docs.min.io/enterprise/aistor-object-store/reference/cli/mc-cors/',
-        note: 'MinIO allows all origins by default. For custom rules, use mc cors set.'
+        note: 'MinIO allows all origins by default (for custom rules use mc cors set). For RustFS or any other custom S3 service, set a CORS policy on the server that allows this origin.'
     },
     storj: {
         defaultEnabled: true,
@@ -389,7 +390,7 @@ export const READ_ONLY_HELP = {
         ]
     },
     minio: {
-        note: 'Create a read-only policy with mc admin policy, or use the built-in readonly canned policy.',
+        note: 'For MinIO, create a read-only policy with mc admin policy or use the built-in readonly canned policy. For RustFS or any other custom S3 service, attach a read-only bucket policy on the server.',
         docsUrl: 'https://docs.min.io/enterprise/aistor-object-store/administration/iam/access/'
     },
     digitalocean: {
@@ -463,7 +464,7 @@ export function buildProviderBaseUrl(provider, endpoint, bucket, region) {
         return `${resolved}/${bucket}`;
     }
     // Fallback: AWS S3 path-style
-    return `https://s3.${region || 'us-east-1'}.amazonaws.com/${bucket}`;
+    return `https://s3.${region || DEFAULT_AWS_REGION}.amazonaws.com/${bucket}`;
 }
 /** Check if a provider uses the GCS JSON API (not S3 XML). */
 export function isGcsProvider(provider, endpoint) {

package/dist/stores/config.svelte.d.ts

@@ -0,0 +1,15 @@
+import { type AppConfig } from '@walkthru-earth/objex-utils';
+export type ConfigStatus = 'pending' | 'bundled' | 'custom' | 'error';
+/** Reactive accessor for the loaded config and its load status. */
+export declare const appConfig: {
+    readonly value: AppConfig;
+    readonly status: ConfigStatus;
+};
+/**
+ * Fetch and merge the runtime config. Awaited in +layout.ts `load` so the
+ * config is ready before any component mounts. A `?config=<url>` param loads a
+ * remote file (status `custom`), otherwise the bundled `static/config.json`
+ * (status `bundled`). Any failure falls back to defaults (status `error`) and
+ * the app still boots.
+ */
+export declare function loadConfig(basePath: string): Promise<void>;

package/dist/stores/config.svelte.js

@@ -0,0 +1,46 @@
+import { DEFAULT_APP_CONFIG, mergeAppConfig } from '@walkthru-earth/objex-utils';
+let config = $state.raw(DEFAULT_APP_CONFIG);
+let status = $state('pending');
+/** Reactive accessor for the loaded config and its load status. */
+export const appConfig = {
+    get value() {
+        return config;
+    },
+    get status() {
+        return status;
+    }
+};
+function readConfigParam() {
+    if (typeof window === 'undefined')
+        return null;
+    try {
+        return new URL(window.location.href).searchParams.get('config');
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Fetch and merge the runtime config. Awaited in +layout.ts `load` so the
+ * config is ready before any component mounts. A `?config=<url>` param loads a
+ * remote file (status `custom`), otherwise the bundled `static/config.json`
+ * (status `bundled`). Any failure falls back to defaults (status `error`) and
+ * the app still boots.
+ */
+export async function loadConfig(basePath) {
+    const customUrl = readConfigParam();
+    const url = customUrl ?? `${basePath}/config.json`;
+    try {
+        const res = await fetch(url, { headers: { accept: 'application/json' } });
+        if (!res.ok)
+            throw new Error(`HTTP ${res.status}`);
+        const json = await res.json();
+        config = mergeAppConfig(DEFAULT_APP_CONFIG, json);
+        status = customUrl ? 'custom' : 'bundled';
+    }
+    catch (err) {
+        console.warn('[objex] config load failed, using defaults', err);
+        config = DEFAULT_APP_CONFIG;
+        status = 'error';
+    }
+}

package/dist/stores/connections.svelte.d.ts

@@ -1,6 +1,6 @@
+import type { DetectedHost } from '@walkthru-earth/objex-utils';
+import { type ConnectionIdentityInput } from '@walkthru-earth/objex-utils';
 import type { Connection, ConnectionConfig } from '../types.js';
-import { type ConnectionIdentityInput } from '../utils/connection-identity.js';
-import type { DetectedHost } from '../utils/host-detection.js';
 /**
  * Outcome of a write. `existed` is true when dedup reused an already-saved
  * connection, false when a new row was persisted. Callers that present UI

package/dist/stores/connections.svelte.js

@@ -1,6 +1,5 @@
+import { connectionIdentityKey, loadFromStorage, persistToStorage } from '@walkthru-earth/objex-utils';
 import { STORAGE_KEYS } from '../constants.js';
-import { connectionIdentityKey } from '../utils/connection-identity.js';
-import { loadFromStorage, persistToStorage } from '../utils/local-storage.js';
 import { credentialStore, storeToNative } from './credentials.svelte.js';
 function toConnection(id, config) {
     return {

package/dist/stores/files.svelte.d.ts

@@ -1,5 +1,5 @@
+import { type SortConfig, type SortField } from '@walkthru-earth/objex-utils';
 import type { FileEntry } from '../types.js';
-import { type SortConfig, type SortField } from '../utils/file-sort.js';
 export declare const files: {
     readonly entries: FileEntry[];
     readonly currentPath: string;

package/dist/stores/files.svelte.js

@@ -1,4 +1,4 @@
-import { sortFileEntries, toggleSortField } from '../utils/file-sort.js';
+import { sortFileEntries, toggleSortField } from '@walkthru-earth/objex-utils';
 function createFilesStore() {
     let files = $state([]);
     let currentPath = $state('');

package/dist/stores/query-history.svelte.js

@@ -1,5 +1,5 @@
+import { loadFromStorage, persistToStorage } from '@walkthru-earth/objex-utils';
 import { MAX_QUERY_HISTORY_ENTRIES, STORAGE_KEYS } from '../constants.js';
-import { loadFromStorage, persistToStorage } from '../utils/local-storage.js';
 function createQueryHistoryStore() {
     let entries = $state(loadFromStorage(STORAGE_KEYS.QUERY_HISTORY, []));
     function save() {

package/dist/stores/settings.svelte.d.ts

@@ -1,4 +1,4 @@
-import { type Locale } from '../i18n/index.svelte.js';
+import type { Locale } from '../i18n/index.svelte.js';
 import type { Theme } from '../types.js';
 export declare function resolveTheme(theme: Theme): 'light' | 'dark';
 export declare const settings: {
@@ -6,7 +6,22 @@ export declare const settings: {
     readonly resolved: "light" | "dark";
     readonly locale: Locale;
     readonly featureLimit: number;
+    readonly mosaicItemLimit: number;
+    readonly showConnectionRail: boolean;
+    readonly showFileTree: boolean;
+    /** True when a link param is forcing the connection-rail visibility. */
+    readonly railLockedByParam: boolean;
+    /** True when a link param is forcing the file-tree visibility. */
+    readonly treeLockedByParam: boolean;
+    /** The user-picked basemap id, or undefined to follow config/theme defaults. */
+    readonly basemapId: string | undefined;
     setTheme(t: Theme): void;
     setLocale(l: Locale): void;
     setFeatureLimit(n: number): void;
+    setMosaicItemLimit(n: number): void;
+    setShowConnectionRail(v: boolean): void;
+    setShowFileTree(v: boolean): void;
+    setBasemap(id: string | undefined): void;
+    /** Clear all user overrides, reverting every value to config or hardcoded fallback. */
+    reset(): void;
 };