feat: consume dmv deck.gl bulk annotations; drop clustering UI

.claude/launch.json

@@ -0,0 +1,12 @@
+{
+  "version": "0.0.1",
+  "configurations": [
+    {
+      "name": "slim-dev",
+      "runtimeExecutable": "pnpm",
+      "runtimeArgs": ["start"],
+      "port": 3000,
+      "autoPort": true
+    }
+  ]
+}

.deepsource.toml

@@ -1,5 +1,14 @@
 version = 1
 
+# Playwright specs, helpers, and the local e2e static server are test
+# infrastructure — not production browser code — so exclude them from the
+# JavaScript analyzer (which is configured for the React app).
+exclude_patterns = [
+  "e2e/**",
+  "scripts/serve-e2e.mjs",
+  "playwright.config.ts",
+]
+
 [[analyzers]]
 name = "javascript"
 enabled = true

.github/workflows/deploy-to-firebase.yml

@@ -53,15 +53,15 @@ jobs:
         run: ./scripts/resolve-dmv-preview-branch.sh
 
       - name: Install dependencies
-        # Install without lifecycle scripts, then rebuild only packages that need prepare
-        # (dicom-microscopy-viewer dist/). Keeps Sonar happy while still building DMV.
+        # Dependency build scripts are gated by allowBuilds in pnpm-workspace.yaml.
+        # The git-hosted dicom-microscopy-viewer needs its prepare script to build dist/.
         env:
           DMV_USE_GIT: ${{ steps.dmv.outputs.use_git }}
           DMV_REF: ${{ steps.dmv.outputs.ref }}
           DMV_SHA: ${{ steps.dmv.outputs.sha }}
         run: |
           set -euo pipefail
-          if [ "${DMV_USE_GIT}" = "true" ]; then
+          if [ "${DMV_USE_GIT:-}" = "true" ]; then
             case "${DMV_REF}" in
               ''|*[!A-Za-z0-9._/-]*|.*|*.)
                 echo "::error::Unsafe DMV_REF rejected"
@@ -82,12 +82,10 @@ jobs:
               );
               fs.writeFileSync('pnpm-workspace.yaml', updated);
             " "${TARBALL_KEY}"
-            pnpm install --no-frozen-lockfile --ignore-scripts
+            pnpm install --no-frozen-lockfile
           else
-            pnpm install --frozen-lockfile --ignore-scripts
+            pnpm install --frozen-lockfile
           fi
-          # allowBuilds in pnpm-workspace.yaml: core-js(+pure) and dicom-microscopy-viewer
-          pnpm rebuild dicom-microscopy-viewer core-js core-js-pure
           # Build DMV if dist files are missing (git dependency in package.json)
           if [ ! -f "node_modules/dicom-microscopy-viewer/dist/dynamic-import/dicomMicroscopyViewer.min.js" ]; then
             echo "DMV dist files missing - building from git dependency"

.github/workflows/e2e-visual.yml

