feat(lif): resolve shading references from a user-supplied library file

[ferrinm]

Motivation

Follow-up to #47 (ADR-0006). That issue landed the extractor + audit surface + MosaicShadingWarning for LIF shading references. Per the empirical spike (2026-07-02, sandbox notebook), LIF acquisition files carry shading references (id + human name) inside <InScanProcessing>/<CameraLane*>/<ShadingProcessingStep> but not the corresponding pixel data — LAS X keeps the shading library on the acquisition PC and does not ship it in exported .lif (or .lifext) files.

To actually apply the correction on affected mosaics — the astrocytes acquisition (#41 follow-up) is the driving case — zarrmony needs a way to accept an external library and resolve the reference ids against it.

What to build

1. New kwarg: convert(..., lif_shading_library: str | Path | None = None). When supplied, zarrmony opens the library, indexes its shading-reference images by id, and uses them for correction whenever the current scene's <ShadingProcessingStep> references match.
2. Library parser: assume LAS X exports the library as a standalone .lif — needs empirical confirmation on a real acquisition PC's library file. May require a custom parser if bioio-lif/readlif can't open it (the .lifext sidecar hits the same "image count ≠ offset count" integrity failure).
3. Correction pass: applied to raw M-intact tiles from tiles_xarray_dask_data before any stitcher (stage / grid / bioio-lif / per-tile) consumes them. Convention TBD — likely tile_corrected = (tile - dark) / (flat - dark) * mean(flat - dark); needs empirical calibration against a LAS X-corrected reference on the same acquisition.
4. Audit surface updates: flip mosaic.shading_correction to {applied: true, method: str, source_library: str, references_resolved: [...], references_unresolved: [...]}. Unresolved references (id in scene missing from library) → keep firing MosaicShadingWarning naming what was missing; conversion still succeeds.
5. CLI: --lif-shading-library PATH matching the kwarg.

Acceptance

• On a LIF + library pair where all references resolve, tile-seam brightness discontinuities visibly reduced on a representative astrocytes scene; before/after screenshots in the PR.
• No lif_shading_library supplied → today's feat(lif): apply per-tile shading correction using LIF's ShadingReference #47 behavior (extract + warn + no-op) unchanged.
• Library present but scene's ref-id not in library → per-scene MosaicShadingWarning, no-op for that scene, conversion continues.
• Synthetic fixture test: library with a known shading pattern → correction restores flat field within tolerance.
• CHANGELOG entry, v0.9.0 (or later — depends on when a real fixture lands).

Blockers

1. No pilot fixture. No user has a resolvable shading library on hand today. Julia's astrocytes acquisition is the driving case; its LAS X shading library lives on the microscope PC and has not been retrieved. Needs an ask to the imaging team.
2. Library format assumption unverified. Assumed to be a plain .lif file. The .lifext spike showed Leica sidecar files can be LIF-container-format but with integrity checks that break readlif; a shading library may share that shape.
3. Correction math unverified. LAS X's exact convention (multiplicative flat only? subtractive dark + multiplicative flat? per-lane vs per-channel scaling?) needs empirical calibration against a LAS X-corrected reference.

Discovered while

Spike for #47 (2026-07-02, s3_zarrmony_sandbox/s3_zarrmony_notebook.org under the ODC51_astrocytes heading) confirmed reference pixels are not embedded in either the .lif or the .lifext, ruling out any zarrmony-alone solution.