Spatialdata chart with associated layers dialog

AGENTS.md

@@ -20,3 +20,13 @@ Triage uses the default labels: `needs-triage`, `needs-info`, `ready-for-agent`,
 ### Domain docs
 
 Domain docs are configured as a single-context layout. See `.agents/domain.md`.
+
+### Spatial image channel controls
+
+For the SpatialData chart image layer panel (`ImageLayerPanel`, `ColorChannelComponents` spatial branch, `image_layer_runtime.ts`):
+
+- Contrast limits, tone, and histogram brush must update **immediately** — do not debounce these writes.
+- Persistence is MobX `renderStack` entry props (`channels`, `vivLayerProps`) via `useLayerChannelState` / `patchLayer`; the canvas reads those props through the Render Stack Adapter.
+- Per-panel zustand (`VivProvider`) is a one-way UI projection only, not a second persistence path.
+- If controls lag or the histogram brush fights itself, fix state ownership/wiring (see `docs/spatialdata-vis-integration.md` § Image channel controls). Debouncing here masks design problems.
+- Do not bump `renderStackGeneration` on in-place `props` patches (channels, tone, opacity); that recreates `vivPassthrough` and stalls the spatial renderer.

CONTEXT.md

@@ -39,4 +39,20 @@ detail, no decisions. Decisions that are hard to reverse live in `docs/adr/`.
 
 - **Installer / lockfile manager** — the tool that resolves, locks, and installs
   dependencies into an environment (e.g. `uv`, `pip`, `poetry`). Produces the lockfile
-  (`uv.lock`). Independent of the build backend.
+  (`uv.lock`). Independent of the build backend.
+
+## SpatialData.js integration terms
+
+Canonical rendering vocabulary lives in [SpatialData.js CONTEXT.md](https://github.com/Taylor-CCB-Group/SpatialData.js/blob/main/CONTEXT.md). MDV chart code uses the same terms:
+
+- **Render Stack** — saved draw order on chart config (`renderStack.entries`), not parallel `layerOrder` arrays
+- **Stack Entry** — one ordered item (`kind: spatial | host | group`)
+- **Host Overlay** — MDV deck layer referenced by `hostLayerId` in the stack, resolved at runtime
+- **Runtime Attachment** — `hostLayerResolver`, tooltip hooks, `deckProps`; not serialized in `entry.props`
+- **Image Layer Registry** — chart-owned runtime attachment (`SpatialDataMdvReact`): callbacks that expose loaded Viv image data (`getImageLoadedDataByElementKey`, load state) from the spatial renderer. The viewer populates it; the layer dialog consumes it via `ImageLayerContextProvider`. Bridges separate React trees (chart vs dialog portal) without duplicating image load paths.
+- **Spatial Image Panel Context** — React context on [`ImageLayerPanel`](src/react/components/spatialLayers/ImageLayerPanel.tsx): wraps `ImageLayerContextProvider` (upstream loaded-image defaults) and exposes `useLayerChannelState` write API (`setChannels`, `addChannel`, `removeChannel`) to channel UI. Persisted field edits go through the hook, not zustand `channelsStore`.
+- **Image Layer Runtime Bridge** — pure helpers in `image_layer_runtime.ts`: `channelId`-keyed stats cache (`domains`, `raster`), viewer parallel-array sync (`channelOptions`, loading flags), and tone → `vivLayerProps` helpers. Not a second MobX persistence bridge.
+- **MobX Control Island** — layer dialog UI that patches `config.renderStack` directly
+- **Layer Channel Config** — serializable image channel state on `renderStack.entries[].props.channels` (`ChannelConfig` in `@spatialdata/vis`): colors, contrast limits, visibility, selections, and extension-related data fields. Tone (brightness/contrast) is **not** part of `channels`; it persists in `entry.props.vivLayerProps`. Distinct from runtime UI state in avivatorish stores.
+- **Root Viv Config** — MDV-only legacy path where `VivMdvReact` serializes `config.viv.channelsStore` on the chart root. Not used by the SpatialData chart; not an upstream SpatialData.js concern.
+- **App Viv Extensions** — runtime attachment: host app supplies Viv `LayerExtension` instances (and passes related props into the renderer). Extension classes are not serialized; extension data may live on Layer Channel Config when persistence is needed.

package.json

@@ -95,6 +95,11 @@
     "@radix-ui/react-radio-group": "^1.1.3",
     "@react-spring/web": "^10.0.3",
     "@slickgrid-universal/common": "10.6.0",
+    "@spatialdata/avivatorish": "^0.2.5",
+    "@spatialdata/core": "^0.2.5",
+    "@spatialdata/layers": "^0.2.5",
+    "@spatialdata/react": "^0.2.5",
+    "@spatialdata/vis": "^0.2.5",
     "@tanstack/react-query": "^5.80.0",
     "@tanstack/react-virtual": "^3.11.1",
     "@turf/clone": "6.5.0",
@@ -171,6 +176,7 @@
     "use-debounce": "^10.0.2",
     "uuid": "^11.1.1",
     "wordcloud": "^1.2.2",
+    "zarrextra": "^0.2.3",
     "zod": "^3.25.49",
     "zustand": "^5.0.6"
   },