feat: render bulk annotations with deck.gl overlay

[igoroctaviano]

Summary

Replace the OpenLayers Feature/cluster pipeline for DICOM Microscopy Bulk Simple Annotations with a deck.gl OrthographicView overlay behind the existing VolumeImageViewer public API (slim remains a thin consumer).

Why

Large ANN groups (hundreds of thousands of polygons) OOM / freeze on master because the viewer builds one OL Feature+Geometry per annotation (Canvas for polygons), does ~25–30 allocations + mathjs work per vertex, retains dual cluster/high-res sources, and re-processes all N on pan. The feat/viv-loader POC proved deck.gl is viable; this PR moves ownership into dmv so every consumer benefits.

What changed

• New src/bulkAnnotations/ subsystem: streaming fetch, Float32 OL-space decode ([col, -(row+1)]), spatial tiles, tiered LOD (centroids / line-strip / PathLayer), Flatbush CPU picking
• Binary PathLayer attributes with PathTesselator scratch neutralization (positions: null + _typedArrayManagerProps: { overAlloc: 1, poolSize: 0 })
• Custom ol/layer/Layer wrapping Deck (official OL + deck.gl pattern); image tiles stay on OL
• API parity: addAnnotationGroups / show / hide / setAnnotationGroupStyle / zoomToROI (first annotation ×7) / getAnnotationGroupMeasurementRange + limitValues
• Events: POINTER_MOVE keeps OL MapBrowserEvent; ROI_SELECTED is a real roi.ROI; VIEWPORT_CLICKED.rois includes bulk hits
• Deprecated public shims kept for bulkSimpleAnnotations Feature builders and annotation.fetch*
• Deck/layers lazy-loaded so jsdom tests stay clean

Benchmark

Script: scripts/benchmark-bulk-ann.mjs (+ benchmark-bulk-ann-results.md). Puppeteer CDP numbers should be filled after a local run against the IDC example series; investigation already showed master OOM vs progressive deck.gl paint on the same study.

Companion slim PR will remove clustering UI and bump/link this branch.

Test plan

