"""FlexohrProtocol — the interface shared by OHR, OHRView, and OHRarray.

Paradigm-agnostic: no pitch-specific concepts.  Defines only structural
access (reference, body, properties, iteration).
"""

from __future__ import annotations

from typing import Any, Iterator, Protocol, runtime_checkable

from flexohr.core.component import Component
from flexohr.harmony.enums import FrozenProperties


@runtime_checkable
class FlexohrProtocol(Protocol):
    """Core interface implemented by OHR, OHRView, and OHRarray."""

    @property
    def reference_component(self) -> Component | None: ...

    @property
    def reference_ohr(self) -> Any: ...  # OHR | None (avoids circular import)

    @property
    def body(self) -> tuple[Any, ...]: ...

    @property
    def ordered(self) -> bool: ...

    @property
    def horizontal(self) -> bool: ...

    @property
    def properties(self) -> FrozenProperties: ...

    def components(self, **filters: Any) -> tuple[Component, ...]: ...

    def nested_ohrs(self) -> tuple[Any, ...]: ...

    def __iter__(self) -> Iterator[Any]: ...

    def __len__(self) -> int: ...
