@dclimate/zarr-map 0.1.0

package/docs/api-design.md

@@ -0,0 +1,185 @@
+# API Design
+
+The package is built around a normalized `GridDataSource`. Renderers, adapters,
+selectors, query helpers, and React components all consume the same contract.
+
+## Core Contract
+
+`GridDataSource` contains:
+
+- `variables`: numeric Zarr/Jaxray variables with dtype, dimensions, shape,
+  chunks, units, fill values, and scale/offset metadata.
+- `dimensions`: named axes with size, kind, coordinate values, units, calendar,
+  coordinate orientation, and optional bounds.
+- `spatialDimensions`: explicit `{ x, y }` mapping when aliases such as `lon`
+  and `lat` are not enough.
+- `bounds`, `crs`, and optional `proj4` for renderer placement.
+- `source` or `store`: an HTTP Zarr URL or a structural Jaxray/Zarrita readable
+  store.
+- Optional `readSlice` and `queryGeometry` hooks for query helpers.
+
+Validation is available through `validateGridDataSource` and
+`assertValidGridDataSource`. Validation errors use `GridError` codes such as
+`MISSING_SPATIAL_DIMENSIONS`, `MISSING_COORDINATES`, and `UNSUPPORTED_DTYPE` so
+applications can show actionable failures.
+
+## Selectors
+
+Selectors preserve intent:
+
+```ts
+import { indexSelector, isoTimeSelector } from "@dclimate/zarr-map/core";
+
+const selectors = {
+  time: isoTimeSelector("2024-01-01T00:00:00.000Z"),
+  month: 1,
+  band: indexSelector(0)
+};
+```
+
+Bare numbers are coordinate values. Numeric indexes must use
+`indexSelector(index)`. Before rendering, selectors are converted to
+`@carbonplan/zarr-layer` selector objects with `type: "value"` or
+`type: "index"`.
+
+## Generic Jaxray Example
+
+```ts
+import { createJaxraySource } from "@dclimate/zarr-map/core";
+
+const source = createJaxraySource(dataset, {
+  bounds: [-10, 35, 5, 45],
+  spatialDimensions: { x: "lon", y: "lat" }
+});
+```
+
+The adapter accepts Jaxray-like datasets or data arrays with `data_vars`,
+`coords`, `dims`, `shape`, `dtype`, and `attrs`. Users can override inferred
+dimension or variable metadata when datasets omit required renderer fields.
+
+## dClimate Example
+
+```ts
+import { createDClimateSource } from "@dclimate/zarr-map/dclimate";
+
+const source = await createDClimateSource(
+  {
+    collection: "ecmwf_era5",
+    dataset: "temperature_2m",
+    variant: "finalized"
+  },
+  {
+    gatewayUrl: "https://ipfs-gateway.dclimate.net"
+  }
+);
+```
+
+React callers should prefer the `DClimateZarrMap` convenience component when
+they already know the dataset, variable, bounds, and time window:
+
+```tsx
+<DClimateZarrMap
+  bounds={[-12, 35, 16, 60]}
+  dataset={{
+    collection: "ecmwf_era5",
+    dataset: "temperature_2m",
+    variant: "finalized"
+  }}
+  map={mapConfig}
+  timeRange={{
+    start: "2024-01-01T00:00:00Z",
+    end: "2024-01-07T23:00:00Z"
+  }}
+  variable="2m_temperature"
+/>
+```
+
+`bounds` and `timeRange` normalize into `sourceOptions.selection`; lower-level
+callers can still pass `sourceOptions.selection` directly.
+
+The validated dClimate fixture uses variable `2m_temperature` and CID
+`bafyr4ifr5jtjeommsulg7srirdkskybj5pay3n4qyehecyzsesas5k2kd4`. The dClimate
+adapter should call `DClimateClient.loadDataset({ request, options })` and
+unwrap the returned `[Dataset, metadata]` tuple before normalizing the source.
+
+`@dclimate/dclimate-client-js` and `@dclimate/jaxray` are optional peer
+dependencies. Generic users can use `@dclimate/zarr-map/core` without installing
+the dClimate client stack.
+
+## Renderer Example
+
+```ts
+import { createMapLibreGridLayer } from "@dclimate/zarr-map/renderer";
+
+const controller = createMapLibreGridLayer({
+  map,
+  source,
+  variable: "temperature",
+  selectors: { time: { kind: "index", index: 0 } },
+  colorScale: { palette: "viridis", domain: [260, 320], unit: "K" }
+});
+
+await controller.mount();
+await controller.update({ selectors: { time: { kind: "index", index: 1 } } });
+controller.remove();
+```
+
+The renderer can attach to a caller-owned MapLibre map or create a map from
+`mapConfig`. Selector and color updates call runtime layer methods instead of
+recreating the map.
+
+`colorScale.palette` accepts built-in palette names or caller-provided color
+stop arrays. Built-ins include semantic weather palettes such as `temperature`,
+`precipitation`, `humidity`, `vegetation`, and `wind`; `magma`,
+`precipitation`, and `vegetation` begin transparent at the lower bound for
+overlay rendering. Renderer domains remain in source units. Legend and inspect
+display can convert supported temperature and precipitation units when `unit`,
+`displayUnit`, and `quantity` are provided.
+
+React inspect controls support the legacy click panel via
+`controls={{ inspect: true }}` and a pointer-following hover tooltip via
+`controls={{ inspect: { mode: "hover" } }}`.
+
+## Query Example
+
+```ts
+import { queryGrid, queryPoint } from "@dclimate/zarr-map/core";
+
+const point = await queryPoint(source, "temperature", [-8.6, 39.5], {
+  time: "2024-01-01T00:00:00.000Z"
+});
+
+const box = await queryGrid({
+  source,
+  variable: "temperature",
+  geometry: { type: "BoundingBox", bounds: [-9, 38, -8, 40] },
+  maxCells: 5000
+});
+```
+
+Bounded and polygon queries enforce a `maxCells` limit. Polygon queries scan the
+polygon bounding box and return a warning in the result.
+
+## Preflight Example
+
+```ts
+import { preflightGridRequest } from "@dclimate/zarr-map/core";
+
+const preflight = preflightGridRequest({
+  bounds: [-12, 35, 16, 60],
+  limits: {
+    maxBytes: 256 * 1024 * 1024,
+    maxCells: 100_000
+  },
+  source,
+  timeRange: {
+    start: "2024-01-01T00:00:00Z",
+    end: "2024-01-07T23:00:00Z"
+  },
+  variable: "2m_temperature"
+});
+```
+
+Preflight uses only source metadata. It estimates selected dimension sizes,
+cell count, and uncompressed bytes when dtype size is known; it does not call
+`readSlice`, `queryGeometry`, `sel`, or `compute`.

