"""# Summary

Family registry — resolve a ``(kind, variant, mode)`` triple to a root class.

A single lookup replaces hand-rolled ``if/else`` family selection.
"""

# Populated by ``register`` as families import.
_FAMILIES: dict[str, dict[str, dict[str, type]]] = {}


def register(kind: str, variant: str, root_cls: type, mode: str = "default") -> type:
    """Register ``root_cls`` for a ``(kind, variant, mode)`` triple.

    Returns:
        Type: The registered class (so it can be used as a decorator).
    """
    _FAMILIES.setdefault(kind, {}).setdefault(variant, {})[mode] = root_cls
    return root_cls


def resolve_root(kind: str, variant: str, mode: str = "default") -> type:
    """Return the root class for a ``(kind, variant, mode)`` triple.

    Raises:
        KeyError: When no family matches the triple.
    """
    return _FAMILIES[kind][variant][mode]