@walkthru-earth/objex-utils 1.3.0 → 1.4.0

package/docs/lru.md

@@ -0,0 +1,76 @@
+# LruCache
+
+Tiny insertion-order LRU built on top of `Map`, with move-to-end on read and an optional eviction callback.
+
+Source: `packages/objex-utils/src/lru.ts`.
+
+## Types
+
+### `LruCacheOptions<K, V>`
+
+```ts
+interface LruCacheOptions<K, V> {
+  max: number;
+  onEvict?: (key: K, value: V) => void;
+}
+```
+
+- `max` -- maximum number of entries. Must be `> 0`. The constructor throws `Error('LruCache: max must be > 0')` for any non-positive value.
+- `onEvict` -- optional callback invoked whenever an entry leaves the cache, whether through LRU overflow, an explicit `delete()`, or `clear()`. Use it to release the cached resource (revoke a blob URL, null a GeoTIFF header, etc.).
+
+## Class
+
+### `LruCache<K, V>`
+
+```ts
+class LruCache<K, V> {
+  constructor(opts: LruCacheOptions<K, V>);
+  readonly max: number;
+  get size(): number;
+  has(key: K): boolean;
+  get(key: K): V | undefined;
+  set(key: K, value: V): void;
+  delete(key: K): boolean;
+  clear(): void;
+}
+```
+
+A small bounded cache keyed on any value `Map` accepts. Recency is tracked by insertion order in the backing `Map`, so the oldest key is always the first one returned by `keys()`.
+
+| Member | Semantics |
+|--------|-----------|
+| `max` | The configured cap, exposed read-only so callers can match a deck.gl `maxCacheSize` to it. |
+| `size` | Current number of entries. |
+| `has(key)` | `true` when the key is present. Does NOT change recency. |
+| `get(key)` | Returns the value or `undefined`. On a hit the entry is deleted and re-inserted so it becomes the most-recent slot (move-to-end). |
+| `set(key, value)` | Inserts or updates. An existing key is deleted first so the new write lands as most-recent. After insertion the cache evicts the oldest entries one at a time, calling `onEvict(key, value)` for each, until `size <= max`. |
+| `delete(key)` | Removes a single entry. Returns `false` if the key was absent (and `onEvict` is not called), `true` after removal (and `onEvict` runs). |
+| `clear()` | Removes every entry. When `onEvict` is set it fires once per entry before the backing `Map` is emptied. |
+
+**Edge cases**
+
+- A `get` on a missing key returns `undefined` and leaves recency untouched.
+- A value of `undefined` is indistinguishable from a miss in `get`, since both return `undefined`. Use `has()` first if you need to store `undefined` values.
+- `set` only evicts after the write, so writing into a full cache momentarily holds `max + 1` entries before trimming back to `max`.
+- `onEvict` runs synchronously inside `set` / `delete` / `clear`, so keep it cheap and non-throwing.
+
+## Example
+
+```ts
+import { LruCache } from '@walkthru-earth/objex-utils';
+
+// Bound a per-source presigned-URL cache so panning does not leak.
+const presignCache = new LruCache<string, string>({
+  max: 64,
+  onEvict: (href) => console.debug('evicted presign for', href)
+});
+
+presignCache.set('s3://bucket/a.tif', 'https://signed-a');
+presignCache.set('s3://bucket/b.tif', 'https://signed-b');
+
+// A read promotes the entry to most-recent.
+const signed = presignCache.get('s3://bucket/a.tif');
+
+// Explicit eviction when deck.gl unloads the matching tile.
+presignCache.delete('s3://bucket/b.tif');
+```

package/docs/map-pixel-inspect.md

