@walkthru-earth/objex-utils 1.3.0 → 1.4.0

package/docs/README.md

@@ -31,18 +31,29 @@ As of v1.2, `yaml` is loaded via dynamic `import()` inside `parseMarkdownDocumen
 
 | Page | Covers |
 |------|--------|
-| [`geometry.md`](./geometry.md) | WKB parser, GeoArrow table builder, geometry-column detection |
-| [`cog.md`](./cog.md) | Cloud-Optimized GeoTIFF helpers (pipeline selection, band configs, color ramps, bounds clamping) |
+| [`geometry.md`](./geometry.md) | WKB parser, GeoArrow table builder, geometry-column detection, parameterized GEOMETRY type parser (`parseGeometryTypeCrs`, `buildTransformExpr`, `wrapWkbWithCrs`) |
+| [`cog.md`](./cog.md) | Cloud-Optimized GeoTIFF pure helpers (bounds clamping, sample format labels, type guards). The render-pipeline surface stays in the Svelte components package and is NOT re-exported here. |
 | [`parquet-metadata.md`](./parquet-metadata.md) | `readParquetMetadata` + CRS / bounds / geometry-types extractors |
 | [`stac-geoparquet.md`](./stac-geoparquet.md) | stac-geoparquet detection (`isStacGeoparquetSchema`) and row-to-Item transforms (`stacRowToItem`, `flattenStacBbox`, `pickStacPrimaryAsset`, `resolveStacAssetHref`) |
-| [`storage.md`](./storage.md) | URL parsing (`parseStorageUrl`, `resolveCloudUrl`), provider registry, `StorageAdapter` interface, `UrlAdapter` |
+| [`stac-facets.md`](./stac-facets.md) | Auto-faceted state for STAC viewers, `extractItemView` / `buildFacets` / `applyFacets` / `sortViews` / `hasActiveFilters` / `emptyFacetState` + `StacItemView` / `Facet*` / `FacetState` types |
+| [`stac-pushdown.md`](./stac-pushdown.md) | `FacetState` → STAC API native query + CQL2-JSON translation. `sniffApiCapabilities`, `toNativeQuery`, `toCql2Filter`, `residualState` gated by what `conformsTo` advertises |
+| [`stac.md`](./stac.md) | Core STAC types and classifiers (`classifyStac`, `isStacItem`, `extractRasterBandAssets`, `extractMosaicAssets`, `buildMosaicSourceMeta`, `spatialCellKey`, `resolvePresetComposite`, `hasCompositableBands`, full type surface) |
+| [`stac-source.md`](./stac-source.md) | `StacSource` contract + `createApiSource` / `createStaticSource` implementations (parquet implementation lives in the Svelte components package because it requires DuckDB-WASM) |
+| [`stac-hydrate.md`](./stac-hydrate.md) | `hydrateStacItems` link-walker (Catalog / Collection / FeatureCollection / STAC API), `hasStacItemsEndpoint`, `absolutizeHref` |
+| [`stac-storage-extension.md`](./stac-storage-extension.md) | STAC Storage Extension v1.0.0 / v2.0.0 hints (`extractStorageHints`, `applyStorageHintsToConnection`) |
+| [`storage.md`](./storage.md) | URL parsing (`parseStorageUrl`, `resolveCloudUrl`, `classifyUrl`, `isKnownBucketHost`, `STAC_API_PATH_RE`), provider registry, `StorageAdapter` interface, `UrlAdapter`, `smokeTestHref`, `detectHostBucket`, `applyStacItemStorageHints`, `connectionIdentityKey` |
+| [`cog-asset.md`](./cog-asset.md) | Vendor-neutral COG asset enumeration (`extractCogAssets`, `syntheticSelfAsset`, `pickNaturalColorComposite`, `isSingleAssetComposite`, `allChannelsBand0`) |
+| [`channel-composite.md`](./channel-composite.md) | RGB composite presets and URL round-trip (`PRESETS`, `applyPreset`, `compositeFromUrl`, `compositeToUrl`, `presetMatchesComposite`) |
 | [`query-engine.md`](./query-engine.md) | `QueryEngine` interface and associated result/handle types |
 | [`file-types.md`](./file-types.md) | File-type registry (`getFileTypeInfo`, `getViewerKind`, `getDuckDbReadFn`, ...) |
-| [`formatting.md`](./formatting.md) | Display formatters, column-type classification, hex dump, CSV/JSON export |
+| [`formatting.md`](./formatting.md) | Display formatters, column-type classification, hex dump, CSV/JSON export, clipboard helper, notebook renderer |
 | [`file-sort.md`](./file-sort.md) | `sortFileEntries`, `toggleSortField` |
 | [`markdown-sql.md`](./markdown-sql.md) | Markdown + SQL block parsing (Evidence-compatible syntax) |
 | [`local-storage.md`](./local-storage.md) | SSR-safe `loadFromStorage` / `persistToStorage` |
-| [`errors.md`](./errors.md) | `handleLoadError` |
+| [`app-config.md`](./app-config.md) | Runtime config schema + precedence resolver (`AppConfig`, `mergeAppConfig`, `resolveSetting`, `resolveBasemap`, `parseVisibilityParam`, `coerce*`) |
+| [`map-pixel-inspect.md`](./map-pixel-inspect.md) | Framework-agnostic click-to-inspect helper (`attachPixelInspector`), minimal `MapLike` shape, per-click abort coordination |
+| [`lru.md`](./lru.md) | `LruCache<K,V>` move-to-end on `get`, optional `onEvict` |
+| [`errors.md`](./errors.md) | `handleLoadError`, `isAbortError` |
 | [`types-constants.md`](./types-constants.md) | `Connection`, `Tab`, `FileEntry`, `WriteResult`, `Theme`, shared constants |
 
 ## Quick recipes
@@ -92,7 +103,7 @@ const rows = generateHexDump(bytes);
 
 ## Upstream source
 
-All modules re-export from `src/lib/` in the [objex](https://github.com/walkthru-earth/objex) monorepo. The re-export list lives at [`packages/objex-utils/src/index.ts`](../src/index.ts).
+Most modules now live physically inside `packages/objex-utils/src/` (each re-exported via `export *` from `index.ts`). A handful of host-side types are still re-exported from `src/lib/` so both `@walkthru-earth/objex` and `@walkthru-earth/objex-utils` share the same shapes (Connection, StorageAdapter, QueryEngine, file-icons, constants). See [`packages/objex-utils/src/index.ts`](../src/index.ts) in the [objex](https://github.com/walkthru-earth/objex) monorepo.
 
 ## Versioning & releases
 

package/docs/app-config.md

@@ -0,0 +1,237 @@
+# App config
+
+Runtime configuration schema and precedence resolver for objex self-hosting (a bundled `config.json`, an optional `?config=<url>` remote override, and an in-app settings panel).
+
+Source: `packages/objex-utils/src/app-config.ts`.
+
+## Types
+
+### `BasemapConfig`
+
+```ts
+interface BasemapConfig {
+  id: string;
+  label: string;
+  type: 'vector' | 'raster';
+  url: string;
+  variant?: 'light' | 'dark';
+}
+```
+
+A basemap option a host can offer. `variant` tags the basemap as suited to a light or dark theme, used by [`resolveBasemap`](#resolvebasemapconfig-variant-userid) to match the active theme. Consumed in Phase 2.
+
+### `ConnectionSeed`
+
+```ts
+interface ConnectionSeed {
+  name: string;
+  provider: string;
+  bucket: string;
+  region?: string;
+  endpoint?: string;
+  anonymous?: boolean;
+  authMethod?: 'sigv4' | 'sas-token';
+  rootPrefix?: string;
+}
+```
+
+A preloaded connection definition baked into the config. **Never carries secrets**, it describes where data lives, not how to authenticate. Consumed in Phase 2.
+
+### `AppConfigDefaults`
+
+```ts
+interface AppConfigDefaults {
+  theme: Theme;
+  locale: string;
+  featureLimit: number;
+  mosaicItemLimit: number;
+}
+```
+
+Default app behaviour. `theme` is the shared [`Theme`](./types-constants.md#theme) union (`'light' | 'dark' | 'system'`). `featureLimit` caps rows pulled into a map layer, `mosaicItemLimit` caps STAC mosaic items.
+
+### `AppConfigUi`
+
+```ts
+interface AppConfigUi {
+  showConnectionRail: boolean;
+  showFileTree: boolean;
+  showSettings: boolean;
+}
+```
+
+Chrome visibility toggles for embedding objex with a trimmed UI.
+
+### `AppConfig`
+
+```ts
+interface AppConfig {
+  defaults: AppConfigDefaults;
+  ui: AppConfigUi;
+  basemaps: BasemapConfig[];
+  defaultBasemap: { light?: string; dark?: string };
+  connections: ConnectionSeed[];
+}
+```
+
+The full resolved configuration. `defaultBasemap.light` / `defaultBasemap.dark` reference a `BasemapConfig.id` to pick the preferred basemap per theme variant.
+
+## Functions
+
+### `DEFAULT_APP_CONFIG`
+
+```ts
+const DEFAULT_APP_CONFIG: AppConfig;
+```
+
+The hardcoded fallback, matching the app's behaviour when no config is present:
+
+```ts
+{
+  defaults: { theme: 'system', locale: 'en', featureLimit: 1000, mosaicItemLimit: 2000 },
+  ui: { showConnectionRail: true, showFileTree: true, showSettings: true },
+  basemaps: [],
+  defaultBasemap: {},
+  connections: []
+}
+```
+
+Use this as the `base` argument to [`mergeAppConfig`](#mergeappconfigbase-override) when no bundled config exists.
+
+### `mergeAppConfig(base, override)`
+
+```ts
+function mergeAppConfig(base: AppConfig, override: unknown): AppConfig
+```
+
+Merge an untrusted JSON value over a base config, field by field. Returns a fully populated `AppConfig`. Behaviour:
+
+- When `override` is not a plain object (null, array, primitive), `base` is returned unchanged.
+- Unknown fields are ignored.
+- Each scalar runs through its `coerce*` validator. A malformed value (wrong type, blank string, non-positive int) falls back to the matching `base` value.
+- `basemaps` and `connections` are filtered: each entry is validated and well-formed entries are kept. A basemap is dropped unless it has a non-blank `id`, `label`, `url`, and a `type` of `'vector'` or `'raster'`. A connection is dropped unless it has a non-blank `name` and `bucket`; its `provider` defaults to `'s3'` when blank. When the field is not an array at all, the whole `base` list is kept.
+- Never reads secrets.
+
+### `resolveSetting<T>(...candidates)`
+
+```ts
+function resolveSetting<T>(...candidates: (T | null | undefined)[]): T | undefined
+```
+
+Returns the first candidate that is neither `null` nor `undefined`, or `undefined` when all are. This encodes objex's settings precedence chain, list candidates highest priority first:
+
+```
+query-param  >  user override  >  config value  >  hardcoded fallback
+```
+
+Because the test is strict (`!== null && !== undefined`), falsy-but-valid values such as `0`, `''`, and `false` are treated as present and win over later candidates. Pre-validate user-supplied strings with the `coerce*` helpers so an invalid value collapses to `undefined` and the chain falls through.
+
+### `parseVisibilityParam(value)`
+
+```ts
+function parseVisibilityParam(value: string | null): boolean | undefined
+```
+
+Maps the `?rail` / `?tree` visibility query param to a boolean. `'hide'` returns `false`, `'show'` returns `true`, anything else (including `null`) returns `undefined`. The `undefined` case is designed to slot in as the top candidate of [`resolveSetting`](#resolvesettingtcandidates), so an absent or invalid param defers to the config.
+
+### `coerceTheme(v)`
+
+```ts
+function coerceTheme(v: unknown): Theme | undefined
+```
+
+Returns `v` only when it is exactly `'light'`, `'dark'`, or `'system'`, otherwise `undefined`.
+
+### `coerceString(v)`
+
+```ts
+function coerceString(v: unknown): string | undefined
+```
+
+Returns the trimmed string when `v` is a string with non-whitespace content, otherwise `undefined`. Note the return value is trimmed, leading/trailing whitespace is stripped.
+
+### `coercePositiveInt(v)`
+
+```ts
+function coercePositiveInt(v: unknown): number | undefined
+```
+
+Returns `Math.floor(v)` when `v` is a finite number `>= 1`, otherwise `undefined`. Fractional inputs are floored, zero and negatives are rejected.
+
+### `coerceBool(v)`
+
+```ts
+function coerceBool(v: unknown): boolean | undefined
+```
+
+Returns `v` only when it is a real boolean, otherwise `undefined`. Truthy/falsy strings like `'true'` are **not** coerced.
+
+### `resolveBasemap(config, variant, userId)`
+
+```ts
+function resolveBasemap(
+  config: AppConfig,
+  variant: 'light' | 'dark',
+  userId: string | undefined
+): BasemapConfig | undefined
+```
+
+Pick the basemap a map should render. Pick order:
+
+1. **Explicit user pick** -- the basemap whose `id` equals `userId`, but only if it still exists in the configured list (a stale `userId` from local storage is ignored).
+2. **Configured default for the variant** -- the basemap whose `id` equals `config.defaultBasemap[variant]`, when present and still in the list.
+3. **First basemap matching the variant** -- the first entry with `variant` equal to the requested variant.
+4. **First basemap of any variant** -- `config.basemaps[0]`.
+
+Returns `undefined` only when no basemaps are configured (`config.basemaps` is empty), signalling the caller to fall back to its own hardcoded default.
+
+## Example
+
+Resolving the active theme through the full precedence chain (query param over user override over config over fallback):
+
+```ts
+import {
+  DEFAULT_APP_CONFIG,
+  mergeAppConfig,
+  resolveSetting,
+  coerceTheme,
+} from '@walkthru-earth/objex-utils';
+
+// Bundled config.json merged over the hardcoded fallback.
+const config = mergeAppConfig(DEFAULT_APP_CONFIG, {
+  defaults: { theme: 'light', locale: 'en' },
+});
+
+const params = new URLSearchParams(location.search);
+const userTheme = loadFromStorage('theme', undefined); // may be undefined
+
+const theme = resolveSetting(
+  coerceTheme(params.get('theme')), // query-param  (highest priority)
+  coerceTheme(userTheme),           // user override
+  config.defaults.theme,            // config value
+  'system',                         // hardcoded fallback (always wins last)
+);
+// ?theme=dark  ->  'dark'
+// no param, user picked 'light'  ->  'light'
+// nothing set  ->  config.defaults.theme === 'light'
+```
+
+Picking the basemap for the active theme variant:
+
+```ts
+import { resolveBasemap } from '@walkthru-earth/objex-utils';
+
+const config = mergeAppConfig(DEFAULT_APP_CONFIG, {
+  basemaps: [
+    { id: 'osm', label: 'OSM', type: 'raster', url: 'https://…', variant: 'light' },
+    { id: 'dark-matter', label: 'Dark Matter', type: 'vector', url: 'https://…', variant: 'dark' },
+  ],
+  defaultBasemap: { dark: 'dark-matter' },
+});
+
+resolveBasemap(config, 'dark', undefined);      // -> the 'dark-matter' entry (config default)
+resolveBasemap(config, 'light', undefined);     // -> the 'osm' entry (first matching variant)
+resolveBasemap(config, 'dark', 'osm');          // -> the 'osm' entry (user pick wins)
+resolveBasemap(config, 'dark', 'gone');         // -> 'dark-matter' (stale id ignored, default used)
+resolveBasemap(DEFAULT_APP_CONFIG, 'light', undefined); // -> undefined (no basemaps configured)
+```

package/docs/channel-composite.md

@@ -0,0 +1,127 @@
+# Channel composite presets and URL round-trip
+
+RGB composite presets (Natural Color, False-Color IR, SWIR, ...) and the `URLSearchParams` round-trip for the unified RGB picker. Pure TypeScript, publishable via objex-utils.
+
+Source: `packages/objex-utils/src/channel-composite.ts`.
+
+Presets describe a semantic band-slot triple (`red`/`green`/`blue` for Natural Color, `nir`/`red`/`green` for False-Color IR, ...). Resolving a preset against a specific item walks the band-key fallbacks in [`stac`](./stac.md) (via `resolvePresetComposite`) to map slots to actual asset keys on that item. NDVI and other single-band derived presets are intentionally not in this list.
+
+This module builds on the [`CogAsset` / `ChannelComposite`](./cog-asset.md) types and the [`BandSlot`](./stac.md) vocabulary.
+
+## Types
+
+### `PresetDef`
+
+```ts
+interface PresetDef {
+  id: string;
+  labelKey: string;
+  slots: { r: BandSlot; g: BandSlot; b: BandSlot };
+}
+```
+
+A preset definition. `id` is the stable string written into the URL (`?preset=...`), `labelKey` is the i18n key for its display label, and `slots` is the semantic band-slot triple ([`BandSlot`](./stac.md): `'red' | 'green' | 'blue' | 'nir' | 'swir1' | 'swir2' | 'rededge'`).
+
+## Constants
+
+### `PRESETS`
+
+```ts
+const PRESETS: PresetDef[]
+```
+
+The built-in preset list, in display order:
+
+| `id` | `labelKey` | r / g / b slots |
+|------|-----------|-----------------|
+| `natural-color` | `map.multiCogPreset.trueColor` | `red` / `green` / `blue` |
+| `false-color-ir` | `map.multiCogPreset.falseColorIR` | `nir` / `red` / `green` |
+| `swir` | `map.multiCogPreset.swir` | `swir2` / `swir1` / `red` |
+| `vegetation` | `map.multiCogPreset.vegetation` | `nir` / `swir1` / `red` |
+| `agriculture` | `map.multiCogPreset.agriculture` | `swir1` / `nir` / `blue` |
+
+## Functions
+
+### `availablePresets(assets)`
+
+```ts
+function availablePresets(assets: CogAsset[]): PresetDef[]
+```
+
+Return the subset of `PRESETS` whose slot triple actually resolves on this item, i.e. every slot maps to a present asset. Use this to render only the presets that will produce a valid composite for the loaded item.
+
+### `applyPreset(assets, preset)`
+
+```ts
+function applyPreset(assets: CogAsset[], preset: PresetDef): ChannelComposite | null
+```
+
+Resolve a preset to a `ChannelComposite` for this item. Each resolved channel binds to its asset key at band index `0`. Returns `null` when the preset's slots do not all resolve against `assets`.
+
+### `presetMatchesComposite(preset, c, assets)`
+
+```ts
+function presetMatchesComposite(
+  preset: PresetDef,
+  c: ChannelComposite,
+  assets: CogAsset[]
+): boolean
+```
+
+`true` when the preset, resolved against `assets`, still matches the user's current composite `c`. The match requires the `r`/`g`/`b` asset keys to be equal and all three band indices on `c` to be `0`. Returns `false` when the preset does not resolve. Use this to highlight which preset (if any) corresponds to the user's current manual picks.
+
+### `compositeFromUrl(params, assets)`
+
+```ts
+function compositeFromUrl(
+  params: URLSearchParams,
+  assets: CogAsset[]
+): ChannelComposite | null
+```
+
+Decode a `URLSearchParams` chunk into a `ChannelComposite`.
+
+**Format** `r=<asset>&g=<asset>&b=<asset>&band_r=<n>&band_g=<n>&band_b=<n>` plus optional `a=<asset>&band_a=<n>`. Each `band_*` defaults to `0` when absent, so legacy MultiCog URLs such as `?r=red&g=green&b=blue&preset=true-color` keep round-tripping.
+
+**Returns** `null` when any required key (`r`, `g`, or `b`) is missing, or when any of the named `r`/`g`/`b` asset keys is not present in `assets`. The optional alpha channel is only added when its `a` key resolves to a known asset; an unresolvable `a` is silently dropped rather than failing the whole parse.
+
+**Band clamping** Each `band_*` value is parsed as a number, floored, and clamped into `[0, bandCount - 1]` for the corresponding asset. A missing, non-finite, or negative value becomes `0`; a value at or beyond `bandCount` becomes `bandCount - 1` (or `0` when `bandCount` is non-positive).
+
+### `compositeToUrl(c, presetId)`
+
+```ts
+function compositeToUrl(c: ChannelComposite, presetId: string | null): URLSearchParams
+```
+
+Encode a composite plus the active preset id into `URLSearchParams` for the URL hash.
+
+**Encoding** Always writes `r`, `g`, `b` asset keys. A `band_*` key is written only when that channel's band index is non-zero (so default-band composites stay compact). The optional alpha channel adds `a` (and `band_a` when non-zero). `preset` is written only when `presetId` is non-null. The result is the inverse of `compositeFromUrl` for any composite whose band indices are valid.
+
+## Example
+
+```ts
+import {
+  PRESETS,
+  availablePresets,
+  applyPreset,
+  presetMatchesComposite,
+  compositeFromUrl,
+  compositeToUrl,
+} from '@walkthru-earth/objex-utils';
+
+// Which presets work on this item?
+const usable = availablePresets(assets); // subset of PRESETS
+
+// Apply False-Color IR if it resolves.
+const ir = PRESETS.find((p) => p.id === 'false-color-ir');
+const composite = ir ? applyPreset(assets, ir) : null;
+
+// Round-trip through the URL hash.
+if (composite) {
+  const params = compositeToUrl(composite, 'false-color-ir');
+  // 'r=B08&g=B04&b=B03&preset=false-color-ir'
+
+  const decoded = compositeFromUrl(params, assets); // ChannelComposite | null
+  const active = ir ? presetMatchesComposite(ir, composite, assets) : false; // true
+}
+```

package/docs/cog-asset.md

@@ -0,0 +1,164 @@
+# COG asset enumeration
+
+Vendor-neutral per-channel COG asset descriptors for the unified RGB picker. Pure TypeScript, no Svelte dependency. Reads `raster:bands.length` and `eo:bands` from STAC metadata without any network access.
+
+Source: `packages/objex-utils/src/cog-asset.ts`.
+
+`CogAsset` is the canonical shape every objex raster viewer (`CogViewer`, `MultiCogViewer`, `StacMosaicViewer`) hands to the shared ChannelPicker UI. The `self` key is used when the viewer is a single bare COG file with no STAC context.
+
+## Types
+
+### `CogAsset`
+
+```ts
+interface CogAsset {
+  key: string;
+  href: string;
+  bandCount: number;
+  bandCountKnown: boolean;
+  dtype?: string;
+  eoCommon: string[];
+  roles: string[];
+  title?: string;
+  mediaType?: string;
+}
+```
+
+| Field | Meaning |
+|-------|---------|
+| `key` | STAC asset key (`red`, `B04`, `image`, `visual`, ...), or `'self'` for a single bare COG without STAC context. |
+| `href` | Absolute or relative href as it appears in the STAC item / URL. |
+| `bandCount` | Number of bands in the asset. `1` by default until a band source is found or the COG header is probed. |
+| `bandCountKnown` | `true` when `bandCount` came from STAC metadata or a probe; `false` means the default `1` is a placeholder and the caller should lazily probe on first pick. |
+| `dtype` | `raster:bands[0].data_type` if known. |
+| `eoCommon` | `eo:bands[].common_name` (or unified `bands[].common_name`) lowercased, aligned to band-index order. Entries are `''` where no common name is present. |
+| `roles` | STAC asset roles (`data`, `visual`, `reflectance`, ...). |
+| `title` | Optional human title. |
+| `mediaType` | Asset media type as advertised by STAC. |
+
+### `ChannelRef`
+
+```ts
+interface ChannelRef {
+  assetKey: string;
+  bandIndex: number;
+}
+```
+
+A single per-channel pixel coordinate inside a STAC item: which asset, and which band within it.
+
+### `ChannelComposite`
+
+```ts
+interface ChannelComposite {
+  r: ChannelRef;
+  g: ChannelRef;
+  b: ChannelRef;
+  a?: ChannelRef;
+}
+```
+
+An RGB(A) composite, one `ChannelRef` per channel. The alpha channel is optional.
+
+## Functions
+
+### `extractCogAssets(item)`
+
+```ts
+function extractCogAssets(item: StacItem): CogAsset[]
+```
+
+Enumerate every TIFF/COG asset on a STAC Item, keeping multi-band assets (NAIP `image`, Sentinel-2 `visual` TCI) alongside single-band per-band assets.
+
+**Filtering** Only assets with an `href` and a TIFF/GeoTIFF media type (`image/tiff` or `image/geotiff`, case-insensitive) are kept. Assets whose `type` is absent are still kept. Assets whose roles include `thumbnail`, `overview`, or `metadata` are skipped.
+
+**`bandCount` source priority** (first present wins):
+
+1. `asset.bands` (STAC 1.1 unified bands array)
+2. `asset['raster:bands']` (STAC 1.0 raster extension)
+3. `asset['eo:bands']` (STAC 1.0 eo extension)
+4. `item.properties.bands` (STAC 1.1 item-level bands, applies to all assets that do not override their own)
+
+The item-level fallback covers catalogs (Hamilton NAIP-style 4-band COGs) which keep band metadata at the item-properties level while the single `data` asset carries none of its own. When none of the four sources yields a positive count, `bandCount` defaults to `1` with `bandCountKnown: false`.
+
+**`eoCommon` source** Independent of the `bandCount` source. Prefers `eo:bands` (the only field guaranteed to carry `common_name` before STAC 1.1), then the unified `bands`, then item-level `properties.bands`. `raster:bands` is skipped for this lookup because it typically has no `common_name`.
+
+**`dtype` source** First entry's `data_type` from `raster:bands`, then unified `bands`, then item-level `bands`.
+
+**Returns** `CogAsset[]`, in the order assets appear on the item.
+
+### `syntheticSelfAsset(href, probedBandCount?)`
+
+```ts
+function syntheticSelfAsset(href: string, probedBandCount?: number): CogAsset
+```
+
+Build a single synthetic asset with key `'self'` for `CogViewer` (a single bare COG file, no STAC context) so the same ChannelPicker UI works without special-casing.
+
+**Parameters**
+
+| Name | Type | Meaning |
+|------|------|---------|
+| `href` | `string` | The COG URL. |
+| `probedBandCount` | `number` (optional) | The probed `geotiff.count`, once known. |
+
+`bandCount` defaults to `1` with `bandCountKnown: false`. When `probedBandCount` is a positive number, `bandCount` is set to it and `bandCountKnown` becomes `true`. `eoCommon` and `roles` are empty arrays.
+
+### `pickNaturalColorComposite(assets)`
+
+```ts
+function pickNaturalColorComposite(
+  assets: CogAsset[]
+): { composite: ChannelComposite; source: 'visual-asset' | 'rgb-bands' | 'fallback' } | null
+```
+
+Pick the most natural and most performant default composite for an item.
+
+**Priority** (first match wins):
+
+1. **`'visual-asset'`** -- a 3-band pre-baked visual asset (`bandCount === 3` and either `roles` contains `visual` or `eoCommon` contains all of `red`/`green`/`blue`). All three channels bind to that one asset, using the `eoCommon` index for each color where present and falling back to bands 0/1/2. Single-layer path, one decoder, fastest.
+2. **`'rgb-bands'`** -- separate single-band assets resolvable by common name, where `eoCommon[0]` is `red`, `green`, and `blue` respectively across three distinct assets. Each channel binds to its asset at band 0.
+3. **`'fallback'`** -- the first three raster assets, band 0 each. When fewer than three assets exist, the single remaining asset is reused for all three channels: R at band 0, G at `min(1, last)`, B at `min(2, last)`, where `last = max(0, bandCount - 1)`.
+
+**Returns** `{ composite, source }`, or `null` when `assets` is empty.
+
+### `isSingleAssetComposite(c)`
+
+```ts
+function isSingleAssetComposite(c: ChannelComposite): boolean
+```
+
+`true` when all three RGB channels (`r`, `g`, `b`) target the same asset key. The optional alpha channel is not considered.
+
+### `allChannelsBand0(c)`
+
+```ts
+function allChannelsBand0(c: ChannelComposite): boolean
+```
+
+`true` when all three RGB channels are at band index `0` (the MultiCOGLayer-compatible case). The optional alpha channel is not considered.
+
+## Example
+
+```ts
+import {
+  extractCogAssets,
+  syntheticSelfAsset,
+  pickNaturalColorComposite,
+  isSingleAssetComposite,
+  allChannelsBand0,
+} from '@walkthru-earth/objex-utils';
+
+// From a STAC item:
+const assets = extractCogAssets(item);
+const pick = pickNaturalColorComposite(assets);
+if (pick) {
+  console.log(pick.source); // 'visual-asset' | 'rgb-bands' | 'fallback'
+  console.log(isSingleAssetComposite(pick.composite)); // true for a pre-baked visual
+  console.log(allChannelsBand0(pick.composite));        // true for the rgb-bands path
+}
+
+// From a single bare COG:
+const self = syntheticSelfAsset('https://example.com/scene.tif', 4);
+// { key: 'self', bandCount: 4, bandCountKnown: true, eoCommon: [], roles: [], ... }
+```

package/docs/cog.md

@@ -2,9 +2,9 @@
 
 Pure, framework-agnostic helpers for working with Cloud-Optimized GeoTIFF metadata and bounds. No Svelte, MapLibre, deck.gl, or GeoTIFF library dependency.
 
-Source: `src/lib/utils/cog.ts`.
+Source: `packages/objex-utils/src/cog-info.ts` (dependency-free subset). The app-side `src/lib/utils/cog.ts` re-exports these same bindings for in-repo consumers.
 
-> The render-pipeline helpers (`selectCogPipeline`, `createConfigurableGetTileData`, `normalizeCogGeotiff`, `createEpsgResolver`, `fitCogBounds`, `renderNonTiledBitmap`, etc.) live in the same source file but are **not** re-exported from `@walkthru-earth/objex-utils` because they pull in `@developmentseed/deck.gl-geotiff`, `@developmentseed/geotiff`, `@developmentseed/proj`, `proj4`, and `maplibre-gl`. If you need them, depend on the full Svelte package [`@walkthru-earth/objex`](https://www.npmjs.com/package/@walkthru-earth/objex) (they are re-exported from `src/lib/index.ts`) and install those optional peers yourself.
+> The render-pipeline helpers (`selectCogPipeline`, `createConfigurableGetTileData`, `normalizeCogGeotiff`, `createEpsgResolver`, `fitCogBounds`, `renderNonTiledBitmap`, etc.) live in `src/lib/utils/cog.ts` but are **not** re-exported from `@walkthru-earth/objex-utils` because they pull in `@developmentseed/deck.gl-geotiff`, `@developmentseed/geotiff`, `@developmentseed/proj`, `proj4`, and `maplibre-gl`. If you need them, depend on the full Svelte package [`@walkthru-earth/objex`](https://www.npmjs.com/package/@walkthru-earth/objex) (they are re-exported from `src/lib/index.ts`) and install those optional peers yourself.
 
 ## Types
 

package/docs/errors.md

@@ -2,7 +2,7 @@
 
 One function. Normalizes thrown values into a displayable string, with special-casing for `AbortError`.
 
-Source: `src/lib/utils/error.ts`.
+Source: `packages/objex-utils/src/error.ts`.
 
 ## `handleLoadError(err)`
 

package/docs/file-sort.md

@@ -2,7 +2,7 @@
 
 Sort a `FileEntry[]` with directories pinned on top. Pure — no mutation of the input.
 
-Source: `src/lib/utils/file-sort.ts`.
+Source: `packages/objex-utils/src/file-sort.ts`.
 
 ## Types
 

package/docs/formatting.md

@@ -4,10 +4,10 @@ Display formatters, column-type classification, hex dump, and data serialization
 
 Sources:
 
-- `src/lib/utils/format.ts`
-- `src/lib/utils/column-types.ts`
-- `src/lib/utils/hex.ts`
-- `src/lib/utils/export.ts`
+- `packages/objex-utils/src/format.ts`
+- `packages/objex-utils/src/column-types.ts`
+- `packages/objex-utils/src/hex.ts`
+- `packages/objex-utils/src/export.ts`
 
 ## Formatters
 

package/docs/geometry.md

@@ -2,7 +2,7 @@
 
 WKB parsing, geometry-column detection, and GeoArrow table construction. Zero-copy where possible.
 
-Source: `src/lib/utils/wkb.ts`, `src/lib/utils/geoarrow.ts`.
+Source: `packages/objex-utils/src/wkb.ts`, `packages/objex-utils/src/geoarrow.ts`.
 
 ## Types
 
@@ -51,7 +51,7 @@ type GeoArrowGeomType =
   | 'multipolygon';
 ```
 
-Lowercase normalized form used by the GeoArrow builder and `@geoarrow/deck.gl-layers`.
+Lowercase normalized form used by the GeoArrow builder and `@geoarrow/deck.gl-geoarrow`.
 
 ### `GeoArrowResult`
 
@@ -152,7 +152,7 @@ function buildGeoArrowTables(
 ): GeoArrowResult[]
 ```
 
-Build one or more Arrow `Table` objects keyed by geometry type, ready for `@geoarrow/deck.gl-layers`.
+Build one or more Arrow `Table` objects keyed by geometry type, ready for `@geoarrow/deck.gl-geoarrow`.
 
 **Parameters**
 

package/docs/local-storage.md

@@ -2,7 +2,7 @@
 
 SSR-safe JSON persistence on top of `window.localStorage`.
 
-Source: `src/lib/utils/local-storage.ts`.
+Source: `packages/objex-utils/src/local-storage.ts`.
 
 ## Functions