@walkthru-earth/objex 1.3.1 → 1.4.0

package/dist/stores/settings.svelte.js

@@ -1,14 +1,26 @@
+import { loadFromStorage, parseVisibilityParam, persistToStorage, resolveSetting } from '@walkthru-earth/objex-utils';
 import { STORAGE_KEYS } from '../constants.js';
-import { setLocale } from '../i18n/index.svelte.js';
-import { loadFromStorage, persistToStorage } from '../utils/local-storage.js';
-const SETTINGS_DEFAULTS = { theme: 'system', locale: 'en', featureLimit: 1000 };
-function loadSettings() {
-    const stored = loadFromStorage(STORAGE_KEYS.SETTINGS, {});
-    return {
-        theme: stored.theme ?? SETTINGS_DEFAULTS.theme,
-        locale: stored.locale ?? SETTINGS_DEFAULTS.locale,
-        featureLimit: stored.featureLimit ?? SETTINGS_DEFAULTS.featureLimit
-    };
+import { appConfig } from './config.svelte.js';
+/**
+ * Heuristic mobile detection. iOS Safari caps the WASM heap at ~1.8 GiB and
+ * Safari < 17.6 has no `credentialless` COEP, so OPFS spill rarely engages.
+ * A 2000-item stac-geoparquet scan with deep STRUCT `assets`/`links` columns
+ * blows the heap before the streaming engine can pace it. Clamp the default
+ * mosaic item limit lower on mobile so first-run mosaic loads succeed; users
+ * can still raise it explicitly in settings.
+ */
+function isMobileLikeAtLoad() {
+    if (typeof navigator === 'undefined')
+        return false;
+    if (/Mobi|Android|iPhone|iPad|iPod/i.test(navigator.userAgent))
+        return true;
+    if (typeof window === 'undefined')
+        return false;
+    return Math.min(window.innerWidth, window.innerHeight) <= 820;
+}
+const MOBILE_MOSAIC_LIMIT = 200;
+function loadUser() {
+    return loadFromStorage(STORAGE_KEYS.SETTINGS, {});
 }
 export function resolveTheme(theme) {
     if (theme !== 'system')
@@ -17,63 +29,107 @@ export function resolveTheme(theme) {
         return 'light';
     return window.matchMedia('(prefers-color-scheme: dark)').matches ? 'dark' : 'light';
 }
-function createSettingsStore() {
-    const initial = loadSettings();
-    let theme = $state(initial.theme);
-    let locale = $state(initial.locale);
-    let featureLimit = $state(initial.featureLimit);
-    let resolved = $state(resolveTheme(initial.theme));
-    // Sync i18n module and document dir with persisted locale
-    setLocale(initial.locale);
-    if (typeof document !== 'undefined') {
-        const dir = initial.locale === 'ar' ? 'rtl' : 'ltr';
-        document.documentElement.dir = dir;
-        document.documentElement.lang = initial.locale;
+function readVisibilityParam(name) {
+    if (typeof window === 'undefined')
+        return undefined;
+    try {
+        return parseVisibilityParam(new URL(window.location.href).searchParams.get(name));
     }
+    catch {
+        return undefined;
+    }
+}
+function createSettingsStore() {
+    let user = $state(loadUser());
+    // Query params and mobile detection are static for the session, read once.
+    const railParam = readVisibilityParam('sidebar');
+    const treeParam = readVisibilityParam('tree');
+    const mobileLikeAtLoad = isMobileLikeAtLoad();
     function persist() {
-        persistToStorage(STORAGE_KEYS.SETTINGS, { theme, locale, featureLimit });
+        persistToStorage(STORAGE_KEYS.SETTINGS, user);
     }
-    function applyTheme(t) {
-        theme = t;
-        resolved = resolveTheme(t);
-        persist();
-        if (typeof document !== 'undefined') {
-            document.documentElement.classList.toggle('dark', resolved === 'dark');
-        }
+    function cfg() {
+        return appConfig.value;
     }
-    function applyLocale(l) {
-        locale = l;
-        setLocale(l);
-        persist();
-        if (typeof document !== 'undefined') {
-            const dir = l === 'ar' ? 'rtl' : 'ltr';
-            document.documentElement.dir = dir;
-            document.documentElement.lang = l;
-        }
+    function effTheme() {
+        return resolveSetting(user.theme, cfg().defaults.theme, 'system');
     }
-    // System theme changes are handled by the $effect in +layout.svelte
-    // which properly cleans up the listener. No module-level listener needed.
     return {
         get theme() {
-            return theme;
+            return effTheme();
         },
         get resolved() {
-            return resolved;
+            return resolveTheme(effTheme());
         },
         get locale() {
-            return locale;
+            return resolveSetting(user.locale, cfg().defaults.locale, 'en');
         },
         get featureLimit() {
-            return featureLimit;
+            return resolveSetting(user.featureLimit, cfg().defaults.featureLimit, 1000);
+        },
+        get mosaicItemLimit() {
+            // Explicit user/query choice always wins, at any value.
+            if (user.mosaicItemLimit !== undefined)
+                return user.mosaicItemLimit;
+            const configured = resolveSetting(cfg().defaults.mosaicItemLimit, 2000);
+            // Mobile heap safety: clamp the default so API/static mosaic loads don't OOM.
+            return mobileLikeAtLoad ? Math.min(configured, MOBILE_MOSAIC_LIMIT) : configured;
+        },
+        get showConnectionRail() {
+            return resolveSetting(railParam, user.showConnectionRail, cfg().ui.showConnectionRail, true);
+        },
+        get showFileTree() {
+            return resolveSetting(treeParam, user.showFileTree, cfg().ui.showFileTree, true);
+        },
+        /** True when a link param is forcing the connection-rail visibility. */
+        get railLockedByParam() {
+            return railParam !== undefined;
+        },
+        /** True when a link param is forcing the file-tree visibility. */
+        get treeLockedByParam() {
+            return treeParam !== undefined;
+        },
+        /** The user-picked basemap id, or undefined to follow config/theme defaults. */
+        get basemapId() {
+            return user.basemapId;
         },
         setTheme(t) {
-            applyTheme(t);
+            user = { ...user, theme: t };
+            persist();
         },
         setLocale(l) {
-            applyLocale(l);
+            user = { ...user, locale: l };
+            persist();
         },
         setFeatureLimit(n) {
-            featureLimit = n;
+            user = { ...user, featureLimit: Math.max(1, Math.floor(n)) };
+            persist();
+        },
+        setMosaicItemLimit(n) {
+            user = { ...user, mosaicItemLimit: Math.max(1, Math.floor(n)) };
+            persist();
+        },
+        setShowConnectionRail(v) {
+            user = { ...user, showConnectionRail: v };
+            persist();
+        },
+        setShowFileTree(v) {
+            user = { ...user, showFileTree: v };
+            persist();
+        },
+        setBasemap(id) {
+            if (id === undefined) {
+                const { basemapId: _omit, ...rest } = user;
+                user = rest;
+            }
+            else {
+                user = { ...user, basemapId: id };
+            }
+            persist();
+        },
+        /** Clear all user overrides, reverting every value to config or hardcoded fallback. */
+        reset() {
+            user = {};
             persist();
         }
     };

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

@@ -11,6 +11,9 @@ export declare const tabs: {
     readonly items: Tab[];
     readonly activeTabId: string | null;
     readonly active: Tab | undefined;
+    readonly migrating: boolean;
+    beginMigration(): void;
+    endMigration(): void;
     /**
      * Tabs that should be kept alive in the DOM (mounted but hidden if inactive).
      * Returns up to MAX_ALIVE tabs in MRU order. The active tab is always included.

package/dist/stores/tabs.svelte.js

@@ -22,6 +22,14 @@ function createTabsStore() {
     // LRU order: most recently activated tab IDs first.
     // Used to decide which tabs stay alive in the DOM.
     let recentOrder = $state([]);
+    // True while the Sidebar is migrating an eager URL tab to a remote tab
+    // (close eager → await credentials/connection save → open remote).
+    // During this window, `tabs.items` is briefly empty, but the tab-sync
+    // effect MUST NOT clear `?url=` / `#hash` — the new viewer needs them.
+    // User-initiated tab closes happen with `migrating === false` and DO
+    // clear URL state, so subsequent Sidebar remounts (e.g. mobile Sheet
+    // open/close) don't auto-re-open the tab the user just closed.
+    let migrating = $state(false);
     function touchRecent(id) {
         recentOrder = [id, ...recentOrder.filter((r) => r !== id)];
         // Dispose resources for tabs that fell out of the alive window.
@@ -50,6 +58,15 @@ function createTabsStore() {
                 return undefined;
             return tabs.find((t) => t.id === activeTabId);
         },
+        get migrating() {
+            return migrating;
+        },
+        beginMigration() {
+            migrating = true;
+        },
+        endMigration() {
+            migrating = false;
+        },
         /**
          * Tabs that should be kept alive in the DOM (mounted but hidden if inactive).
          * Returns up to MAX_ALIVE tabs in MRU order. The active tab is always included.

package/dist/utils/cog-histogram.d.ts

@@ -0,0 +1,121 @@
+/**
+ * Streaming histogram + GDAL stats reader for COGs.
+ *
+ * This module owns the canonical `HISTOGRAM_BINS` constant (128) and a
+ * tile-by-tile histogram builder. The streamer fetches tiles from the
+ * coarsest overview, bins pixel values into a `Uint32Array` of length
+ * `HISTOGRAM_BINS`, and emits a snapshot via `onProgress` after each
+ * tile so the UI can fill in the histogram chart incrementally.
+ *
+ * When GDAL_METADATA `STATISTICS_MINIMUM` / `STATISTICS_MAXIMUM` are
+ * present we use them as fixed bin edges (single-pass streaming). When
+ * they are absent we fall back to a two-pass scan (min/max first, then
+ * bin), in which case progress fires only at the end, bin edges are
+ * not stable until the first pass finishes.
+ *
+ * Runs in workers and on the main thread. No DOM APIs (window,
+ * document, DOMParser), no Svelte runes. XML parsing is a tolerant
+ * regex over the GDAL_METADATA tag string, not a DOMParser pass.
+ */
+import type { GeoTIFF as GeoTIFFType } from '@developmentseed/geotiff';
+import { type RescaleConfig } from './cog.js';
+/** Number of histogram buckets. PR #3 bumps from 64 to 128. */
+export declare const HISTOGRAM_BINS = 128;
+/** Per-band GDAL statistics block read from the GDAL_METADATA tag. */
+export type GdalBandStats = {
+    min: number;
+    max: number;
+    mean?: number;
+    stddev?: number;
+};
+/** Map of 1-based band index to per-band stats. Empty when absent. */
+export type GdalImageStats = Map<number, GdalBandStats>;
+/** Snapshot of an in-progress histogram bake. */
+export type HistogramSnapshot = {
+    /** Bin counts of length `HISTOGRAM_BINS`. */
+    bins: Uint32Array;
+    /** Lower bin-edge (inclusive). */
+    min: number;
+    /** Upper bin-edge (exclusive for inner bins, inclusive for the last). */
+    max: number;
+    /** Tiles binned so far. */
+    tilesProcessed: number;
+    /** Total tiles the streamer plans to consume, or null if unknown. */
+    tilesTotal: number | null;
+};
+/** Options for {@link streamHistogram}. */
+export type StreamHistogramOptions = {
+    geotiff: GeoTIFFType;
+    /** 1-based band index. */
+    bandIndex: number;
+    signal: AbortSignal;
+    onProgress: (snap: HistogramSnapshot) => void;
+    /**
+     * 0-based overview index. When omitted, the lowest-resolution overview
+     * (i.e. the smallest available source, last entry of `geotiff.overviews`)
+     * is used. Falls back to the full-resolution image when `overviews` is
+     * empty.
+     */
+    overviewIndex?: number;
+    /** Hard upper bound on tiles consumed. Defaults to 32. */
+    maxTiles?: number;
+};
+/**
+ * Parse per-band stats out of the GDAL_METADATA tag. Tolerant of
+ * malformed XML, uses a regex pass over `<Item ...>...</Item>` rather
+ * than DOMParser so this can run inside a Web Worker.
+ *
+ * Prefers the library's pre-parsed `geotiff.storedStats` when present,
+ * falls back to scanning the raw `cachedTags.gdalMetadata` string when
+ * the library could not parse it but the tag is still present (defensive
+ * path, rarely fires with current @developmentseed/geotiff but cheap).
+ *
+ * Returns an empty Map when no usable per-band ranges are found.
+ */
+export declare function readGdalStats(geotiff: GeoTIFFType): GdalImageStats;
+/**
+ * Stream a 128-bin histogram for a single band. Fires `onProgress` after
+ * each tile so the UI can fill in the chart incrementally, the snapshots
+ * share no buffer references between calls (each `bins` is a fresh
+ * `Uint32Array`).
+ *
+ * Algorithm:
+ *  - With GDAL priors, one pass, known bin edges, progressive snapshots.
+ *  - Without priors, two passes, pass 1 finds min/max across all
+ *    selected tiles, pass 2 bins into 128 buckets. Snapshots fire
+ *    per-cached-tile in pass 2 so the UI still sees the histogram fill
+ *    in on the no-priors path, bin edges aren't stable during pass 1.
+ *
+ * Honors `signal.aborted` between every tile fetch and after each bin
+ * pass. Throws no error on abort, returns silently with whatever
+ * partial snapshot the caller already received.
+ */
+export declare function streamHistogram(opts: StreamHistogramOptions): Promise<void>;
+/** Options for {@link seedRescaleFromGeotiff}. */
+export type SeedRescaleOptions = {
+    signal?: AbortSignal;
+    /** 1-based band index. Defaults to 1. */
+    bandIndex?: number;
+};
+/**
+ * Seed a {@link RescaleConfig} for a freshly opened COG in the same
+ * normalized shader-space [0, 1] coordinate system the rescale slider
+ * operates on. The GPU's hardware normalization (`r8unorm` / `r16unorm`)
+ * and the `Colormap` CPU baker both divide raw integer samples by the
+ * format's max (255 for uint8, 65535 for uint16) before sampling, and
+ * `CogControls`'s `setRescaleMin/Max` clamps the slider via `clamp01`.
+ * Storing raw GeoTIFF stats (e.g. `{min: 0, max: 10000}` for uint16
+ * reflectance) here would snap back to `{0, 1}` on the user's first
+ * slider touch.
+ *
+ * Fallback chain:
+ *   1. GDAL `STATISTICS_MINIMUM` / `STATISTICS_MAXIMUM` for the band,
+ *      normalized to shader space by dividing by the sample-format
+ *      factor (255 for uint8, 65535 for uint ≥ 8 bps). Float bands are
+ *      passed through unchanged because they already live near [0, 1].
+ *   2. `buildHistogramFromGeotiff` + p2 / p98 percentile lookup so a
+ *      uint16 reflectance band with no STATISTICS tag still gets a
+ *      contrasted preview from the first tile of the smallest overview.
+ *   3. {@link defaultRescaleForGeotiff} bit-depth-aware constants.
+ */
+export declare function seedRescaleFromGeotiff(geotiff: GeoTIFFType, options?: SeedRescaleOptions): Promise<RescaleConfig>;