@@ -0,0 +1,132 @@
+# map-pixel-inspect
+
+Framework-agnostic click-to-inspect helper that wires a map `click` event to an async probe, with per-click abort coordination.
+
+Source: `packages/objex-utils/src/map-pixel-inspect.ts`.
+
+This module has no dependency on Svelte, MapLibre, or deck.gl. The `MapLike` shape captures only the on/off surface the helper needs, so the flow can be unit-tested against a tiny stub. It factors out the "subscribe to click, mark inspecting, await the probe, surface the payload, abort the previous probe if a new click arrives mid-flight, tear down on cleanup" boilerplate shared by the COG-style viewers (`CogViewer`, `StacMosaicViewer`, `MultiCogViewer`).
+
+## Types
+
+### `PixelInspectClickEvent` / `PixelInspectClickHandler`
+
+```ts
+interface PixelInspectClickEvent {
+  lngLat: { lng: number; lat: number };
+}
+
+type PixelInspectClickHandler = (event: PixelInspectClickEvent) => void;
+```
+
+The minimal click payload the helper reads. Only `lngLat.lng` and `lngLat.lat` are consumed.
+
+### `MapLike`
+
+```ts
+interface MapLike {
+  on(type: 'click', handler: PixelInspectClickHandler): unknown;
+  off(type: 'click', handler: PixelInspectClickHandler): unknown;
+}
+```
+
+Minimal subset of MapLibre's map API. Anything that dispatches a `click` event carrying `{ lngLat }` and supports symmetric `on` / `off` registration plugs in. Return values of `on` / `off` are ignored (`unknown`).
+
+### `PixelInspectProbeRequest` / `PixelInspectProbe<T>`
+
+```ts
+interface PixelInspectProbeRequest {
+  lng: number;
+  lat: number;
+  signal: AbortSignal;
+}
+
+type PixelInspectProbe<T> = (req: PixelInspectProbeRequest) => Promise<T | null>;
+```
+
+Your probe receives the clicked coordinate plus a per-click `AbortSignal`. Thread the `signal` into every `fetch()` / range read the probe issues so a superseding click cancels the in-flight work. Resolve to the inspect payload, or to `null` when there is nothing to report at that location.
+
+### `PixelInspectCallbacks<T>`
+
+```ts
+interface PixelInspectCallbacks<T> {
+  onStart(): void;
+  onResult(result: T | null): void;
+}
+```
+
+- `onStart()` -- called synchronously when a click is accepted, before the probe is awaited. Use it to set an "inspecting" flag.
+- `onResult(result)` -- called once per accepted click after the probe settles. Receives `null` when the probe returned `null` or threw a non-helper-driven error, including an `AbortError` that did NOT originate from this helper's own controller (for example a viewer-teardown or upstream cancel). It is NOT called when a newer click superseded this one via the helper's own controller.
+
+### `AttachPixelInspectorOptions<T>`
+
+```ts
+interface AttachPixelInspectorOptions<T> {
+  probe: PixelInspectProbe<T>;
+  onStart: PixelInspectCallbacks<T>['onStart'];
+  onResult: PixelInspectCallbacks<T>['onResult'];
+}
+```
+
+The options bag for `attachPixelInspector`. Flattens the callbacks so the call site reads as a single object.
+
+## Functions
+
+### `attachPixelInspector<T>(map, options)`
+
+```ts
+function attachPixelInspector<T>(
+  map: MapLike,
+  { probe, onStart, onResult }: AttachPixelInspectorOptions<T>
+): () => void
+```
+
+Wire a click-to-inspect probe onto `map`. Returns a `detach()` function.
+
+On each accepted click the helper:
+
+1. Aborts the previous click's controller, if a probe is still in flight.
+2. Creates a fresh `AbortController` for this click and calls `onStart()` synchronously.
+3. Awaits `probe({ lng, lat, signal })`.
+4. Calls `onResult(payload)` exactly once, unless this click was itself superseded by a newer click.
+
+**Abort semantics**
+
+- A fast second click cancels the first probe via the first probe's own controller. That helper-owned abort is swallowed (no `onResult`), so a stale result never lands after the click that replaced it.
+- Any other `AbortError` (viewer teardown, an upstream signal) still flows through to `onResult(null)`, matching the pre-refactor behavior of each viewer's catch block.
+- The distinction is made by `isHelperAbort()`, an internal guard that checks whether the helper's own signal aborted and whether the error is a `DOMException` named `AbortError` or any object with `name === 'AbortError'`. `isHelperAbort` is not exported.
+
+**`detach()`**
+
+The returned function removes the `click` listener AND aborts any in-flight probe. It is idempotent (a second call is a no-op) and after detach all further clicks are ignored.
+
+## Example
+
+```ts
+import { attachPixelInspector } from '@walkthru-earth/objex-utils';
+
+interface PixelSample {
+  band: number;
+  value: number;
+}
+
+let inspecting = false;
+let sample: PixelSample | null = null;
+
+const detach = attachPixelInspector<PixelSample>(map, {
+  probe: async ({ lng, lat, signal }) => {
+    const px = await readPixelAtLngLat(geotiff, lng, lat, { signal });
+    if (!px) return null;
+    return { band: 0, value: px.value };
+  },
+  onStart: () => {
+    inspecting = true;
+  },
+  onResult: (result) => {
+    inspecting = false;
+    sample = result; // null when nothing was found at that point
+  }
+});
+
+// On viewer cleanup: removes the listener and aborts the in-flight probe.
+detach();
+```

