xnano

@classmethod
def keyboard(
    cls,
    *bindings: KeyboardBinding,
    kind: KeyboardEventKind | None = None,
) -> "KeyboardAction":
    """Match one or more keyboard bindings."""
    return KeyboardAction(bindings=bindings, kind=kind)

@classmethod
def mouse(
    cls,
    *buttons: MouseButton,
    kind: MouseEventKind | None = None,
) -> "MouseAction":
    """Match a mouse event."""
    return MouseAction(buttons=buttons, kind=kind)

@classmethod
def click(
    cls,
    field: str | None = None,
    button: MouseButton = "left",
) -> "ClickAction":
    """Match a button press on a field."""
    return ClickAction(field=field, button=button)

@classmethod
def focus(
    cls,
    field: str | None = None,
    kind: FocusEventKind | None = None,
) -> "FocusAction":
    """Match a focus transition."""
    return FocusAction(field=field, kind=kind)

@classmethod
def clipboard(cls, text: str | None = None) -> "ClipboardAction":
    """Match pasted text."""
    return ClipboardAction(text=text)

@classmethod
def tick(cls, interval_ms: int = 0) -> "TickAction":
    """Match a clock tick."""
    return TickAction(interval_ms=interval_ms)

@classmethod
def resize(
    cls,
    width: int | None = None,
    height: int | None = None,
) -> "ResizeAction":
    """Match a resize event."""
    return ResizeAction(width=width, height=height)

@classmethod
def request(cls, method: str, path: str = "/") -> "RequestAction":
    """Match an HTTP request."""
    return RequestAction(method=method.upper(), path=path)

@abc.abstractmethod
def matches(self, event: Any) -> bool:
    """Return whether ``event`` satisfies this action."""

@staticmethod
def option(
    name_or_flags: str | list[str],
    *,
    default: Any = None,
    help: str | None = None,
    is_flag: bool | None = None,
) -> Callable[[Callable[..., Any]], Callable[..., Any]]:
    """Attach option names and help text to a command parameter."""

    def decorator(func: Callable[..., Any]) -> Callable[..., Any]:
        options = getattr(func, "_cli_options", None)
        if options is None:
            options = []
            setattr(func, "_cli_options", options)
        if isinstance(name_or_flags, str):
            flags = [name_or_flags]
        else:
            flags = list(name_or_flags)
        options.append(
            {
                "flags": flags,
                "default": default,
                "help": help,
                "is_flag": is_flag,
            }
        )
        return func

    return decorator

def command(
    self,
    name: str | None = None,
    *,
    description: str | None = None,
) -> Callable[[Callable[..., Any]], Callable[..., Any]]:
    """Decorator to register a subcommand."""

    def decorator(func: Callable[..., Any]) -> Callable[..., Any]:
        func_name = getattr(func, "__name__", None) or "command"
        command_name = name or func_name.replace("_", "-")
        command_description = description or func.__doc__
        subcommand = Command(
            name=command_name,
            description=command_description,
            strict=self.strict,
            help=self.help,
        )
        subcommand._callback = func
        subcommand._register_from_function(func)
        self._subcommands[command_name] = subcommand
        self._parser_dirty = True
        return func

    return decorator

def register_callback(
    self, func: Callable[..., Any]
) -> Callable[..., Any]:
    """Register the main callback for this command."""
    self._callback = func
    self._register_from_function(func)
    self._parser_dirty = True
    return func

def add_subcommand(self, subcommand: "Command") -> None:
    """Add a subcommand programmatically."""
    if not subcommand.name:
        raise CliError("Subcommand must have a name to be added.")
    self._subcommands[subcommand.name] = subcommand
    self._parser_dirty = True

def parse_arguments(
    self, arguments: list[str]
) -> tuple["Command", dict[str, Any]]:
    """Parse arguments without exiting the process.

    Raises:
        HelpRequested: When help was requested.
        CliError: On usage / validation failures.
    """
    # Prefer the stable hand-parser semantics for drop-in parity with
    # existing tests, while exposing argparse caching for future work.
    return self._parse_manual(arguments)

def run(self, arguments: list[str] | None = None) -> Any:
    """Parse arguments and run the command, exiting on errors/help."""
    if arguments is None:
        arguments = sys.argv[1:]
    try:
        target, parsed = self.parse_arguments(arguments)
    except HelpRequested as help_requested:
        print(render_help(help_requested.command), end="")
        sys.exit(0)
    except HelpException as help_exception:
        print(render_help(help_exception.command), end="")
        sys.exit(0)
    except CliError as error:
        print_error(error.message, error.command or self)
        sys.exit(error.exit_code)
    except ValueError as error:
        # Compatibility with callers raising plain ValueError.
        print_error(str(error), self)
        sys.exit(2)

    if target._callback is None:
        print(render_help(target), end="")
        sys.exit(0)
    return target._callback(**parsed)

def get_help(self) -> str:
    """Return plain help text for this command."""
    return format_plain_help(self)

def __call__(self, *args: Any, **kwargs: Any) -> Any:
    """Register a callback or run with ``sys.argv``."""
    if len(args) == 1 and callable(args[0]) and not kwargs:
        return self.register_callback(args[0])
    return self.run(sys.argv[1:])

def component_post_init(self) -> None:
    """Initialize subclass state after dataclass fields are assigned.

    Override this method instead of ``__post_init__``.
    """
    return None

def get_frame(self) -> Any | None:
    """Optional frame/panel chrome around composed content."""
    return None

