Add typed Cell Annotation provider interfaces and replay plugin registration

[Copilot]

Cell Annotation needed a lightweight contract for coordinating with Heatmap and FlowSOM without hard dependencies, plus reliable provider registration during plugin startup. This updates the shared interfaces and fixes the registration path so providers are discovered even when Cell Annotation is initialized after other plugins.

• Shared cross-plugin interfaces

  • completes viewer/interfaces.py with the FlowSOM orchestration method required by Cell Annotation:
    • run_flowsom(selection, params, training_markers, extra_markers, imputation, projection) -> Mapping
  • keeps SelectionSpec as the opaque selection handle passed across plugin boundaries

• Provider registration lifecycle

  • adds explicit Heatmap / FlowSOM registration logging in CellAnnotationPlugin
  • deduplicates repeated registrations for the same provider
  • adds register_loaded_providers(...) to replay provider self-registration against already-instantiated side-plot plugins
  • hooks that replay into main_viewer after cell_annotation_plugin is created, fixing the startup ordering gap

• Plugin-side compatibility hooks

  • keeps Heatmap registration minimal via register_heatmap(self)
  • updates FlowSOM to expose the requested orchestration signature while preserving the existing button-driven UI path through a thin click wrapper
  • stores selection context through the provider API without refactoring FlowSOM internals

• Focused coverage

  • verifies interface importability and method shape
  • verifies provider replay registers Heatmap / FlowSOM once per session
  • verifies FlowSOM remains optional and absence does not break Cell Annotation save/load wiring
  • verifies plugin registration hooks call into Cell Annotation as expected

Example of the new protocol surface:

class FlowsomParamsProvider(Protocol):
    def export_flowsom_params(self) -> dict[str, Any]: ...
    def import_flowsom_params(self, params: Mapping[str, Any]) -> None: ...
    def set_selection_context(self, selection: SelectionSpec) -> None: ...
    def run_flowsom(
        self,
        selection: SelectionSpec | None,
        params: Mapping[str, Any] | None,
        training_markers: Sequence[str] | None,
        extra_markers: Sequence[str] | None,
        imputation: Any,
        projection: Any,
    ) -> Mapping[str, Any]: ...

Original prompt

---

This section details on the original issue you should resolve

<issue_title>Sub-issue: Cross-Plugin Interfaces & Registration</issue_title>
<issue_description># Interfaces: SelectionSpec, Heatmap/FlowSOM provider protocols, registration

Tracked by: #15
Milestone: M1 — Scaffolding
Labels: area:cell-annotation, area:heatmap, area:flowsom, type:infra, size:S, priority:P1

Summary

Define lightweight, typed interfaces that allow the Cell Annotation plugin to coordinate Heatmap and FlowSOM without tight coupling. Add registration calls in both plugins.

Scope

In

• viewer/interfaces.py:
  • SelectionSpec (opaque selection handle protocol; placeholder methods/attrs acceptable)
  • HeatmapStateProvider:
    • export_heatmap_state(include_embeddings, include_raw_medians, extra_obs_cols) -> dict
    • import_heatmap_state(adata_path: str) -> None
  • FlowsomParamsProvider:
    • export_flowsom_params() -> dict
    • import_flowsom_params(params: Mapping[str, Any]) -> None
    • set_selection_context(selection: SelectionSpec) -> None
    • run_flowsom(selection, params, training_markers, extra_markers, imputation, projection) -> Mapping
• Registration:
  • Heatmap plugin: viewer.services.cell_annotation.register_heatmap(self)
  • FlowSOM plugin: viewer.services.cell_annotation.register_flowsom(self)

Out

• No concrete SelectionSpec persistence (that’s in Merge/Selection work)
• No FlowSOM/Heatmap internal refactors yet, just method shells and registration

Deliverables

• viewer/interfaces.py with Protocols and type hints
• Minimal SelectionSpec class stub in plugins/cell_annotation/selection_spec.py to pass around
• Registration code paths in Heatmap & FlowSOM plugin init

Acceptance Criteria

• Application boots with flag on; Cell Annotation logs successful provider registration when plugins load
• With FlowSOM missing/disabled, registration is optional; Cell Annotation remains functional for save/load hooks
• Static type check (mypy/pyright if used) passes on the new interfaces

Test Plan

• Unit: importability of viewer/interfaces.py; method signatures
• Integration: log-based assertion that providers register once per session; absence of FlowSOM doesn’t crash

Dependencies

• Tracked by Epic: Cell Annotation Workflow (checkpoints, merge, flexible markers) #15
• Blocked by: Plugin Scaffolding (#)
• Blocks: Serializer (#), Browser UI (#)
  </issue_description>

Comments on the Issue (you are @copilot in this section)

• Fixes Sub-issue: Cross-Plugin Interfaces & Registration #17

---

📍 Connect Copilot coding agent with Jira, Azure Boards or Linear to delegate work to Copilot in one click without leaving your project management tool.