package/docs/markdown-sql.md

@@ -2,7 +2,7 @@
 
 Parse markdown documents with YAML frontmatter and Evidence-style SQL code blocks, run interpolation, and stub blocks for server-side rendering.
 
-Source: `src/lib/utils/markdown-sql.ts`.
+Source: `packages/objex-utils/src/markdown-sql.ts`.
 
 ## Peer dependency
 

package/docs/parquet-metadata.md

@@ -2,7 +2,7 @@
 
 Lightweight GeoParquet-aware metadata reader for remote Parquet files. Uses [`hyparquet`](https://github.com/hyparam/hyparquet) via HTTP range requests (~512 KB) so you can inspect schemas and geo metadata **before** DuckDB-WASM finishes booting.
 
-Source: `src/lib/utils/parquet-metadata.ts`.
+Source: `packages/objex-utils/src/parquet-metadata.ts`.
 
 ## Peer dependencies
 

package/docs/stac-facets.md

@@ -0,0 +1,198 @@
+# stac-facets
+
+Auto-faceted client-side filter / sort / projection helpers for STAC item collections. Pure TypeScript, framework-agnostic. Useful when you want a STAC viewer (or any UI) to show a filter panel that adapts to the loaded dataset rather than hardcoding controls that may not have variance.
+
+```ts
+import {
+  type StacItemView,
+  type Facet,
+  type NumericFacet,
+  type EnumFacet,
+  type DatetimeFacet,
+  type FacetSet,
+  type FacetState,
+  type FacetSort,
+  type NumericFacetField,
+  type EnumFacetField,
+  extractItemView,
+  buildFacets,
+  applyFacets,
+  sortViews,
+  hasActiveFilters,
+  emptyFacetState,
+  DATETIME_HISTOGRAM_BINS,
+} from '@walkthru-earth/objex-utils';
+```
+
+## Concept
+
+A typical STAC viewer pipeline is:
+
+1. Hydrate items into a flat `StacItem[]`.
+2. Project each item into a slim `StacItemView` (id, bbox, datetime, cloud cover, platform, etc.) once, and never re-walk the heavy `properties` / `assets` again at filter time.
+3. Build a `FacetSet` from the projected views. The builder *auto-detects* which controls have variance: numeric facets only emit when there are >=2 distinct finite values, enum facets only when >=2 distinct values, datetime histogram with `DATETIME_HISTOGRAM_BINS = 32` fixed-width bins.
+4. Maintain a `FacetState` (filter selection) in component state.
+5. Filter via `applyFacets(views, state)` (pure, never mutates), sort via `sortViews(views, sort)`, render.
+
+This module covers steps 2-5 and the type surface the UI consumes.
+
+## Types
+
+### `StacItemView`
+
+```ts
+interface StacItemView {
+  id: string;
+  collection?: string;
+  bbox?: [number, number, number, number];
+  datetime?: string;
+  endDatetime?: string;
+  cloudCover?: number;
+  gsd?: number;
+  platform?: string;
+  constellation?: string;
+  instruments?: string[];
+  epsg?: number;
+  thumbnailHref?: string;
+  assetRoles?: string[];
+  raw: StacItem;
+}
+```
+
+The slim projection a faceting / strip / inspector layer reads. `raw` is kept as an escape hatch (the inspector's raw-JSON view, the `flyTo` bbox fallback when the projection lacks one).
+
+### `Facet`, `NumericFacet`, `EnumFacet`, `DatetimeFacet`
+
+Discriminated union with `kind: 'numeric' | 'enum' | 'datetime'`. Numeric facets carry `min`/`max`/`step`/`histogram?`; enum facets carry `values: { value, count }[]`; datetime facets carry an ISO `min`/`max` and a 32-bin histogram.
+
+### `FacetSet`
+
+```ts
+interface FacetSet {
+  numeric: Partial<Record<NumericFacetField, NumericFacet>>;
+  enum: Partial<Record<EnumFacetField, EnumFacet>>;
+  datetime?: DatetimeFacet;
+}
+```
+
+The shape `buildFacets()` returns. Only fields with variance appear, so a UI can iterate the keys and skip rendering controls that would not narrow this dataset.
+
+### `FacetState`
+
+```ts
+interface FacetState {
+  cloudCover?: { min?: number; max?: number };
+  gsd?: { min?: number; max?: number };
+  datetime?: { min?: string; max?: string };
+  collection?: string[];
+  platform?: string[];
+  constellation?: string[];
+  instruments?: string[];
+  assetRoles?: string[];
+  epsg?: number[];
+}
+```
+
+What the UI reads / writes. Open-bound ranges (one of `min` / `max` undefined) are valid. Empty arrays are treated as no constraint.
+
+### `FacetSort`
+
+```ts
+type FacetSort =
+  | 'datetime-desc'
+  | 'datetime-asc'
+  | 'cloud-asc'
+  | 'cloud-desc'
+  | 'gsd-asc'
+  | 'gsd-desc';
+```
+
+Items missing the sort field always sink to the bottom regardless of asc/desc.
+
+## Functions
+
+### `extractItemView(item)`
+
+```ts
+function extractItemView(item: StacItem): StacItemView;
+```
+
+Pure projection. Reads `properties.datetime`, `properties.start_datetime` / `properties.end_datetime`, `properties['eo:cloud_cover']`, `properties.gsd`, `properties.platform`, `properties.constellation`, `properties.instruments`, `properties['proj:epsg']` / `properties['proj:code']`, and the first asset whose `roles` includes `'thumbnail'` / `'overview'` / `'visual'` (in that order). Returns a `StacItemView` with `raw: item`.
+
+Non-finite numerics, missing properties, and malformed CRS strings are normalized to `undefined`.
+
+### `buildFacets(views)`
+
+```ts
+function buildFacets(views: readonly StacItemView[]): FacetSet;
+```
+
+Auto-detects which facets have variance. Numeric facets emit when there are >=2 distinct finite values; enum facets emit when there are >=2 distinct values. The datetime facet emits an ISO `min`/`max` plus a 32-bin histogram (`DATETIME_HISTOGRAM_BINS`) when the views span more than one day.
+
+### `applyFacets(views, state)`
+
+```ts
+function applyFacets(views: readonly StacItemView[], state: FacetState): StacItemView[];
+```
+
+Pure filter. Every constraint in `state` must match. Numeric ranges treat absent items as failing the constraint; enum arrays match if the item's value is in the array (or, for `instruments` / `assetRoles`, if any of the item's values is in the array).
+
+### `sortViews(views, sort)`
+
+```ts
+function sortViews(views: readonly StacItemView[], sort: FacetSort): StacItemView[];
+```
+
+Stable sort. Items missing the sort field sink to the bottom regardless of direction.
+
+### `hasActiveFilters(state)`
+
+```ts
+function hasActiveFilters(state: FacetState): boolean;
+```
+
+True if any field constrains. Use to short-circuit filter computation on hot paths (e.g. only filter the source list when active).
+
+### `emptyFacetState()`
+
+```ts
+function emptyFacetState(): FacetState;
+```
+
+Stable empty constant suitable for `$state(emptyFacetState())`.
+
+## Constants
+
+### `DATETIME_HISTOGRAM_BINS`
+
+`32`. Fixed bin count for the datetime facet histogram so the consumer UI can size its bars without re-computing.
+
+## Recipe: build a faceted item strip
+
+```ts
+import {
+  extractItemView,
+  buildFacets,
+  applyFacets,
+  emptyFacetState,
+  hasActiveFilters,
+  type FacetState,
+} from '@walkthru-earth/objex-utils';
+
+const views = items.map(extractItemView);
+const facets = buildFacets(views);
+let state: FacetState = emptyFacetState();
+
+function setFilter(next: FacetState): void {
+  state = next;
+  const filtered = hasActiveFilters(state) ? applyFacets(views, state) : views;
+  renderStrip(filtered);
+  renderFootprints(filtered);
+}
+```
+
+## Caveats
+
+- This module is **client-side only**. For server push-down (STAC API native parameters and CQL2-JSON), pair it with [`stac-pushdown`](./stac-pushdown.md): translate the `FacetState` into a native query, send to the server, then `applyFacets(views, residualState(state, caps))` for whatever the server could not honor.
+- `buildFacets` is O(n) over `views`. For very large catalogs (>50 k items) call it once per committed render set, not per filter change.
+- The datetime histogram bins are computed in UTC (`Date.parse` / `Date.UTC`). A consumer rendering local-time tick labels is responsible for the timezone conversion.

package/docs/stac-hydrate.md

@@ -0,0 +1,181 @@
+# stac-hydrate
+
+STAC link-following hydrator. Walks a classified STAC payload into a flat `StacItem[]` by following `links[rel=item]` (Collection), `links[rel=child]` then `links[rel=item]` (Catalog), the `rel="items"` endpoint (OGC API Features / STAC API), and `links[rel=next]` pagination (FeatureCollection / STAC API). Pure async TypeScript, zero Svelte / DuckDB / deck.gl dependency. Fetches through a caller-supplied `StorageAdapter` so private buckets can be walked.
+
+Source: `packages/objex-utils/src/stac-hydrate.ts`.
+
+```ts
+import {
+  type HydrateOptions,
+  type StacItemsQuery,
+  type HydrateResult,
+  hydrateStacItems,
+  hasStacItemsEndpoint,
+  absolutizeHref,
+} from '@walkthru-earth/objex-utils';
+```
+
+## Concept
+
+`classifyStac` (from [`stac`](./stac.md)) turns parsed JSON into a `StacRoutableKind`. `hydrateStacItems` takes that verdict plus the URL it was fetched from and recursively walks links into a flat item list, emitting batches as it goes for progressive rendering. It branches by variant:
+
+- `item`: a single Item, emitted immediately with its asset hrefs absolutized.
+- `item-collection`: a FeatureCollection, items accepted then `rel="next"` pages followed (when `followPagination`).
+- `collection` / `catalog`: walks static `rel="item"` links if present, else the `rel="items"` endpoint (STAC API convention), else recurses into `rel="child"` links with a bounded worker pool.
+
+All fetches route through the supplied `StorageAdapter`: absolute URLs that the optional `urlToKey` maps to a bucket key are read via `adapter.read` (so SigV4 presigning applies), foreign origins fall back to a raw `fetch`, and relative hrefs go straight to `adapter.read`.
+
+## Types
+
+### `HydrateOptions`
+
+```ts
+interface HydrateOptions {
+  signal: AbortSignal;
+  concurrency?: number;
+  limit?: number;
+  followPagination?: boolean;
+  onBatch?: (items: StacItem[]) => void;
+  onProgress?: (fetched: number, totalHinted: number | undefined) => void;
+  urlToKey?: (absoluteUrl: string) => string | null;
+  itemsQuery?: StacItemsQuery;
+}
+```
+
+- `signal` -- required abort signal, threaded into every adapter read and `fetch`.
+- `concurrency` -- max parallel fetches for item links and child walks. Default `12`.
+- `limit` -- hard cap on items, catalogs larger than this are truncated. Default `2000`.
+- `followPagination` -- follow `links[rel=next]` in FeatureCollections. Default `true`.
+- `onBatch` -- called with each newly fetched batch for progressive rendering. Items in a batch already have absolutized asset hrefs.
+- `onProgress` -- called after each emit with the running item count, `totalHinted` is always `undefined` in the current implementation.
+- `urlToKey` -- maps an absolute HTTPS URL to a bucket-relative key when it belongs to the caller's connection. When it returns a non-null string, the fetch routes through `adapter.read` (SigV4) instead of cross-origin `fetch`, so private-bucket catalogs can be walked. Return `null` for foreign origins.
+- `itemsQuery` -- optional native STAC API filters appended to the `rel="items"` endpoint and re-stamped on every `rel="next"` page. See `StacItemsQuery`.
+
+### `StacItemsQuery`
+
+```ts
+interface StacItemsQuery {
+  bbox?: [number, number, number, number];
+  datetime?: string;
+  limit?: number;
+  filter?: unknown;
+}
+```
+
+Native filters supported by OGC API Features / STAC API on `/items`.
+
+- `bbox` -- WGS84 `[west, south, east, north]`, stamped as `?bbox=w,s,e,n`.
+- `datetime` -- RFC 3339 instant or interval `start/end` (use `..` for open ends).
+- `limit` -- per-page item count hint, floored to an integer, the server may cap it.
+- `filter` -- a CQL2-JSON filter expression (STAC API Filter extension). When set it is appended as `?filter=<json>&filter-lang=cql2-json` and re-stamped onto every `rel="next"` page so cursor URLs cannot strip it.
+
+Each param is only stamped when the URL does not already carry it, so a server that echoes the original filter on its cursor links is not double-stamped (which would corrupt the JSON). `filter` is `JSON.stringify`-ed, a stringify failure (cyclic input) is swallowed and hydration continues without the filter.
+
+### `HydrateResult`
+
+```ts
+interface HydrateResult {
+  items: StacItem[];
+  truncated: boolean;
+  rootBaseHref: string;
+}
+```
+
+The aggregate result. `items` is the flat list capped at `limit`. `truncated` is true when the catalog exceeded `limit` or a sub-walk truncated. `rootBaseHref` echoes the `baseHref` argument the walk started from.
+
+## Functions
+
+### `hydrateStacItems(root, baseHref, adapter, opts)`
+
+```ts
+function hydrateStacItems(
+  root: StacRoutableKind,
+  baseHref: string,
+  adapter: StorageAdapter,
+  opts: HydrateOptions
+): Promise<HydrateResult>;
+```
+
+Walk `root` into a flat `StacItem[]`.
+
+- `root` -- the classified payload from `classifyStac`. A `kind: 'none'` root yields an empty, non-truncated result.
+- `baseHref` -- the URL `root` was fetched from. All relative hrefs (child links, item links, asset hrefs) resolve against this.
+- `adapter` -- the `StorageAdapter` every fetch routes through (see `urlToKey` for the routing rule).
+- `opts` -- see `HydrateOptions`.
+
+Behavior by `root.kind`:
+
+- `item` -- emits the single Item (asset hrefs absolutized against `baseHref`) and returns immediately, never truncated.
+- `item-collection` -- accepts every valid feature, then follows `rel="next"` recursively when `followPagination` and the running count is under `limit`. The `itemsQuery` is re-stamped on each next URL.
+- `collection` / `catalog` -- if the payload has static `rel="item"` links it fetches them with the worker pool. Otherwise, when no static item links exist, it tries the single `rel="items"` endpoint (with `itemsQuery` applied) and consumes it as a paginated FeatureCollection. A Catalog (or an item-link-less Collection) then also recurses into `rel="child"` links with up to `concurrency` workers, each child re-entering `hydrateStacItems` with a `limit` reduced by the count already gathered.
+
+Aborting via `opts.signal` stops the walk, in-flight reads reject with the adapter's abort behavior. Dead links and unreachable children are skipped, not fatal, so a partial catalog still hydrates. The returned `items` is sliced to `limit`.
+
+The `rel="items"` versus `rel="item"` distinction is load-bearing: STAC API endpoints (earth-search, planetary-computer, pgstac) advertise a single `rel="items"` link to a paginated FeatureCollection, while static self-contained catalogs use one `rel="item"` link per item file. The walker only consults the items endpoint when no static item links are present.
+
+### `hasStacItemsEndpoint(payload)`
+
+```ts
+function hasStacItemsEndpoint(payload: StacCollection | StacCatalog): boolean;
+```
+
+True when `payload` exposes a `rel="items"` link, the OGC API Features / STAC API convention. Lets callers detect a server-backed collection up front and switch to viewport-scoped fetching (passing an `itemsQuery` bbox) instead of walking every page of a static catalog.
+
+### `absolutizeHref(href, baseHref)`
+
+```ts
+function absolutizeHref(href: string, baseHref: string): string;
+```
+
+Resolve a possibly-relative href against `baseHref` via `new URL(href, baseHref)`. Hrefs that already carry an `http(s):`, `s3:`, or `azure:` scheme are returned unchanged. A `new URL` failure returns the original `href` unchanged. STAC catalogs commonly use `./child/foo.json` or `../foo.json`, both of which resolve correctly.
+
+## Example
+
+```ts
+import {
+  classifyStac,
+  hydrateStacItems,
+  hasStacItemsEndpoint,
+  type StacItem,
+} from '@walkthru-earth/objex-utils';
+import type { StorageAdapter } from '@walkthru-earth/objex-utils';
+
+async function loadCatalog(
+  url: string,
+  adapter: StorageAdapter,
+  bbox: [number, number, number, number],
+  signal: AbortSignal,
+) {
+  const json = await fetch(url, { signal }).then((r) => r.json());
+  const root = classifyStac(json);
+  if (root.kind === 'none') throw new Error('Not a STAC payload');
+
+  // Map our own bucket's HTTPS URLs back to keys so private reads use SigV4.
+  const urlToKey = (abs: string): string | null => {
+    const prefix = 'https://my-bucket.s3.amazonaws.com/';
+    return abs.startsWith(prefix) ? abs.slice(prefix.length) : null;
+  };
+
+  // Viewport-scope when the server supports it; otherwise walk everything.
+  const itemsQuery =
+    (root.kind === 'collection' || root.kind === 'catalog') &&
+    hasStacItemsEndpoint(root.payload)
+      ? { bbox, limit: 250 }
+      : undefined;
+
+  const all: StacItem[] = [];
+  const { items, truncated } = await hydrateStacItems(root, url, adapter, {
+    signal,
+    limit: 2000,
+    itemsQuery,
+    urlToKey,
+    onBatch: (batch) => all.push(...batch), // render progressively
+  });
+
+  return { items, truncated };
+}
+```
+
+## Peer dependencies
+
+None bundled. `hydrateStacItems` and `createApiSource` / `createStaticSource` (see [`stac-source`](./stac-source.md)) depend only on the caller-supplied `StorageAdapter` interface (re-exported from this package's host-side surface) and the global `fetch` for foreign origins. No DuckDB, Svelte, maplibre, or deck.gl on the import graph.