[WSI integration] Bind QuPath slide + ROI context to file/folder LabConstrictor runs and import spatial results safely #51

Goal

Make the existing QuPath LabConstrictor bridge capable of launching a Python tool on an existing OME-Zarr file/folder without exporting the full WSI, while maintaining trustworthy QuPath image identity, user-selected tissue ROI geometry and full-resolution coordinate mapping so feature results can be imported onto the correct original slide.

This is the bridge ownership for the WSI route. CellPatcher owns tiling, morphobricks-preprocessing owns window reads/pyramid calibration, morphobricks-normalization owns stain conversion, FiberFeatures/MorphoFeature own measurements. Do not implement WSI readers or new tilers here.

Current code / limitations

• Bridge prepareInput/prepareImageInput: file and folder inputs already pass paths to Python; typed image file inputs are also passed by path. By contrast, a live QuPath image/ROI is TIFF-exported with a default 100M-pixel and 4GiB limit (correctly refusing giant slides). Do not increase these limits to enable WSI.
• Bridge run binding freezes selected ROI shapes and viewer source identity when a live image input is used. With only file/folder inputs, there is currently no automatic source ImageData binding, selection snapshot, or safe result placement.
• Bridge result display: points/shapes from file input are explicitly not placed on the active image because they are in the file's own coordinate frame; images open as separate images. This is a correct safeguard; extend it through an explicit verified context, never remove the safeguard.
• LabConstrictor-Tools protocol supports generic file, folder, table, points, shapes outputs and opt-in display metadata. Define any new source-context/measurement or overlay semantics upstream as needed.

Proposed small, opt-in source context

1. Add an explicit action such as "Run on source file/OME-Zarr associated with current QuPath image" (name to be designed), selecting an existing path readable by the Python process. A plain unrelated file/folder chooser retains current unbound behaviour. Never infer equivalence from basename, folder name, dimensions or currently open viewer.
2. Freeze at Run: stable project entry / server identity, original image URI or user-confirmed alternate OME-Zarr mapping, original QuPath ROI UUIDs + polygons/holes and selection plane, full-resolution bounds, channel/RGB meaning, physical calibration and original colour profile. Preserve a versioned context manifest accessible to the tool. The source-data equivalence and any coordinate transformation from the QuPath source to OME-Zarr must be explicitly verified or confirmed with independent evidence before attaching results. A file fingerprint alone does not prove another converted representation has matching pixels.
3. Carry pyramid level and coordinate transform separately: level index, dataset path, physical (dy,dx), NGFF affine scale/translation where supported, rounding/pixel-centre convention and exact ROI clipping. A Zarr level is not guaranteed to downsample by 2; never guess scale or offset.
4. Export ROI geometry / masks separately from its rectangular bounding box. Only include ROI-mask pixels for tissue measurements; attach an explicit ROI UUID ↔ label/shape table (not solely numerical label). QuPath's image selection may contain several disjoint annotations and holes.
5. On completion, re-check original source identity, geometry, run status and coordinate transform. Support opt-in result import (see #50), preserving result files and warning when original image no longer safely matches. Do not draw file outputs at pixel origin or on an arbitrary current slide.
6. Keep long-running result bundles in an explicit durable output location with an owned manifest and selective cleanup. The bridge's ordinary recent-results retention is not an archive/backup of valuable WSI analyses. Provide cancellation, progress and run-state handling consistent with LabConstrictor protocol.

Return modalities — stage them

Phase A (first WSI import): feature table keyed by source ROI UUID and explicit CellPatcher patch_id + rectangular bounds, aggregate numeric measurements over the original selected ROI; import selected measurements via #50. A CSV report alone is an acceptable preliminary output, not the final overlay claim.

Phase B: optional spatial sampling heatmap, generated on a known pyramid grid and shown in QuPath as a registered overlay (not opened as an unrelated image). A manageable number of tile objects may be offered, but never create millions of QuPath detections by default. Test caching/pan/zoom performance and correct coordinate registration.

Fail-closed integration tests

• QuPath slide A open, Python tool reads a confirmed matching OME-Zarr source; result ROI measurements/maps land on A at exact coordinates and same Z/T; switch to B midrun does not retarget.
• Same basename but different pixels, mismatched pyramid level, off-by-one geometry, transformed/rescaled/rotated slide or unknown calibration -> no automatic attachment.
• QuPath ROI with polygon holes, disjoint regions, multiple annotations and changed geometry after launch; incorrect/missing UUID mapping refused.
• RGB remains a coherent colour image; no silent display-to-pixel LUT mixing, colour profile changes or CYX/spatial ZYX confusion.
• Input WSI larger than current export guards works by file path and true lazy window reading, not by bypassing the guards or materializing a full TIFF.
• Run can be cancelled; output is not advertised complete until source/ROI/feature manifest and success marker are validated. Test recovery of partial output.
• UI results and any overlays remain correct after window/view changes and reopening the project; performance measured on a real large OME-Zarr slide.

Dependencies / coordination

• QuPath #49 — small-ROI smoke test
• QuPath #50 — safe ROI UUID/measurement attachment
• morphobricks-preprocessing #179 — explicit level/window reads
• CellPatcher #87 — lazy OME-Zarr tiling
• FiberFeatures #160 — tile normalization/halo equivalence
• MorphoBricks-Spec #2 — WSI umbrella

This work is not required for the initial one-ROI QuPath smoke test.