xnano.markdown

def viewport_height(self) -> int:
    """Return the visible row count for the current terminal size."""
    from xnano.core.runtime import get_active_runtime

    runtime = get_active_runtime()
    height = runtime.size[1] if runtime is not None else 24
    return max(1, height - self.reserved_rows)

def total_rows(self) -> int:
    """Return the document height in rows across all blocks."""
    width = self._layout_width
    viewport = self.viewport_height()
    self._sync_image_block_rows(
        terminal_width=width,
        viewport_rows=viewport,
    )
    return sum(block.rows for block in self._blocks())

def max_offset(self) -> int:
    """Return the largest useful offset — the last full page of rows."""
    return max(0, self.total_rows() - self.viewport_height())

def page_rows(self) -> int:
    """Return the offset delta for a page-sized jump (one row overlap)."""
    return max(1, self.viewport_height() - 1)

def scroll_percentage(self) -> int:
    """Return how far the view has scrolled, from 0 to 100."""
    maximum = self.max_offset()
    if maximum <= 0:
        return 100
    return round(min(self.offset, maximum) / maximum * 100)

def scroll_by(self, delta: int) -> None:
    """Move the view by ``delta`` rows, clamped to the document."""
    self.offset = min(self.max_offset(), max(0, self.offset + delta))

def scroll_to_top(self) -> None:
    """Move the view to the first row."""
    self.offset = 0

def scroll_to_bottom(self) -> None:
    """Move the view to the last page."""
    self.offset = self.max_offset()

def has_expandable_image(self) -> bool:
    """Return whether the document contains at least one local image."""
    return any(block.kind == "image" for block in self._blocks())

def active_image_key(self) -> str | None:
    """Return the pinned or hovered image key, if any."""
    return self._pinned_image_key or self._hovered_image_key

def update_pointer(self, x: int, y: int) -> bool:
    """Update hover from body-local cell coordinates.

    Args:
        x: Column within the body field.
        y: Row within the body field (0 = top of the viewport).

    Returns:
        ``True`` when the hovered image identity changed.
    """
    document_row = min(self.offset, self.max_offset()) + max(0, y)
    previous = self._hovered_image_key
    hit_key: str | None = None
    for region in self._image_hit_regions:
        if (
            region.start_row <= document_row < region.end_row
            and 0 <= x < max(1, region.width + 2)
        ):
            hit_key = region.key
            break
    self._hovered_image_key = hit_key
    return previous != hit_key

def clear_pointer(self) -> bool:
    """Clear hover state.

    Returns:
        ``True`` when a hovered image was cleared.
    """
    if self._hovered_image_key is None:
        return False
    self._hovered_image_key = None
    return True

def toggle_pin_at(self, x: int, y: int) -> bool:
    """Pin or unpin the image under body-local coordinates.

    Args:
        x: Column within the body field.
        y: Row within the body field.

    Returns:
        ``True`` when pin state changed.
    """
    document_row = min(self.offset, self.max_offset()) + max(0, y)
    for region in self._image_hit_regions:
        if (
            region.start_row <= document_row < region.end_row
            and 0 <= x < max(1, region.width + 2)
        ):
            if self._pinned_image_key == region.key:
                self._pinned_image_key = None
            else:
                self._pinned_image_key = region.key
                self._hovered_image_key = region.key
            return True
    return False

def toggle_expand(self) -> bool:
    """Toggle expand on the hovered, pinned, or first visible image.

    Returns:
        ``True`` when pin state changed.
    """
    if self._pinned_image_key is not None:
        self._pinned_image_key = None
        return True
    if self._hovered_image_key is not None:
        self._pinned_image_key = self._hovered_image_key
        return True
    # Fall back to the first image currently intersecting the viewport.
    top = min(self.offset, self.max_offset())
    bottom = top + self.viewport_height()
    for region in self._image_hit_regions:
        if region.end_row > top and region.start_row < bottom:
            self._pinned_image_key = region.key
            return True
    for block in self._blocks():
        if block.kind == "image" and block.image_key:
            self._pinned_image_key = block.image_key
            return True
    return False

