gitpane 1.0.0__py3-none-any.whl

gitpane/ui/welcome/welcome_window.py

@@ -0,0 +1,1137 @@
+"""Show the welcome window, where the user opens a recent repository, a folder or a clone."""
+
+from __future__ import annotations
+
+import enum
+from dataclasses import dataclass
+from functools import partial
+from itertools import pairwise
+from math import ceil
+from typing import TYPE_CHECKING, Self
+
+from PySide6.QtCore import QEvent, QMargins, QModelIndex, QPointF, QRect, QRectF, QSize, Qt, QTimer, Signal
+from PySide6.QtGui import QAction, QColor, QFont, QFontMetrics, QPainter, QPalette, QTextLayout, QTextOption
+from PySide6.QtWidgets import (
+    QAbstractItemView,
+    QApplication,
+    QFileDialog,
+    QFrame,
+    QGridLayout,
+    QHBoxLayout,
+    QLabel,
+    QLayout,
+    QLineEdit,
+    QListWidget,
+    QListWidgetItem,
+    QMessageBox,
+    QPushButton,
+    QScrollArea,
+    QSizePolicy,
+    QStyle,
+    QStyledItemDelegate,
+    QStyleOptionViewItem,
+    QVBoxLayout,
+    QWidget,
+)
+
+from gitpane.config import (
+    FIRST_ROW,
+    MILLISECONDS_PER_SECOND,
+    RECENT_CHECK_UNKNOWN_DELAY_MS,
+    RECENT_CHECKING_DISPLAY_DELAY_MS,
+    SCREEN_MARGIN,
+    SPACING_XS,
+    UNKNOWN_DARK_COLOR,
+    UNKNOWN_LIGHT_COLOR,
+    WELCOME_MAX_SCREEN_RATIO,
+    WELCOME_MIN_HEIGHT,
+    WELCOME_MIN_WIDTH,
+    WELCOME_WIDTH,
+    SharedText,
+    center_window_at,
+    fit_window,
+)
+from gitpane.operation.diagnostic import SensitiveTextFilter
+from gitpane.recent.mount_table import PLATFORM_MOUNT_TABLE_READER
+from gitpane.recent.recent_availability import RecentAvailabilityCheck, folder_is_reachable, ignore_log_line, unanswered_after_wait_log_line
+from gitpane.recent.recent_name import repository_display_name
+from gitpane.recent.recent_search import ranked_recent_dirs
+from gitpane.text.typed_path import session_typed_path, typed_path_value
+from gitpane.text.typed_text import typed_value
+from gitpane.thread.weak_signal import weak_signal_emitter
+from gitpane.ui.look.action_icon import action_icon
+from gitpane.ui.look.theme_color import is_dark_palette
+from gitpane.ui.look.theme_look import follow_theme
+from gitpane.ui.look.windows_control_look import WINDOWS_LIST_BORDER_WIDTH, apply_windows_line_edit_look, fit_windows_field_height, secondary_text_color, windows_list_style_sheet
+from gitpane.ui.transport.clone_dialog import CLONE_FORM_CAPTIONS, CLONE_PLAIN_SIDE_BUTTON_TEXTS
+from gitpane.ui.widget.busy_indicator import FRAME_INTERVAL_MS, next_busy_angle, paint_busy_arc
+from gitpane.ui.widget.dialog_layout import (
+    BROWSE_TEXT,
+    BUTTON_COLUMN,
+    FIELD_COLUMN,
+    FORM_BAND_BUTTON_MIN_SIZE,
+    FORM_GRID_BODY_MARGINS,
+    FORM_GRID_CAPTION_INDENT,
+    FORM_GRID_COLUMN_SPACING,
+    FORM_GRID_ROW_SPACING,
+    FORM_GRID_ROWS_TO_BLOCK_SPACE,
+    BandButtonSizing,
+    add_form_caption,
+    apply_side_button_look,
+    fit_caption_to_other_form,
+    fit_side_buttons,
+    install_banded_layout,
+    refresh_style_sheet_fonts,
+)
+from gitpane.ui.widget.long_text import LONG_WORD_WRAP_MODE, WrappingLabel
+from gitpane.ui.widget.result_label import ResultTone, result_color
+from gitpane.ui.window_control.dialog_modality import prepare_message_box
+from gitpane.ui.window_control.item_activation import activate_current_row
+from gitpane.ui.window_control.window_placement import WELCOME_ANCHOR_RANK, centre_on_placement_anchor, is_visible_window, mark_placement_anchor
+
+if TYPE_CHECKING:
+    from collections.abc import Callable
+
+    from PySide6.QtGui import QCloseEvent, QHideEvent, QResizeEvent, QScreen, QShowEvent
+
+    from gitpane.operation.diagnostic import DiagnosticLog
+    from gitpane.recent.mount_table import MountEntry
+
+
+RECENT_COLUMN = 0
+# The Open repository form uses the margins of the shared form grid, as the Clone window does, except at the bottom: the Clone window has a fixed height
+# that provides the room under its content, while this form's height follows its content, so the recent list keeps as
+# much room above the button band as on its left.
+WELCOME_BODY_MARGINS = QMargins(FORM_GRID_BODY_MARGINS.left(), FORM_GRID_BODY_MARGINS.top(), FORM_GRID_BODY_MARGINS.right(), FORM_GRID_BODY_MARGINS.left())
+# The form's grid has a single row: the repository path.
+PATH_ROW = 0
+# The Open repository form adds its clone button in a column right of Browse…; the rest of the grid keeps the columns of
+# the Clone form, so the caption, the field and Browse… stay lined up with that window.
+CLONE_BUTTON_COLUMN = BUTTON_COLUMN + 1
+# Read alone by a screen reader, "or Clone" does not say what the button does.
+CLONE_BUTTON_ACCESSIBLE_NAME = "Clone a repository"
+# Width of the Search field above the recent list, in logical pixels: wide enough for a few words, while the row of
+# Recent repositories:, Search: and the field still fits in the narrowest form.
+RECENT_SEARCH_FIELD_WIDTH = 200
+RECENT_SEARCH_ACCESSIBLE_NAME = "Search recent repositories"
+# The style only wraps an item's text inside a valid rectangle; the height given does not change the measured height.
+MEASURE_RECT_MIN_HEIGHT = 1
+RECENT_MIN_VISIBLE_ROW_COUNT = 1
+"""Recent rows the list keeps room for however short the form gets, before the form itself has to scroll."""
+UNWRAPPED_MEASURE_WIDTH = 100000
+"""Width wide enough for any recent path to fit on one line, to measure a row as if its text did not wrap."""
+# A little air above and below the lines of a recent repository.
+RECENT_ROW_VERTICAL_PADDING = 3
+# The text of the recents, and of the empty recent box, starts at the same x as the captions' text: the captions' indent
+# minus the list border, which already moves the text right.
+RECENT_ROW_PADDING = QMargins(FORM_GRID_CAPTION_INDENT - WINDOWS_LIST_BORDER_WIDTH, RECENT_ROW_VERTICAL_PADDING,
+                              FORM_GRID_CAPTION_INDENT - WINDOWS_LIST_BORDER_WIDTH, RECENT_ROW_VERTICAL_PADDING)
+
+
+def empty_recent_style_sheet(palette: QPalette) -> str:
+    """Return the style sheet of the text shown in place of an empty recent list: the list's border and background, grey text.
+
+    The text sits as far from the border as the text of a recent row, so both start at the same place.
+    """
+    padding = f"{RECENT_ROW_PADDING.top()}px {RECENT_ROW_PADDING.right()}px {RECENT_ROW_PADDING.bottom()}px {RECENT_ROW_PADDING.left()}px"
+    return windows_list_style_sheet(palette, "QLabel", hide_focus_outline=False) + f" QLabel {{ color: {secondary_text_color(palette).name()}; padding: {padding}; }}"
+
+
+class WelcomeText(enum.Enum):
+    """Texts the Open repository window shows, one member per text."""
+
+    TITLE = "GitPane"
+    OPEN_REPOSITORY = "Open repository"
+    OPEN = "Open"
+    CLONE = "or Clone"
+    CANCEL_READING = "Cancel reading"
+    REPOSITORY_PATH = "Repository path"
+    EMPTY_PATH = "Enter a repository path or use Browse."
+    RECENT_SEARCH = "Search"
+    RECENT_EMPTY = "No recent repositories"
+    RECENT_NO_MATCH = "No matching repositories"
+    RECENT_HELP = "Enter a repository path or click Browse to get started."
+    OPENING = "Opening…"
+    INVALID_PATH_TITLE = "Invalid path"
+    INVALID_PATH = "This folder does not exist:\n{path}"
+
+
+class RecentMark(enum.Enum):
+    """What the third line of a recent's row says about the check of its folder: nothing, still checking, Unknown or Unavailable.
+
+    The value is what a listed row keeps in its item data; the text the line shows is the ``label`` attribute.
+    """
+
+    NONE = ("", "")
+    CHECKING = ("checking", "checking")
+    UNKNOWN = ("unknown", "Unknown")
+    UNAVAILABLE = ("unavailable", "Unavailable")
+
+    def __new__(cls, value: str, label: str) -> Self:
+        """Keep the value its row stores as the member's value, and the text its line shows beside it."""
+        member = object.__new__(cls)
+        member._value_ = value
+        member.label = label
+        return member
+
+
+# Item data role that holds the value of a recent repository's mark; the path itself is in UserRole.
+RECENT_MARK_ROLE = int(Qt.ItemDataRole.UserRole) + 1
+
+
+def index_recent_mark(index: QModelIndex) -> RecentMark:
+    """Return the mark a listed row carries; a row without any mark data has none."""
+    mark_value = index.data(RECENT_MARK_ROLE)
+    if mark_value is None:
+        return RecentMark.NONE
+    return RecentMark(mark_value)
+
+
+def recent_item_text(recent_dir: str, mark: RecentMark) -> str:
+    """Return the whole row of a recent as plain text, for screen readers: its name, its path, and its mark's label when it has one.
+
+    The name is the one the search ranks and the window title shows, the whole path for the root of a drive, which has
+    no folder name. The delegate draws the same lines in colors.
+    """
+    text = f"{repository_display_name(recent_dir)}\n{recent_dir}"
+    if mark != RecentMark.NONE:
+        text += "\n" + mark.label
+    return text
+
+
+@dataclass(frozen=True)
+class RecentRowLine:
+    """One line of text of a recent repository, as it is measured and painted.
+
+    ``indent`` moves the text right, in the measure as in the painting, so the measured height stays the painted one;
+    the "checking" line leaves that room for the turning arc drawn at its left when ``shows_busy_arc`` is set.
+    """
+
+    text: str
+    font: QFont
+    color: QColor
+    indent: int = 0
+    shows_busy_arc: bool = False
+
+
+# Space between the turning arc and the "checking" text it stands before.
+RECENT_BUSY_ARC_GAP = SPACING_XS
+
+
+class RecentRepositoryDelegate(QStyledItemDelegate):
+    """Draw a recent repository as its folder name, its full path in the secondary text color, then its mark in italics.
+
+    The mark is "checking" while the folder's answer is late, in the secondary text color, Unknown when the check got no
+    answer, in yellow, or Unavailable in the warning color. The three take the same line, so going from one to another
+    never changes the row's height.
+
+    The measured height is exactly the painted height: one function lays the lines out for both, so the list asks for
+    the room its rows really take and the window grows with them. The text is laid out as plain text, never as rich
+    text, since folder names come from the disk.
+    """
+
+    def __init__(self, parent: QWidget | None = None) -> None:
+        """Start the arc of the "checking" rows at its first angle; the window's spinner timer turns it."""
+        super().__init__(parent)
+        self.busy_angle = 0
+
+    def row_lines(self, option: QStyleOptionViewItem, index: QModelIndex) -> list[RecentRowLine]:
+        """Return the lines of a listed row: name, path, then its mark in italics when it has one."""
+        return self.recent_row_lines(option, index.data(Qt.ItemDataRole.UserRole) or "", index_recent_mark(index))
+
+    def recent_row_lines(self, option: QStyleOptionViewItem, recent_dir: str, mark: RecentMark) -> list[RecentRowLine]:
+        """Return the lines of a recent's row, whether or not the list shows it right now.
+
+        Unavailable is written in the warning color. "checking" only says the answer is late, so it takes the path's
+        secondary color; Unknown says the check gave up, so it is yellow, to be noticed without being read as gone. A
+        selected row is written entirely in the selection's text color, of the active or inactive group as the window
+        is, so every line stays readable on the selection.
+        """
+        palette = option.palette
+        dark = is_dark_palette(palette)
+        name_color = palette.color(QPalette.ColorRole.Text)
+        path_color = secondary_text_color(palette)
+        warning_color = QColor(result_color(ResultTone.WARNING, dark))
+        unknown_color = QColor(UNKNOWN_DARK_COLOR if dark else UNKNOWN_LIGHT_COLOR)
+        if option.state & QStyle.StateFlag.State_Selected:
+            group = QPalette.ColorGroup.Active if option.state & QStyle.StateFlag.State_Active else QPalette.ColorGroup.Inactive
+            selected_color = palette.color(group, QPalette.ColorRole.HighlightedText)
+            name_color = path_color = warning_color = unknown_color = selected_color
+        font = QFont(option.font)
+        lines = [RecentRowLine(repository_display_name(recent_dir), font, name_color), RecentRowLine(recent_dir, font, path_color)]
+        if mark == RecentMark.NONE:
+            return lines
+        italic_font = QFont(font)
+        italic_font.setItalic(True)
+        if mark == RecentMark.UNAVAILABLE:
+            lines.append(RecentRowLine(mark.label, italic_font, warning_color))
+            return lines
+        if mark == RecentMark.UNKNOWN:
+            lines.append(RecentRowLine(mark.label, italic_font, unknown_color))
+            return lines
+        # The arc sits in a square as tall as the line, left of the text.
+        arc_side = QFontMetrics(italic_font).height()
+        lines.append(RecentRowLine(mark.label, italic_font, path_color, arc_side + RECENT_BUSY_ARC_GAP, shows_busy_arc=True))
+        return lines
+
+    def _lay_out_lines(self, lines: list[RecentRowLine], width: int) -> tuple[list[tuple[QTextLayout, RecentRowLine, float]], float, float]:
+        """Wrap each line at the width less its indent and stack them, returning the layouts, their total height and the widest wrapped line.
+
+        Each layout comes with its row line and the top of its first text line. A path without spaces still wraps,
+        anywhere if needed, as the other long values of the application do.
+        """
+        text_option = QTextOption()
+        text_option.setWrapMode(LONG_WORD_WRAP_MODE)
+        layouts: list[tuple[QTextLayout, RecentRowLine, float]] = []
+        top = 0.0
+        widest = 0.0
+        for row_line in lines:
+            layout = QTextLayout(row_line.text, row_line.font)
+            layout.setTextOption(text_option)
+            line_top = top
+            layout.beginLayout()
+            while True:
+                text_line = layout.createLine()
+                if not text_line.isValid():
+                    break
+                text_line.setLineWidth(max(1, width - row_line.indent))
+                text_line.setPosition(QPointF(row_line.indent, top))
+                top += text_line.height()
+                widest = max(widest, row_line.indent + text_line.naturalTextWidth())
+            layout.endLayout()
+            layouts.append((layout, row_line, line_top))
+        return layouts, top, widest
+
+    def sizeHint(self, option: QStyleOptionViewItem, index: QModelIndex) -> QSize:
+        """Measure the listed row at the width given in option.rect, which the list sets to its own width, padding included."""
+        item_option = QStyleOptionViewItem(option)
+        self.initStyleOption(item_option, index)
+        return self.measure_recent_row(item_option, index.data(Qt.ItemDataRole.UserRole) or "", index_recent_mark(index))
+
+    def measure_recent_row(self, option: QStyleOptionViewItem, recent_dir: str, mark: RecentMark) -> QSize:
+        """Measure a recent's row at the width given in option.rect, padding included, whether or not the list shows it.
+
+        Qt also asks with an invalid rectangle, during its own layout and before the list has a width; the text is then
+        measured unwrapped, as Qt's own delegate does, rather than wrapped at one pixel into one glyph per line.
+        """
+        horizontal_padding = RECENT_ROW_PADDING.left() + RECENT_ROW_PADDING.right()
+        vertical_padding = RECENT_ROW_PADDING.top() + RECENT_ROW_PADDING.bottom()
+        if option.rect.isValid():
+            text_width = max(1, option.rect.width() - horizontal_padding)
+        else:
+            text_width = UNWRAPPED_MEASURE_WIDTH
+        _layouts, height, widest = self._lay_out_lines(self.recent_row_lines(option, recent_dir, mark), text_width)
+        return QSize(ceil(widest) + horizontal_padding, ceil(height) + vertical_padding)
+
+    def paint(self, painter: QPainter, option: QStyleOptionViewItem, index: QModelIndex) -> None:
+        """Let the style draw the row's background, selection, hover and focus without text, then draw the lines over it.
+
+        A "checking" line gets the turning arc at its left, at the angle the window's spinner timer last set; painting
+        only reads that angle.
+        """
+        item_option = QStyleOptionViewItem(option)
+        self.initStyleOption(item_option, index)
+        lines = self.row_lines(item_option, index)
+        item_option.text = ""
+        widget = option.widget
+        style = widget.style() if widget is not None else QApplication.style()
+        style.drawControl(QStyle.ControlElement.CE_ItemViewItem, item_option, painter, widget)
+        text_rect = option.rect.marginsRemoved(RECENT_ROW_PADDING)
+        layouts, _height, _widest = self._lay_out_lines(lines, max(1, text_rect.width()))
+        painter.save()
+        painter.setClipRect(option.rect)
+        origin = QPointF(text_rect.topLeft())
+        for layout, row_line, line_top in layouts:
+            painter.setPen(row_line.color)
+            layout.draw(painter, origin)
+            if row_line.shows_busy_arc:
+                arc_side = row_line.indent - RECENT_BUSY_ARC_GAP
+                paint_busy_arc(painter, QRectF(origin.x(), origin.y() + line_top, arc_side, arc_side), self.busy_angle, row_line.color)
+        painter.restore()
+
+
+class RecentRepositoryList(QListWidget):
+    """Recent repositories, as tall as all their rows when the form has room, otherwise scrolling on their own.
+
+    The list asks for the height of every row, so a short list needs no scrolling at all; when the form reaches its height
+    cap the layout shrinks only the list, which then scrolls, so the path field above it stays visible; the buttons sit
+    in the band under the form and are always visible.
+    The paths wrap, so a row's height depends on the list width: the wanted height is measured again whenever that width
+    changes.
+    """
+
+    def __init__(self) -> None:
+        """Draw the rows with the recent delegate, wrap long paths instead of eliding them, and scroll by pixel since a wrapped row can be several lines tall."""
+        super().__init__()
+        self.delegate = RecentRepositoryDelegate(self)
+        self.setItemDelegate(self.delegate)
+        self.setWordWrap(True)
+        self.setTextElideMode(Qt.TextElideMode.ElideNone)
+        self.setVerticalScrollMode(QAbstractItemView.ScrollMode.ScrollPerPixel)
+
+    def measure_option(self, width: int) -> QStyleOptionViewItem:
+        """Return the list's item option with a rectangle of the given width; without any width yet, wide enough not to wrap."""
+        option = QStyleOptionViewItem()
+        self.initViewItemOption(option)
+        option.rect = QRect(0, 0, width if width > 0 else UNWRAPPED_MEASURE_WIDTH, MEASURE_RECT_MIN_HEIGHT)
+        return option
+
+    def row_height_at_width(self, row: int, width: int) -> int:
+        """Return the height the row takes once its text wraps at the given width; without any width yet, its unwrapped height."""
+        index = self.model().index(row, RECENT_COLUMN)
+        return self.itemDelegateForIndex(index).sizeHint(self.measure_option(width), index).height()
+
+    def recent_height_at_width(self, recent_dir: str, mark: RecentMark, width: int) -> int:
+        """Return the height a recent's row takes at the given width with the given mark, even while the search hides it."""
+        return self.delegate.measure_recent_row(self.measure_option(width), recent_dir, mark).height()
+
+    def sizeHintForRow(self, row: int) -> int:
+        """Return the height the row takes once its text wraps at the list's current width.
+
+        The base implementation measures the text without any width, so a wrapped path would count as a single line.
+        """
+        return self.row_height_at_width(row, self.viewport().width())
+
+    def rows_height(self) -> int:
+        """Return the height every row takes at the current width, plus the list frame."""
+        height = self.frameWidth() * 2
+        for row in range(self.count()):
+            height += self.sizeHintForRow(row)
+        return height
+
+    def sizeHint(self) -> QSize:
+        """Ask for the height of every row, so the form grows to show all the recents without scrolling when it can."""
+        return QSize(super().sizeHint().width(), self.rows_height())
+
+    def minimumSizeHint(self) -> QSize:
+        """Let the layout shrink the list down to room for its first rows; below its wanted height the list scrolls on its own.
+
+        The first rows are measured as if their text did not wrap: a long path that wraps over many lines on a narrow form
+        would otherwise raise the minimum past the room left, and the whole form would scroll instead of the list.
+        """
+        height = self.frameWidth() * 2
+        for row in range(min(RECENT_MIN_VISIBLE_ROW_COUNT, self.count())):
+            height += self.row_height_at_width(row, UNWRAPPED_MEASURE_WIDTH)
+        return QSize(super().minimumSizeHint().width(), height)
+
+    def resizeEvent(self, event: QResizeEvent) -> None:
+        """Measure the wanted height again when the width changes, since the paths then wrap differently.
+
+        Only a width change triggers it: the scroll bar appearing narrows the rows but not the list, so this cannot loop.
+        """
+        super().resizeEvent(event)
+        if event.size().width() != event.oldSize().width():
+            self.updateGeometry()
+
+
+class WelcomeFormContent(QWidget):
+    """Content of the scrolling form, which the scroll area may shrink down to its minimum height rather than its preferred one."""
+
+    def heightForWidth(self, width: int) -> int:
+        """Return the smallest height the form's layout accepts at this width, instead of the height it would like.
+
+        Workaround: a resizable QScrollArea never makes a content whose height depends on its width (the wrapped labels)
+        shorter than that content's heightForWidth, which QWidget answers with the preferred height. The form would then
+        always be as tall as every recent row and scroll as a whole. Answering with the minimum height lets the scroll
+        area fit the form to the window, so the layout shrinks the recent list, which scrolls on its own; the form only
+        scrolls once it is shorter than that minimum.
+        """
+        layout = self.layout()
+        if layout is None or not layout.hasHeightForWidth():
+            return super().heightForWidth(width)
+        return layout.totalMinimumHeightForWidth(width)
+
+
+class WelcomeWindow(QWidget):
+    """Collect a repository path and display persisted successful openings.
+
+    Drawn like the Git Extensions windows: a white body holding the path row (field, Browse… and the "or Clone" button
+    that opens the Clone window) and the recent repositories, above a grey band carrying Settings on its left and Open
+    on its right. A Search field at the top right of the recent list filters it as the user types.
+
+    Each recent's folder is checked in the background: a recent whose answer is late shows "checking" with a turning
+    arc after a short delay, then Unknown when its check fails without answer or waits too long; a missing folder or a
+    failed opening shows Unavailable. A real answer, however late, always replaces "checking" and Unknown.
+    """
+
+    open_requested = Signal(str)
+    clone_requested = Signal()
+    closed = Signal()
+    cancel_requested = Signal()
+    setting_requested = Signal()
+    availability_checked = Signal(str, bool)
+    availability_log_line = Signal(str)
+    availability_unanswered = Signal(str)
+
+    def __init__(self, recent_dirs: list[str], anchor: QWidget | None = None, is_reachable: Callable[[str], bool] = folder_is_reachable,
+                 diagnostic_log: DiagnosticLog | None = None, read_mount_table: Callable[[], list[MountEntry]] | None = PLATFORM_MOUNT_TABLE_READER,
+                 typed_path: Callable[[str], str] = session_typed_path) -> None:
+        """Build the opening form as a body above a button band, with keyboard-accessible actions.
+
+        ``anchor`` is the repository window the form was opened from; the form opens centred on it, or on the screen
+        when there is none (at startup). ``is_reachable`` answers whether a recent folder can be reached, on a
+        background thread; tests give their own answers instead of asking the disk. ``diagnostic_log`` is the --log
+        file, which learns why a folder check got no answer; without it those reasons are dropped.
+        ``read_mount_table`` reads the system's mount table to group the folder checks by disk; tests give their own table.
+        ``typed_path`` turns the text of the path field, without its blanks, into the path to open, expanding ``~`` where
+        that is the usage; tests give their own system and home folder.
+        """
+        super().__init__()
+        mark_placement_anchor(self, WELCOME_ANCHOR_RANK)
+        self.placement_anchor = anchor
+        self.typed_path = typed_path
+        self.centred = False
+        self.setWindowTitle(WelcomeText.TITLE.value)
+        # Starts at the height cap so the first layout gives the recent list its full width; the first show then fits the
+        # height to the recent repositories. Both are measured on the screen the form opens on, which may not be its own yet.
+        self.resize(min(WELCOME_WIDTH, self.placement_screen().availableGeometry().width() - SCREEN_MARGIN * 2), self.recent_height_cap())
+        # The recent list does the scrolling when the recents do not fit; this scroll area is only the last resort for a
+        # form shorter than its controls plus one recent row (very small screen, or the user shrinking the window). The
+        # buttons sit in the band under it and never scroll.
+        self.scroll_area = QScrollArea()
+        self.scroll_area.setWidgetResizable(True)
+        self.scroll_area.setFrameShape(QFrame.Shape.NoFrame)
+        # Without a frame the scroll area would be an invisible Tab stop; it still scrolls to whichever child takes the focus.
+        self.scroll_area.setFocusPolicy(Qt.FocusPolicy.NoFocus)
+        content = WelcomeFormContent()
+        layout = QVBoxLayout(content)
+        self.scroll_area.setWidget(content)
+        layout.setSpacing(0)
+        layout.setContentsMargins(WELCOME_BODY_MARGINS)
+        self.path_edit = QLineEdit()
+        self.path_edit.setAccessibleName(WelcomeText.REPOSITORY_PATH.value)
+        self.path_edit.returnPressed.connect(self._request_open)
+        self.browse_button = QPushButton(BROWSE_TEXT)
+        # Enter opens the typed path; it never runs Browse….
+        self.browse_button.setAutoDefault(False)
+        self.browse_button.setIcon(action_icon("folder", self.devicePixelRatioF()))
+        self.browse_button.clicked.connect(self._browse)
+        self.clone_button = QPushButton(WelcomeText.CLONE.value)
+        # Enter opens the typed path; it never starts a clone.
+        self.clone_button.setAutoDefault(False)
+        self.clone_button.setAccessibleName(CLONE_BUTTON_ACCESSIBLE_NAME)
+        self.clone_button.clicked.connect(self.clone_requested)
+        path_grid = QGridLayout()
+        path_grid.setContentsMargins(0, 0, 0, 0)
+        path_grid.setHorizontalSpacing(FORM_GRID_COLUMN_SPACING)
+        path_grid.setVerticalSpacing(FORM_GRID_ROW_SPACING)
+        path_grid.setColumnStretch(FIELD_COLUMN, 1)
+        self.path_caption_label = add_form_caption(path_grid, PATH_ROW, WelcomeText.REPOSITORY_PATH.value + ":", self.path_edit)
+        path_grid.addWidget(self.path_edit, PATH_ROW, FIELD_COLUMN)
+        path_grid.addWidget(self.browse_button, PATH_ROW, BUTTON_COLUMN)
+        path_grid.addWidget(self.clone_button, PATH_ROW, CLONE_BUTTON_COLUMN)
+        layout.addLayout(path_grid)
+        # Plain text: the line shows paths and Git causes. A long path wraps instead of widening the window, and the
+        # line stays hidden while it has nothing to say.
+        self.status_label = WrappingLabel()
+        self.status_label.setWordWrap(True)
+        status_policy = self.status_label.sizePolicy()
+        status_policy.setHorizontalPolicy(QSizePolicy.Policy.Ignored)
+        self.status_label.setSizePolicy(status_policy)
+        # One row space under the path, its text in line with the captions.
+        self.status_label.setContentsMargins(FORM_GRID_CAPTION_INDENT, FORM_GRID_ROW_SPACING, 0, 0)
+        self.status_label.hide()
+        layout.addWidget(self.status_label)
+        # The Clone window leaves this space between its rows and the block under them.
+        layout.addSpacing(FORM_GRID_ROWS_TO_BLOCK_SPACE)
+        self.recent_list = RecentRepositoryList()
+        self.recent_list.setAccessibleName(SharedText.RECENT_REPOSITORY.value)
+        self.unavailable_dir_set: set[str] = set()
+        self.recent_list.itemClicked.connect(self._select_recent)
+        self.recent_list.itemActivated.connect(self._open_recent)
+        self.recent_list.installEventFilter(self)
+        self.recent_dirs: list[str] = []
+        # Answers of the background folder checks, kept for the window's life: a new history only asks about new folders.
+        self.reachable_by_dir: dict[str, bool] = {}
+        # Folders asked about by this window that have no real answer yet and are not shown as Unknown.
+        self.pending_dir_set: set[str] = set()
+        # Pending folders that have waited longer than the display delay: their rows show "checking".
+        self.checking_dir_set: set[str] = set()
+        # Folders whose question failed without an answer, or waited too long: their rows show Unknown until an answer comes.
+        self.unknown_dir_set: set[str] = set()
+        # Row of each recent the list shows right now, rebuilt with the rows, so a mark change finds its row without a walk.
+        self.row_by_recent_dir: dict[str, int] = {}
+        # One timer turns the arcs of every "checking" row, and only runs while one is shown.
+        self.checking_spinner_timer = QTimer(self)
+        self.checking_spinner_timer.setInterval(FRAME_INTERVAL_MS)
+        self.checking_spinner_timer.timeout.connect(self._advance_checking_spinner)
+        # The answers arrive on worker threads; the queued connections run the row update and the log write on the
+        # window's own thread, the only one that writes the log file.
+        self.availability_checked.connect(self._show_availability, Qt.ConnectionType.QueuedConnection)
+        self.availability_unanswered.connect(self._show_unanswered, Qt.ConnectionType.QueuedConnection)
+        self.diagnostic_log = diagnostic_log
+        log_line = ignore_log_line
+        if diagnostic_log is not None:
+            self.availability_log_line.connect(self._write_availability_log_line, Qt.ConnectionType.QueuedConnection)
+            log_line = weak_signal_emitter(self, lambda form: form.availability_log_line)
+        self.availability_check = RecentAvailabilityCheck(weak_signal_emitter(self, lambda form: form.availability_checked), is_reachable, log_line=log_line,
+                                                          read_mount_table=read_mount_table,
+                                                          report_unanswered=weak_signal_emitter(self, lambda form: form.availability_unanswered))
+        self.search_edit = QLineEdit()
+        self.search_edit.setAccessibleName(RECENT_SEARCH_ACCESSIBLE_NAME)
+        self.search_edit.setClearButtonEnabled(True)
+        self.search_edit.setFixedWidth(RECENT_SEARCH_FIELD_WIDTH)
+        self.search_edit.textChanged.connect(self._search_changed)
+        self.search_edit.returnPressed.connect(self._open_search_result)
+        self.search_edit.installEventFilter(self)
+        self.search_label = QLabel(WelcomeText.RECENT_SEARCH.value + ":")
+        self.search_label.setBuddy(self.search_edit)
+        self.recent_caption_label = QLabel(SharedText.RECENT_REPOSITORY.value + ":")
+        self.recent_caption_label.setContentsMargins(FORM_GRID_CAPTION_INDENT, 0, 0, 0)
+        self.recent_caption_label.setBuddy(self.recent_list)
+        # The caption of the list on the left, the search on the right: the field's right edge falls on the list's.
+        recent_caption_row = QHBoxLayout()
+        recent_caption_row.setContentsMargins(0, 0, 0, 0)
+        recent_caption_row.setSpacing(FORM_GRID_COLUMN_SPACING)
+        recent_caption_row.addWidget(self.recent_caption_label, 0, Qt.AlignmentFlag.AlignVCenter)
+        recent_caption_row.addStretch(1)
+        recent_caption_row.addWidget(self.search_label, 0, Qt.AlignmentFlag.AlignVCenter)
+        recent_caption_row.addWidget(self.search_edit, 0, Qt.AlignmentFlag.AlignVCenter)
+        layout.addLayout(recent_caption_row)
+        layout.addSpacing(SPACING_XS)
+        layout.addWidget(self.recent_list, 1)
+        # Without recents, this text takes the list's place inside the same border, so the window keeps its layout.
+        self.empty_label = QLabel(WelcomeText.RECENT_EMPTY.value + "\n" + WelcomeText.RECENT_HELP.value)
+        self.empty_label.setTextFormat(Qt.TextFormat.PlainText)
+        self.empty_label.setWordWrap(True)
+        self.empty_label.setAlignment(Qt.AlignmentFlag.AlignLeft | Qt.AlignmentFlag.AlignTop)
+        # A framed QLabel indents its text by half an "x" on its own; the padding alone places the text.
+        self.empty_label.setIndent(0)
+        layout.addWidget(self.empty_label, 1)
+        body = QVBoxLayout()
+        body.addWidget(self.scroll_area)
+        self.setting_button = QPushButton(SharedText.SETTING_BUTTON.value)
+        self.setting_button.clicked.connect(self.setting_requested)
+        self.open_button = QPushButton(WelcomeText.OPEN.value)
+        self.open_button.clicked.connect(self._request_open)
+        # Outside a dialog the default role only draws the default outline; Enter opens through the path field and the
+        # recent list, connected above. It is given before the band is built and measured: the default outline makes
+        # Open taller, and Qt does not measure a band again when one of its buttons becomes the default, so a band
+        # measured earlier would keep the shorter height and be laid out too short.
+        self.open_button.setDefault(True)
+        # Shown in Open's place while a repository is read: the band skips the hidden Open button.
+        self.cancel_button = QPushButton(WelcomeText.CANCEL_READING.value)
+        self.cancel_button.clicked.connect(self.cancel_requested)
+        self.cancel_button.hide()
+        for button in (self.setting_button, self.open_button, self.cancel_button):
+            button.setMinimumSize(FORM_BAND_BUTTON_MIN_SIZE)
+        self.button_band = install_banded_layout(self, body, [self.open_button, self.cancel_button], body_margins=QMargins(), leading_buttons=[self.setting_button], button_sizing=BandButtonSizing.WINDOW)
+        # Height of the button band when the form last laid its theme look or fitted its metrics: a theme switch changes
+        # it, and a shown form follows by the difference only.
+        self.band_height = self.button_band.sizeHint().height()
+        self._apply_theme_look()
+        # Tab follows the reading order: the form from top to bottom, then the band from left to right.
+        tab_order = [self.path_edit, self.browse_button, self.clone_button, self.search_edit, self.recent_list, self.setting_button, self.open_button,
+                     self.cancel_button]
+        for previous_control, next_control in pairwise(tab_order):
+            QWidget.setTabOrder(previous_control, next_control)
+        self.show_recent(recent_dirs)
+        close_action = QAction("Close", self)
+        close_action.setShortcut("Ctrl+W")
+        close_action.triggered.connect(self.close)
+        self.addAction(close_action)
+        # Set once the band helper has created the outer layout: without it, Qt makes that layout's minimum size the
+        # window's, and the form could not be shrunk below all its rows.
+        self.layout().setSizeConstraint(QLayout.SizeConstraint.SetNoConstraint)
+        self.refresh_metrics(self.placement_screen().availableGeometry())
+        self.path_edit.setFocus()
+        follow_theme(self, self._apply_theme_look)
+
+    def _apply_theme_look(self) -> None:
+        """Lay down everything of the form's own look that depends on the light or dark theme; the only place that does.
+
+        The body, the band and the band's buttons are laid by the banded layout, which follows the theme on its own.
+        This lays the rest: Browse… and the clone button, the two text fields, the recent list and its empty text. It
+        runs once at construction and again at each theme switch, after the band. The colors come from the application
+        palette, never from a widget's: a style sheet changes its widget's palette. The recent list keeps its focus
+        rectangle for keyboard navigation.
+
+        The band's buttons are not as tall in both themes, so a shown form changes its height by as much as the band
+        did since the last look: the recent list keeps its height and does not start scrolling, exactly as in a form
+        opened in the new theme.
+        """
+        source = QApplication.palette()
+        # Browse… and the clone button beside it share the Windows look, the field height and one common width.
+        apply_side_button_look([self.browse_button, self.clone_button], CLONE_PLAIN_SIDE_BUTTON_TEXTS)
+        apply_windows_line_edit_look(self.path_edit)
+        apply_windows_line_edit_look(self.search_edit)
+        self.recent_list.setStyleSheet(windows_list_style_sheet(source, "QListWidget", hide_focus_outline=False))
+        self.empty_label.setStyleSheet(empty_recent_style_sheet(source))
+        band_height = self.button_band.sizeHint().height()
+        if self.centred:
+            self.resize(self.width(), self.height() + band_height - self.band_height)
+        self.band_height = band_height
+
+    def refresh_metrics(self, available: QRect | None = None) -> None:
+        """Follow the screen density and the system text size, and keep the opening form within the current screen.
+
+        Runs again after every font change: the path field, Browse… and the clone button keep the captures' size at the
+        default text size and grow with a larger one, so their text is never cut; the caption follows the font on its own,
+        and takes the Clone window's caption column width so the path field stays in line with the Clone window's fields.
+        """
+        refresh_style_sheet_fonts(self)
+        fit_caption_to_other_form(self.path_caption_label, CLONE_FORM_CAPTIONS)
+        self.browse_button.setIcon(action_icon("folder", self.devicePixelRatioF()))
+        fit_side_buttons([self.browse_button, self.clone_button], CLONE_PLAIN_SIDE_BUTTON_TEXTS)
+        fit_windows_field_height(self.path_edit)
+        fit_windows_field_height(self.search_edit)
+        fit_window(self, WELCOME_MIN_WIDTH, WELCOME_MIN_HEIGHT, available)
+        self.band_height = self.button_band.sizeHint().height()
+
+    def show_recent(self, recent_dirs: list[str]) -> None:
+        """Keep the full recent history and show it through the current search at once, then learn in the background which folders are gone.
+
+        Only the folders this window never asked about are checked, on background threads: a disk spinning up from
+        sleep or a disconnected network drive never freezes the window, and a new history does not ask again about
+        the folders already answered. A folder already known unavailable is not asked about. Rows are shown without
+        a mark until their answer comes back; a folder still without an answer after a short delay shows "checking",
+        so a local folder answering at once never makes the list jump, and Unknown after the long wait. Its answer
+        still replaces either mark whenever it comes. The editable path text is left alone.
+        """
+        self.recent_dirs = list(recent_dirs)
+        checked_recent_dirs: list[str] = []
+        new_pending_dir_set: set[str] = set()
+        for recent_dir in recent_dirs:
+            if recent_dir in self.unavailable_dir_set:
+                continue
+            checked_recent_dirs.append(recent_dir)
+            if recent_dir not in self.reachable_by_dir and recent_dir not in self.pending_dir_set and recent_dir not in self.unknown_dir_set:
+                new_pending_dir_set.add(recent_dir)
+        self.pending_dir_set.update(new_pending_dir_set)
+        self.availability_check.request(checked_recent_dirs)
+        if new_pending_dir_set:
+            # The folders asked about together wait from the same instant: one single-shot timer per batch, with the
+            # window as its context so it is dropped along with a deleted window.
+            batch = frozenset(new_pending_dir_set)
+            QTimer.singleShot(RECENT_CHECKING_DISPLAY_DELAY_MS, self, partial(self._show_checking, batch))
+            QTimer.singleShot(RECENT_CHECK_UNKNOWN_DELAY_MS, self, partial(self._show_unknown_after_wait, batch))
+        self._apply_recent_filter(keep_current=True)
+
+    def recent_mark(self, recent_dir: str) -> RecentMark:
+        """Return the mark the row of a recent carries now, by the one rule the window follows."""
+        return self._mark_with_answer(recent_dir, self.reachable_by_dir.get(recent_dir))
+
+    def _mark_with_answer(self, recent_dir: str, reachable: bool | None) -> RecentMark:
+        """Return the mark of a recent whose folder check answered ``reachable``, None for no answer yet.
+
+        In this order: a failed opening or a folder found missing is Unavailable; a folder found present has no mark;
+        then a folder without answer is Unknown once the check gave up, "checking" once it waited past the display
+        delay, and unmarked before that. A real answer therefore always wins over Unknown, and only a real "absent" or
+        a failed opening ever gives Unavailable.
+        """
+        if recent_dir in self.unavailable_dir_set or reachable is False:
+            return RecentMark.UNAVAILABLE
+        if reachable:
+            return RecentMark.NONE
+        if recent_dir in self.unknown_dir_set:
+            return RecentMark.UNKNOWN
+        if recent_dir in self.checking_dir_set:
+            return RecentMark.CHECKING
+        return RecentMark.NONE
+
+    def is_marked_unavailable(self, recent_dir: str) -> bool:
+        """Tell whether the row of a recent carries the Unavailable mark: it failed to open, or its folder was found missing.
+
+        A folder whose answer has not come back yet is never marked Unavailable: a slow answer is never taken for a missing folder.
+        """
+        return self.recent_mark(recent_dir) is RecentMark.UNAVAILABLE
+
+    def _show_checking(self, batch: frozenset[str]) -> None:
+        """Show "checking" on the folders of a batch that still have no answer once the display delay has passed.
+
+        Nothing changes once the check is closed: its folders will never answer this window.
+        """
+        if self.availability_check.closed:
+            return
+        late_dir_set: set[str] = set()
+        for recent_dir in batch:
+            if recent_dir in self.pending_dir_set and recent_dir not in self.checking_dir_set:
+                late_dir_set.add(recent_dir)
+        if not late_dir_set:
+            return
+        fitted_before = self.fitted_height() if self.centred else 0
+        self.checking_dir_set.update(late_dir_set)
+        self._refresh_recent_rows(late_dir_set)
+        self._follow_fitted_height(fitted_before)
+
+    def _show_unknown_after_wait(self, batch: frozenset[str]) -> None:
+        """Stop waiting for the folders of a batch still without answer after the long wait: show them as Unknown and say so in --log.
+
+        A question blocked on a dead network mount cannot be cancelled, so it goes on: its real answer, present or
+        absent, still replaces Unknown whenever it comes. Nothing changes once the check is closed.
+        """
+        if self.availability_check.closed:
+            return
+        waited_dir_set: set[str] = set()
+        for recent_dir in batch:
+            if recent_dir in self.pending_dir_set:
+                waited_dir_set.add(recent_dir)
+        if not waited_dir_set:
+            return
+        fitted_before = self.fitted_height() if self.centred else 0
+        self.pending_dir_set.difference_update(waited_dir_set)
+        self.checking_dir_set.difference_update(waited_dir_set)
+        self.unknown_dir_set.update(waited_dir_set)
+        self._refresh_recent_rows(waited_dir_set)
+        self._follow_fitted_height(fitted_before)
+        waited_seconds = RECENT_CHECK_UNKNOWN_DELAY_MS / MILLISECONDS_PER_SECOND
+        for recent_dir in sorted(waited_dir_set):
+            self._write_availability_log_line(unanswered_after_wait_log_line(recent_dir, waited_seconds))
+
+    def _show_unanswered(self, recent_dir: str) -> None:
+        """Show a recent as Unknown when its folder question failed without saying whether the folder exists.
+
+        Access refused, a network timeout or a drive that is not ready say nothing about the folder: it is not marked
+        Unavailable and stays openable. A real answer already known, or a failed opening, keeps its mark.
+        """
+        if recent_dir in self.reachable_by_dir or recent_dir in self.unavailable_dir_set or recent_dir in self.unknown_dir_set:
+            return
+        fitted_before = self.fitted_height() if self.centred else 0
+        self.pending_dir_set.discard(recent_dir)
+        self.checking_dir_set.discard(recent_dir)
+        self.unknown_dir_set.add(recent_dir)
+        self._refresh_recent_rows({recent_dir})
+        self._follow_fitted_height(fitted_before)
+
+    def _advance_checking_spinner(self) -> None:
+        """Turn the arcs one step and repaint the listed "checking" rows alone, not the whole list."""
+        delegate = self.recent_list.delegate
+        delegate.busy_angle = next_busy_angle(delegate.busy_angle)
+        model = self.recent_list.model()
+        for recent_dir in self.checking_dir_set:
+            row = self.row_by_recent_dir.get(recent_dir)
+            if row is not None:
+                self.recent_list.update(model.index(row, RECENT_COLUMN))
+
+    def _follow_checking_spinner(self) -> None:
+        """Run the spinner timer only while a row shows "checking" and the form is visible, so it costs nothing otherwise."""
+        if self.checking_dir_set and self.isVisible():
+            if not self.checking_spinner_timer.isActive():
+                self.checking_spinner_timer.start()
+            return
+        self.checking_spinner_timer.stop()
+
+    def _show_availability(self, recent_dir: str, reachable: bool) -> None:
+        """Remember whether a recent folder can be reached and update its row in place, only when its mark changes.
+
+        A real answer ends the wait, even one that comes after the folder was shown as Unknown: a late answer always
+        wins. The row is changed where it stands, so the search, the chosen row and the scroll position stay as the
+        user left them; a recent the search hides right now gets its mark from the remembered answer once it is listed
+        again. The answers always come back after the first fit of the form's height, even for a local folder answered
+        at once, since they cross threads through the event loop: a shown form changes its height by as much as the row
+        did, so the list does not start scrolling while every recent still fits. That holds for a row the search hides
+        too: the fitted height counts every recent of the history, so the room is there once the search is emptied.
+        """
+        mark_changes = self._mark_with_answer(recent_dir, reachable) is not self.recent_mark(recent_dir)
+        fitted_before = self.fitted_height() if mark_changes and self.centred else 0
+        self.pending_dir_set.discard(recent_dir)
+        self.checking_dir_set.discard(recent_dir)
+        self.unknown_dir_set.discard(recent_dir)
+        self.reachable_by_dir[recent_dir] = reachable
+        if mark_changes:
+            self._refresh_recent_rows({recent_dir})
+            self._follow_fitted_height(fitted_before)
+
+    def _write_availability_log_line(self, line: str) -> None:
+        """Write why a folder check got no answer into the --log file, filtered like every other record of that file."""
+        if self.diagnostic_log is None:
+            return
+        self.diagnostic_log.write_line(SensitiveTextFilter().redact(line))
+
+    def _refresh_recent_rows(self, changed_dir_set: set[str] | frozenset[str]) -> None:
+        """Rewrite the listed rows of recents whose mark changed, in one pass, and let the list measure its rows again.
+
+        A whole batch goes through one pass, and its caller through one height measure: a hundred recents of a dead
+        mount changing their mark at once must not walk the list and measure the form a hundred times. A recent the
+        search hides has no row to rewrite; the fitted height counts it with its new mark all the same. Every change of
+        the waiting folders comes through here, so the spinner timer follows them here too.
+        """
+        for recent_dir in changed_dir_set:
+            row = self.row_by_recent_dir.get(recent_dir)
+            if row is None:
+                continue
+            mark = self.recent_mark(recent_dir)
+            item = self.recent_list.item(row)
+            item.setText(recent_item_text(recent_dir, mark))
+            item.setData(RECENT_MARK_ROLE, mark.value)
+        # A mark line makes a row taller: the list lays its rows out again by itself after the data change, and the form
+        # learns the list's new height.
+        self.recent_list.updateGeometry()
+        self._follow_checking_spinner()
+
+    def _search_changed(self, _text: str) -> None:
+        """List what the new search keeps and let go of the row chosen before it, so Enter in Search opens the best match.
+
+        A row chosen before the search changed, by a click or by Qt picking the first row when the list took the focus,
+        must not win over the match the user now sees at the top; a row is chosen again only in the list itself.
+        """
+        self._apply_recent_filter(keep_current=False)
+
+    def _apply_recent_filter(self, *, keep_current: bool) -> None:
+        """Show the recents the search keeps, best first, from what show_recent remembered, without looking at the disk.
+
+        With ``keep_current``, the row chosen in the list stays chosen while it is still listed: a new history or an
+        Unavailable mark does not undo the user's choice. When no row is left, a grey text takes the list's place in the
+        same border: the usual help without any recent, or a no-match line when the search hides them all. The window is
+        never resized here: the list scrolls or leaves room, as for any other number of recents.
+        """
+        listed_dirs = ranked_recent_dirs(self.search_edit.text(), self.recent_dirs)
+        current_item = self.recent_list.currentItem() if keep_current else None
+        current_dir = None if current_item is None else current_item.data(Qt.ItemDataRole.UserRole)
+        self.recent_list.clear()
+        self.row_by_recent_dir = {}
+        for recent_dir in listed_dirs:
+            mark = self.recent_mark(recent_dir)
+            item = QListWidgetItem(recent_item_text(recent_dir, mark))
+            item.setData(Qt.ItemDataRole.UserRole, recent_dir)
+            item.setData(RECENT_MARK_ROLE, mark.value)
+            self.row_by_recent_dir[recent_dir] = self.recent_list.count()
+            self.recent_list.addItem(item)
+            if recent_dir == current_dir:
+                # Only the current row moves: itemClicked and itemActivated come from the user alone, so nothing opens.
+                self.recent_list.setCurrentItem(item)
+        if self.recent_dirs:
+            self.empty_label.setText(WelcomeText.RECENT_NO_MATCH.value)
+        else:
+            self.empty_label.setText(WelcomeText.RECENT_EMPTY.value + "\n" + WelcomeText.RECENT_HELP.value)
+        self.empty_label.setVisible(not listed_dirs)
+        self.recent_list.setVisible(bool(listed_dirs))
+        self.recent_list.updateGeometry()
+
+    def placement_screen(self) -> QScreen:
+        """Return the screen the form opens on: the one of the repository window it was opened from, else its own.
+
+        Before its first show the form's own screen is the primary one, which may be taller than the screen it is centred on.
+        """
+        if is_visible_window(self.placement_anchor):
+            return self.placement_anchor.screen()
+        return self.screen()
+
+    def recent_height_cap(self) -> int:
+        """Return the tallest the form grows to show its recent repositories: a share of the usable height of the screen it opens on."""
+        return round(WELCOME_MAX_SCREEN_RATIO * self.placement_screen().availableGeometry().height())
+
+    def fitted_height(self) -> int:
+        """Return the height that shows every recent repository without scrolling, within the minimum height and the height cap.
+
+        Measured at the current width, since the recent paths and the status line wrap. The button band sits outside the
+        scrolling form, so its height is added to the form's. Every recent of the history counts, with its known mark,
+        including those the search hides right now.
+        """
+        content_layout = self.scroll_area.widget().layout()
+        scroll_frame_height = self.scroll_area.frameWidth() * 2
+        content_width = self.scroll_area.width() - scroll_frame_height
+        if content_layout.hasHeightForWidth():
+            content_height = content_layout.totalHeightForWidth(content_width)
+        else:
+            content_height = content_layout.totalSizeHint().height()
+        content_height += self._unlisted_recent_height(content_layout, content_width)
+        outer_margins = self.layout().contentsMargins()
+        wanted_height = content_height + scroll_frame_height + outer_margins.top() + outer_margins.bottom() + self.button_band.sizeHint().height()
+        return min(max(wanted_height, WELCOME_MIN_HEIGHT), self.recent_height_cap())
+
+    def _unlisted_recent_height(self, content_layout: QLayout, content_width: int) -> int:
+        """Return the height the form's laid-out content lacks to hold every recent of the history, the ones the search hides included.
+
+        The window keeps its height while the user types in Search, so the room for the whole history has to be known
+        all along: a mark that arrives on a hidden row then grows the window at once, and every row fits without
+        scrolling once the search is emptied. Without a search every recent is listed and nothing is missing.
+        """
+        if self.recent_list.count() == len(self.recent_dirs):
+            return 0
+        history_height = self.recent_list.frameWidth() * 2
+        row_width = self.recent_list.viewport().width()
+        for recent_dir in self.recent_dirs:
+            history_height += self.recent_list.recent_height_at_width(recent_dir, self.recent_mark(recent_dir), row_width)
+        if not self.recent_list.isHidden():
+            return history_height - self.recent_list.sizeHint().height()
+        # The search hides every recent: the no-match text holds the list's place in the layout, at the layout's inner width.
+        label_item = content_layout.itemAt(content_layout.indexOf(self.empty_label))
+        layout_margins = content_layout.contentsMargins()
+        label_width = content_width - layout_margins.left() - layout_margins.right()
+        if label_item.hasHeightForWidth():
+            return history_height - label_item.heightForWidth(label_width)
+        return history_height - label_item.sizeHint().height()
+
+    def fit_recent_height(self) -> None:
+        """Make the form tall enough to show every recent repository without scrolling, up to the height cap.
+
+        Runs at the first show, once the children have their real widths: the recent paths wrap, so their height depends
+        on the width. The window never goes below its minimum height; past the cap, the layout shrinks only the recent
+        list, which then scrolls while every other control stays visible.
+        """
+        self.resize(self.width(), self.fitted_height())
+
+    def mark_unavailable(self, repository_dir: str) -> None:
+        """Keep a recent that failed to open visible with its Unavailable marker, without reading the disk again for the others.
+
+        The mark goes into the remembered history, not into the shown rows, so a recent the search hides right now is
+        still marked once the search is emptied; a history received later keeps it marked too, whatever the background
+        check of its folder answers, so the folder stops waiting for one. The form keeps its height: the list shows the
+        taller row or scrolls.
+        """
+        self.unavailable_dir_set.add(repository_dir)
+        self.pending_dir_set.discard(repository_dir)
+        self.checking_dir_set.discard(repository_dir)
+        self.unknown_dir_set.discard(repository_dir)
+        self._refresh_recent_rows({repository_dir})
+
+    def set_loading(self, loading: bool) -> None:
+        """Keep the window responsive while preventing a duplicate opening request.
+
+        While a repository is read, Cancel reading takes Open's place in the band and the status line says so. Open is
+        hidden and disabled: the path field and the recent list refuse to open while it is disabled. The clone button of
+        the path row is disabled too, since a clone cannot start while a repository is read. The keyboard focus follows
+        the swap, so a user who pressed Open lands on Cancel reading, and back on Open once the reading ends.
+        """
+        focus_widget = self.focusWidget()
+        self.cancel_button.setVisible(loading)
+        self.open_button.setVisible(not loading)
+        self.open_button.setEnabled(not loading)
+        self.clone_button.setEnabled(not loading)
+        self.show_status(WelcomeText.OPENING.value if loading else "")
+        if loading and focus_widget is self.open_button:
+            self.cancel_button.setFocus()
+            return
+        if not loading and focus_widget is self.cancel_button:
+            self.open_button.setFocus()
+
+    def show_status(self, text: str) -> None:
+        """Write the line under the repository path, and show it only while it has something to say.
+
+        An empty text hides the line, so no blank space sits between the path and the recent repositories. A shown form
+        changes its height by as much as the line changes its fitted height, so the recent list keeps its room and does
+        not start scrolling while every recent still fits; a height the user set by hand keeps its difference.
+        """
+        fitted_before = self.fitted_height() if self.centred else 0
+        self.status_label.setText(text)
+        self.status_label.setVisible(bool(text))
+        self._follow_fitted_height(fitted_before)
+
+    def _follow_fitted_height(self, fitted_before: int) -> None:
+        """Change a shown form's height by as much as its fitted height changed since ``fitted_before``.
+
+        The one rule for content that grows or shrinks after the first fit (the status line, the mark of a folder check):
+        the recent list keeps its room, a height the user set by hand keeps its difference, and a form at its height cap
+        does not move, its list scrolling instead. Before the first show there is nothing to follow: the first fit
+        measures everything.
+        """
+        if not self.centred:
+            return
+        self.scroll_area.widget().layout().invalidate()
+        difference = self.fitted_height() - fitted_before
+        if difference:
+            self.resize(self.width(), self.height() + difference)
+
+    def showEvent(self, event: QShowEvent) -> None:
+        """Size and centre the form on its first show: on the repository window it was opened from, else on the usable screen.
+
+        The form is itself a placement anchor, so the application-wide placement of new windows skips it and it has to
+        place itself. Later shows keep the form's size and place, including a place the user dragged it to. The arcs of
+        the rows still "checking" turn again.
+        """
+        super().showEvent(event)
+        self._follow_checking_spinner()
+        if self.centred:
+            return
+        self.centred = True
+        self.fit_recent_height()
+        if centre_on_placement_anchor(self, self.placement_anchor):
+            return
+        screen = self.placement_screen()
+        center_window_at(self, screen.availableGeometry().center(), screen)
+
+    def closeEvent(self, event: QCloseEvent) -> None:
+        """Stop listening to the folder checks still running, then notify the owner before discarding a pending opening.
+
+        A question to a sleeping disk cannot be cancelled; closing the check makes sure its late answer is dropped
+        instead of reaching a window Qt may already have deleted; the pending "checking" and Unknown timers then change
+        nothing. The arcs of the "checking" rows stop turning.
+        """
+        self.availability_check.close()
+        self.checking_spinner_timer.stop()
+        self.closed.emit()
+        super().closeEvent(event)
+
+    def hideEvent(self, event: QHideEvent) -> None:
+        """Stop turning the arcs of the "checking" rows while the form is hidden: nobody sees them."""
+        super().hideEvent(event)
+        self._follow_checking_spinner()
+
+    def _browse(self) -> None:
+        """Start the native chooser at the typed path, read as Open reads it, and keep the current text when the chooser is cancelled.
+
+        GitPane does not look at that folder itself: the chooser starts there, or where it can when the folder is missing.
+        """
+        repository_dir = QFileDialog.getExistingDirectory(self, WelcomeText.OPEN_REPOSITORY.value, typed_path_value(self.path_edit.text(), self.typed_path))
+        if repository_dir:
+            self.path_edit.setText(repository_dir)
+        self.path_edit.setFocus()
+
+    def _request_open(self) -> None:
+        """Validate the empty form locally before requesting asynchronous opening.
+
+        The path is used without the blanks around it, so a path pasted with a space opens its repository, and with
+        ``~`` expanded to the home folder where that is the usage; the field keeps the text as typed.
+        """
+        if not self.open_button.isEnabled():
+            return
+        if not typed_value(self.path_edit.text()):
+            self.show_status(WelcomeText.EMPTY_PATH.value)
+            self.path_edit.setFocus()
+            return
+        self.open_requested.emit(typed_path_value(self.path_edit.text(), self.typed_path))
+
+    def invalid_path_message(self, repository_dir: str) -> QMessageBox:
+        """Build, without opening it, the message saying that no folder exists at ``repository_dir``.
+
+        The path is plain text, since a path may hold a ``<`` or a ``&`` that rich text would read as markup, and it can
+        be selected, so the user can copy it. The caller keeps and opens the message.
+        """
+        box = QMessageBox(QMessageBox.Icon.Warning, WelcomeText.INVALID_PATH_TITLE.value, WelcomeText.INVALID_PATH.value.format(path=repository_dir), QMessageBox.StandardButton.Ok, self)
+        box.setTextFormat(Qt.TextFormat.PlainText)
+        box.setTextInteractionFlags(Qt.TextInteractionFlag.TextSelectableByMouse | Qt.TextInteractionFlag.TextSelectableByKeyboard)
+        prepare_message_box(box, WelcomeText.INVALID_PATH_TITLE.value)
+        return box
+
+    def eventFilter(self, watched: QWidget, event: QEvent) -> bool:
+        """Open the current recent on Enter in the recent list, and give the Search field the two keys it leaves unused.
+
+        Qt for macOS does not activate a list row on Enter, so the list's Enter goes through the shared helper that does
+        it on every system. In Search, Down moves to the recent list and Escape empties the search.
+        """
+        if watched is self.recent_list and activate_current_row(self.recent_list, event):
+            return True
+        if watched is not self.search_edit or event.type() != QEvent.Type.KeyPress:
+            return super().eventFilter(watched, event)
+        if event.key() == Qt.Key.Key_Down and self.recent_list.count():
+            self.recent_list.setFocus()
+            if self.recent_list.currentRow() < 0:
+                self.recent_list.setCurrentRow(FIRST_ROW)
+            return True
+        if event.key() == Qt.Key.Key_Escape and self.search_edit.text():
+            self.search_edit.clear()
+            return True
+        return super().eventFilter(watched, event)
+
+    def _open_search_result(self) -> None:
+        """Open the recent chosen in the list since the search last changed on Enter in Search, else the best match, as a launcher does.
+
+        Every change of the search lets go of the chosen row, so a current row here was picked after the last key typed.
+        """
+        item = self.recent_list.currentItem()
+        if item is None:
+            item = self.recent_list.item(FIRST_ROW)
+        if item is None:
+            return
+        self._open_recent(item)
+
+    def _open_recent(self, item: QListWidgetItem) -> None:
+        """Activate the exact saved directory without substituting another location."""
+        if not self.open_button.isEnabled():
+            return
+        self._select_recent(item)
+        self._request_open()
+
+    def _select_recent(self, item: QListWidgetItem) -> None:
+        self.path_edit.setText(item.data(Qt.ItemDataRole.UserRole))