Taylor-CCB-Group · xinaesthete · Jun 8, 2026 · Jun 8, 2026 · Jun 8, 2026
diff --git a/.changeset/config.json b/.changeset/config.json
@@ -0,0 +1,28 @@
+{
+  "$schema": "https://unpkg.com/@changesets/config@3.1.1/schema.json",
+  "changelog": [
+    "@changesets/changelog-github",
+    {
+      "repo": "Taylor-CCB-Group/SpatialData.js"
+    }
+  ],
+  "commit": false,
+  "fixed": [
+    [
+      "@spatialdata/core",
+      "@spatialdata/react",
+      "@spatialdata/layers",
+      "@spatialdata/avivatorish",
+      "@spatialdata/vis"
+    ]
+  ],
+  "linked": [],
+  "access": "public",
+  "baseBranch": "main",
+  "updateInternalDependencies": "patch",
+  "ignore": [],
+  "privatePackages": {
+    "version": false,
+    "tag": false
+  }
+}
diff --git a/.changeset/mdv-prerelease.md b/.changeset/mdv-prerelease.md
@@ -0,0 +1,10 @@
+---
+"zarrextra": minor
+"@spatialdata/core": minor
+"@spatialdata/react": minor
+"@spatialdata/layers": minor
+"@spatialdata/avivatorish": minor
+"@spatialdata/vis": minor
+---
+
+Prepare the first MDV-targeted alpha prerelease.
diff --git a/.changeset/pre.json b/.changeset/pre.json
@@ -0,0 +1,13 @@
+{
+  "mode": "pre",
+  "tag": "next",
+  "initialVersions": {
+    "zarrextra": "0.0.1",
+    "@spatialdata/core": "0.0.1",
+    "@spatialdata/react": "0.0.1",
+    "@spatialdata/layers": "0.0.1",
+    "@spatialdata/avivatorish": "0.0.1",
+    "@spatialdata/vis": "0.0.1"
+  },
+  "changesets": []
+}
diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
@@ -0,0 +1,44 @@
+name: Version Packages
+
+on:
+  push:
+    branches:
+      - main
+  workflow_dispatch:
+
+concurrency: ${{ github.workflow }}-${{ github.ref }}
+
+permissions:
+  contents: write
+  pull-requests: write
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Setup pnpm
+        uses: pnpm/action-setup@v4
+        with:
+          run_install: false
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '24.14.1'
+          cache: 'pnpm'
+          registry-url: 'https://registry.npmjs.org'
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+
+      - name: Create version PR
+        uses: changesets/action@v1
+        with:
+          version: pnpm version-packages
+          title: Version packages
+          commit: Version packages
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
diff --git a/README.md b/README.md
@@ -6,9 +6,11 @@ A library for interfacing with SpatialData stores in TypeScript/JavaScript.
 
 This monorepo contains:
 
-- **[@spatialdata/zarrextra](./packages/zarrextra)** - Utility layer on top of `zarrita` for higher-level representations of metadata
+- **[zarrextra](./packages/zarrextra)** - Lower-level utility layer on top of `zarrita` for higher-level metadata representations
 - **[@spatialdata/core](./packages/core)** - Core library for reading and validating SpatialData stores
 - **[@spatialdata/react](./packages/react)** - React hooks for providing SpatialData context, with few extra dependencies
+- **[@spatialdata/layers](./packages/layers)** - deck.gl layers and versioned rendering props
+- **[@spatialdata/avivatorish](./packages/avivatorish)** - Viv loaders, channel stats, and image viewer state helpers
 - **[@spatialdata/vis](./packages/vis)** - High-level react components for visualising data
 - **[docs](./docs)** - Documentation site built with Docusaurus
 