def compose(self, ctx: "ComponentRenderContext[Any]") -> Any:
    """Compose the blocks currently inside the viewport."""
    import xnano_core.core as core
    import xnano_core.rust.native as native

    from xnano.core.content import Native
    from xnano.core.rendering import lower_content
    from xnano.core.runtime import get_active_runtime

    del ctx  # area comes from the active runtime / field slot
    viewport = self.viewport_height()
    runtime = get_active_runtime()
    width = runtime.size[0] if runtime is not None else 80
    self._layout_width = width
    self._sync_image_block_rows(
        terminal_width=width,
        viewport_rows=viewport,
    )
    top = min(self.offset, self.max_offset())
    bottom = top + viewport

    children: list[Any] = []
    constraints: list[Any] = []
    hit_regions: list[_ImageHitRegion] = []
    row = 0
    for block in self._blocks():
        start, end = row, row + block.rows
        row = end
        if block.kind == "image" and block.image_key:
            body_cols, _ = self._image_body_size(
                block,
                terminal_width=width,
                viewport_rows=viewport,
            )
            hit_regions.append(
                _ImageHitRegion(
                    key=block.image_key,
                    start_row=start,
                    end_row=end,
                    width=body_cols,
                )
            )
        if end <= top or start >= bottom:
            continue
        visible_rows = min(end, bottom) - max(start, top)
        if visible_rows <= 0:
            continue
        if block.kind == "text":
            first = max(start, top) - start
            window = block.lines[first : first + visible_rows]
            node = lower_content(
                TextBlock(
                    lines=tuple(window),
                    foreground=self.foreground,
                    background=self.background,
                    modifiers=self.modifiers,
                    horizontal_align=self.horizontal_align,
                    wrap=self.wrap,
                )
            )
        else:
            first = max(start, top) - start
            node = self._compose_image_block(
                block,
                terminal_width=width,
                viewport_rows=viewport,
                first_row=first,
                visible_rows=visible_rows,
            )
        children.append(node)
        constraints.append(native.Constraint.length(visible_rows))

    self._image_hit_regions = tuple(hit_regions)

    if not children:
        return TextBlock(lines=(), visible=self.visible)
    column = core.CoreRenderNode.column(
        children, constraints=constraints, gap=0
    )
    return Native(interface_kind="terminal", payload=column)

def component_post_init(self) -> None:
    """Force markdown mode, then run ``Text`` setup."""
    self.markdown = True
    super().component_post_init()

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[Any]",
    area: "Area",
) -> None:
    """Record the multi-line editor caret so the terminal cursor tracks it."""
    if not (self._input_focused and self._editor is not None):
        self._cursor_position = None
        return
    row, column = self._editor.cursor()
    # ponytail: no soft-wrap/scroll accounting; clamps to the slot, which
    # is exact for a note-sized editor. Add offsets if the body scrolls.
    x = area.x + max(0, min(column, max(0, area.width - 1)))
    y = area.y + max(0, min(row, max(0, area.height - 1)))
    self._cursor_position = (x, y)

@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:
    """Edit this text when it has focus.

    Passthrough bindings remain available to hooks. Read-only inputs reject
    edits, and ``max_length`` limits inserted content.

    Args:
        keyboard: The keyboard event payload.

    Returns:
        ``True`` when the key was consumed as text editing.
    """
    if self.passthrough and keyboard.matches(*self.passthrough):
        return False
    if not self.input:
        return False

    if self._editor is not None:
        return self._handle_editor_keyboard(keyboard)
    return self._handle_single_line_keyboard(keyboard)

def handle_paste(self, text: str) -> bool:
    """Insert pasted text at the caret of a multi-line editor.

    Args:
        text: The pasted clipboard text.

    Returns:
        ``True`` when the paste was consumed by the native editor.
    """
    if self._editor is None:
        return False
    if self.read_only:
        return True
    text = self._clamp_text(text)
    if self.max_length is not None:
        remaining = self.max_length - len(self._editor.text())
        if remaining <= 0:
            return True
        text = text[:remaining]
    self._editor.insert_text(text)
    object.__setattr__(self, "content", self._editor.text())
    return True

def get_terminal_node(
    self, ctx: ComponentRenderContext[Any]
) -> TextBlock | Native | Panel | None:
    """Return composed content for terminal compatibility.

    Args:
        ctx: Render-time scope for this paint.

    Returns:
        The same interface-neutral content as ``compose``.
    """
    return self.compose(ctx)