feat: controllable highlight state for embedding hosts #4401

Summary

NMRium's highlight state is currently private to HighlightProvider / useHighlight. Embedding hosts (for example via nmrium-react-wrapper) sometimes need to drive that state from outside NMRium — typically across a cross-origin iframe with postMessage.

Proposed API

export interface NMRiumHighlightState {
  highlighted: string[];
  highlightedPermanently: string[];
  sourceData: HighlightEventSource | null;
}

interface NMRiumProps {
  // ...existing
  /** When provided, highlight state is controlled by the host. */
  highlight?: NMRiumHighlightState;
  /** Called for every highlight change, including internal hover/click. */
  onHighlightChange?: (state: NMRiumHighlightState) => void;
}

Leaving highlight out keeps today's behaviour unchanged (uncontrolled).

Implementation sketch

• HighlightProvider accepts optional value / onChange.
• In controlled mode, render from value; dispatch runs the existing reducer against a latest-state ref and calls onChange(next) instead of updating internal state.
• Keep that ref in sync with each reduced value (not only with props), so consecutive dispatches such as the useHighlight unmount cleanup (HIDE then UNSET_PERMANENT) do not drop updates.
• The internal highlights record can stay derived from highlighted and remain private.
• Wire highlight / onHighlightChange from NMRiumProps through InnerNMRium into HighlightProvider.
• Export NMRiumHighlightState (and HighlightEventSource if not already public).

Out of scope (separate discussion)

NMRium regenerates peak ids on load, so imported ids from a host never match. Hosts currently fall back to matching by nucleus + ppm. Keeping imported peak ids stable would let hosts highlight by id; that can be a follow-up.

Questions for the team

1. Is the controlled-prop shape preferred over an imperative NMRiumRefAPI.highlight(ids) / clearHighlight() method?
2. Any concern about onHighlightChange firing on every hover (performance for large spectra / embedding hosts)?