diff --git a/RELEASE.md b/RELEASE.md
@@ -0,0 +1,100 @@
+# Release Process
+
+SpatialData.js uses Changesets for versioning and release notes, but npm
+publishing is intentionally manual for now.
+
+## Security posture
+
+- Do not add `NPM_TOKEN` or other npm publish credentials to GitHub repository
+  secrets.
+- GitHub Actions may create the Changesets version PR, but it must not publish
+  packages to npm.
+- Publish only from a clean local checkout after reviewing the final diff and
+  generated package contents.
+- Use the npm `next` dist-tag for the MDV-targeted alpha line. Do not publish
+  this prerelease as `latest`.
+
+## Package versioning
+
+- The `@spatialdata/*` packages are fixed together by Changesets:
+  - `@spatialdata/core`
+  - `@spatialdata/react`
+  - `@spatialdata/layers`
+  - `@spatialdata/avivatorish`
+  - `@spatialdata/vis`
+- `zarrextra` is published outside the `@spatialdata/*` namespace.
+- `zarrextra` participates in the first prerelease because `@spatialdata/core`
+  depends on it, but it is not fixed to the `@spatialdata/*` version train for
+  future releases.
+
+## Normal flow
+
+1. Add one or more Changesets for user-facing package changes:
+
+   ```bash
+   pnpm changeset
+   ```
+
+2. Merge the feature PR.
+
+3. Let the `Version Packages` GitHub Action open the version PR, or run it
+   locally:
+
+   ```bash
+   pnpm version-packages
+   ```
+
+4. Review the version PR carefully:
+
+   - package versions
+   - changelog entries
+   - generated dependency versions
+   - any unexpected files
+
+5. Merge the version PR.
+
+6. From a clean local checkout of the merged commit on `main`, verify:
+
+   ```bash
+   pnpm install --frozen-lockfile
+   pnpm build
+   pnpm -r --filter @spatialdata/vis test
+   pnpm docs:build
+   ```
+
+7. Dry-run the important publish targets:
+
+   ```bash
+   pnpm --filter zarrextra publish --dry-run --no-git-checks --tag next
+   pnpm --filter @spatialdata/core publish --dry-run --no-git-checks --tag next
+   pnpm --filter @spatialdata/vis publish --dry-run --no-git-checks --tag next
+   ```
+
+8. Confirm the generated `@spatialdata/core` package manifest depends on
+   `zarrextra`, not `@spatialdata/zarrextra`:
+
+   ```bash
+   pnpm --filter @spatialdata/core pack --pack-destination /tmp --json
+   tar -xOf /tmp/spatialdata-core-*.tgz package/package.json
+   ```
+
+9. Publish manually with the `next` dist-tag:
+
+   ```bash
+   pnpm publish:next
+   ```
+
+10. Smoke-test in MDV:
+
+    ```bash
+    pnpm add @spatialdata/vis@next
+    ```
+
+## If something looks wrong
+
+- Do not publish.
+- Delete local tarballs or build outputs if needed, rebuild, and repeat the
+  dry-runs.
+- If a bad version is published, prefer deprecating it on npm and publishing a
+  fixed version. Unpublishing should be a last resort because it can disrupt
+  downstream installs.
diff --git a/docs/docs/core/error-handling.mdx b/docs/docs/core/error-handling.mdx
@@ -16,7 +16,7 @@ This aspect of the design may be subject to review, and community feedback is en
 
 :::note Result implementation
 
-The `Result` type is implemented in `@spatialdata/zarrextra` and re-exported from `@spatialdata/core` for convenience. This is currently a custom implementation for simplicity and to avoid dependencies. We may review using an existing Result library (such as `neverthrow`) in the future, but for now this provides a lightweight, dependency-free solution.
+The `Result` type is implemented in `zarrextra` and re-exported from `@spatialdata/core` for convenience. This is currently a custom implementation for simplicity and to avoid dependencies. We may review using an existing Result library (such as `neverthrow`) in the future, but for now this provides a lightweight, dependency-free solution.
 
 :::
 

diff --git a/docs/docs/core/internals.mdx b/docs/docs/core/internals.mdx
@@ -243,10 +243,10 @@ The `zarrUtils.ts` module handles parsing zarr store contents:
 
 ## Result Type Implementation
 