package/docs/architecture.md

@@ -0,0 +1,246 @@
+# Architecture: Renderer Compatibility
+
+Date: 2026-06-09
+
+## Recommendation
+
+Use MapLibre GL JS with `@carbonplan/zarr-layer` as the primary MVP renderer. Build the package around a normalized `GridDataSource` contract, then adapt dClimate/Jaxray-backed datasets into the `zarrita.Readable` store shape accepted by `ZarrLayer`.
+
+Do not pass a dClimate `GeoTemporalDataset` or Jaxray `Dataset` directly to the renderer. The renderer bridge should pass either:
+
+- `source: "https://.../dataset.zarr"` for conventional HTTP/S3 Zarr stores.
+- `store: jaxrayStore` for dClimate IPFS datasets opened with `openIpfsStore(cid, options)`.
+
+The dClimate gateway is not generally down. A current STAC ERA5 fixture opens through `https://ipfs-gateway.dclimate.net` using dClimate client plus Jaxray. The static CIDs that timed out during the first spike should be treated as stale or unretrievable fixtures, not proof that the gateway or Jaxray are broken. Jaxray `ShardedStore` and `HamtStore` expose the `get(key)` method, and sometimes `getRange(key, range)`, that `@carbonplan/zarr-layer` requires for custom stores.
+
+## Renderer Path
+
+The MVP data flow should be:
+
+```txt
+dClimate request or direct CID
+  -> DClimateClient.loadDataset({ request, options }) resolves [Dataset, metadata]
+  -> adapter unwraps the Dataset and metadata tuple
+  -> openIpfsStore(cid, { gatewayUrl | ipfsElements })
+  -> validate and normalize GridDataSource metadata
+  -> new ZarrLayer({
+       id,
+       store,
+       variable,
+       selector,
+       spatialDimensions: { lon, lat },
+       zarrVersion,
+       crs | proj4,
+       bounds,
+       fillValue,
+       colormap,
+       clim
+     })
+  -> map.addLayer(layer)
+```
+
+For non-dClimate HTTP stores, skip the dClimate/Jaxray step and pass a URL as `source`.
+
+## Compatibility Findings
+
+### `@carbonplan/zarr-layer`
+
+`@carbonplan/zarr-layer` 0.5.0 is the best default fit because it is already a MapLibre/Mapbox custom layer, supports Zarr v2 and v3 through `zarrita`, accepts custom stores, supports selectors, has runtime color/selector updates, exposes loading callbacks, and includes `queryData` for point and polygon inspection.
+
+Important constraints:
+
+- High-resolution datasets need multiscale metadata or practical chunking. Single-level arrays may work only for small datasets.
+- Tiled data must be in EPSG:4326 or EPSG:3857. Untiled data can use `proj4`, but explicit `bounds` are strongly recommended.
+- Selectors are exact by value unless explicitly passed as `{ selected, type: "index" }`.
+- `setSelector` can trigger a fetch per call, so time slider updates must be debounced.
+- The package is explicitly described as experimental, so pin exact versions for the MVP.
+
+### `@dclimate/dclimate-client-js`
+
+`@dclimate/dclimate-client-js` 0.5.5 resolves dClimate dataset requests, supports direct CID loading, has browser and Node builds, and uses `@dclimate/jaxray` for IPFS-backed Zarr access. It should be optional for users who only use generic grid-source mode.
+
+The adapter should call the real `DClimateClient.loadDataset({ request, options })` API, pass gateway and Jaxray options through `options`, request a Jaxray dataset when supported, and unwrap the returned `[Dataset, metadata]` tuple. For rendering, the useful output is the resolved CID, the Jaxray dataset metadata, and the underlying Jaxray/IPFS store, not the higher-level geotemporal selection wrapper.
+
+### `@dclimate/jaxray`
+
+`@dclimate/jaxray` 0.6.9 can open IPFS-hosted Zarr datasets from one CID and auto-detect `sharded` or `hamt` stores. Its stores are structurally compatible with `zarrita.Readable`:
+
+- `ShardedStore.get(key): Promise<Uint8Array | undefined>`
+- `HamtStore.get(key): Promise<Uint8Array | undefined>`
+- `HamtStore.getRange(key, range): Promise<Uint8Array | undefined>`
+- `listMetadataKeys()` for metadata discovery in Jaxray's own backend
+
+The adapter should not assume TypeScript package identity between Jaxray's `zarrita` dependency and `zarr-layer`'s `zarrita` dependency. Treat store compatibility as structural and validate at runtime.
+
+### MapLibre GL JS
+
+MapLibre GL JS is still the correct base map. `ZarrLayer` implements MapLibre's custom-layer model, so it can be inserted into the normal map layer stack and render directly into the map WebGL context.
+
+### deck.gl Alternatives
+
+Core deck.gl provides `BitmapLayer` and `TileLayer`, which can be composed into a raster renderer but do not by themselves understand Zarr metadata.
+
+`@developmentseed/deck.gl-zarr` 0.7.0 is a real Zarr option. It renders GeoZarr datasets with deck.gl, uses `zarrita`, and builds on `@developmentseed/deck.gl-raster`. It is a credible fallback, especially if the project later needs deck.gl's broader layer ecosystem. It is not the MVP default because it requires a deck.gl runtime, caller-supplied `getTileData` and `renderTile` callbacks, and stricter GeoZarr metadata/selection constraints than `@carbonplan/zarr-layer`.
+
+## Proof Of Concept Results
+
+### dClimate Gateway Validation
+
+Validated on 2026-06-09 with the sibling `../dclimate-client-js-autoresearch`
+project. Its smoke benchmark still works through `@dclimate/dclimate-client-js`
+and `@dclimate/jaxray` against the current STAC CID.
+
+Current validated fixture:
+
+- collection: `ecmwf_era5`
+- dataset: `temperature_2m`
+- variant: `finalized`
+- variable: `2m_temperature`
+- CID: `bafyr4ifr5jtjeommsulg7srirdkskybj5pay3n4qyehecyzsesas5k2kd4`
+- gateway: `https://ipfs-gateway.dclimate.net`
+
+The current CID returned successful gateway root and range probes, opened as a
+Jaxray store, and loaded through `DClimateClient.loadDataset({ request, options })`.
+
+### Stale dClimate CID attempts
+
+Tested the static CIDs bundled in `@dclimate/dclimate-client-js`:
+
+- `cpc-precip-conus`: `bafyr4iff6vuvpkb4zexkx7exoafsjvfnno4ofidyc37gsto2aaxixg5zia`
+- `cpc-precip-global`: `bafyr4ihe35o55qz47y2dbau6ikvfkbrthqn57pdhem5jdxhvqf5u7qlrbm`
+- `chirps-final-p05`: `bafyr4ic2n63fkxdvwgh2uzealcrbeubncivcqaptttfrr4vp5ecbe5e65a`
+
+Observed results:
+
+- `openIpfsStore` stalled on the first CID through `https://ipfs-gateway.dclimate.net`.
+- Bounded `curl` GET/HEAD requests to the same gateway timed out with zero bytes for tested root CIDs.
+- `w3s.link` returned CORS headers on redirect and preflight, but followed requests ended in timeout or `504`.
+- `https://ipfs-gateway.dclimate.net` returned permissive CORS preflight headers, including `Range`, `Content-Range`, and IPFS headers, but data fetches still timed out.
+
+Conclusion: these static CIDs are stale or unretrievable through the tested
+gateways. They should not be used as proof that the gateway or Jaxray are
+broken, and they should not be used as the first public dClimate fixture.
+
+### Control Zarr read
+
+The CarbonPlan demo store at `https://carbonplan-maps.s3.us-west-2.amazonaws.com/v2/demo/4d/tavg-prec-month` was readable with `zarrita`:
+
+- `.zmetadata`: HTTP 200 with browser CORS when an `Origin` header is sent.
+- Chunk range request: HTTP 206 with browser CORS.
+- Opened array `2/climate`:
+  - shape: `[2, 12, 512, 512]`
+  - chunks: `[2, 12, 128, 128]`
+  - dimensions: `["band", "month", "y", "x"]`
+  - fill value: `9.969209968386869e+36`
+  - month coordinate values: `1` through `12`
+
+This validates the `zarr-layer`/`zarrita` renderer path for browser-compatible Zarr stores.
+
+## Required Dataset Metadata
+
+The normalized source contract must require or derive the following before creating a renderer layer.
+
+### Variable
+
+- Variable name or path inside the Zarr hierarchy.
+- Numeric dtype supported by `zarrita` and WebGL texture upload path.
+- Shape, chunks, and dimension order.
+- Fill value from Zarr metadata, `_FillValue`, or explicit config.
+- Optional `scale_factor` and `add_offset`; if present, query and render paths should apply them consistently.
+- Units, long name, and standard name when available for legends and tooltips.
+
+### Dimensions
+
+- Ordered dimension names from Zarr v3 `dimension_names` or Zarr v2 `_ARRAY_DIMENSIONS`.
+- Core spatial dimensions mapped to `{ x, y }`, accepting common aliases such
+  as `lat`, `latitude`, `y`, `lon`, `longitude`, `x`, and `lng`. The renderer
+  adapter converts this to CarbonPlan's `spatialDimensions: { lon, lat }`
+  option.
+- Non-spatial dimensions such as `time`, `band`, `member`, `scenario`, or `level`.
+- Size for each dimension and whether the dimension has a coordinate array.
+
+### Coordinates
+
+- Coordinate arrays for all selector dimensions when value-based selection is exposed.
+- Spatial coordinate arrays, bounds, or affine metadata sufficient to locate pixels.
+- Latitude orientation (`latIsAscending`) when it cannot be inferred safely.
+- Longitude convention, especially `[-180, 180]` versus `[0, 360]`.
+- Time coordinate raw values plus decoded ISO strings when decoding is possible.
+
+### CRS And Bounds
+
+- CRS as `EPSG:4326`, `EPSG:3857`, or a full `proj4` definition.
+- Explicit edge bounds `[xMin, yMin, xMax, yMax]`, especially for projected or untiled datasets.
+- For tiled datasets, confirm the CRS is EPSG:4326 or EPSG:3857.
+- For nonstandard projections, require `proj4` and explicit bounds.
+
+### Zarr Format And Codecs
+
+- Zarr format version, preferably explicit as `2` or `3`.
+- Consolidated metadata availability when applicable.
+- Codec list. Register aliases for `numcodecs.*` names before opening the renderer if a dataset uses them.
+
+### Network
+
+- Browser CORS support for metadata and chunk URLs.
+- Range request support and exposed `Content-Range` headers when range reads are used.
+- Gateway timeout and retry behavior.
+- Authentication/header behavior through `transformRequest` or custom store injection.
+
+## Time Selector Representation
+
+Use a normalized internal selector model that preserves intent:
+
+```ts
+type NormalizedSelector =
+  | { kind: "coordinate"; value: number | string }
+  | { kind: "index"; index: number }
+  | { kind: "isoTime"; iso: string };
+```
+
+Rules:
+
+- Public API should prefer coordinate values and ISO strings for time.
+- Numeric indexes are supported only when explicitly marked as indexes.
+- Bare numeric selector values are treated as coordinate values first, not indexes.
+- Before passing selectors to `ZarrLayer`, convert:
+  - coordinate values to `{ selected: value, type: "value" }`
+  - numeric indexes to `{ selected: index, type: "index" }`
+  - ISO strings to the dataset's actual time coordinate value when possible
+- If the dataset time coordinate is already an ISO/string coordinate, pass the ISO value as a value selector.
+- If the dataset time coordinate is numeric CF time, decode enough metadata to map ISO input to the numeric coordinate value. Exact matching is the MVP behavior.
+- Arrays are supported for query/time-series selectors and custom-shader bands, but normal map rendering should use one selected value per non-spatial dimension unless a renderer-specific multi-band shader is configured.
+
+This avoids the ambiguity in `zarr-layer` where a simple numeric selector may match a coordinate value first and fall back to an index.
+
+## Follow-Up Work
+
+- `todo/011-validate-dclimate-browser-gateway-fixture.md`: keep the current STAC dClimate fixture and gateway validation record up to date.
+- `todo/002-core-grid-data-source-contract.md`: encode the metadata requirements and selector model above.
+- `todo/003-renderer-adapter.md`: implement the MapLibre plus `ZarrLayer` bridge, including debounced selector updates and typed load errors.
+
+## Ticket 011 Revalidation
+
+Ticket 011 revalidation found that the dClimate gateway works for the current
+STAC ERA5 fixture:
+`bafyr4ifr5jtjeommsulg7srirdkskybj5pay3n4qyehecyzsesas5k2kd4`. The sibling
+`../dclimate-client-js-autoresearch` project still works with dClimate client
+plus Jaxray, and its smoke benchmark succeeded on that CID.
+
+The static CIDs tested during the renderer research still timed out or returned
+gateway errors and should be documented as stale or unretrievable. The adapter
+should use `DClimateClient.loadDataset({ request, options })`, unwrap
+`[Dataset, metadata]`, and use the metadata CID with
+`openIpfsStore(cid, { gatewayUrl })` when a renderer store is needed. The
+current validation record is checked in at
+`fixtures/dclimate-gateway-validation.json`.
+
+## Sources Inspected
+
+- `@carbonplan/zarr-layer` 0.5.0 README and type definitions: https://github.com/carbonplan/zarr-layer
+- `@dclimate/dclimate-client-js` 0.5.5 README and type definitions: https://github.com/dClimate/dclimate-client-js
+- `@dclimate/jaxray` 0.6.9 README and type definitions: https://github.com/dClimate/jaxray
+- MapLibre GL JS custom layer documentation: https://maplibre.org/maplibre-gl-js/docs/API/interfaces/CustomLayerInterface/
+- deck.gl `BitmapLayer` and `TileLayer` documentation: https://deck.gl/docs/api-reference/layers/bitmap-layer and https://deck.gl/docs/api-reference/geo-layers/tile-layer
+- `@developmentseed/deck.gl-zarr` 0.7.0 package README and type definitions: https://github.com/developmentseed/deck.gl-raster
+- Zarr v2 and v3 specs: https://zarr.readthedocs.io/en/v2.13.6/spec/v2.html and https://zarr-specs.readthedocs.io/en/latest/v3/core/index.html