@@ -0,0 +1,120 @@
+name: slim/e2e-visual-regression
+
+# Visual-regression tests for the deck.gl bulk-annotation renderer.
+#
+# Runs inside the pinned Playwright container so the (SwiftShader) browser
+# environment is byte-for-byte identical to the committed Linux baselines under
+# e2e/__screenshots__/. See e2e/README.md.
+#
+# The default target study is fetched from the public IDC proxy, so runs depend
+# on that external service; retries (configured in playwright.config.ts) absorb
+# cold-start slowness. This check is intentionally not required for merge —
+# promote it in branch protection once data is hosted locally for hermetic runs.
+
+on:
+  pull_request:
+    branches: [master]
+    # edited: re-run when the PR body changes (e.g. add/update dmv-branch:)
+    types: [opened, synchronize, reopened, edited]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pull-requests: read
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+
+jobs:
+  visual:
+    name: "Bulk annotation visual regression"
+    # Skip re-run on PR body edit unless the body actually changed (dmv-branch updates)
+    if: github.event.action != 'edited' || github.event.changes.body != null
+    runs-on: ubuntu-latest
+    timeout-minutes: 45
+    container:
+      # Keep this tag in sync with the @playwright/test version in package.json.
+      image: mcr.microsoft.com/playwright:v1.62.1-jammy
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+
+      - name: Setup pnpm
+        uses: pnpm/action-setup@0ebf47130e4866e96fce0953f49152a61190b271 # v6.0.9
+
+      - name: Install GitHub CLI
+        # The Playwright container doesn't include gh CLI, needed for DMV branch resolution
+        run: |
+          apt-get update && apt-get install -y gh
+
+      - name: Resolve DMV branch for preview
+        id: dmv
+        if: github.event_name == 'pull_request'
+        shell: bash
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          PR_BODY: ${{ github.event.pull_request.body }}
+          HEAD_REF: ${{ github.head_ref }}
+        run: ./scripts/resolve-dmv-preview-branch.sh
+
+      - name: Install dependencies
+        # Dependency build scripts are gated by allowBuilds in pnpm-workspace.yaml.
+        # The git-hosted dicom-microscopy-viewer needs its prepare script to build dist/.
+        shell: bash
+        env:
+          DMV_USE_GIT: ${{ steps.dmv.outputs.use_git }}
+          DMV_REF: ${{ steps.dmv.outputs.ref }}
+          DMV_SHA: ${{ steps.dmv.outputs.sha }}
+        run: |
+          set -euo pipefail
+          if [ "${DMV_USE_GIT:-}" = "true" ]; then
+            case "${DMV_REF}" in
+              ''|*[!A-Za-z0-9._/-]*|.*|*.)
+                echo "::error::Unsafe DMV_REF rejected"
+                exit 1
+                ;;
+            esac
+            pnpm pkg set 'dependencies["dicom-microscopy-viewer"]'"=github:ImagingDataCommons/dicom-microscopy-viewer#${DMV_REF}"
+            # Dynamically allow builds for the resolved tarball URL so pnpm's
+            # dependency status check passes during `pnpm run build`
+            TARBALL_KEY="dicom-microscopy-viewer@https://codeload.github.com/ImagingDataCommons/dicom-microscopy-viewer/tar.gz/${DMV_SHA}"
+            node -e "
+              const fs = require('fs');
+              const content = fs.readFileSync('pnpm-workspace.yaml', 'utf8');
+              // Insert the tarball allowBuilds entry after 'dicom-microscopy-viewer: true'
+              const updated = content.replace(
+                /(allowBuilds:[\s\S]*?dicom-microscopy-viewer: true)/,
+                \"\$1\\n  '\" + process.argv[1] + \"': true\"
+              );
+              fs.writeFileSync('pnpm-workspace.yaml', updated);
+            " "${TARBALL_KEY}"
+            pnpm install --no-frozen-lockfile --ignore-scripts
+          else
+            pnpm install --frozen-lockfile --ignore-scripts
+          fi
+          # allowBuilds in pnpm-workspace.yaml: core-js(+pure) and dicom-microscopy-viewer
+          pnpm rebuild dicom-microscopy-viewer core-js core-js-pure
+          # Build DMV if dist files are missing (git dependency in package.json)
+          if [ ! -f "node_modules/dicom-microscopy-viewer/dist/dynamic-import/dicomMicroscopyViewer.min.js" ]; then
+            echo "DMV dist files missing - building from git dependency"
+            (cd node_modules/dicom-microscopy-viewer && pnpm run build)
+          fi
+
+      - name: Build (e2e config)
+        run: pnpm run build:e2e
+
+      - name: Run visual-regression tests
+        # Playwright starts the static server (serve:e2e) itself via the
+        # webServer config and compares against the committed baselines.
+        run: pnpm run test:e2e
+
+      - name: Upload Playwright report
+        if: ${{ !cancelled() }}
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: playwright-report
+          path: |
+            playwright-report/
+            test-results/
+          retention-days: 14

.github/workflows/release.yml

@@ -36,7 +36,9 @@ jobs:
           cache: pnpm
 
       - name: Install dependencies
-        run: pnpm install --frozen-lockfile --ignore-scripts
+        # Dependency build scripts are gated by allowBuilds in pnpm-workspace.yaml.
+        # The git-hosted dicom-microscopy-viewer needs its prepare script to build dist/.
+        run: pnpm install --frozen-lockfile
 
       - name: Build
         run: pnpm run build