def get_size(self, ctx: ComponentRenderContext[StateT]) -> Size:
    """Return the preferred cell size of this component."""
    return Size(width=0, height=0)

def before_render(
    self,
    ctx: ComponentRenderContext[StateT],
    area: "Area",
) -> "Area":
    """Called before rendering; returns the effective render area."""
    return area

def after_render(
    self,
    ctx: ComponentRenderContext[StateT],
    area: "Area",
) -> None:
    """Called after rendering for optional post-paint work."""
    return None

def compose(self, ctx: ComponentRenderContext[StateT]) -> Content | None:
    """Compose interface-neutral content for this component.

    Returns:
        A ``Content`` tree, or ``None`` when nothing should paint.
    """
    return None

@responsive_noop
def compose_extra_small(
    self, ctx: ComponentRenderContext[StateT]
) -> Content | None:
    """Compose content when the viewport is extra small (< 40 cols).

    Optional responsive counterpart to :meth:`compose`. When
    overridden, it is used *instead of* ``compose`` while the window
    is in this size tier. Overriding any ``compose_*`` variant opts the
    component into breakpoint dispatch; a component that overrides none
    pays no per-frame cost.
    """
    return None

@responsive_noop
def compose_small(
    self, ctx: ComponentRenderContext[StateT]
) -> Content | None:
    """Compose content when the viewport is small (40–79 cols).

    See :meth:`compose_extra_small`.
    """
    return None

@responsive_noop
def compose_medium(
    self, ctx: ComponentRenderContext[StateT]
) -> Content | None:
    """Compose content when the viewport is medium (80–119 cols).

    See :meth:`compose_extra_small`.
    """
    return None

@responsive_noop
def compose_large(
    self, ctx: ComponentRenderContext[StateT]
) -> Content | None:
    """Compose content when the viewport is large (120–159 cols).

    See :meth:`compose_extra_small`.
    """
    return None

@responsive_noop
def compose_extra_large(
    self, ctx: ComponentRenderContext[StateT]
) -> Content | None:
    """Compose content when the viewport is extra large (>= 160 cols).

    See :meth:`compose_extra_small`.
    """
    return None

def handle_keyboard(self, keyboard: "KeyboardEventData") -> bool:
    """Optional keyboard handler while focused.

    Returns:
        ``True`` when the event was consumed.
    """
    return False

def handle_paste(self, text: str) -> bool:
    """Optional paste handler while focused.

    Returns:
        ``True`` when the paste was consumed.
    """
    return False

def get_state(self) -> StateT:
    """Return the shared application state.

    Raises:
        RuntimeError: If no state was attached to this context.
    """
    if self.state is None:
        raise RuntimeError("No state attached to this context.")
    return self.state

def focus(self, group: str) -> bool:
    """Focus the field labeled ``group`` on any attached grid."""
    focus_group = getattr(self.terminal, "focus_group", None)
    if callable(focus_group):
        return bool(focus_group(group))
    return bool(self.terminal.focus(group))

def blur(self) -> None:
    """Clear field focus on the active runtime."""
    blur_field = getattr(self.terminal, "blur_field", None)
    if callable(blur_field):
        blur_field()
        return
    blur = getattr(self.terminal, "blur", None)
    if callable(blur):
        blur()

def is_focused(self, group: str) -> bool:
    """Return whether the field labeled ``group`` currently holds focus."""
    return self.focused_group == group

def call_soon(self, callback: "Callable[..., Any]", *args: Any) -> None:
    """Schedule ``callback`` to run on the UI thread before the next pump.

    The thread-safe bridge for updating grid state from a worker thread:
    the callback runs on the runtime's own thread, so it can freely mutate
    components/fields without racing the renderer.
    """
    self.terminal.call_soon(callback, *args)

def field_area(self, name: str) -> "Area | None":
    """Return the last painted area for field ``name``, if known.

    Reads the always-on layout map so viewports and chrome math can use
    measured slot sizes instead of guessing.
    """
    return self.stage.get_area(name)

def scroll(self, group: str) -> "ScrollHandle | None":
    """Return a scroll handle for ``Field(scroll=...)`` labeled ``group``."""
    from xnano.utils.focus import scroll_handle_for_group

    return scroll_handle_for_group(self.terminal, group)

def get_scroll(self, group: str) -> "ScrollHandle | None":
    """Return scroll state for ``group``, or ``None`` if it is unavailable."""
    return self.scroll(group)

def with_event(self, event: "Event") -> "Context[StateT]":
    """Return a copy carrying a different event."""
    return dataclasses.replace(self, event=event)

def with_scope(self, **kwargs: Any) -> "Context[StateT]":
    """Return a shallow copy with the given fields replaced."""
    return dataclasses.replace(self, **kwargs)

def has_clipboard_event(self) -> bool:
    """Return whether this context contains a clipboard event."""
    return self.event.is_clipboard_event()

def has_focus_event(self) -> bool:
    """Return whether this is a focus event."""
    return self.event.is_focus_event()

def has_keyboard_event(self) -> bool:
    """Return whether this is a keyboard event."""
    return self.event.is_keyboard_event()

def has_mouse_event(self) -> bool:
    """Return whether this is a mouse event."""
    return self.event.is_mouse_event()

def has_resize_event(self) -> bool:
    """Return whether this is a resize event."""
    return self.event.is_resize_event()

def contains(self, needle: str) -> bool:
    """Return whether plain text contains ``needle``."""
    return needle in self.text