gitpane 1.0.0__py3-none-any.whl

gitpane/ui/console/operation_output_view.py

@@ -0,0 +1,373 @@
+"""Show the filtered output of one operation, one bounded page at a time, following its end while it streams."""
+
+from __future__ import annotations
+
+import re
+from typing import TYPE_CHECKING
+
+from PySide6.QtCore import QElapsedTimer, Qt, QTimer
+from PySide6.QtGui import QFontDatabase, QTextCursor
+from PySide6.QtWidgets import QApplication, QGridLayout, QLabel, QPlainTextEdit, QPushButton, QVBoxLayout, QWidget
+
+from gitpane.config import TRACE_NAVIGATION_INTERVAL_MS, TRACE_RENDER_INTERVAL_MS, TRACE_VIEW_LIMIT_BYTES
+from gitpane.history.revision_file import utf16_length
+from gitpane.operation.console_tone import ConsoleTone
+from gitpane.ui.console.operation_output import OperationOutputHighlighter
+
+if TYPE_CHECKING:
+    from collections.abc import Iterator
+
+    from gitpane.operation.operation_trace import OperationTrace, TraceEvent
+
+# Reading this many bytes from any offset always reaches the first byte of the next UTF-8 character.
+UTF8_CHARACTER_MAX_BYTES = 4
+DOCUMENT_START_POSITION = 0
+DOCUMENT_START_BLOCK_NUMBER = 0
+# What starts a new block when Qt reads plain text: a line feed, a carriage return, both together (a single break), or
+# the Unicode paragraph separator, written here in UTF-8.
+QT_BLOCK_BREAK_PATTERN = re.compile(rb"\r\n|\r|\n|\xe2\x80\xa9")
+# Page buttons go on two columns, with the byte counter below them, when one row does not fit the available width.
+NARROW_NAVIGATION_COLUMNS = 2
+
+
+class BlockNumberWalker:
+    """Give the Qt block number of increasing byte offsets of a page, reading the page's line breaks only once."""
+
+    def __init__(self, data: bytes, first_block_number: int) -> None:
+        """Start before the first byte of the page, which lies in the given block."""
+        self.break_ends: Iterator[int] = (match.end() for match in QT_BLOCK_BREAK_PATTERN.finditer(data))
+        self.next_break_end = next(self.break_ends, None)
+        self.block_number = first_block_number
+
+    def block_number_at(self, offset: int) -> int:
+        """Return the number of the block holding the byte at an offset no smaller than the one asked before."""
+        while self.next_break_end is not None and self.next_break_end <= offset:
+            self.block_number += 1
+            self.next_break_end = next(self.break_ends, None)
+        return self.block_number
+
+
+class OperationOutputView(QWidget):
+    """Display the already filtered text of an operation trace, as the operation consoles and the clone form show it.
+
+    Only one bounded page of text lives in Qt at a time; the page buttons reach earlier and later output. While the
+    user follows the end, new output is appended in batches; a user who scrolls up, selects text or reads an older page
+    keeps an untouched view.
+    """
+
+    def __init__(self, trace: OperationTrace, parent: QWidget | None = None) -> None:
+        """Build the read-only output above its page buttons and byte counter, then show the latest page."""
+        super().__init__(parent)
+        self.trace = trace
+        self.stopped = False
+        self.page_start = 0
+        self.page_end = 0
+        self.unstable_start: int | None = None
+        self.unstable_length = 0
+        self.follow_tail = True
+        # Set only by the user's own scrolling (wheel, keys, scrollbar) and by page navigation, never read back from the
+        # scroll position: Qt moves the scrollbar by itself when it lays wrapped lines out again, for instance when the
+        # first overflowing output shows the vertical scrollbar and narrows the view.
+        self.scrolled_away = False
+        self.render_pending = False
+        self.output_missed = False
+        self.render_timer = QTimer(self)
+        self.render_timer.setSingleShot(True)
+        self.render_timer.timeout.connect(self.flush_output)
+        self.navigation_timer = QTimer(self)
+        self.navigation_timer.setSingleShot(True)
+        self.navigation_timer.timeout.connect(self._update_page_label)
+        self.navigation_clock = QElapsedTimer()
+        layout = QVBoxLayout(self)
+        layout.setContentsMargins(0, 0, 0, 0)
+        self.detail_edit = QPlainTextEdit()
+        self.detail_edit.setReadOnly(True)
+        # Output is appended to the document while it streams; an undo history would keep every appended and trimmed
+        # piece alive for the whole operation, and a read-only view never undoes anything.
+        self.detail_edit.setUndoRedoEnabled(False)
+        self.detail_edit.setAccessibleName("Operation output")
+        self.detail_edit.setPlaceholderText("Waiting for output…")
+        self.detail_edit.setFont(QFontDatabase.systemFont(QFontDatabase.SystemFont.FixedFont))
+        self.output_highlighter = OperationOutputHighlighter(self.detail_edit)
+        self.detail_edit.selectionChanged.connect(self._output_selection_changed)
+        output_scrollbar = self.detail_edit.verticalScrollBar()
+        output_scrollbar.actionTriggered.connect(self._output_scrolled_by_user)
+        output_scrollbar.rangeChanged.connect(self._output_range_changed)
+        output_scrollbar.valueChanged.connect(self._output_value_changed)
+        layout.addWidget(self.detail_edit, 1)
+        self.navigation_layout = QGridLayout()
+        self.first_button = QPushButton("First output")
+        self.first_button.clicked.connect(lambda: self.show_page(0))
+        self.previous_button = QPushButton("Previous output")
+        self.previous_button.clicked.connect(lambda: self.show_page(max(0, self.page_start - TRACE_VIEW_LIMIT_BYTES)))
+        self.next_button = QPushButton("Next output")
+        self.next_button.clicked.connect(lambda: self.show_page(self.page_end))
+        self.latest_button = QPushButton("Latest output")
+        self.latest_button.clicked.connect(self.show_latest)
+        self.navigation_buttons = (self.first_button, self.previous_button, self.next_button, self.latest_button)
+        for column, button in enumerate(self.navigation_buttons):
+            button.setAutoDefault(False)
+            button.setAccessibleName(button.text())
+            self.navigation_layout.addWidget(button, 0, column)
+        self.page_label = QLabel()
+        self.page_label.setTextFormat(Qt.TextFormat.PlainText)
+        self.page_label.setWordWrap(True)
+        self.navigation_layout.addWidget(self.page_label, 0, len(self.navigation_buttons))
+        layout.addLayout(self.navigation_layout)
+        trace.event_added.connect(self.append_event)
+        self.show_latest()
+
+    def refresh_metrics(self, available_width: int) -> None:
+        """Put the page buttons on two columns, the byte counter below them, when one row is wider than the available width."""
+        spacing = self.navigation_layout.horizontalSpacing()
+        navigation_width = self.page_label.sizeHint().width()
+        for button in self.navigation_buttons:
+            navigation_width += button.sizeHint().width() + spacing
+        columns = len(self.navigation_buttons)
+        if navigation_width > available_width:
+            columns = NARROW_NAVIGATION_COLUMNS
+        for button in self.navigation_buttons:
+            self.navigation_layout.removeWidget(button)
+        self.navigation_layout.removeWidget(self.page_label)
+        for index, button in enumerate(self.navigation_buttons):
+            row, column = divmod(index, columns)
+            self.navigation_layout.addWidget(button, row, column)
+        if columns < len(self.navigation_buttons):
+            page_row = len(self.navigation_buttons) // columns
+            self.navigation_layout.addWidget(self.page_label, page_row, 0, 1, columns)
+        else:
+            self.navigation_layout.addWidget(self.page_label, 0, columns)
+        self.layout().activate()
+
+    def stop(self) -> None:
+        """Stop the render and counter timers and ignore any later output, once nobody looks at this view anymore."""
+        self.stopped = True
+        self.render_timer.stop()
+        self.navigation_timer.stop()
+
+    def show_page(self, start: int) -> None:
+        """Load one bounded page of already filtered text on explicit navigation.
+
+        The page is read from its top: nothing follows the end while it loads, and on the latest page following resumes
+        only once the user scrolls down to its end.
+        """
+        if self.trace.closed:
+            return
+        text, self.page_start, self.page_end = self.trace.read_text_page(start)
+        self.output_missed = False
+        self.follow_tail = False
+        self.detail_edit.setPlainText(text)
+        self._apply_tones(self.page_start, text, DOCUMENT_START_BLOCK_NUMBER)
+        self._remember_unstable_tail(text, self.page_start)
+        self.follow_tail = self.page_end == self._total_size()
+        scrollbar = self.detail_edit.verticalScrollBar()
+        self.scrolled_away = scrollbar.value() < scrollbar.maximum()
+        self._update_navigation()
+
+    def show_latest(self) -> None:
+        """Resume following output from the last bounded page."""
+        self.show_page(max(0, self._total_size() - TRACE_VIEW_LIMIT_BYTES))
+        self.follow_tail = True
+        self.scrolled_away = False
+        self.detail_edit.verticalScrollBar().setValue(self.detail_edit.verticalScrollBar().maximum())
+
+    def append_event(self, event: TraceEvent) -> None:
+        """Schedule a render for records of the trace's current operation; the batch interval keeps the UI thread free."""
+        if event.operation_id != self.trace.operation_id or self.stopped:
+            return
+        self.render_pending = True
+        if not self.render_timer.isActive():
+            self.render_timer.start(TRACE_RENDER_INTERVAL_MS)
+
+    def flush_output(self, *, exact_count: bool = False) -> None:
+        """Render one batch only when doing so preserves the user's selection and scroll.
+
+        While the user follows the end of the output, only the text written since the last batch is appended; a user
+        who scrolled up, selected text or reads an older page keeps an untouched view. What they missed is appended,
+        as a terminal does, once they scroll back down to the end of the latest page or clear their selection.
+        ``exact_count`` rewrites the byte counter at once, for a finished operation whose
+        total must be shown exactly; otherwise the counter is rewritten at most once per interval.
+        """
+        self.render_timer.stop()
+        if self.stopped or self.trace.closed:
+            return
+        if self._following_output():
+            self._append_latest()
+        elif self.render_pending:
+            self.output_missed = True
+        self.render_pending = False
+        if exact_count:
+            self._update_navigation()
+            return
+        self._schedule_navigation_update()
+
+    def copy_detail(self) -> None:
+        """Copy the same filtered text exposed by the model."""
+        QApplication.clipboard().setText(self.trace.copy_text())
+
+    def _total_size(self) -> int:
+        """Return the size of the whole filtered text, including the closing record of an incomplete trace."""
+        return self.trace.text_size + len(self.trace.failure_text)
+
+    def _update_navigation(self) -> None:
+        """Keep earlier and later output accessible without loading it into Qt."""
+        self._update_navigation_buttons()
+        self._update_page_label()
+
+    def _update_navigation_buttons(self) -> None:
+        """Enable the page buttons that lead somewhere; an unchanged state costs Qt nothing, so this runs on every batch."""
+        total = self._total_size()
+        self.first_button.setEnabled(self.page_start > 0)
+        self.previous_button.setEnabled(self.page_start > 0)
+        self.next_button.setEnabled(self.page_end < total)
+        self.latest_button.setEnabled(self.page_end < total)
+
+    def _update_page_label(self) -> None:
+        """Rewrite the byte counter now, restarting the clock that spaces out its rewrites and dropping a deferred one."""
+        self.navigation_clock.start()
+        self.navigation_timer.stop()
+        total = self._total_size()
+        # The last line can shrink while the user keeps an unchanged view of older output.
+        self.page_label.setText(f"{self.page_start}–{min(self.page_end, total)} / {total} bytes")
+
+    def _following_output(self) -> bool:
+        """Tell whether the view keeps showing the newest output: latest page loaded, no user scroll away from its end, no selection."""
+        return self.follow_tail and not self.scrolled_away and not self.detail_edit.textCursor().hasSelection()
+
+    def _output_scrolled_by_user(self, _action: int) -> None:
+        """Stop following when the user scrolls above the end, and follow again once they scroll back down to it.
+
+        Qt reports the position the user's action leads to before applying it. Coming back to the end also shows the
+        output written meanwhile, which matters when the operation ended while the user was reading higher up.
+        """
+        scrollbar = self.detail_edit.verticalScrollBar()
+        self.scrolled_away = scrollbar.sliderPosition() < scrollbar.maximum()
+        missed_output = self.output_missed or self.page_end < self._total_size()
+        if self._following_output() and missed_output and not self.render_timer.isActive():
+            self.render_timer.start(TRACE_RENDER_INTERVAL_MS)
+
+    def _output_range_changed(self, _minimum: int, maximum: int) -> None:
+        """Keep the end in view when new text, wrapping or resizing changes the scroll range."""
+        if self._following_output():
+            self.detail_edit.verticalScrollBar().setValue(maximum)
+
+    def _output_selection_changed(self) -> None:
+        """Show output missed during a selection once its release resumes following the end."""
+        if self._following_output() and self.output_missed and not self.render_timer.isActive():
+            self.render_timer.start(TRACE_RENDER_INTERVAL_MS)
+
+    def _output_value_changed(self, value: int) -> None:
+        """Put the end back in view when Qt itself moves a followed view, as it does when it lays wrapped lines out again."""
+        scrollbar = self.detail_edit.verticalScrollBar()
+        if value != scrollbar.maximum() and self._following_output():
+            scrollbar.setValue(scrollbar.maximum())
+
+    def _remember_unstable_tail(self, text: str, text_start: int) -> None:
+        """Remember the shown tail the trace can still replace, measured in Qt's UTF-16 positions."""
+        stable_size = self.trace.stable_size()
+        self.unstable_start = None
+        self.unstable_length = 0
+        if stable_size >= self.page_end:
+            return
+        self.unstable_start = stable_size
+        offset = max(0, stable_size - text_start)
+        self.unstable_length = utf16_length(text.encode("utf-8")[offset:].decode("utf-8"))
+
+    def _append_latest(self) -> None:
+        """Replace the still-open tail and append new bytes, then trim the start back to one page.
+
+        More new text than one page at once is shown by reloading the last page instead, which gives the same view.
+        """
+        self.output_missed = False
+        total = self._total_size()
+        if self.unstable_start is not None and self.unstable_start < self.page_start:
+            self.show_latest()
+            return
+        document = self.detail_edit.document()
+        cursor = QTextCursor(document)
+        cursor.movePosition(QTextCursor.MoveOperation.End)
+        if self.unstable_start is not None:
+            cursor.setPosition(document.characterCount() - 1 - self.unstable_length)
+            cursor.movePosition(QTextCursor.MoveOperation.End, QTextCursor.MoveMode.KeepAnchor)
+            self.page_end = self.unstable_start
+            document.findBlock(cursor.selectionStart()).setUserState(int(ConsoleTone.NEUTRAL))
+        if total - self.page_end > TRACE_VIEW_LIMIT_BYTES:
+            self.show_latest()
+            return
+        text, text_start, end = self.trace.read_text_page(self.page_end, total - self.page_end)
+        if not text and self.unstable_start is None:
+            return
+        last_block_number = document.findBlock(cursor.selectionStart()).blockNumber()
+        cursor.insertText(text)
+        self._apply_tones(text_start, text, last_block_number)
+        self.page_end = end
+        self._remember_unstable_tail(text, text_start)
+        if not self._trim_start():
+            self.show_latest()
+            return
+        # Text inserted where the view's own cursor stands pushes that cursor along, and a reload used to put it back
+        # at the start of the page; moving it back keeps a shift-click selecting from the same place as before.
+        view_cursor = self.detail_edit.textCursor()
+        if view_cursor.position() != DOCUMENT_START_POSITION:
+            view_cursor.setPosition(DOCUMENT_START_POSITION)
+            self.detail_edit.setTextCursor(view_cursor)
+        self.follow_tail = True
+        scrollbar = self.detail_edit.verticalScrollBar()
+        scrollbar.setValue(scrollbar.maximum())
+
+    def _apply_tones(self, start: int, text: str, first_block_number: int) -> None:
+        """Set on each block of a page the tone the trace recorded for its bytes, then colour those blocks again.
+
+        ``text`` was just put in the document from byte ``start`` of the trace, its first character in block
+        ``first_block_number``. A coloured range always starts at the beginning of a line, or is cut to the start of
+        the page, so a block number is a count of line breaks; the breaks are counted once, from range to range.
+        """
+        data = text.encode("utf-8")
+        spans = self.trace.tone_spans_between(start, start + len(data))
+        if not spans:
+            return
+        document = self.detail_edit.document()
+        walker = BlockNumberWalker(data, first_block_number)
+        for span in spans:
+            first_number = walker.block_number_at(max(0, span.start - start))
+            last_number = walker.block_number_at(min(len(data), span.end - start) - 1)
+            block = document.findBlockByNumber(first_number)
+            while block.isValid() and block.blockNumber() <= last_number:
+                block.setUserState(int(span.tone))
+                self.output_highlighter.rehighlightBlock(block)
+                block = block.next()
+
+    def _trim_start(self) -> bool:
+        """Remove from the start of the view the bytes a reload of the last page would not show.
+
+        The cut is computed on the trace bytes, never on Qt blocks, so the view keeps matching exactly the byte range
+        the navigation buttons and the counter describe. Returns False when the removed text could not be read back
+        exactly; the caller then reloads the last page.
+        """
+        bound = self.page_end - TRACE_VIEW_LIMIT_BYTES
+        if bound <= self.page_start:
+            return True
+        if self.unstable_start is not None and bound > self.unstable_start:
+            return False
+        _character, bound, _character_end = self.trace.read_text_page(bound, UTF8_CHARACTER_MAX_BYTES)
+        prefix, _prefix_start, prefix_end = self.trace.read_text_page(self.page_start, bound - self.page_start)
+        # A carriage return followed by a line feed is a single position in a Qt document, so the position count would be wrong.
+        if prefix_end != bound or "\r" in prefix:
+            return False
+        cursor = QTextCursor(self.detail_edit.document())
+        cursor.setPosition(utf16_length(prefix), QTextCursor.MoveMode.KeepAnchor)
+        cursor.removeSelectedText()
+        self.page_start = bound
+        return True
+
+    def _schedule_navigation_update(self) -> None:
+        """Keep the page buttons current, and rewrite the byte counter at most once per interval while output streams.
+
+        A counter change arriving too early is written once the interval has passed, so the last value is never lost.
+        """
+        self._update_navigation_buttons()
+        if not self.navigation_clock.isValid() or self.navigation_clock.elapsed() >= TRACE_NAVIGATION_INTERVAL_MS:
+            self._update_page_label()
+            return
+        if not self.navigation_timer.isActive():
+            self.navigation_timer.start(TRACE_NAVIGATION_INTERVAL_MS - self.navigation_clock.elapsed())