package/docs/decision-record-renderer.md

@@ -0,0 +1,144 @@
+# Decision Record: Renderer Selection
+
+Date: 2026-06-09
+
+## Status
+
+Accepted for MVP. Ticket `011` validated a current STAC dClimate fixture through
+the dClimate gateway; old static CIDs from the first spike remain stale or
+unretrievable and should not be used as public fixtures.
+
+## Context
+
+`@dclimate/zarr-map` needs to render dClimate and generic Zarr/Jaxray gridded climate datasets on an interactive map. The package direction already prefers MapLibre GL JS and wants to avoid a custom WebGL renderer unless existing renderers cannot support the target datasets.
+
+The renderer must support:
+
+- Browser-compatible Zarr chunk and metadata loading.
+- Time and other non-spatial selectors.
+- Latitude/longitude grids and projected grids.
+- Color scale, opacity, loading, error, cleanup, and query behavior.
+- dClimate IPFS stores opened through Jaxray.
+
+## Decision
+
+Use `@carbonplan/zarr-layer` as the primary renderer behind a renderer adapter. Keep deck.gl Zarr support as a fallback path, and do not build a custom raster renderer for the MVP.
+
+For dClimate datasets, do not rely on `source: "https://gateway/ipfs/<cid>"`
+alone unless the CID is a conventional directory-style Zarr store. The realistic
+path is:
+
+```txt
+DClimateClient.loadDataset({ request, options })
+  -> [Dataset, metadata]
+  -> metadata.cid
+  -> openIpfsStore
+  -> Jaxray store
+  -> ZarrLayer({ store, spatialDimensions: { lon, lat }, ... })
+```
+
+`@carbonplan/zarr-layer` can render target dClimate datasets through a realistic
+adapter when the dataset exposes renderer-compatible metadata and chunks through
+a responsive browser gateway. On 2026-06-09, the current STAC ERA5
+`ecmwf_era5/temperature_2m/finalized` fixture loaded through
+`https://ipfs-gateway.dclimate.net`; its validated CID is
+`bafyr4ifr5jtjeommsulg7srirdkskybj5pay3n4qyehecyzsesas5k2kd4`. The bundled
+static CIDs tested during the first spike timed out or returned `504`, so treat
+those as stale fixture choices rather than proof that Jaxray or the gateway are
+broken.
+
+## Options Compared
+
+| Option                                    | Fit              | Pros                                                                                                                                                                 | Constraints                                                                                                                                                                    | Decision                                                               |
+| ----------------------------------------- | ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------- |
+| MapLibre GL JS + `@carbonplan/zarr-layer` | Strong           | Native MapLibre/Mapbox custom layer; Zarr v2/v3 via `zarrita`; accepts custom `Readable` stores; selectors, color updates, loading state, queries, CRS/proj4 support | Experimental package; high-res data needs multiscales or practical chunking; exact selector matching; dClimate CID path needs Jaxray custom store and a current pinned fixture | Primary MVP renderer                                                   |
+| deck.gl core raster path                  | Medium           | Mature visualization stack; `TileLayer` and `BitmapLayer` can render tiled raster products; broad layer ecosystem                                                    | Core layers do not understand Zarr metadata; requires building tile/chunk loading, pixel conversion, color mapping, and MapLibre overlay integration                           | Not MVP default                                                        |
+| `@developmentseed/deck.gl-zarr`           | Medium to strong | Current package for GeoZarr rendering; uses `zarrita`; handles tiling and reprojection through `@developmentseed/deck.gl-raster`; caller-owned store                 | Adds deck.gl/luma runtime; requires caller-supplied `getTileData` and `renderTile`; expects GeoZarr metadata and strict selection/spatial-dim layout                           | Keep as fallback or future adapter                                     |
+| Custom renderer                           | Weak for MVP     | Full control over Jaxray, time selection, shader logic, and query APIs                                                                                               | Highest implementation and testing cost; must solve projection, tiling, caching, WebGL lifecycle, color mapping, and queries from scratch                                      | Defer unless existing renderers fail after gateway/metadata validation |
+
+## Why `@carbonplan/zarr-layer`
+
+The package directly matches the intended MapLibre architecture. It implements a custom layer, can be added with `map.addLayer`, accepts either `source` or a custom `store`, and exposes runtime methods such as `setSelector`, `setVariable`, `setClim`, `setColormap`, and `queryData`.
+
+The custom-store requirement is the key compatibility point. `ZarrLayerOptions.store` requires a `zarrita.Readable` with at least `get(key)`. Jaxray's IPFS stores expose that shape, so the bridge can adapt dClimate CIDs without repackaging datasets.
+
+## Required Adapter Behavior
+
+The renderer adapter must:
+
+- Open dClimate CIDs with `openIpfsStore` rather than passing gateway CID URLs directly to `ZarrLayer`.
+- Validate that the selected variable is numeric and has exactly two spatial dimensions.
+- Normalize core `{ x, y }` spatial dimension names into CarbonPlan's
+  `spatialDimensions: { lon, lat }` option when aliases are not enough.
+- Pass only non-spatial selectors to `ZarrLayer`; latitude and longitude remain
+  render axes.
+- Pass explicit `zarrVersion` when known.
+- Pass `fillValue`, `crs`, `proj4`, `bounds`, and `latIsAscending` when inferred metadata is missing or ambiguous.
+- Debounce rapid selector changes before calling `setSelector`.
+- Surface metadata, chunk, CORS, timeout, codec, and projection failures as typed load errors.
+- Keep renderer lifecycle separate from React and map ownership.
+
+## Time Selector Decision
+
+Support coordinate values, ISO strings, and numeric indexes, but keep them distinct internally.
+
+Use this internal intent model:
+
+```ts
+type NormalizedSelector =
+  | { kind: "coordinate"; value: number | string }
+  | { kind: "index"; index: number }
+  | { kind: "isoTime"; iso: string };
+```
+
+For `@carbonplan/zarr-layer`:
+
+- Coordinate values become `{ selected: value, type: "value" }`.
+- Numeric indexes become `{ selected: index, type: "index" }`.
+- ISO strings become exact coordinate values after time normalization.
+
+Bare numbers in public APIs should not silently mean indexes. They should mean numeric coordinate values unless the user uses an explicit index selector. This avoids ambiguity for dimensions where coordinate values are also integers, such as `month: 1`.
+
+## Metadata Contract Required Before Rendering
+
+The core source contract must require:
+
+- Variable name/path, dtype, shape, chunks, dimensions, units, fill value, optional `scale_factor`, and optional `add_offset`.
+- Dimension names from v2 `_ARRAY_DIMENSIONS` or v3 `dimension_names`.
+- Coordinate arrays for time and every value-selectable non-spatial dimension.
+- Spatial dimension mapping, coordinate orientation, and longitude convention.
+- CRS as EPSG code or `proj4`, plus explicit edge bounds when projected or untiled.
+- Zarr format version and codec requirements.
+- Browser-reachable metadata/chunk URLs or a custom store with equivalent access.
+
+## Consequences
+
+Positive:
+
+- MVP implementation can stay focused on adapters and validation rather than low-level raster rendering.
+- The renderer remains MapLibre-first and can attach to existing user maps.
+- The same normalized source can support both dClimate and generic Zarr/Jaxray use cases.
+
+Negative:
+
+- The package inherits `@carbonplan/zarr-layer`'s experimental status and exact selector semantics.
+- Direct dClimate CID rendering depends on gateway responsiveness, CORS, IPFS layout, and using a current pinned CID.
+- Some dClimate datasets may need metadata overrides or preprocessing before they are renderer-compatible.
+
+## Follow-Up Tickets
+
+- `todo/011-validate-dclimate-browser-gateway-fixture.md`
+- `todo/002-core-grid-data-source-contract.md`
+- `todo/003-renderer-adapter.md`
+
+## References
+
+- `@carbonplan/zarr-layer`: https://github.com/carbonplan/zarr-layer
+- `@dclimate/dclimate-client-js`: https://github.com/dClimate/dclimate-client-js
+- `@dclimate/jaxray`: https://github.com/dClimate/jaxray
+- MapLibre custom layers: https://maplibre.org/maplibre-gl-js/docs/API/interfaces/CustomLayerInterface/
+- deck.gl `BitmapLayer`: https://deck.gl/docs/api-reference/layers/bitmap-layer
+- deck.gl `TileLayer`: https://deck.gl/docs/api-reference/geo-layers/tile-layer
+- `@developmentseed/deck.gl-zarr`: https://github.com/developmentseed/deck.gl-raster
+- Zarr v2 spec: https://zarr.readthedocs.io/en/v2.13.6/spec/v2.html
+- Zarr v3 spec: https://zarr-specs.readthedocs.io/en/latest/v3/core/index.html