.gitignore

@@ -4,6 +4,7 @@
 /node_modules
 /.pnp
 .pnp.js
+/.pnpm-store
 
 # testing
 /coverage
@@ -18,6 +19,13 @@ public/config/*
 !public/config/demo.js
 !public/config/local.js
 !public/config/preview.js
+!public/config/e2e.js
+
+# Playwright
+/test-results
+/playwright-report
+/blob-report
+/playwright/.cache
 
 # misc
 .DS_Store

.sonarcloud.properties

@@ -0,0 +1,13 @@
+# SonarCloud automatic-analysis configuration.
+#
+# Workflow files are excluded because rule githubactions:S6505 flags
+# "pnpm install" without --ignore-scripts. While dicom-microscopy-viewer is
+# pinned to a git commit, its prepare script must run at install time to
+# build dist/. Lifecycle scripts remain gated per-package by the allowBuilds
+# allowlist in pnpm-workspace.yaml, which is stricter than a blanket
+# --ignore-scripts. Remove this exclusion once dmv is pinned to a published
+# npm release again (npm tarballs ship prebuilt dist/).
+# e2e/ and scripts/serve-e2e.mjs are test infrastructure (Playwright + a local
+# static server), not production code. Excluding them keeps the quality gate
+# focused on the shipped app.
+sonar.exclusions=.github/workflows/*.yml,e2e/**,scripts/serve-e2e.mjs,playwright.config.ts

e2e/README.md

@@ -0,0 +1,81 @@
+# End-to-end / visual-regression tests
+
+Playwright tests that drive the real app in a real (WebGL-capable) browser and
+compare the deck.gl bulk-annotation overlay against committed screenshot
+baselines, so rendering regressions are caught automatically.
+
+## What is covered
+
+- `bulk-annotations.spec.ts`
+  - A large (~396k-polygon) annotation group loads and paints without
+    exhausting the JS heap (the OpenLayers Feature pipeline this replaced OOM'd
+    on groups this size).
+  - The annotation overlay matches a committed screenshot baseline (clipped to
+    the map viewport so the memory footer / sidebar never affect the diff).
+  - Hiding a group frees the overlay.
+
+## Data source
+
+By default the app is built with `public/config/e2e.js`, which points at the
+**public NCI Imaging Data Commons proxy** — no local DICOM server required. The
+default study is `TCGA-02-0001` (a glioblastoma WSI with a large "Nuclei"
+POLYGON group).
+
+Override the target without editing code:
+
+- `E2E_STUDY_UID` — study to open
+- `E2E_SERIES_UID` — SM series to open (pinned so the suite doesn't depend
+  on slim's default study→series redirect; this study has four slides)
+- `E2E_GROUP_NAME` — annotation group name to toggle (default `Nuclei`)
+- `E2E_BASE_URL` — point at an already-running server instead of letting
+  Playwright serve the build (e.g. a local dcm4chee-backed deployment)
+
+### Fully local / hermetic data (optional)
+
+For a network-independent run you can host the study yourself (e.g. a local
+`dcm4chee` via the
+[imaging-data-commons-skill](https://github.com/ImagingDataCommons/imaging-data-commons-skill)
+to fetch the study, then upload to your DICOMweb server), copy
+`public/config/e2e.js` to point `url` at it, and run the suite normally. This
+avoids proxy rate limits but is heavier to set up and is not used in CI.
+
+## Running locally
+
+```bash
+# 1. Build once with the e2e config and serve it (or use the dev server:
+#    PORT=3977 REACT_APP_CONFIG=e2e pnpm start).
+pnpm run build:e2e && pnpm run serve:e2e     # terminal A
+# 2. Run the tests (reuses the running server).
+pnpm run test:e2e                            # terminal B
+```
+
+`serve:e2e` is a tiny dependency-free SPA static server
+(`scripts/serve-e2e.mjs`) that listens on port **3977** (chosen so it never
+collides with other common `:3000` dev servers). Playwright can also start it
+itself via the `webServer` config when nothing is listening on that port.
+
+## Screenshot baselines
+
+WebGL output is made deterministic across machines by forcing ANGLE +
+SwiftShader (software rendering). SwiftShader still differs between operating
+systems, so **baselines are per-OS** and the ones committed here are **Linux**,
+matching CI.
+
+Regenerate them with the pinned Playwright container (browser runs in the
+container; the app is served from the host):
+
+```bash
+pnpm run build:e2e && pnpm run serve:e2e     # terminal A
+pnpm run test:e2e:update:docker              # terminal B
+# review the diff under e2e/__screenshots__/ and commit
+```
+
+Generating baselines with a plain `pnpm run test:e2e:update` on macOS/Windows
+produces host-OS snapshots that will **not** match CI — always use the Docker
+script for committed baselines.
+
+## CI
+
+`.github/workflows/e2e-visual.yml` runs this suite inside the same pinned
+Playwright container, so the browser environment is byte-for-byte identical to
+the local baseline-generation path above.

e2e/bulk-annotations.spec.ts

@@ -0,0 +1,83 @@
+import { expect, test } from '@playwright/test'
+
+import {
+  GROUP_NAME,
+  SERIES_UID,
+  STUDY_UID,
+  deckDrawnPixelCount,
+  expandAnnotationGroups,
+  mapClip,
+  setGroupVisibility,
+  prepareAnnotationScreenshot,
+  usedHeapMB,
+  waitForAnnotationsCleared,
+  waitForAnnotationsDrawn,
+  waitForAnnotationsStable,
+  waitForSlide,
+} from './helpers'
+
+/**
+ * Visual-regression + smoke coverage for the deck.gl bulk-annotation renderer.
+ *
+ * The default target is a ~396k-polygon "Nuclei" group (see helpers.ts). The
+ * suite asserts three things that matter for the renderer:
+ *   1. A large group loads and paints without exhausting the JS heap (the OL
+ *      Feature pipeline this replaced OOM'd on groups this size).
+ *   2. The annotation overlay matches a committed screenshot baseline.
+ *   3. Hiding the group frees the overlay.
+ *
+ * Screenshots are clipped to the map viewport so the volatile memory footer
+ * and sidebar text never enter the comparison.
+ */
+test.describe('bulk annotations (deck.gl overlay)', () => {
+  test.beforeEach(async ({ page }) => {
+    await page.goto(`/studies/${STUDY_UID}/series/${SERIES_UID}`)
+    await waitForSlide(page)
+    await expandAnnotationGroups(page)
+  })
+
+  test('renders a large annotation group without exhausting memory', async ({
+    page,
+  }) => {
+    const heapBefore = await usedHeapMB(page)
+
+    await setGroupVisibility(page, GROUP_NAME, true)
+
+    const drawnPixels = await waitForAnnotationsDrawn(page)
+    expect(drawnPixels).toBeGreaterThan(500)
+
+    // Wait for progressive streaming to finish so the whole-slide overlay
+    // (the deterministic screenshot target) reflects the complete group.
+    await waitForAnnotationsStable(page)
+
+    const heapAfter = await usedHeapMB(page)
+    if (heapBefore >= 0 && heapAfter >= 0) {
+      // Guardrail against a regression to the old multi-GB / OOM behavior.
+      // ~396k polygons decode to a few hundred MB; 1500 MB leaves headroom
+      // without letting a runaway leak pass.
+      expect(heapAfter).toBeLessThan(1500)
+    }
+
+    // The whole-slide fit is fully deterministic (image dimensions + viewport).
+    // Hide the WSI tile layers / chrome so the screenshot compares only the
+    // deck.gl overlay — WSI tile decoding is non-deterministic across runs.
+    await page
+      .waitForLoadState('networkidle', { timeout: 60_000 })
+      .catch(() => undefined)
+    await prepareAnnotationScreenshot(page)
+    await expect(page).toHaveScreenshot('nuclei-whole-slide.png', {
+      clip: await mapClip(page),
+      timeout: 120_000,
+    })
+  })
+
+  test('hides an annotation group on toggle-off', async ({ page }) => {
+    await setGroupVisibility(page, GROUP_NAME, true)
+    await waitForAnnotationsDrawn(page)
+
+    await setGroupVisibility(page, GROUP_NAME, false)
+
+    await waitForAnnotationsCleared(page)
+    expect(await deckDrawnPixelCount(page)).toBeLessThan(500)
+  })
+})