gitpane/ui/emoji/emoji_font.py

@@ -0,0 +1,257 @@
+"""Give each system its colour emoji font: the Noto Color Emoji file shipped with GitPane, bundled exactly as Google publishes it, or the system's own.
+
+Windows and Linux draw emoji with the bundled Noto file; macOS draws them with its own Apple Color Emoji and never reads
+the bundled file, because CoreText does not draw that file in colour. A table keyed by the system says which font each
+one uses, and only one font file is shipped. This module holds the family names, the file names of the font and of its
+licence, and reads the font bytes from the installed package. It loads the font of the running system once per
+process, the first time a symbol area needs it, checks that it really draws in colour, and builds the font the emoji
+keyboard and the commit message use. The bundled file keeps its bytes and its family name on disk; only when a system
+font of the same family name takes that name and draws it blank does GitPane register an in-memory copy renamed
+GitPane Noto Color Emoji. The rest of the application keeps the system font.
+"""
+
+from __future__ import annotations
+
+import functools
+import sys
+from dataclasses import dataclass
+from importlib.resources import files
+
+from PySide6.QtCore import QPointF, Qt
+from PySide6.QtGui import QFont, QFontDatabase, QFontInfo, QImage, QPainter, QTextLayout
+
+from gitpane.config import LINUX_PLATFORM, MACOS_PLATFORM, UI_RESOURCE_DIR_NAME, UI_RESOURCE_PACKAGE_NAME, WINDOWS_PLATFORM
+from gitpane.ui.emoji.opentype_family_name import font_with_family_name
+
+# The upstream family name of the bundled file, which is shipped without any modification.
+EMOJI_FONT_FAMILY = "Noto Color Emoji"
+# The family name of the in-memory copy registered when a system font of the upstream name draws blank in its place. The
+# font licence reserves no font name, so the copy may carry another one; the file on disk is never changed.
+RENAMED_EMOJI_FONT_FAMILY = "GitPane Noto Color Emoji"
+# The file keeps the name Google publishes it under, so its origin can be read from the name alone.
+EMOJI_FONT_BASENAME = "NotoColorEmoji_WindowsCompatible.ttf"
+EMOJI_FONT_LICENSE_BASENAME = "NotoColorEmoji-OFL.txt"
+# A red circle, not the check mark: Noto draws the check mark in grey, which would look like a monochrome font.
+EMOJI_PROBE_TEXT = "\U0001F534"
+EMOJI_PROBE_SIDE = 64
+# The probe glyph takes half the image, so it fits whole whatever the ascent of the font.
+EMOJI_PROBE_PIXEL_SIZE = EMOJI_PROBE_SIDE // 2
+# The centre of the Noto red circle is #f44336, a red lead of 177 over green and blue; a monochrome glyph has a black
+# or white centre, a lead of 0.
+EMOJI_PROBE_RED_MARGIN = 96
+# Draws, on Windows, the keyboard symbols the bundled font lacks: the mathematical letter, the arrow and the combining
+# marks. This family ships only with Windows.
+WINDOWS_SYMBOL_FALLBACK_FAMILIES = ("Segoe UI Symbol",)
+# Draws, on Linux, the same symbols. Without a family named here, fontconfig picked one among the installed fonts, and a
+# CJK font could take a combining mark and give it the advance of a whole character, so the button elided its sample.
+# Symbola comes first: Debian's desktop task recommends it, it gives every combining mark a zero advance, and it is the
+# font the offscreen tests already get. FreeSans and DejaVu Math TeX Gyre follow because each of them also covers all
+# the combining marks, so the row is never split between two fonts. No CJK font is listed.
+LINUX_SYMBOL_FALLBACK_FAMILIES = ("Symbola", "FreeSans", "DejaVu Math TeX Gyre")
+# The colour emoji font every macOS ships with.
+APPLE_COLOR_EMOJI_FAMILY = "Apple Color Emoji"
+FAILED_FONT_ID = -1
+FIRST_FAMILY_INDEX = 0
+# A symbol drawn by one font alone gives one glyph run, the only one read.
+ONLY_GLYPH_RUN_INDEX = 0
+
+
+@dataclass(frozen=True)
+class EmojiFontStatus:
+    """Outcome of loading the colour emoji font: the colour family, or an empty family and why the system fonts are used.
+
+    The font is usable only when `family` is not empty. `font_id` is the Qt id of the registration of the bundled font,
+    kept even when the font was removed again, and -1 when Qt refused the bytes or no file was registered. `warning` is
+    meant for the --log file.
+    """
+
+    family: str
+    warning: str
+    font_id: int = FAILED_FONT_ID
+
+
+@dataclass(frozen=True)
+class EmojiFontChoice:
+    """How one system draws colour emoji: with the bundled Noto file or with a colour font of its own.
+
+    `loads_bundled_font` says whether the bundled file is read and registered; `system_color_family` names the colour
+    family the system already has, empty when the bundled font is used; `symbol_fallback_families` follow the colour
+    family for the keyboard symbols it lacks.
+    """
+
+    loads_bundled_font: bool
+    system_color_family: str
+    symbol_fallback_families: tuple[str, ...]
+
+
+# Windows and Linux both load the bundled Noto file, each with the fallback families its own fonts provide.
+# macOS differs: CoreText does not draw the bundled Noto file in colour, it hands every emoji to Apple Color Emoji
+# instead, and Apple Color Emoji is the colour font of the system. Reading the 10.7 MB file there would only end in a
+# refusal and a warning in the --log file.
+EMOJI_FONT_CHOICE_BY_PLATFORM = {
+    WINDOWS_PLATFORM: EmojiFontChoice(loads_bundled_font=True, system_color_family="", symbol_fallback_families=WINDOWS_SYMBOL_FALLBACK_FAMILIES),
+    LINUX_PLATFORM: EmojiFontChoice(loads_bundled_font=True, system_color_family="", symbol_fallback_families=LINUX_SYMBOL_FALLBACK_FAMILIES),
+    MACOS_PLATFORM: EmojiFontChoice(loads_bundled_font=False, system_color_family=APPLE_COLOR_EMOJI_FAMILY, symbol_fallback_families=()),
+}
+
+
+def emoji_font_choice(platform: str) -> EmojiFontChoice:
+    """Return how this system draws colour emoji, read from the table of the systems GitPane runs on.
+
+    The system is a parameter, so the choice of each system can be checked from any other. An unknown system raises
+    OSError rather than borrowing the choice of another one.
+    """
+    choice = EMOJI_FONT_CHOICE_BY_PLATFORM.get(platform)
+    if choice is None:
+        raise OSError("No emoji font is chosen for the system " + platform)
+    return choice
+
+
+def read_packaged_font() -> bytes:
+    """Return the bytes of the bundled emoji font, read from the installed package and never from a user supplied path.
+
+    A missing or unreadable file raises OSError; the caller that registers the font decides how to fall back.
+    """
+    return files(UI_RESOURCE_PACKAGE_NAME).joinpath(UI_RESOURCE_DIR_NAME, EMOJI_FONT_BASENAME).read_bytes()
+
+
+def register_emoji_font(content: bytes) -> EmojiFontStatus:
+    """Register the bundled font bytes with Qt and keep them only if they give a family that draws in colour here.
+
+    The upstream family name is tried first; when it does not draw in colour, a copy renamed in memory is tried in its
+    place. A font refused after registration is removed from the Qt font database again, so no half working family is
+    left for Qt to pick as a fallback. Nothing is shown on screen: the warning goes back to the caller.
+    """
+    # Qt fills its font database with the system fonts at the first family lookup. A font registered before that wins
+    # its family name over a system font of the same name, but loses it again as soon as Qt fills or refills the
+    # database, so the colour check would judge a font Qt no longer draws. Listing the families first makes the check
+    # judge the database Qt keeps; in the running application it is already filled and this costs only the list.
+    QFontDatabase.families()
+    status = register_first_family(content)
+    if not status.family or draws_in_color(status.family):
+        return status
+    QFontDatabase.removeApplicationFont(status.font_id)
+    refusal = refused_color_warning(status.family)
+    # Workaround: a system can install its own font under the same family name, one this Qt draws blank (Fedora ships a
+    # COLRv1 Noto Color Emoji that Qt 6.11 draws empty), and Qt then answers the upstream name with the system font.
+    # Qt's name with the foundry ("Noto Color Emoji [GOOG]") does reach the bundled font when asked directly, but Qt's
+    # emoji fallback, which draws an emoji the first family of a font lacks, matches the family name only and drops the
+    # foundry, so menu icons and the commit message still got the blank system font. A copy under a name of its own has
+    # no rival; it is only built here, so systems where the upstream name draws in colour keep that name.
+    try:
+        renamed_content = font_with_family_name(content, RENAMED_EMOJI_FONT_FAMILY)
+    except ValueError as error:
+        return EmojiFontStatus("", refusal + " Its renamed copy could not be built: " + str(error), status.font_id)
+    renamed = register_first_family(renamed_content)
+    if not renamed.family or draws_in_color(renamed.family):
+        return renamed
+    QFontDatabase.removeApplicationFont(renamed.font_id)
+    return EmojiFontStatus("", refusal, renamed.font_id)
+
+
+def refused_color_warning(family: str) -> str:
+    """Return the --log line of a bundled font family that does not draw in colour here."""
+    return f"The bundled emoji font {family} does not draw in color here; using system fonts."
+
+
+def register_first_family(content: bytes) -> EmojiFontStatus:
+    """Register font bytes with Qt and return their first family, without judging how it draws.
+
+    Bytes Qt refuses, or that give no family name, are not kept: the status then has an empty family and the reason.
+    """
+    font_id = QFontDatabase.addApplicationFontFromData(content)
+    if font_id == FAILED_FONT_ID:
+        return EmojiFontStatus("", "Qt refused the bundled emoji font; using system fonts.", font_id)
+    families = QFontDatabase.applicationFontFamilies(font_id)
+    if not families:
+        QFontDatabase.removeApplicationFont(font_id)
+        return EmojiFontStatus("", "The bundled emoji font has no family name; using system fonts.", font_id)
+    return EmojiFontStatus(families[FIRST_FAMILY_INDEX], "", font_id)
+
+
+def emoji_font_status(choice: EmojiFontChoice) -> EmojiFontStatus:
+    """Load the colour emoji font a system uses and check that it draws in colour, falling back to the system fonts if not.
+
+    The bundled font is read from the package and registered with Qt; a colour family of the system is only probed, no
+    file is read. The warning of a refusal is returned for the --log file, nothing is shown on screen.
+    """
+    if not choice.loads_bundled_font:
+        family = choice.system_color_family
+        if draws_in_color(family):
+            return EmojiFontStatus(family, "")
+        return EmojiFontStatus("", f"The system emoji font {family} does not draw in color here; using system fonts.")
+    try:
+        content = read_packaged_font()
+    except OSError as error:
+        return EmojiFontStatus("", f"Cannot read the bundled emoji font; using system fonts: {error}")
+    return register_emoji_font(content)
+
+
+@functools.cache
+def load_emoji_font() -> EmojiFontStatus:
+    """Load and check the colour emoji font of the running system once per process, the first time a symbol area needs it.
+
+    The bundled file weighs about 10.7 MB; reading, registering and probing it took about 30 ms on Windows 10, so it
+    is done once and never at import or application start. The emoji window controller writes the warning to the --log file.
+    """
+    return emoji_font_status(emoji_font_choice(sys.platform))
+
+
+def draws_in_color(family: str) -> bool:
+    """Tell whether this family draws the red probe emoji in colour on this system.
+
+    The probe must be laid out as one glyph run of this very family, so a fallback font cannot answer in its place; it is
+    then drawn glyph by glyph (plain text drawing would let Qt substitute another emoji font) and the pixel at the
+    centre of the glyph must be clearly red.
+    """
+    font = QFont(family)
+    font.setPixelSize(EMOJI_PROBE_PIXEL_SIZE)
+    layout = QTextLayout(EMOJI_PROBE_TEXT, font)
+    layout.beginLayout()
+    layout.createLine()
+    layout.endLayout()
+    runs = layout.glyphRuns()
+    if len(runs) != 1:
+        return False
+    run = runs[ONLY_GLYPH_RUN_INDEX]
+    if run.rawFont().familyName() != family:
+        return False
+    image = QImage(EMOJI_PROBE_SIDE, EMOJI_PROBE_SIDE, QImage.Format.Format_ARGB32)
+    image.fill(Qt.GlobalColor.white)
+    painter = QPainter(image)
+    painter.drawGlyphRun(QPointF(0, 0), run)
+    painter.end()
+    centre = run.boundingRect().center().toPoint()
+    if not image.rect().contains(centre):
+        return False
+    colour = image.pixelColor(centre)
+    return colour.red() - max(colour.green(), colour.blue()) >= EMOJI_PROBE_RED_MARGIN
+
+
+def emoji_font_families(status: EmojiFontStatus, platform: str = sys.platform) -> list[str]:
+    """Return the families of the symbol font, in the order Qt tries them.
+
+    The system family comes first, otherwise digits, spaces and '#' would be drawn by the emoji font, which has them
+    too. The colour family follows when it loaded, then the families this system uses for the symbols it lacks.
+    """
+    # The system font can be named by a generic family ("Sans Serif"), and Qt skips a generic name at the head of
+    # setFamilies: plain text then fell to the next family, the emoji or a symbol font with wide spaces. The family Qt
+    # resolves for the system font is the one it really draws the interface with.
+    families = [QFontInfo(QFontDatabase.systemFont(QFontDatabase.SystemFont.GeneralFont)).family()]
+    if status.family:
+        families.append(status.family)
+    families.extend(emoji_font_choice(platform).symbol_fallback_families)
+    return families
+
+
+def emoji_capable_font(point_size: float | None = None) -> QFont:
+    """Return the font of the emoji keyboard symbols and of the commit message, loading the colour font on first use.
+
+    An empty QFont only sets the families, so the widget keeps inheriting everything else, including the size of its
+    window; a size is set only when one is given.
+    """
+    font = QFont()
+    font.setFamilies(emoji_font_families(load_emoji_font()))
+    if point_size is not None:
+        font.setPointSizeF(point_size)
+    return font