package/docs/package-boundaries.md

@@ -0,0 +1,50 @@
+# Package Boundaries
+
+`@dclimate/zarr-map` is a light map-rendering wrapper. It should make a known
+dClimate-compatible Zarr dataset easy to render on MapLibre, without becoming a
+marketplace, dashboard, or explorer application.
+
+## Belongs Here
+
+- React and non-React APIs for rendering normalized gridded sources on maps.
+- dClimate dataset request adaptation into `GridDataSource`.
+- Passing caller-provided bounds and time ranges into dClimate loading.
+- Jaxray/Zarr metadata normalization needed by the renderer.
+- MapLibre layer setup, updates, loading state, errors, and teardown.
+- Selector normalization for time, band, and other non-spatial dimensions.
+- Light visual customization: palette or gradient, color domain, opacity,
+  display unit, legend, time selector, and inspect callbacks.
+- Request preflight that estimates cells and bytes before unsuitable render jobs
+  begin expensive bounded loading.
+
+## Belongs Upstream
+
+Prefer `@dclimate/dclimate-client-js` or another dClimate data package for:
+
+- Catalog lookup and dataset discovery.
+- Authentication or access-gated dataset retrieval.
+- Decryption codec registration and key handling.
+- IPFS and gateway store opening improvements.
+- Slicing APIs that are generally useful outside map rendering.
+- Dataset metadata repair or standardization.
+
+## Belongs In Consuming Apps
+
+- Marketplace purchase flow.
+- Wallet or order state.
+- User-facing decryption UX.
+- CSV or JSON export workflows.
+- 2D charts and aggregation dashboards.
+- Modal layouts and dashboard pages.
+- Coordinate entry forms and calendars.
+- Map drawing or editing workflows unless accepted later as a small optional
+  primitive.
+
+## Dependency Guardrails
+
+Package source must not import app-level dependencies such as `@apollo/client`,
+wallet or ethers packages, `eciesjs`, `libsodium`, `next`, dClimate frontend
+theme/component packages, `mapbox-gl`, `streamsaver`, or `chart.js`.
+
+The test suite includes a lightweight boundary check for `package.json` and
+`src/**` imports.