-The `Result` type and utilities are implemented in `@spatialdata/zarrextra` and re-exported from `@spatialdata/core` for convenience:
+The `Result` type and utilities are implemented in `zarrextra` and re-exported from `@spatialdata/core` for convenience:
 
 ```ts
-// In @spatialdata/zarrextra
+// In zarrextra
 type Result<T, E = Error> = 
   | { ok: true; value: T }
   | { ok: false; error: E };
@@ -259,7 +259,7 @@ const unwrap = <T, E>(result: Result<T, E>): T => { ... };
 const unwrapOr = <T, E>(result: Result<T, E>, defaultValue: T): T => { ... };
 ```
 
-You can import `Result` and its utilities from either `@spatialdata/core` or `@spatialdata/zarrextra`.
+You can import `Result` and its utilities from either `@spatialdata/core` or `zarrextra`.
 
 :::note Future considerations
 

diff --git a/docs/docs/core/overview.mdx b/docs/docs/core/overview.mdx
@@ -10,20 +10,22 @@ The bundle should be tree-shakeable and avoid loading heavy dependencies before
 
 ## Installation
 
-:::info you can't actually install this from npm right now
+:::info alpha prerelease
 
-As of writing, this isn't actually published to npm yet and when it is it may not be under this exact name. This documentation is evolving with the implementation, anticipating the expected usage.
+The first npm line is an MDV-targeted alpha prerelease. Install from the
+`next` tag until the public API is declared stable.
 
 You're more than welcome to clone the git repo and do what you will with it.
 
-Note that as of now it only works with outputs from `spatialdata ~=0.5.0` / `zarr v2` (this should change reasonably soon).
+Known risks and release-readiness notes are tracked in the
+[MDV release checklist](../vis/mdv-release-checklist).
 
 :::
 
 ```bash
-npm install @spatialdata/core
+npm install @spatialdata/core@next
 # or
-pnpm add @spatialdata/core
+pnpm add @spatialdata/core@next
 ```
 
 ## Quick Start

diff --git a/docs/docs/intro.mdx b/docs/docs/intro.mdx
@@ -16,13 +16,22 @@ There are several packages that aim to facilitate the use and development of thi
 
 | Package | Role | React? | npm status |
 |---------|------|--------|------------|
-| `@spatialdata/core` | Load SpatialData Zarr stores; elements, transforms, table association | No | Not published yet |
-| `@spatialdata/react` | Thin hooks around core (`useSpatialData`, provider) | Yes | Not published yet |
-| `@spatialdata/layers` | deck.gl layers, shape/point renderers, versioned layer props | No | Not published yet |
-| `@spatialdata/avivatorish` | Viv loaders, channel stats, image Zustand stores | No | Not published yet |
-| `@spatialdata/vis` | `SpatialCanvas` UI + headless `SpatialCanvasViewer` | Yes | Not published yet; MDV-targeted prerelease in progress |
+| `zarrextra` | Lower-level zarr metadata helpers used by core | No | Prerelease via `next` |
+| `@spatialdata/core` | Load SpatialData Zarr stores; elements, transforms, table association | No | Prerelease via `next` |
+| `@spatialdata/react` | Thin hooks around core (`useSpatialData`, provider) | Yes | Prerelease via `next` |
+| `@spatialdata/layers` | deck.gl layers, shape/point renderers, versioned layer props | No | Prerelease via `next` |
+| `@spatialdata/avivatorish` | Viv loaders, channel stats, image Zustand stores | No | Prerelease via `next` |
+| `@spatialdata/vis` | `SpatialCanvas` UI + headless `SpatialCanvasViewer` | Yes | MDV-targeted prerelease via `next` |
+
+The first npm release line is an MDV-targeted prerelease. Install with the
+`next` tag while the API is still alpha:
+
+```bash
+pnpm add @spatialdata/vis@next
+```
 