• Unit tests (src/bulkAnnotations/**) — decode, stream helpers, PathTesselator positions:null, OL→deck viewState
• Full jest suite (190) + webpack bundle + dynamic-import builds
• Manual: REACT_APP_CONFIG=example slim against linked dmv; toggle large POLYGON groups; verify no mirror (OL Y), progressive paint when Range works, hide frees GPU layers, pick/ROI_SELECTED/zoomToROI
• Run node scripts/benchmark-bulk-ann.mjs --url <study/series> and paste heap table into the PR

[igoroctaviano]

Code review pass — fixes pushed in 51a7c31

A careful self-review of the branch found several real defects, all fixed and covered by the existing test suite (190 tests passing, both webpack builds green):

Correctness

• affineForReferencedPyramidLevel returned bare coeffs while manager.js destructured { coeffs } — every decode would have received undefined coefficients and produced NaN positions. The referenced-image lookup also read ReferencedImageSequence from the group sequence item, where it never exists; it now falls back to the top-level instance metadata (matching the legacy OL path), and the not-found fallback for 2D coordinates now composes the base level's pixel-to-slide affine (≈ identity) instead of the raw slide-to-pixel inverse, which would have scaled every coordinate by the downsample factor.
• zoomToAnnotationGroup called view.it(...) instead of view.fit(...). Root cause: biome's noFocusedTests unsafe autofix rewrites fit( → it( because it pattern-matches focused tests. Fixed and suppressed at the call site so lint:fix --unsafe can't reintroduce it.

Rendering lifecycle

• Nothing requested an OL render frame when a group's deck layer list changed, so hydration/hide/style changes only painted after the next map interaction. The manager now calls layer.changed() + map.render() whenever layers change.
• The LOD tier and visible spatial-tile set were computed once at build time and never refreshed — panning/zooming kept stale tiles/tiers. A moveend listener now rebuilds a group's layers when its view signature (tier | rotation | visible tile keys) changes.
• OL view rotation was ignored by the overlay (misalignment on rotated slides). Rotation is now reproduced via a per-layer modelMatrix = R(-rotation) plus a rotated OrthographicView target, mirroring OL's coordinateToPixelTransform.

Performance / plan-fidelity

• Layer factories rebuilt fresh data objects on every style change, defeating deck's reference-based diffing (full re-tessellation + attribute re-upload per opacity tweak). Factories now accept prebuilt data objects; the manager caches them per group and per spatial tile, with stable tile-key-based layer ids.
• Measurement-based styling was accepted but had no effect, and getAnnotationGroupMeasurementRange returned a hardcoded stub. Measurements are now lazily fetched (warmed after hydrate), real min/max ranges are computed, and DataFilterExtension filtering is wired end-to-end (per-vertex values for path layers, per-annotation for centroid/point layers, limitValues → filterRange).
• CPU pick tolerance was a fixed 2 world units (sub-pixel when zoomed out); it now scales with the view resolution (~6 screen px). Bulk pick ROIs also include fetched measurement values, and getExtendedROI no longer emits NaN NumContentItems when values are unavailable.
• Hydrate now goes through data/fetch.js's fetchGraphicDataForGroup instead of duplicating streaming-eligibility logic in the manager.

[igoroctaviano]

Review round 2 (b0fcc04)

Second review pass over the branch, focused on event lifecycles, external API assumptions, and the code added in round 1. Three issues found and fixed:

1. Stuck loading indicator — _hydrateGroup published LOADING_STARTED unconditionally but only published LOADING_ENDED on the happy path. An aborted hydrate (group hidden mid-load), a fetch/decode error, or a stale-generation early return left consumers that pair the two events (slim's global spinner) stuck forever. LOADING_ENDED now fires from a finally block.
2. Wrong dicomweb-client property — the streaming fallback passed client?.url as the base URL for relative BulkDataURI resolution, but dicomweb-client exposes baseURL (and wadoURL), not url, so the value was always undefined. Now client?.wadoURL || client?.baseURL.
3. Unhandled rejection — showAnnotationGroup chained .then on ensureOverlay() without a .catch; overlay init failures are now logged instead of surfacing as unhandled promise rejections.

Also re-verified this round (no changes needed):

• Rotation math: rotationModelMatrix and the rotated deck target both apply R(−θ), matching OL's coordinateToPixelTransform composition (checked with a concrete 90° example).
• annotation.js named exports (fetchGraphicData, fetchGraphicIndex, getCommonZCoordinate, getCoordinateDimensionality) all exist for the manager's imports.
• Filter cache invalidation order in _rebuildLayersForGroupAsync (filter computed before the stable-data check, so a measurement switch correctly rebuilds GPU data).
• Per-vertex filter expansion bounds for both full paths and per-tile slices.
• scripts/prepare.mjs dist sentinel matches the actual webpack output filename.

✅ biome clean · 190/190 jest tests pass · webpack build OK

[igoroctaviano]

CI note (6041fe0)

One more fix, found while getting slim's CI green: when this package is installed as a git dependency, pnpm builds it inside its content-addressable store, whose path on GitHub Actions contains a node_modules segment (.../setup-pnpm/node_modules/.bin/store/...). The webpack babel rule excluded on /(node_modules)/, which then matched every source file, silently skipping babel-plugin-transform-import-meta — so webpack treated new URL('./dataLoader.worker.min.js', import.meta.url) in webWorkerManager.js as a build-time file dependency and failed with "Module not found".

The babel rule now uses include: src instead of the path-segment exclude, which is robust regardless of where the checkout lives. Verified by reproducing the failure from a git archive extracted under a node_modules path (old config fails, new config builds), plus the usual local build and 190/190 tests.

Both this PR's check and all of slim PR #405's checks are green.