package/docs/release-checklist.md

@@ -0,0 +1,31 @@
+# Release Checklist
+
+- `npm run typecheck`
+- `npm run format:check`
+- `npm run lint`
+- `npm run test`
+- `npm run build`
+- Confirm package output is ESM/CJS with declaration files in `dist`.
+- Confirm the separate demo app builds against the package:
+  `cd ../zarr-map-demo && npm ci && npm run build`.
+- Confirm peer dependencies are installed by the consuming app:
+  - `maplibre-gl`
+  - `@carbonplan/zarr-layer`
+  - `react` and `react-dom` for React components
+  - `@dclimate/dclimate-client-js` and `@dclimate/jaxray` for dClimate mode
+- Confirm dClimate mode still loads the validated current STAC fixture through
+  `https://ipfs-gateway.dclimate.net`:
+  `ecmwf_era5/temperature_2m/finalized`, variable `2m_temperature`, CID
+  `bafyr4ifr5jtjeommsulg7srirdkskybj5pay3n4qyehecyzsesas5k2kd4`.
+- Confirm the adapter uses `DClimateClient.loadDataset({ request, options })`
+  and unwraps the returned `[Dataset, metadata]` tuple.
+- `package.json` is publishable and does not set `private: true`.
+
+Known MVP renderer limitations:
+
+- `@carbonplan/zarr-layer` is experimental and should remain pinned at `0.5.0`.
+- High-resolution datasets need practical chunking or multiscale metadata.
+- Selector values require exact coordinate matches after normalization.
+- The dClimate gateway is not generally down; the current STAC ERA5 fixture
+  works. Static CIDs from the first spike timed out and should be described as
+  stale or unretrievable fixtures.