-Nothing is on npm yet. Clone the monorepo or `pnpm pack` workspace packages for local integration (see [Headless viewer guide](./vis/headless-viewer)).
+Clone the monorepo or `pnpm pack` workspace packages for local integration
+while preparing release candidates (see [Headless viewer guide](./vis/headless-viewer)).
 
 ## `@spatialdata/core`
 
@@ -170,4 +179,4 @@ import { SpatialCanvas } from '@spatialdata/vis';
 
 `SpatialCanvas` manages its own zustand store (layer visibility, order, channel
 UI). Use it for demos and exploration; MDV and other hosts should prefer
-`SpatialCanvasViewer` with externally owned state.
+`SpatialCanvasViewer` with externally owned state.
diff --git a/docs/docs/vis/headless-viewer.mdx b/docs/docs/vis/headless-viewer.mdx
@@ -224,7 +224,13 @@ Suggested experiments (matching the [MDV integration roadmap](./mdv-integration)
 4. **Controlled view** — save/restore `viewState` in `sessionStorage`.
 5. **External tooltips** — `renderTooltip={false}` + log `onShapeHover` payloads.
 
-Pack for MDV smoke tests:
+Install the prerelease for MDV smoke tests:
+
+```bash
+pnpm add @spatialdata/vis@next
+```
+
+Pack local builds when testing an unpublished branch:
 
 ```bash
 pnpm build
@@ -244,7 +250,7 @@ Before treating the API as stable for MDV:
 - [x] `demo/headless` route with local `blobs.zarr` fixture
 - [ ] Additional `demo/headless-*` variants (Leva controls, custom deck layers)
 - [ ] Tooltip/pick row resolution fully on shared `FeatureTableAlignment` (in progress)
-- [ ] npm prerelease published and smoke-tested in MDV
+- [ ] npm `next` prerelease published and smoke-tested in MDV
 
 See also [MDV release checklist](./mdv-release-checklist) and
 [Feature table associations](./feature-table-associations).
diff --git a/docs/docs/vis/mdv-integration.mdx b/docs/docs/vis/mdv-integration.mdx
@@ -25,7 +25,7 @@ The near-term target is not a full replacement for every MDV spatial feature. Th
 
 **Remaining MDV blockers** are packaging and polish, not the absence of a headless component:
 
-- packages are not yet published to npm (pack / link / prerelease for MDV smoke tests)
+- publish and smoke-test the npm `next` prerelease in MDV
 - tooltip/pick row resolution should finish converging on the shared core resolver
 - points layer is minimal scatter only (v1.1 for MDV parity)
 
@@ -62,6 +62,7 @@ Acceptance signal: demos should import the same public API MDV uses (`SpatialCan
   - `@spatialdata/layers`
   - `@spatialdata/vis`
   - optional: `@spatialdata/avivatorish`
+  - lower-level dependency: `zarrextra`
 - [ ] Decide whether MDV first consumes via local `npm link` / packed tarballs / workspace path / published prerelease.
 - [ ] Treat this repo as the place where Viv/deck/luma versions are selected. MDV should follow those versions, not constrain them.
 - [x] Upgrade to `@hms-dbmi/viv@0.21.0` / deck.gl `9.2.9` in this repo (Viv PR [hms-dbmi/viv#924](https://github.com/hms-dbmi/viv/pull/924): uniform-buffer-backed shader props, `model.shaderInputs`, variable channel counts).
-Original file line number
+Diff line change
@@ Expand Up @@
     :::note Result implementation
-    The `Result` type is implemented in `@spatialdata/zarrextra` and re-exported from `@spatialdata/core` for convenience. This is currently a custom implementation for simplicity and to avoid dependencies. We may review using an existing Result library (such as `neverthrow`) in the future, but for now this provides a lightweight, dependency-free solution.
+    The `Result` type is implemented in `zarrextra` and re-exported from `@spatialdata/core` for convenience. This is currently a custom implementation for simplicity and to avoid dependencies. We may review using an existing Result library (such as `neverthrow`) in the future, but for now this provides a lightweight, dependency-free solution.
     :::
@@ Expand Down @@