[WIP] fix: Add display set split/store logic to metadata

.agents/skills/metadata-migration.md

@@ -0,0 +1,44 @@
+---
+name: metadata-migration
+description: Migrate codebases from legacy CS3D metadata flows to the metadata branch model with required init/provider updates and recommended provider/cache/imageId changes.
+---
+
+# Metadata Migration Skill (`origin/main` -> `metadata`)
+
+Use this skill to migrate codebases from the legacy CS3D metadata flow in
+`origin/main` to the `metadata` branch model.
+
+## Mandated changes
+
+1. Add the metadata module.
+2. Re-add required providers after each CS3D init call.
+
+### Required checklist
+
+- Add and initialize the metadata module in bootstrap/startup.
+- Ensure provider registration runs after CS3D init.
+- Re-register all providers needed by your workflows after init.
+- Confirm provider priority/ordering where providers overlap.
+
+## Recommended changes
+
+1. Use metadata module imports instead of legacy import paths.
+2. Switch to new metadata providers and deprecate old providers.
+3. Adopt the new caching model.
+4. Adopt the `imageId` / `frameImageId` storage model.
+
+## Compatibility notes
+
+- Some providers are not yet available in both old and new schemes.
+- Do not block migration on full parity.
+- Keep temporary fallback providers only where required.
+- Track and remove fallbacks as equivalent providers become available.
+
+## Suggested migration sequence
+
+1. Add metadata module and initialize it.
+2. Move provider registration to post-init and re-add required providers.
+3. Validate key metadata workflows and provider lookups.
+4. Replace old imports with metadata module imports.
+5. Migrate providers to new implementations where available.
+6. Incrementally adopt new cache and `imageId`/`frameImageId` storage.

.circleci/config.yml

@@ -103,6 +103,7 @@ jobs:
       - persist_to_workspace:
           root: ~/repo
           paths:
+            - packages/metadata/dist
             - packages/core/dist
             - packages/tools/dist
             - packages/adapters/dist

.github/workflows/ohif-downstream.yml

@@ -28,8 +28,9 @@ jobs:
     runs-on: self-hosted
     timeout-minutes: 120
     env:
-      BUN_VERSION: 1.3.11
+      BUN_VERSION: 1.3.13
       NODE_VERSION: 24
+      OHIF_REF: master
       OHIF_DIR: ohif
       # Update to force a rebuild of the OHIF integration
       BUILD_INDEX: 0
@@ -73,7 +74,7 @@ jobs:
       - name: Install Cornerstone dependencies
         run: bun install --frozen-lockfile
 
-      - name: Build local Cornerstone packages for OHIF
+      - name: Build local Cornerstone packages for OHIF (includes metadata)
         run: bun run build:esm
 
       - name: Checkout OHIF
@@ -116,7 +117,7 @@ jobs:
         working-directory: ${{ env.OHIF_DIR }}
         env:
           PLAYWRIGHT_HTML_OPEN: never
-        run: bun run test:e2e:ci
+        run: bun run test:e2e:ci -- --max-failures=10 --retries=1
 
       - name: Upload OHIF Playwright artifacts
         if: always()

.github/workflows/playwright.yml

@@ -9,35 +9,48 @@
 
 jobs:
   playwright-tests:
-    timeout-minutes: 60
+    timeout-minutes: 120
     runs-on: self-hosted
     strategy:
       fail-fast: false
       matrix:
         node-version: [20]
     steps:
       - uses: actions/checkout@v4
       - uses: oven-sh/setup-bun@v2
         with:
           bun-version: 1.2.23
       - uses: actions/setup-node@v4
         with:
           node-version: ${{ matrix.node-version }}
       - name: Install dependencies
         run: bun install --frozen-lockfile
       # - name: Install Playwright browsers
       #   run: bun x playwright install-deps chromium
       - name: Run Playwright tests
+        env:
+          CI: true
+          PLAYWRIGHT_HTML_OPEN: never
         run: |
           export NODE_OPTIONS="--max_old_space_size=10192"
-          bun run test:e2e:coverage
+          bun x nyc --reporter=html npx playwright test --max-failures=10 --retries=1
+      - name: Upload Playwright report and test results
+        if: failure()
+        uses: actions/upload-artifact@v4
+        with:
+          name: playwright-results-${{ github.sha }}
+          if-no-files-found: warn
+          path: |
+            tests/playwright-report/
+            tests/test-results/
+          retention-days: 7
       - name: create the coverage report
         run: |
           bun nyc report --reporter=lcov --reporter=text
       - name: Upload the coverage report to GitHub Actions Artifacts
         if: ${{ !cancelled() }}
         uses: actions/upload-artifact@v4
         with:
           name: coverage-report-pr
           path: coverage
           retention-days: 7

CHANGELOG.md

@@ -15,32 +15,16 @@ See [Conventional Commits](https://conventionalcommits.org) for commit guideline
 
 - **security:** Update various dependencies to fix security vulnerabilities. ([#2736](https://github.com/cornerstonejs/cornerstone3D/issues/2736)) ([f8385af](https://github.com/cornerstonejs/cornerstone3D/commit/f8385afe4116f8e824f2480b7a5c0c032c1e5da0))
 
-## [4.22.7](https://github.com/cornerstonejs/cornerstone3D/compare/v4.22.6...v4.22.7) (2026-05-15)
+# [5.0.0-beta.2](https://github.com/cornerstonejs/cornerstone3D/compare/v5.0.0-beta.1...v5.0.0-beta.2) (2026-05-15)
 
 ### Bug Fixes
 
 - **annotations:** incorrect area calculation for livewire, spline, rectangle, and planar freehand ROI tools ([#2734](https://github.com/cornerstonejs/cornerstone3D/issues/2734)) ([c8a96e9](https://github.com/cornerstonejs/cornerstone3D/commit/c8a96e9a025a51e70f0c20f217827fdd036aa4c5))
-
-## [4.22.6](https://github.com/cornerstonejs/cornerstone3D/compare/v4.22.5...v4.22.6) (2026-05-12)
-
-### Bug Fixes
-
 - **segmentation:** fully remove segmentations from viewport on delete after reload ([#2729](https://github.com/cornerstonejs/cornerstone3D/issues/2729)) ([0e186bd](https://github.com/cornerstonejs/cornerstone3D/commit/0e186bd7a804d706df1bb9ee263378e09726b087))
-
-## [4.22.5](https://github.com/cornerstonejs/cornerstone3D/compare/v4.22.4...v4.22.5) (2026-05-12)
-
-**Note:** Version bump only for package root
-
-## [4.22.4](https://github.com/cornerstonejs/cornerstone3D/compare/v4.22.3...v4.22.4) (2026-05-06)
-
-**Note:** Version bump only for package root
-
-## [4.22.3](https://github.com/cornerstonejs/cornerstone3D/compare/v4.22.2...v4.22.3) (2026-04-23)
-
-### Bug Fixes
-
 - **security:** Patch protobufjs for CVE-2026-41242 ([#2712](https://github.com/cornerstonejs/cornerstone3D/issues/2712)) ([7027290](https://github.com/cornerstonejs/cornerstone3D/commit/7027290d168d91829f608a6c2f3c39c995e28c31))
 
+# [5.0.0-beta.1](https://github.com/cornerstonejs/cornerstone3D/compare/v4.18.3...v5.0.0-beta.1) (2026-02-27)
+
 ## [4.22.2](https://github.com/cornerstonejs/cornerstone3D/compare/v4.22.1...v4.22.2) (2026-04-21)
 
 ### Bug Fixes

README.md

@@ -1,11 +1,11 @@
 # [Cornerstone.js](https://cornerstonejs.org/) · ![GitHub license](https://img.shields.io/badge/license-MIT-blue.svg)
 
-Cornerstone is a set of JavaScript libraries that can be used to build web-based medical imaging applications. It provides a framework to build radiology applications such as the [OHIF Viewer](https://ohif.org/).
+Cornerstone is a set of JavaScript libraries that can be used to build web-based medical imaging applications. It provides a framework to build radiology applications such as the [OHIF Viewer](https://ohif.org/)
 
 - **Fast:** Cornerstone leverages WebGL to provide high-performance image rendering and WebAssembly for fast image decompression.
 - **Flexible:** Cornerstone provides APIs for defining custom image, volume, and metadata loading schemes, allowing developers to easily connect with proprietary image archives.
 - **Community Driven:** Cornerstone is supported by the [Open Health Imaging Foundation](https://ohif.org/). We publish our roadmap and welcome contributions and collaboration.
-- **Standards Compliant:** Cornerstone's core focus is Radiology, so it provides DICOMweb compatibility out-of-the-box.
+- **Standards Compliant:** Cornerstone's core focus is Radiology, so it provides DICOMweb compatibility out-of-the-box
 
 [Learn how to use Cornerstone3D in your project](https://www.cornerstonejs.org/docs/getting-started/overview).
 
@@ -108,6 +108,7 @@ following packages are linked:
 | `@cornerstonejs/core` | `packages/core` |
 | `@cornerstonejs/dicom-image-loader` | `packages/dicomImageLoader` |
 | `@cornerstonejs/labelmap-interpolation` | `packages/labelmap-interpolation` |
+| `@cornerstonejs/metadata` | `packages/metadata` |
 | `@cornerstonejs/nifti-volume-loader` | `packages/nifti-volume-loader` |
 | `@cornerstonejs/polymorphic-segmentation` | `packages/polymorphic-segmentation` |
 | `@cornerstonejs/tools` | `packages/tools` |
@@ -154,6 +155,10 @@ node scripts/unlink-ohif-cornerstone-node-modules.mjs /path/to/ohif
 > package rather than the full set), see the
 > [Linking Cornerstone Libraries](packages/docs/docs/contribute/linking.md) doc.
 
+## Troubleshooting
+
+If unit tests fail with **\"Cannot find module '../build/Release/canvas.node'\"**, the native `canvas` addon wasn’t built. Run `yarn rebuild:canvas` (or `npm run rebuild:canvas`); if that doesn’t fix it, see [docs/troubleshooting.md](docs/troubleshooting.md#unit-tests-cannot-find-module-buildreleasecanvasnode).
+
 ## Support
 
 Users can post questions and issues on the [Open Health Imaging Foundation (OHIF) Community Forum](https://community.ohif.org/). Developer issues or bugs can be reported as [Github Issues](https://github.com/cornerstonejs/cornerstone3D/issues).